Improve events (#454)

* Fix typo in docs

* Improve events
Expose `error` event
Add `once`
Allow method chaining for `on` and `once`

packages/api/src/Base.ts

@@ -169,14 +169,14 @@ export default abstract class ApiBase<R, S, E> implements ApiBaseInterface<R, S,
   /**
    * @description Attach an eventemitter handler to listen to a specific event
    *
-   * @param type The type of event to listen to. Available events are `connected`, `disconnected` and `ready`
+   * @param type The type of event to listen to. Available events are `connected`, `disconnected`, `ready` and `error`
    * @param handler The callback to be called when the event fires. Depending on the event type, it could fire with additional arguments.
    *
    * @example
    * <BR>
    *
    * ```javascript
-   * api.on('disconnected', () => {
+   * api.on('connected', () => {
    *   console.log('API has been connected to the endpoint');
    * });
    *
@@ -185,8 +185,33 @@ export default abstract class ApiBase<R, S, E> implements ApiBaseInterface<R, S,
    * });
    * ```
    */
-  on (type: ApiInterface$Events, handler: (...args: Array<any>) => any): void {
+  on (type: ApiInterface$Events, handler: (...args: Array<any>) => any): this {
     this._eventemitter.on(type, handler);
+    return this;
+  }
+
+  /**
+   * @description Attach an one-time eventemitter handler to listen to a specific event
+   *
+   * @param type The type of event to listen to. Available events are `connected`, `disconnected`, `ready` and `error`
+   * @param handler The callback to be called when the event fires. Depending on the event type, it could fire with additional arguments.
+   *
+   * @example
+   * <BR>
+   *
+   * ```javascript
+   * api.once('connected', () => {
+   *   console.log('API has been connected to the endpoint');
+   * });
+   *
+   * api.once('disconnected', () => {
+   *   console.log('API has been disconnected from the endpoint');
+   * });
+   * ```
+   */
+  once (type: ApiInterface$Events, handler: (...args: Array<any>) => any): this {
+    this._eventemitter.once(type, handler);
+    return this;
   }
 
   protected emit (type: ApiInterface$Events, ...args: Array<any>): void {
@@ -200,6 +225,10 @@ export default abstract class ApiBase<R, S, E> implements ApiBaseInterface<R, S,
       this.emit('disconnected');
     });
 
+    this._rpcBase._provider.on('error', (error) => {
+      this.emit('error', error);
+    });
+
     this._rpcBase._provider.on('connected', async () => {
       this.emit('connected');
 

packages/api/src/promise/index.ts

@@ -154,10 +154,14 @@ export default class ApiPromise extends ApiBase<Rpc, QueryableStorage, Submittab
   constructor (options?: ApiOptions | ProviderInterface) {
     super(options);
 
-    this._isReady = new Promise((resolveReady) =>
-      super.on('ready', () =>
-        resolveReady(this)
-      )
+    this._isReady = new Promise((resolveReady, rejectReady) =>
+      super
+        .once('ready', () =>
+          resolveReady(this)
+        )
+        .once('error', () =>
+          rejectReady(this)
+        )
     );
   }
 

packages/rpc-provider/src/types.ts

@@ -37,7 +37,7 @@ export type JsonRpcResponse = JsonRpcObject & JsonRpcResponseBase;
 
 export type ProviderInterface$Callback = (result: any) => void;
 
-export type ProviderInterface$Emitted = 'connected' | 'disconnected';
+export type ProviderInterface$Emitted = 'connected' | 'disconnected' | 'error';
 
 export type ProviderInterface$EmitCb = (value?: any) => any;
 

packages/rpc-provider/src/ws/index.ts

@@ -245,6 +245,7 @@ export default class WsProvider implements WSProviderInterface {
 
   private onSocketError = (error: Event): void => {
     l.debug(() => ['socket error', error]);
+    this.emit('error', error);
   }
 
   private onSocketMessage = (message: MessageEvent): void => {

packages/rpc-rx/src/types.ts

@@ -3,6 +3,7 @@
 // of the Apache-2.0 license. See the LICENSE file for details.
 
 import { ReplaySubject, Observable } from 'rxjs';
+import { ProviderInterface$Emitted } from '@polkadot/rpc-provider/types';
 
 export type RpcRxInterface$Method = (...params: Array<any>) => Observable<any> | ReplaySubject<any>;
 
@@ -10,7 +11,7 @@ export type RpcRxInterface$Section = {
   [index: string]: RpcRxInterface$Method
 };
 
-export type RpcRxInterface$Events = 'connected' | 'disconnected';
+export type RpcRxInterface$Events = ProviderInterface$Emitted;
 
 export type RpcRxInterface = {
   readonly author: RpcRxInterface$Section;