@pezkuwi/api 16.5.8 → 16.5.10

package/build/cjs/promise/Api.d.ts

@@ -1,158 +0,0 @@
-import type { ApiOptions, UnsubscribePromise } from '../types/index.js';
-import type { CombinatorCallback, CombinatorFunction } from './Combinator.js';
-import { ApiBase } from '../base/index.js';
-/**
- * # @pezkuwi/api/promise
- *
- * ## Overview
- *
- * @name ApiPromise
- * @description
- * ApiPromise is a standard JavaScript wrapper around the RPC and interfaces on the Pezkuwi network. As a full Promise-based, all interface calls return Promises, including the static `.create(...)`. Subscription calls utilise `(value) => {}` callbacks to pass through the latest values.
- *
- * The API is well suited to real-time applications where either the single-shot state is needed or use is to be made of the subscription-based features of Pezkuwi (and Bizinikiwi) clients.
- *
- * @see [[ApiRx]]
- *
- * ## Usage
- *
- * Making rpc calls -
- * <BR>
- *
- * ```javascript
- * import ApiPromise from '@pezkuwi/api/promise';
- *
- * // initialise via static create
- * const api = await ApiPromise.create();
- *
- * // make a subscription to the network head
- * api.rpc.chain.subscribeNewHeads((header) => {
- *   console.log(`Chain is at #${header.number}`);
- * });
- * ```
- * <BR>
- *
- * Subscribing to chain state -
- * <BR>
- *
- * ```javascript
- * import { ApiPromise, WsProvider } from '@pezkuwi/api';
- *
- * // initialise a provider with a specific endpoint
- * const provider = new WsProvider('wss://example.com:9944')
- *
- * // initialise via isReady & new with specific provider
- * const api = await new ApiPromise({ provider }).isReady;
- *
- * // retrieve the block target time
- * const blockPeriod = await api.query.timestamp.blockPeriod().toNumber();
- * let last = 0;
- *
- * // subscribe to the current block timestamp, updates automatically (callback provided)
- * api.query.timestamp.now((timestamp) => {
- *   const elapsed = last
- *     ? `, ${timestamp.toNumber() - last}s since last`
- *     : '';
- *
- *   last = timestamp.toNumber();
- *   console.log(`timestamp ${timestamp}${elapsed} (${blockPeriod}s target)`);
- * });
- * ```
- * <BR>
- *
- * Submitting a transaction -
- * <BR>
- *
- * ```javascript
- * import ApiPromise from '@pezkuwi/api/promise';
- *
- * ApiPromise.create().then((api) => {
- *   const [nonce] = await api.query.system.account(keyring.alice.address);
- *
- *   api.tx.balances
- *     // create transfer
- *     transfer(keyring.bob.address, 12345)
- *     // sign the transcation
- *     .sign(keyring.alice, { nonce })
- *     // send the transaction (optional status callback)
- *     .send((status) => {
- *       console.log(`current status ${status.type}`);
- *     })
- *     // retrieve the submitted extrinsic hash
- *     .then((hash) => {
- *       console.log(`submitted with hash ${hash}`);
- *     });
- * });
- * ```
- */
-export declare class ApiPromise extends ApiBase<'promise'> {
-    #private;
-    /**
-     * @description Creates an instance of the ApiPromise class
-     * @param options Options to create an instance. This can be either [[ApiOptions]] or
-     * an [[WsProvider]].
-     * @example
-     * <BR>
-     *
-     * ```javascript
-     * import Api from '@pezkuwi/api/promise';
-     *
-     * new Api().isReady.then((api) => {
-     *   api.rpc.subscribeNewHeads((header) => {
-     *     console.log(`new block #${header.number.toNumber()}`);
-     *   });
-     * });
-     * ```
-     */
-    constructor(options?: ApiOptions);
-    /**
-     * @description Creates an ApiPromise instance using the supplied provider. Returns an Promise containing the actual Api instance.
-     * @param options options that is passed to the class contructor. Can be either [[ApiOptions]] or a
-     * provider (see the constructor arguments)
-     * @example
-     * <BR>
-     *
-     * ```javascript
-     * import Api from '@pezkuwi/api/promise';
-     *
-     * Api.create().then(async (api) => {
-     *   const timestamp = await api.query.timestamp.now();
-     *
-     *   console.log(`lastest block timestamp ${timestamp}`);
-     * });
-     * ```
-     */
-    static create(options?: ApiOptions): Promise<ApiPromise>;
-    /**
-     * @description Promise that resolves the first time we are connected and loaded
-     */
-    get isReady(): Promise<ApiPromise>;
-    /**
-     * @description Promise that resolves if we can connect, or reject if there is an error
-     */
-    get isReadyOrError(): Promise<ApiPromise>;
-    /**
-     * @description Returns a clone of this ApiPromise instance (new underlying provider connection)
-     */
-    clone(): ApiPromise;
-    /**
-     * @description Creates a combinator that can be used to combine the latest results from multiple subscriptions
-     * @param fns An array of function to combine, each in the form of `(cb: (value: void)) => void`
-     * @param callback A callback that will return an Array of all the values this combinator has been applied to
-     * @example
-     * <BR>
-     *
-     * ```javascript
-     * const address = '5DTestUPts3kjeXSTMyerHihn1uwMfLj8vU8sqF7qYrFacT7';
-     *
-     * // combines values from balance & nonce as it updates
-     * api.combineLatest([
-     *   api.rpc.chain.subscribeNewHeads,
-     *   (cb) => api.query.system.account(address, cb)
-     * ], ([head, [balance, nonce]]) => {
-     *   console.log(`#${head.number}: You have ${balance.free} units, with ${nonce} transactions sent`);
-     * });
-     * ```
-     */
-    combineLatest<T extends any[] = any[]>(fns: (CombinatorFunction | [CombinatorFunction, ...any[]])[], callback: CombinatorCallback<T>): UnsubscribePromise;
-}

