@pezkuwi/api 16.5.5 → 16.5.8

package/cjs/rx/Api.d.ts

@@ -0,0 +1,155 @@
+import type { Observable } from 'rxjs';
+import type { ApiOptions } from '../types/index.js';
+import { ApiBase } from '../base/index.js';
+/**
+ * # @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 '@pezkuwi/api/rx';
+ *
+ * // 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 'rxjs';
+ * import { ApiRx, WsProvider } from '@pezkuwi/api';
+ *
+ *
+ * // 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 'rxjs';
+ * import ApiRx from '@pezkuwi/api/rx';
+ *
+ * // import the test keyring (already has dev keys for Alice, Bob, Charlie, Eve & Ferdie)
+ * import testingPairs from '@pezkuwi/keyring/testingPairs';
+ * 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 declare class ApiRx extends ApiBase<'rxjs'> {
+    #private;
+    /**
+     * @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 'rxjs';
+     * import Api from '@pezkuwi/api/rx';
+     *
+     * new Api().isReady
+     *   .pipe(
+     *     switchMap((api) =>
+     *       api.rpc.chain.subscribeNewHeads()
+     *   ))
+     *   .subscribe((header) => {
+     *     console.log(`new block #${header.number.toNumber()}`);
+     *   });
+     * ```
+     */
+    constructor(options?: ApiOptions);
+    /**
+     * @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 'rxjs';
+     * import Api from '@pezkuwi/api/rx';
+     *
+     * Api.create()
+     *   .pipe(
+     *     switchMap((api) =>
+     *       api.rpc.chain.subscribeNewHeads()
+     *   ))
+     *   .subscribe((header) => {
+     *     console.log(`new block #${header.number.toNumber()}`);
+     *   });
+     * ```
+     */
+    static create(options?: ApiOptions): Observable<ApiRx>;
+    /**
+     * @description Observable that returns the first time we are connected and loaded
+     */
+    get isReady(): Observable<ApiRx>;
+    /**
+     * @description Returns a clone of this ApiRx instance (new underlying provider connection)
+     */
+    clone(): ApiRx;
+}

