@pezkuwi/api 16.5.5 → 16.5.8

package/build-deno/promise/decorateMethod.ts

@@ -0,0 +1,111 @@
+
+import type { Observable, Subscription } from 'https://esm.sh/rxjs@7.8.1';
+import type { Callback, Codec } from 'https://deno.land/x/pezkuwi/types/types/index.ts';
+import type { DecorateFn, DecorateMethodOptions, ObsInnerType, StorageEntryPromiseOverloads, UnsubscribePromise, VoidFn } from '../types/index.ts';
+
+import { catchError, EMPTY, tap } from 'https://esm.sh/rxjs@7.8.1';
+
+import { isFunction, nextTick } from 'https://deno.land/x/pezkuwi/util/mod.ts';
+
+interface Tracker<T> {
+  reject: (value: Error) => Observable<never>;
+  resolve: (value: T) => void;
+}
+
+type CodecReturnType<T extends (...args: unknown[]) => Observable<Codec>> =
+  T extends (...args: any) => infer R
+    ? R extends Observable<Codec>
+      ? ObsInnerType<R>
+      : never
+    : never;
+
+export function promiseTracker<T> (resolve: (value: T) => void, reject: (value: Error) => void): Tracker<T> {
+  let isCompleted = false;
+
+  return {
+    reject: (error: Error): Observable<never> => {
+      if (!isCompleted) {
+        isCompleted = true;
+
+        reject(error);
+      }
+
+      return EMPTY;
+    },
+    resolve: (value: T): void => {
+      if (!isCompleted) {
+        isCompleted = true;
+
+        resolve(value);
+      }
+    }
+  };
+}
+
+function extractArgs (args: unknown[], needsCallback: boolean): [unknown[], Callback<Codec> | undefined] {
+  const actualArgs = args.slice();
+
+  // If the last arg is a function, we pop it, put it into callback.
+  // actualArgs will then hold the actual arguments to be passed to `method`
+  const callback = (args.length && isFunction(args[args.length - 1]))
+    ? actualArgs.pop() as Callback<Codec>
+    : undefined;
+
+  // When we need a subscription, ensure that a valid callback is actually passed
+  if (needsCallback && !isFunction(callback)) {
+    throw new Error('Expected a callback to be passed with subscriptions');
+  }
+
+  return [actualArgs, callback];
+}
+
+function decorateCall<M extends DecorateFn<CodecReturnType<M>>> (method: M, args: unknown[]): Promise<CodecReturnType<M>> {
+  return new Promise((resolve, reject): void => {
+    // single result tracker - either reject with Error or resolve with Codec result
+    const tracker = promiseTracker(resolve, reject);
+
+    // encoding errors reject immediately, any result unsubscribes and resolves
+    const subscription: Subscription = method(...args)
+      .pipe(
+        catchError((error: Error) => tracker.reject(error))
+      )
+      .subscribe((result): void => {
+        tracker.resolve(result);
+
+        nextTick(() => subscription.unsubscribe());
+      });
+  });
+}
+
+function decorateSubscribe<M extends DecorateFn<CodecReturnType<M>>> (method: M, args: unknown[], resultCb: Callback<Codec>): UnsubscribePromise {
+  return new Promise<VoidFn>((resolve, reject): void => {
+    // either reject with error or resolve with unsubscribe callback
+    const tracker = promiseTracker(resolve, reject);
+
+    // errors reject immediately, the first result resolves with an unsubscribe promise, all results via callback
+    const subscription: Subscription = method(...args)
+      .pipe(
+        catchError((error: Error) => tracker.reject(error)),
+        tap(() => tracker.resolve(() => subscription.unsubscribe()))
+      )
+      .subscribe((result): void => {
+        // queue result (back of queue to clear current)
+        nextTick(() => resultCb(result));
+      });
+  });
+}
+
+/**
+ * @description Decorate method for ApiPromise, where the results are converted to the Promise equivalent
+ */
+export function toPromiseMethod<M extends DecorateFn<CodecReturnType<M>>> (method: M, options?: DecorateMethodOptions): StorageEntryPromiseOverloads {
+  const needsCallback = !!(options?.methodName && options.methodName.includes('subscribe'));
+
+  return function (...args: unknown[]): Promise<CodecReturnType<M>> | UnsubscribePromise {
+    const [actualArgs, resultCb] = extractArgs(args, needsCallback);
+
+    return resultCb
+      ? decorateSubscribe(method, actualArgs, resultCb)
+      : decorateCall((options?.overrideNoSub as M) || method, actualArgs);
+  } as StorageEntryPromiseOverloads;
+}