package/build/cjs/promise/Api.js

@@ -1,195 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ApiPromise = void 0;
-const util_1 = require("@pezkuwi/util");
-const index_js_1 = require("../base/index.js");
-const Combinator_js_1 = require("./Combinator.js");
-const decorateMethod_js_1 = require("./decorateMethod.js");
-/**
- * # @pezkuwi/api/promise
- *
- * ## Overview
- *
- * @name ApiPromise
- * @description
- * ApiPromise is a standard JavaScript wrapper around the RPC and interfaces on the Pezkuwi network. As a full Promise-based, all interface calls return Promises, including the static `.create(...)`. Subscription calls utilise `(value) => {}` callbacks to pass through the latest values.
- *
- * The API is well suited to real-time applications where either the single-shot state is needed or use is to be made of the subscription-based features of Pezkuwi (and Bizinikiwi) clients.
- *
- * @see [[ApiRx]]
- *
- * ## Usage
- *
- * Making rpc calls -
- * <BR>
- *
- * ```javascript
- * import ApiPromise from '@pezkuwi/api/promise';
- *
- * // initialise via static create
- * const api = await ApiPromise.create();
- *
- * // make a subscription to the network head
- * api.rpc.chain.subscribeNewHeads((header) => {
- *   console.log(`Chain is at #${header.number}`);
- * });
- * ```
- * <BR>
- *
- * Subscribing to chain state -
- * <BR>
- *
- * ```javascript
- * import { ApiPromise, WsProvider } from '@pezkuwi/api';
- *
- * // initialise a provider with a specific endpoint
- * const provider = new WsProvider('wss://example.com:9944')
- *
- * // initialise via isReady & new with specific provider
- * const api = await new ApiPromise({ provider }).isReady;
- *
- * // retrieve the block target time
- * const blockPeriod = await api.query.timestamp.blockPeriod().toNumber();
- * let last = 0;
- *
- * // subscribe to the current block timestamp, updates automatically (callback provided)
- * api.query.timestamp.now((timestamp) => {
- *   const elapsed = last
- *     ? `, ${timestamp.toNumber() - last}s since last`
- *     : '';
- *
- *   last = timestamp.toNumber();
- *   console.log(`timestamp ${timestamp}${elapsed} (${blockPeriod}s target)`);
- * });
- * ```
- * <BR>
- *
- * Submitting a transaction -
- * <BR>
- *
- * ```javascript
- * import ApiPromise from '@pezkuwi/api/promise';
- *
- * ApiPromise.create().then((api) => {
- *   const [nonce] = await api.query.system.account(keyring.alice.address);
- *
- *   api.tx.balances
- *     // create transfer
- *     transfer(keyring.bob.address, 12345)
- *     // sign the transcation
- *     .sign(keyring.alice, { nonce })
- *     // send the transaction (optional status callback)
- *     .send((status) => {
- *       console.log(`current status ${status.type}`);
- *     })
- *     // retrieve the submitted extrinsic hash
- *     .then((hash) => {
- *       console.log(`submitted with hash ${hash}`);
- *     });
- * });
- * ```
- */
-class ApiPromise extends index_js_1.ApiBase {
-    #isReadyPromise;
-    #isReadyOrErrorPromise;
-    /**
-     * @description Creates an instance of the ApiPromise class
-     * @param options Options to create an instance. This can be either [[ApiOptions]] or
-     * an [[WsProvider]].
-     * @example
-     * <BR>
-     *
-     * ```javascript
-     * import Api from '@pezkuwi/api/promise';
-     *
-     * new Api().isReady.then((api) => {
-     *   api.rpc.subscribeNewHeads((header) => {
-     *     console.log(`new block #${header.number.toNumber()}`);
-     *   });
-     * });
-     * ```
-     */
-    constructor(options) {
-        super(options, 'promise', decorateMethod_js_1.toPromiseMethod);
-        this.#isReadyPromise = new Promise((resolve) => {
-            super.once('ready', () => resolve(this));
-        });
-        this.#isReadyOrErrorPromise = new Promise((resolve, reject) => {
-            const tracker = (0, decorateMethod_js_1.promiseTracker)(resolve, reject);
-            super.once('ready', () => tracker.resolve(this));
-            super.once('error', (error) => tracker.reject(error));
-        });
-    }
-    /**
-     * @description Creates an ApiPromise instance using the supplied provider. Returns an Promise containing the actual Api instance.
-     * @param options options that is passed to the class contructor. Can be either [[ApiOptions]] or a
-     * provider (see the constructor arguments)
-     * @example
-     * <BR>
-     *
-     * ```javascript
-     * import Api from '@pezkuwi/api/promise';
-     *
-     * Api.create().then(async (api) => {
-     *   const timestamp = await api.query.timestamp.now();
-     *
-     *   console.log(`lastest block timestamp ${timestamp}`);
-     * });
-     * ```
-     */
-    static create(options) {
-        const instance = new ApiPromise(options);
-        if (options && options.throwOnConnect) {
-            return instance.isReadyOrError;
-        }
-        // Swallow any rejections on isReadyOrError
-        // (in Node 15.x this creates issues, when not being looked at)
-        instance.isReadyOrError.catch(util_1.noop);
-        return instance.isReady;
-    }
-    /**
-     * @description Promise that resolves the first time we are connected and loaded
-     */
-    get isReady() {
-        return this.#isReadyPromise;
-    }
-    /**
-     * @description Promise that resolves if we can connect, or reject if there is an error
-     */
-    get isReadyOrError() {
-        return this.#isReadyOrErrorPromise;
-    }
-    /**
-     * @description Returns a clone of this ApiPromise instance (new underlying provider connection)
-     */
-    clone() {
-        return new ApiPromise((0, util_1.objectSpread)({}, this._options, { source: this }));
-    }
-    /**
-     * @description Creates a combinator that can be used to combine the latest results from multiple subscriptions
-     * @param fns An array of function to combine, each in the form of `(cb: (value: void)) => void`
-     * @param callback A callback that will return an Array of all the values this combinator has been applied to
-     * @example
-     * <BR>
-     *
-     * ```javascript
-     * const address = '5DTestUPts3kjeXSTMyerHihn1uwMfLj8vU8sqF7qYrFacT7';
-     *
-     * // combines values from balance & nonce as it updates
-     * api.combineLatest([
-     *   api.rpc.chain.subscribeNewHeads,
-     *   (cb) => api.query.system.account(address, cb)
-     * ], ([head, [balance, nonce]]) => {
-     *   console.log(`#${head.number}: You have ${balance.free} units, with ${nonce} transactions sent`);
-     * });
-     * ```
-     */
-    // eslint-disable-next-line @typescript-eslint/require-await
-    async combineLatest(fns, callback) {
-        const combinator = new Combinator_js_1.Combinator(fns, callback);
-        return () => {
-            combinator.unsubscribe();
-        };
-    }
-}
-exports.ApiPromise = ApiPromise;