package/cjs/rx/Api.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiRx = void 0;
+const rxjs_1 = require("rxjs");
+const util_1 = require("@pezkuwi/util");
+const index_js_1 = require("../base/index.js");
+const decorateMethod_js_1 = require("./decorateMethod.js");
+/**
+ * # @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 '@pezkuwi/api/rx';
+ *
+ * // 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 'rxjs';
+ * import { ApiRx, WsProvider } from '@pezkuwi/api';
+ *
+ *
+ * // 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 'rxjs';
+ * import ApiRx from '@pezkuwi/api/rx';
+ *
+ * // import the test keyring (already has dev keys for Alice, Bob, Charlie, Eve & Ferdie)
+ * import testingPairs from '@pezkuwi/keyring/testingPairs';
+ * 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());
+ *     }
+ *   });
+ * ```
+ */
+class ApiRx extends index_js_1.ApiBase {
+    #isReadyRx;
+    /**
+     * @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 'rxjs';
+     * import Api from '@pezkuwi/api/rx';
+     *
+     * new Api().isReady
+     *   .pipe(
+     *     switchMap((api) =>
+     *       api.rpc.chain.subscribeNewHeads()
+     *   ))
+     *   .subscribe((header) => {
+     *     console.log(`new block #${header.number.toNumber()}`);
+     *   });
+     * ```
+     */
+    constructor(options) {
+        super(options, 'rxjs', decorateMethod_js_1.toRxMethod);
+        this.#isReadyRx = (0, rxjs_1.from)(
+        // You can create an observable from an event, however my mind groks this form better
+        new Promise((resolve) => {
+            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 'rxjs';
+     * import Api from '@pezkuwi/api/rx';
+     *
+     * Api.create()
+     *   .pipe(
+     *     switchMap((api) =>
+     *       api.rpc.chain.subscribeNewHeads()
+     *   ))
+     *   .subscribe((header) => {
+     *     console.log(`new block #${header.number.toNumber()}`);
+     *   });
+     * ```
+     */
+    static create(options) {
+        return new ApiRx(options).isReady;
+    }
+    /**
+     * @description Observable that returns the first time we are connected and loaded
+     */
+    get isReady() {
+        return this.#isReadyRx;
+    }
+    /**
+     * @description Returns a clone of this ApiRx instance (new underlying provider connection)
+     */
+    clone() {
+        return new ApiRx((0, util_1.objectSpread)({}, this._options, { source: this }));
+    }
+}
+exports.ApiRx = ApiRx;

package/cjs/rx/decorateMethod.d.ts

@@ -0,0 +1,3 @@
+import type { Codec } from '@pezkuwi/types/types';
+import type { DecorateFn } from '../types/index.js';
+export declare function toRxMethod<M extends DecorateFn<Codec>>(method: M): M;

package/cjs/rx/decorateMethod.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toRxMethod = toRxMethod;
+function toRxMethod(method) {
+    return method;
+}

package/cjs/rx/index.d.ts

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

package/cjs/rx/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toRxMethod = exports.ApiRx = void 0;
+var Api_js_1 = require("./Api.js");
+Object.defineProperty(exports, "ApiRx", { enumerable: true, get: function () { return Api_js_1.ApiRx; } });
+var decorateMethod_js_1 = require("./decorateMethod.js");
+Object.defineProperty(exports, "toRxMethod", { enumerable: true, get: function () { return decorateMethod_js_1.toRxMethod; } });

package/cjs/submittable/Result.d.ts

@@ -0,0 +1,31 @@
+import type { BlockNumber, DispatchError, DispatchInfo, EventRecord, ExtrinsicStatus, Hash } from '@pezkuwi/types/interfaces';
+import type { AnyJson, ISubmittableResult } from '@pezkuwi/types/types';
+import type { SubmittableResultValue } from './types.js';
+export declare 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);
+    get isCompleted(): boolean;
+    get isError(): boolean;
+    get isFinalized(): boolean;
+    get isInBlock(): boolean;
+    get isWarning(): boolean;
+    /**
+     * @description Filters EventRecords for the specified method & section (there could be multiple)
+     */
+    filterRecords(section: string, method: string | string[]): EventRecord[];
+    /**
+     * @description Finds an EventRecord for the specified method & section
+     */
+    findRecord(section: string, method: string | string[]): EventRecord | undefined;
+    /**
+     * @description Creates a human representation of the output
+     */
+    toHuman(isExtended?: boolean): AnyJson;
+}

package/cjs/submittable/Result.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubmittableResult = void 0;
+const recordIdentity = (record) => record;
+function filterAndApply(events, section, methods, onFound) {
+    return events
+        .filter(({ event }) => section === event.section &&
+        methods.includes(event.method))
+        .map((record) => onFound(record));
+}
+function getDispatchError({ event: { data: [dispatchError] } }) {
+    return dispatchError;
+}
+function getDispatchInfo({ event: { data, method } }) {
+    return method === 'ExtrinsicSuccess'
+        ? data[0]
+        : data[1];
+}
+function extractError(events = []) {
+    return filterAndApply(events, 'system', ['ExtrinsicFailed'], getDispatchError)[0];
+}
+function extractInfo(events = []) {
+    return filterAndApply(events, 'system', ['ExtrinsicFailed', 'ExtrinsicSuccess'], getDispatchInfo)[0];
+}
+class SubmittableResult {
+    dispatchError;
+    dispatchInfo;
+    internalError;
+    events;
+    status;
+    txHash;
+    txIndex;
+    blockNumber;
+    constructor({ blockNumber, dispatchError, dispatchInfo, events, internalError, status, txHash, txIndex }) {
+        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;
+    }
+    get isCompleted() {
+        return this.isError || this.status.isInBlock || this.status.isFinalized;
+    }
+    get isError() {
+        return this.status.isDropped || this.status.isFinalityTimeout || this.status.isInvalid || this.status.isUsurped;
+    }
+    get isFinalized() {
+        return this.status.isFinalized;
+    }
+    get isInBlock() {
+        return this.status.isInBlock;
+    }
+    get isWarning() {
+        return this.status.isRetracted;
+    }
+    /**
+     * @description Filters EventRecords for the specified method & section (there could be multiple)
+     */
+    filterRecords(section, method) {
+        return filterAndApply(this.events, section, Array.isArray(method) ? method : [method], recordIdentity);
+    }
+    /**
+     * @description Finds an EventRecord for the specified method & section
+     */
+    findRecord(section, method) {
+        return this.filterRecords(section, method)[0];
+    }
+    /**
+     * @description Creates a human representation of the output
+     */
+    toHuman(isExtended) {
+        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)
+        };
+    }
+}
+exports.SubmittableResult = SubmittableResult;

package/cjs/submittable/createClass.d.ts

@@ -0,0 +1,12 @@
+import type { CodecClass } from '@pezkuwi/types/types';
+import type { ApiBase } from '../base/index.js';
+import type { ApiInterfaceRx, ApiTypes } from '../types/index.js';
+import type { SubmittableExtrinsic } from './types.js';
+interface SubmittableOptions<ApiType extends ApiTypes> {
+    api: ApiInterfaceRx;
+    apiType: ApiTypes;
+    blockHash?: Uint8Array | undefined;
+    decorateMethod: ApiBase<ApiType>['_decorateMethod'];
+}
+export declare function createClass<ApiType extends ApiTypes>({ api, apiType, blockHash, decorateMethod }: SubmittableOptions<ApiType>): CodecClass<SubmittableExtrinsic<ApiType>>;
+export {};