Merge 2d9be8d into 174978a

packages/api/src/Base.ts

@@ -46,12 +46,12 @@ export default abstract class ApiBase<R, S, E> implements ApiBaseInterface<R, S,
    * <BR>
    *
    * ```javascript
-   * import Api from '@polkadot/api/rx';
+   * import Api from '@polkadot/api/promise';
    *
-   * new Api().isReady.subscribe((api) => {
-   *   api.rpc.subscribeNewHead().subscribe((header) => {
-   *     console.log(`new block #${header.blockNumber.toNumber()}`);
-   *   });
+   * const api = new Api().isReady();
+   *
+   * api.rpc.subscribeNewHead((header) => {
+   *   console.log(`new block #${header.blockNumber.toNumber()}`);
    * });
    * ```
    */
@@ -99,11 +99,9 @@ export default abstract class ApiBase<R, S, E> implements ApiBaseInterface<R, S,
    * <BR>
    *
    * ```javascript
-   * api.query.balances
-   *   .freeBalance(<accountId>)
-   *   .subscribe((balance) => {
-   *     console.log('new balance', balance);
-   *   });
+   * api.query.balances.freeBalance(<accountId>, (balance) => {
+   *   console.log('new balance', balance);
+   * });
    * ```
    */
   get query (): S {
@@ -121,11 +119,9 @@ export default abstract class ApiBase<R, S, E> implements ApiBaseInterface<R, S,
    * <BR>
    *
    * ```javascript
-   * api.rpc.chain
-   *   .subscribeNewHead()
-   *   .subscribe((header) => {
-   *     console.log('new header', header);
-   *   });
+   * api.rpc.chain.subscribeNewHead((header) => {
+   *   console.log('new header', header);
+   * });
    * ```
    */
   get rpc (): R {
@@ -142,8 +138,7 @@ export default abstract class ApiBase<R, S, E> implements ApiBaseInterface<R, S,
    * api.tx.balances
    *   .transfer(<recipientId>, <balance>)
    *   .sign(<keyPair>, <accountNonce>, <blockHash (optional)>)
-   *   .send()
-   *   .subscribe((status) => {
+   *   .send((status) => {
    *     console.log('tx status', status);
    *   });
    * ```
@@ -164,7 +159,7 @@ export default abstract class ApiBase<R, S, E> implements ApiBaseInterface<R, S,
    * <BR>
    *
    * ```javascript
-   * * api.on('disconnected', () => {
+   * api.on('disconnected', () => {
    *   console.log('API has been connected to the endpoint');
    * });
    *

packages/api/src/promise/Combinator.ts

@@ -0,0 +1,50 @@
+// Copyright 2017-2018 @polkadot/api authors & contributors
+// This software may be modified and distributed under the terms
+// of the ISC license. See the LICENSE file for details.
+
+import { isFunction } from '@polkadot/util';
+
+export type CombinatorCallback = (value: Array<any>) => any;
+
+type CombinatorFunction = (value: any) => void;
+
+export default class Combinator {
+  protected _callback?: CombinatorCallback;
+  protected _results: Array<any>;
+
+  constructor (callback?: CombinatorCallback) {
+    this._callback = callback;
+    this._results = [];
+  }
+
+  next (): CombinatorFunction {
+    const index = this._results.length;
+
+    // Add an empty value, so we are not operating a sparse array
+    this._results[index] = undefined;
+
+    return (value: any): void => {
+      this._results[index] = value;
+
+      this.triggerUpdate();
+    };
+  }
+
+  subscribe (callback: CombinatorCallback): void {
+    this._callback = callback;
+
+    this.triggerUpdate();
+  }
+
+  protected triggerUpdate (): void {
+    if (!isFunction(this._callback) || !this._results.length) {
+      return;
+    }
+
+    try {
+      this._callback(this._results);
+    } catch (error) {
+      // swallow, we don't want the handler to trip us up
+    }
+  }
+}

packages/api/src/promise/index.ts

@@ -13,6 +13,7 @@ import { StorageFunction } from '@polkadot/types/StorageKey';
 import { isFunction } from '@polkadot/util';
 
 import ApiBase from '../Base';
+import Combinator, { CombinatorCallback } from './Combinator';
 import SubmittableExtrinsic from './SubmittableExtrinsic';
 
 /**
@@ -165,6 +166,27 @@ export default class ApiPromise extends ApiBase<Rpc, QueryableStorage, Submittab
     return rpc;
   }
 
+  /**
+   * @description Creats a combinator that can be used to combine the results from multiple subscriptions
+   * @param callback A callback that will return an Array of all the values this combinator has been applied to
+   * @example
+   * <BR>
+   *
+   * ```javascript
+   * // create the combinator
+   * const combinator = api.combinator(([balance, nonce]) => {
+   *   console.log(`You have ${balance} units, with ${nonce} transactions sent`);
+   * });
+   *
+   * // subscribe to balance & nonce using combinator
+   * api.query.balances.freeBalance(<address>, combinator.next());
+   * api.query.system.accountNonce(<address>, combinator.next());
+   * ```
+   */
+  combinator (callback?: CombinatorCallback): Combinator {
+    return new Combinator(callback);
+  }
+
   protected decorateExtrinsics (extrinsics: Extrinsics): SubmittableExtrinsics {
     return Object.keys(extrinsics).reduce((result, sectionName) => {
       const section = extrinsics[sectionName];