package/build/cjs/promise/Combinator.d.ts

@@ -1,12 +0,0 @@
-import type { Callback } from '@pezkuwi/types/types';
-import type { UnsubscribePromise } from '../types/index.js';
-export type CombinatorCallback<T extends unknown[]> = Callback<T>;
-export type CombinatorFunction = (cb: Callback<any>) => UnsubscribePromise;
-export declare class Combinator<T extends unknown[] = unknown[]> {
-    #private;
-    constructor(fns: (CombinatorFunction | [CombinatorFunction, ...unknown[]])[], callback: CombinatorCallback<T>);
-    protected _allHasFired(): boolean;
-    protected _createCallback(index: number): (value: any) => void;
-    protected _triggerUpdate(): void;
-    unsubscribe(): void;
-}

package/build/cjs/promise/Combinator.js

@@ -1,72 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Combinator = void 0;
-const util_1 = require("@pezkuwi/util");
-class Combinator {
-    #allHasFired = false;
-    #callback;
-    #fired = [];
-    #fns = [];
-    #isActive = true;
-    #results = [];
-    #subscriptions = [];
-    constructor(fns, callback) {
-        this.#callback = callback;
-        // eslint-disable-next-line @typescript-eslint/no-floating-promises, @typescript-eslint/require-await
-        this.#subscriptions = fns.map(async (input, index) => {
-            const [fn, ...args] = Array.isArray(input)
-                ? input
-                : [input];
-            this.#fired.push(false);
-            this.#fns.push(fn);
-            // Not quite 100% how to have a variable number at the front here
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-return,@typescript-eslint/ban-types
-            return fn(...args, this._createCallback(index));
-        });
-    }
-    _allHasFired() {
-        this.#allHasFired ||= this.#fired.filter((hasFired) => !hasFired).length === 0;
-        return this.#allHasFired;
-    }
-    _createCallback(index) {
-        return (value) => {
-            this.#fired[index] = true;
-            this.#results[index] = value;
-            this._triggerUpdate();
-        };
-    }
-    _triggerUpdate() {
-        if (!this.#isActive || !(0, util_1.isFunction)(this.#callback) || !this._allHasFired()) {
-            return;
-        }
-        try {
-            Promise
-                .resolve(this.#callback(this.#results))
-                .catch(util_1.noop);
-        }
-        catch {
-            // swallow, we don't want the handler to trip us up
-        }
-    }
-    unsubscribe() {
-        if (!this.#isActive) {
-            return;
-        }
-        this.#isActive = false;
-        Promise
-            .all(this.#subscriptions.map(async (subscription) => {
-            try {
-                const unsubscribe = await subscription;
-                if ((0, util_1.isFunction)(unsubscribe)) {
-                    unsubscribe();
-                }
-            }
-            catch {
-                // ignore
-            }
-        })).catch(() => {
-            // ignore, already ignored above, should never throw
-        });
-    }
-}
-exports.Combinator = Combinator;

