pezkuwi-api/packages/api-derive/src/chain/bestNumberLag.ts

// Copyright 2017-2026 @pezkuwi/api-derive authors & contributors
// SPDX-License-Identifier: Apache-2.0

import type { Observable } from 'rxjs';
import type { BlockNumber } from '@pezkuwi/types/interfaces';
import type { DeriveApi } from '../types.js';

import { combineLatest, map } from 'rxjs';

import { memo } from '../util/index.js';

/**
 * @name bestNumberLag
 * @returns A number of blocks
 * @description Calculates the lag between finalized head and best head
 * @examplew
 * ```javascript
 * api.derive.chain.bestNumberLag((lag) => {
 *   console.log(`finalized is ${lag} blocks behind head`);
 * });
 * ```
 */
export function bestNumberLag (instanceId: string, api: DeriveApi): () => Observable<BlockNumber> {
  return memo(instanceId, (): Observable<BlockNumber> =>
    combineLatest([
      api.derive.chain.bestNumber(),
      api.derive.chain.bestNumberFinalized()
    ]).pipe(
      map(([bestNumber, bestNumberFinalized]): BlockNumber =>
        api.registry.createType('BlockNumber', bestNumber.sub(bestNumberFinalized))
      )
    ));
}