package/build-deno/promise/index.ts

@@ -0,0 +1,3 @@
+
+export { ApiPromise } from './Api.ts';
+export { toPromiseMethod } from './decorateMethod.ts';

package/build-deno/promise/types.ts

@@ -0,0 +1,7 @@
+
+import type { SubmittableExtrinsic as SubmittableExtrinsicBase } from '../submittable/types.ts';
+import type { QueryableStorageEntry as QueryableStorageEntryBase, SubmittableExtrinsicFunction as SubmittableExtrinsicFunctionBase } from '../types/index.ts';
+
+export type QueryableStorageEntry = QueryableStorageEntryBase<'promise'>;
+export type SubmittableExtrinsic = SubmittableExtrinsicBase<'promise'>;
+export type SubmittableExtrinsicFunction = SubmittableExtrinsicFunctionBase<'promise'>;

package/build-deno/rx/Api.ts

@@ -0,0 +1,184 @@
+
+import type { Observable } from 'https://esm.sh/rxjs@7.8.1';
+import type { ApiOptions } from '../types/index.ts';
+
+import { from } from 'https://esm.sh/rxjs@7.8.1';
+
+import { objectSpread } from 'https://deno.land/x/pezkuwi/util/mod.ts';
+
+import { ApiBase } from '../base/index.ts';
+import { toRxMethod } from './decorateMethod.ts';
+
+/**
+ * # @pezkuwi/api/rx
+ *
+ * ## Overview
+ *
+ * @name ApiRx
+ *
+ * @description
+ * ApiRx is a powerful RxJS Observable wrapper around the RPC and interfaces on the Pezkuwi network. As a full Observable API, all interface calls return RxJS Observables, including the static `.create(...)`. In the same fashion and subscription-based methods return long-running Observables that update with the latest values.
+ *
+ * The API is well suited to real-time applications where the latest state is needed, unlocking the subscription-based features of Pezkuwi (and Bizinikiwi) clients. Some familiarity with RxJS is a requirement to use the API, however just understanding `.subscribe` and `.pipe` on Observables will unlock full-scale use thereof.
+ *
+ * @see [[ApiPromise]]
+ *
+ * ## Usage
+ *
+ * Making rpc calls -
+ * <BR>
+ *
+ * ```javascript
+ * import ApiRx from 'https://deno.land/x/pezkuwi/api/rx/index.ts';
+ *
+ * // initialize via Promise & static create
+ * const api = await ApiRx.create().toPromise();
+ *
+ * // make a call to retrieve the current network head
+ * api.rpc.chain.subscribeNewHeads().subscribe((header) => {
+ *   console.log(`Chain is at #${header.number}`);
+ * });
+ * ```
+ * <BR>
+ *
+ * Subscribing to chain state -
+ * <BR>
+ *
+ * ```javascript
+ * import { combineLatest, pairwise, switchMap } from 'https://esm.sh/rxjs@7.8.1';
+ * import { ApiRx, WsProvider } from 'https://deno.land/x/pezkuwi/api/mod.ts';
+ *
+ *
+ * // initialize a provider with a specific endpoint
+ * const provider = new WsProvider('wss://example.com:9944')
+ *
+ * // initialize via isReady & new with specific provider
+ * new ApiRx({ provider })
+ *   .isReady
+ *   .pipe(
+ *     switchMap((api) =>
+ *       combineLatest([
+ *         api.query.timestamp.blockPeriod(),
+ *         api.query.timestamp.now().pipe(pairwise())
+ *       ])
+ *     )
+ *   )
+ *   .subscribe(([blockPeriod, timestamp]) => {
+ *      const elapsed = timestamp[1].toNumber() - timestamp[0].toNumber();
+ *      console.log(`timestamp ${timestamp[1]} \nelapsed ${elapsed} \n(${blockPeriod}s target)`);
+ *   });
+ * ```
+ * <BR>
+ *
+ * Submitting a transaction -
+ * <BR>
+ *
+ * ```javascript
+ * import { first, switchMap } from 'https://esm.sh/rxjs@7.8.1';
+ * import ApiRx from 'https://deno.land/x/pezkuwi/api/rx/index.ts';
+ *
+ * // import the test keyring (already has dev keys for Alice, Bob, Charlie, Eve & Ferdie)
+ * import testingPairs from 'https://deno.land/x/pezkuwi/keyring/testingPairs.ts';
+ * const keyring = testingPairs();
+ *
+ * // get api via Promise
+ * const api = await ApiRx.create().toPromise();
+ *
+ * // retrieve nonce for the account
+ * api.query.system
+ *   .account(keyring.alice.address)
+ *   .pipe(
+ *      first(),
+ *      // pipe nonce into transfer
+ *      switchMap(([nonce]) =>
+ *        api.tx.balances
+ *          // create transfer
+ *          .transferAllowDeath(keyring.bob.address, 12345)
+ *          // sign the transaction
+ *          .sign(keyring.alice, { nonce })
+ *          // send the transaction
+ *          .send()
+ *      )
+ *   )
+ *   // subscribe to overall result
+ *   .subscribe(({ status }) => {
+ *     if (status.isInBlock) {
+ *       console.log('Completed at block hash', status.asFinalized.toHex());
+ *     }
+ *   });
+ * ```
+ */
+export class ApiRx extends ApiBase<'rxjs'> {
+  #isReadyRx: Observable<ApiRx>;
+
+  /**
+   * @description Create an instance of the ApiRx class
+   * @param options Options to create an instance. Can be either [[ApiOptions]] or [[WsProvider]]
+   * @example
+   * <BR>
+   *
+   * ```javascript
+   * import { switchMap } from 'https://esm.sh/rxjs@7.8.1';
+   * import Api from 'https://deno.land/x/pezkuwi/api/rx/index.ts';
+   *
+   * new Api().isReady
+   *   .pipe(
+   *     switchMap((api) =>
+   *       api.rpc.chain.subscribeNewHeads()
+   *   ))
+   *   .subscribe((header) => {
+   *     console.log(`new block #${header.number.toNumber()}`);
+   *   });
+   * ```
+   */
+  constructor (options?: ApiOptions) {
+    super(options, 'rxjs', toRxMethod);
+
+    this.#isReadyRx = from<Promise<ApiRx>>(
+      // You can create an observable from an event, however my mind groks this form better
+      new Promise((resolve): void => {
+        super.on('ready', () => resolve(this));
+      })
+    );
+  }
+
+  /**
+   * @description Creates an ApiRx instance using the supplied provider. Returns an Observable containing the actual Api instance.
+   * @param options options that is passed to the class constructor. Can be either [[ApiOptions]] or [[WsProvider]]
+   * @example
+   * <BR>
+   *
+   * ```javascript
+   * import { switchMap } from 'https://esm.sh/rxjs@7.8.1';
+   * import Api from 'https://deno.land/x/pezkuwi/api/rx/index.ts';
+   *
+   * Api.create()
+   *   .pipe(
+   *     switchMap((api) =>
+   *       api.rpc.chain.subscribeNewHeads()
+   *   ))
+   *   .subscribe((header) => {
+   *     console.log(`new block #${header.number.toNumber()}`);
+   *   });
+   * ```
+   */
+  public static create (options?: ApiOptions): Observable<ApiRx> {
+    return new ApiRx(options).isReady;
+  }
+
+  /**
+   * @description Observable that returns the first time we are connected and loaded
+   */
+  public get isReady (): Observable<ApiRx> {
+    return this.#isReadyRx;
+  }
+
+  /**
+   * @description Returns a clone of this ApiRx instance (new underlying provider connection)
+   */
+  public clone (): ApiRx {
+    return new ApiRx(
+      objectSpread({}, this._options, { source: this })
+    );
+  }
+}