package/build/cjs/promise/decorateMethod.d.ts

@@ -1,14 +0,0 @@
-import type { Observable } from 'rxjs';
-import type { Codec } from '@pezkuwi/types/types';
-import type { DecorateFn, DecorateMethodOptions, ObsInnerType, StorageEntryPromiseOverloads } from '../types/index.js';
-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 declare function promiseTracker<T>(resolve: (value: T) => void, reject: (value: Error) => void): Tracker<T>;
-/**
- * @description Decorate method for ApiPromise, where the results are converted to the Promise equivalent
- */
-export declare function toPromiseMethod<M extends DecorateFn<CodecReturnType<M>>>(method: M, options?: DecorateMethodOptions): StorageEntryPromiseOverloads;
-export {};

package/build/cjs/promise/decorateMethod.js

@@ -1,75 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.promiseTracker = promiseTracker;
-exports.toPromiseMethod = toPromiseMethod;
-const rxjs_1 = require("rxjs");
-const util_1 = require("@pezkuwi/util");
-function promiseTracker(resolve, reject) {
-    let isCompleted = false;
-    return {
-        reject: (error) => {
-            if (!isCompleted) {
-                isCompleted = true;
-                reject(error);
-            }
-            return rxjs_1.EMPTY;
-        },
-        resolve: (value) => {
-            if (!isCompleted) {
-                isCompleted = true;
-                resolve(value);
-            }
-        }
-    };
-}
-function extractArgs(args, needsCallback) {
-    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 && (0, util_1.isFunction)(args[args.length - 1]))
-        ? actualArgs.pop()
-        : undefined;
-    // When we need a subscription, ensure that a valid callback is actually passed
-    if (needsCallback && !(0, util_1.isFunction)(callback)) {
-        throw new Error('Expected a callback to be passed with subscriptions');
-    }
-    return [actualArgs, callback];
-}
-function decorateCall(method, args) {
-    return new Promise((resolve, reject) => {
-        // 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 = method(...args)
-            .pipe((0, rxjs_1.catchError)((error) => tracker.reject(error)))
-            .subscribe((result) => {
-            tracker.resolve(result);
-            (0, util_1.nextTick)(() => subscription.unsubscribe());
-        });
-    });
-}
-function decorateSubscribe(method, args, resultCb) {
-    return new Promise((resolve, reject) => {
-        // 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 = method(...args)
-            .pipe((0, rxjs_1.catchError)((error) => tracker.reject(error)), (0, rxjs_1.tap)(() => tracker.resolve(() => subscription.unsubscribe())))
-            .subscribe((result) => {
-            // queue result (back of queue to clear current)
-            (0, util_1.nextTick)(() => resultCb(result));
-        });
-    });
-}
-/**
- * @description Decorate method for ApiPromise, where the results are converted to the Promise equivalent
- */
-function toPromiseMethod(method, options) {
-    const needsCallback = !!(options?.methodName && options.methodName.includes('subscribe'));
-    return function (...args) {
-        const [actualArgs, resultCb] = extractArgs(args, needsCallback);
-        return resultCb
-            ? decorateSubscribe(method, actualArgs, resultCb)
-            : decorateCall(options?.overrideNoSub || method, actualArgs);
-    };
-}

package/build/cjs/promise/index.d.ts

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

package/build/cjs/promise/index.js

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

package/build/cjs/promise/types.d.ts

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

package/build/cjs/promise/types.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });