Add derive.chain.bestNumberLag (#629)

* Add derive.chain.bestNumberLag

* type typo

packages/api-derive/src/chain/bestNumber.ts

@@ -10,7 +10,15 @@ import { BlockNumber, Header } from '@polkadot/types/index';
 import { drr } from '../util/drr';
 
 /**
- * Get the latest block number.
+ * @description Get the latest block number.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * api.derive.chain.bestNumber((blockNumber) => {
+ *   console.log(`the current best block is #${blockNumber}`);
+ * });
+ * ```
  */
 export function bestNumber (api: ApiInterface$Rx) {
   return (): Observable<BlockNumber> =>

packages/api-derive/src/chain/bestNumberFinalised.ts

@@ -10,7 +10,15 @@ import { BlockNumber, Header } from '@polkadot/types/index';
 import { drr } from '../util/drr';
 
 /**
- * Get the latest finalised block number.
+ * @description Get the latest finalised block number.
+ * example
+ * <BR>
+ *
+ * ```javascript
+ * api.derive.chain.bestNumberFinalised((blockNumber) => {
+ *   console.log(`the current finalised block is #${blockNumber}`);
+ * });
+ * ```
  */
 export function bestNumberFinalised (api: ApiInterface$Rx) {
   return (): Observable<BlockNumber> =>

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

@@ -0,0 +1,36 @@
+// Copyright 2017-2019 @polkadot/api-derive authors & contributors
+// This software may be modified and distributed under the terms
+// of the Apache-2.0 license. See the LICENSE file for details.
+
+import { Observable, combineLatest } from 'rxjs';
+import { map } from 'rxjs/operators';
+import { ApiInterface$Rx } from '@polkadot/api/types';
+import { BlockNumber } from '@polkadot/types/index';
+
+import { drr } from '../util/drr';
+import { bestNumber } from './bestNumber';
+import { bestNumberFinalised } from './bestNumberFinalised';
+
+/**
+ * @description Calculates the lag between finalised head and best head
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * api.derive.chain.bestNumberLag((lag) => {
+ *   console.log(`finalised is ${lag} blocks behind head`);
+ * });
+ * ```
+ */
+export function bestNumberLag (api: ApiInterface$Rx) {
+  return (): Observable<BlockNumber> =>
+    combineLatest(
+      bestNumber(api)(),
+      bestNumberFinalised(api)()
+    ).pipe(
+      map(([bestNumber, bestNumberFinalised]) =>
+        new BlockNumber(bestNumber.sub(bestNumberFinalised))
+      ),
+      drr()
+    );
+}

packages/api-derive/src/chain/getHeader.ts

@@ -12,7 +12,16 @@ import { drr } from '../util/drr';
 import { HeaderAndValidators } from './subscribeNewHead';
 
 /**
- * Get the a specific block header and extend it with the author
+ * @description Get the a specific block header and extend it with the author
+ * @param hash: Uint8Array | string
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * const { author, blockNumber } = await api.derive.chain.getHeader('0x123...456');
+ *
+ * console.log(`block #${blockNumber} was authored by ${author}`);
+ * ```
  */
 export function getHeader (api: ApiInterface$Rx) {
   return (hash: Uint8Array | string): Observable<HeaderExtended | undefined> =>

packages/api-derive/src/chain/index.ts

@@ -4,5 +4,6 @@
 
 export * from './bestNumber';
 export * from './bestNumberFinalised';
+export * from './bestNumberLag';
 export * from './getHeader';
 export * from './subscribeNewHead';

packages/api-derive/src/chain/subscribeNewHead.ts

@@ -13,7 +13,15 @@ import { drr } from '../util/drr';
 export type HeaderAndValidators = [Header, Array<AccountId>];
 
 /**
- * Subscribe to block headers and extend it with the author
+ * @description Subscribe to block headers and extend it with the author
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * api.derive.chain.subscribeNewHead(({ author, blockNumber }) => {
+ *   console.log(`block #${blockNumber} was authored by ${author}`);
+ * });
+ * ```
  */
 export function subscribeNewHead (api: ApiInterface$Rx) {
   return (): Observable<HeaderExtended> =>
@@ -31,7 +39,7 @@ export function subscribeNewHead (api: ApiInterface$Rx) {
             api.query.session.validators.at(header.hash) as any as Observable<Array<AccountId>>
           )
         ),
-        map(([header, validators]: HeaderAndValidators) =>
+        map(([header, validators]) =>
           new HeaderExtended(header, validators)
         ),
         drr()