package/build-deno/rx/decorateMethod.ts

@@ -0,0 +1,7 @@
+
+import type { Codec } from 'https://deno.land/x/pezkuwi/types/types/index.ts';
+import type { DecorateFn } from '../types/index.ts';
+
+export function toRxMethod <M extends DecorateFn<Codec>> (method: M): M {
+  return method;
+}

package/build-deno/rx/index.ts

@@ -0,0 +1,3 @@
+
+export { ApiRx } from './Api.ts';
+export { toRxMethod } from './decorateMethod.ts';

package/build-deno/submittable/Result.ts

@@ -0,0 +1,109 @@
+
+import type { BlockNumber, DispatchError, DispatchInfo, EventRecord, ExtrinsicStatus, Hash } from 'https://deno.land/x/pezkuwi/types/interfaces/index.ts';
+import type { AnyJson, ISubmittableResult } from 'https://deno.land/x/pezkuwi/types/types/index.ts';
+import type { SubmittableResultValue } from './types.ts';
+
+const recordIdentity = (record: EventRecord) => record;
+
+function filterAndApply <T> (events: EventRecord[], section: string, methods: string[], onFound: (record: EventRecord) => T): T[] {
+  return events
+    .filter(({ event }) =>
+      section === event.section &&
+      methods.includes(event.method)
+    )
+    .map((record) => onFound(record));
+}
+
+function getDispatchError ({ event: { data: [dispatchError] } }: EventRecord): DispatchError {
+  return dispatchError as DispatchError;
+}
+
+function getDispatchInfo ({ event: { data, method } }: EventRecord): DispatchInfo {
+  return method === 'ExtrinsicSuccess'
+    ? data[0] as DispatchInfo
+    : data[1] as DispatchInfo;
+}
+
+function extractError (events: EventRecord[] = []): DispatchError | undefined {
+  return filterAndApply(events, 'system', ['ExtrinsicFailed'], getDispatchError)[0];
+}
+
+function extractInfo (events: EventRecord[] = []): DispatchInfo | undefined {
+  return filterAndApply(events, 'system', ['ExtrinsicFailed', 'ExtrinsicSuccess'], getDispatchInfo)[0];
+}
+
+export class SubmittableResult implements ISubmittableResult {
+  readonly dispatchError?: DispatchError | undefined;
+
+  readonly dispatchInfo?: DispatchInfo | undefined;
+
+  readonly internalError?: Error | undefined;
+
+  readonly events: EventRecord[];
+
+  readonly status: ExtrinsicStatus;
+
+  readonly txHash: Hash;
+
+  readonly txIndex?: number | undefined;
+
+  readonly blockNumber?: BlockNumber | undefined;
+
+  constructor ({ blockNumber, dispatchError, dispatchInfo, events, internalError, status, txHash, txIndex }: SubmittableResultValue) {
+    this.dispatchError = dispatchError || extractError(events);
+    this.dispatchInfo = dispatchInfo || extractInfo(events);
+    this.events = events || [];
+    this.internalError = internalError;
+    this.status = status;
+    this.txHash = txHash;
+    this.txIndex = txIndex;
+    this.blockNumber = blockNumber;
+  }
+
+  public get isCompleted (): boolean {
+    return this.isError || this.status.isInBlock || this.status.isFinalized;
+  }
+
+  public get isError (): boolean {
+    return this.status.isDropped || this.status.isFinalityTimeout || this.status.isInvalid || this.status.isUsurped;
+  }
+
+  public get isFinalized (): boolean {
+    return this.status.isFinalized;
+  }
+
+  public get isInBlock (): boolean {
+    return this.status.isInBlock;
+  }
+
+  public get isWarning (): boolean {
+    return this.status.isRetracted;
+  }
+
+  /**
+   * @description Filters EventRecords for the specified method & section (there could be multiple)
+   */
+  public filterRecords (section: string, method: string | string[]): EventRecord[] {
+    return filterAndApply(this.events, section, Array.isArray(method) ? method : [method], recordIdentity);
+  }
+
+  /**
+   * @description Finds an EventRecord for the specified method & section
+   */
+  public findRecord (section: string, method: string | string[]): EventRecord | undefined {
+    return this.filterRecords(section, method)[0];
+  }
+
+  /**
+   * @description Creates a human representation of the output
+   */
+  public toHuman (isExtended?: boolean): AnyJson {
+    return {
+      dispatchError: this.dispatchError?.toHuman(),
+      dispatchInfo: this.dispatchInfo?.toHuman(),
+      events: this.events.map((e) => e.toHuman(isExtended)),
+      internalError: this.internalError?.message.toString(),
+      status: this.status.toHuman(isExtended)
+    };
+  }
+}