@pezkuwi/api 16.5.5 → 16.5.8

package/build-deno/checkTypes.manual.ts

@@ -0,0 +1,320 @@
+
+
+import 'https://deno.land/x/pezkuwi/api-augment/mod.ts';
+
+import type { HeaderExtended } from 'https://deno.land/x/pezkuwi/api-derive/types.ts';
+import type { TestKeyringMapBizinikiwi } from 'https://deno.land/x/pezkuwi/keyring/testingPairs.ts';
+import type { StorageKey } from 'https://deno.land/x/pezkuwi/types/mod.ts';
+import type { AccountId, Balance, DispatchErrorModule, Event, Header, Index } from 'https://deno.land/x/pezkuwi/types/interfaces/index.ts';
+import type { PezframeSystemAccountInfo } from 'https://deno.land/x/pezkuwi/types/lookup.ts';
+import type { AnyTuple, IExtrinsic, IMethod } from 'https://deno.land/x/pezkuwi/types/types/index.ts';
+import type { SubmittableResult } from './index.ts';
+
+import { ApiPromise } from 'https://deno.land/x/pezkuwi/api/mod.ts';
+import { createTestPairs } from 'https://deno.land/x/pezkuwi/keyring/testingPairs.ts';
+import { createTypeUnsafe, TypeRegistry } from 'https://deno.land/x/pezkuwi/types/create/index.ts';
+
+const registry = new TypeRegistry();
+
+async function calls (api: ApiPromise): Promise<void> {
+  // it allows defaults
+  const testSetId = await api.call.grandpaApi.currentSetId();
+
+  // it allows type overrides (generally shouldn't be used, but available)
+  const testSetIdO = await api.call.grandpaApi.currentSetId<AccountId>();
+
+  // it allows actual params
+  const nonce = await api.call.accountNonceApi.accountNonce('5Test');
+
+  console.log(testSetId.toNumber(), testSetIdO.isAscii, nonce.toNumber());
+}
+
+function consts (api: ApiPromise): void {
+  // constants has actual value & metadata
+  console.log(
+    api.consts['notIn']['augmentation'],
+    api.consts.balances.existentialDeposit.toNumber(),
+    api.consts.balances.existentialDeposit.meta.docs.map((s) => s.toString()).join(''),
+    api.consts.system.blockWeights.maxBlock.refTime.toNumber()
+  );
+}
+
+async function derive (api: ApiPromise): Promise<void> {
+  await api.derive.chain.subscribeNewHeads((header: HeaderExtended): void => {
+    console.log('current author:', header.author);
+  });
+
+  const info = await api.derive.balances.account('0x1234');
+
+  console.log('info', info);
+}
+
+function errors (api: ApiPromise): void {
+  const someError = {} as DispatchErrorModule;
+
+  // existing
+  console.log(api.errors.vesting.AmountLow.is(someError));
+
+  // non-existing error, existing module
+  console.log(api.errors.vesting['NonAugmented'].is(someError));
+
+  // something random
+  console.log(api.errors['thisIsNot']['Augmented'].is(someError));
+}
+
+function events (api: ApiPromise): void {
+  const event = {} as Event;
+
+  // existing
+  if (api.events.balances.Transfer.is(event)) {
+    // the types are correctly expanded
+    const [afrom, ato, aamount] = event.data;
+
+    console.log(
+      afrom.toHuman(),
+      ato.toHuman(),
+      aamount.toBn()
+    );
+
+    // the types have getters
+    const { amount, from, to } = event.data;
+
+    console.log(
+      from.toHuman(),
+      to.toHuman(),
+      amount.toBn()
+    );
+  }
+
+  // something with only tuple data
+  if (api.events.staking.Bonded.is(event)) {
+    const [account, amount] = event.data;
+
+    console.log(account.toHuman(), amount.toBn());
+  }
+
+  // something random, just codec[]
+  if (api.events['not']['Augmented'].is(event)) {
+    const [a, b] = event.data;
+
+    console.log(a.toHuman(), b.toHuman());
+  }
+}
+
+async function query (api: ApiPromise, pairs: TestKeyringMapBizinikiwi): Promise<void> {
+  const intentions = await api.query.staking.bonded();
+
+  console.log('intentions:', intentions);
+
+  // api.query.*.* is well-typed
+  const bar = await api.query['notIn']['augmentation'](); // bar is Codec (unknown module)
+  const bal = await api.query.balances.totalIssuance(); // bal is Balance
+  const bal2 = await api.query.balances.totalIssuance('WRONG_ARG'); // bal2 is Codec (wrong args)
+  const override = await api.query.balances.totalIssuance<Header>(); // override is still available
+
+  // eslint-disable-next-line deprecation/deprecation
+  const oldBal = await api.query.balances.totalIssuance.at('abcd');
+
+  // For older queries we can cast with `<Balance>` (newer chain have multi typed)
+  const multia = await api.query.balances['freeBalance'].multi<Balance>([pairs.alice.address, pairs.bob.address]);
+  const multib = await api.query.system.account.multi([pairs.alice.address, pairs.bob.address]);
+
+  await api.query.system.account(pairs.alice.address);
+  await api.query.system.account<PezframeSystemAccountInfo>(pairs.alice.address);
+
+  console.log('query types:', bar, bal, bal2, override, oldBal, multia, multib);
+}
+
+async function queryExtra (api: ApiPromise): Promise<void> {
+  // events destructing
+  await api.query.system.events((records): void => {
+    records.forEach(({ event, phase }): void => {
+      if (phase.isApplyExtrinsic) {
+        // Dunno... this should work
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        const [accountId, value]: [AccountId, Balance] = event.data;
+
+        console.log(`${accountId.toString()} has ${value.toHuman()}`);
+      }
+    });
+  });
+
+  // at queries
+  // eslint-disable-next-line deprecation/deprecation
+  const events = await api.query.system.events.at('0x12345');
+
+  console.log(`Received ${events.length} events:`);
+
+  // check entries()
+  await api.query.system.account.entries(); // should not take a param
+  await api.query.staking.nominatorSlashInEra.entries(123); // should take a param
+
+  // nmap with keys
+  await api.query.assets.approvals.keys(123, 'blah');
+  await api.query.assets.account.keys(123);
+  await api.query.assets.account.entries(123);
+  await api.query.assets['notAugmented'].keys();
+
+  // is
+  const key = {} as StorageKey;
+
+  if (api.query.balances.account.is(key)) {
+    const [accountId] = key.args;
+
+    // should be AccountId type
+    console.log(accountId.toHuman());
+  }
+}
+
+async function queryMulti (api: ApiPromise, pairs: TestKeyringMapBizinikiwi): Promise<void> {
+  // check multi for unsub
+  const multiUnsub = await api.queryMulti([
+    [api.query.staking.validators],
+    [api.query.system.events]
+  ], (values): void => {
+    console.log('values', values);
+
+    multiUnsub();
+  });
+
+  // check multi , Promise result
+  const multiRes = await api.queryMulti([
+    [api.query.system.account, pairs.eve.address],
+    // older chains only
+    [api.query.system['accountNonce'], pairs.eve.address]
+  ]);
+
+  console.log(multiRes);
+
+  // check multi, via at
+  const apiAt = await api.at('0x12345678');
+  const multiResAt = await apiAt.queryMulti([
+    api.query.timestamp.now,
+    [apiAt.query.staking.validators],
+    [apiAt.query.system.account, pairs.eve.address]
+  ]);
+
+  console.log(multiResAt);
+}
+
+async function rpc (api: ApiPromise): Promise<void> {
+  // defaults
+  await api.rpc.chain.subscribeNewHeads((header): void => {
+    console.log('current header #', header.number.toNumber());
+  });
+
+  // with generic params
+  await api.rpc.state.subscribeStorage<[Balance]>(['my_balance_key'], ([balance]): void => {
+    console.log('current balance:', balance.toString());
+  });
+
+  // using json & raw
+  await api.rpc.chain.getBlock.raw('0x123456');
+
+  // using raw subs
+  await api.rpc.chain.subscribeNewHeads.raw((result: Uint8Array): void => {
+    console.log(result);
+  });
+
+  // deprecated methods
+  // eslint-disable-next-line deprecation/deprecation
+  await api.rpc.state.getPairs('123');
+}
+
+function types (api: ApiPromise): void {
+  // check correct types with `createType`
+  const balance = registry.createType('Balance', 2);
+  const gas = registry.createType('Gas', 2);
+  const compact = registry.createType('Compact<u32>', 2);
+  const f32 = registry.createType('f32');
+  const u32 = registry.createType('u32');
+  const raw = registry.createType('Raw');
+  // const random = registry.createType('RandomType', 2); // This one should deliberately show a TS error
+
+  const gasUnsafe = createTypeUnsafe(registry, 'Gas', [2]);
+  const overriddenUnsafe = createTypeUnsafe<Header>(registry, 'Gas', [2]);
+
+  console.log(balance, gas, compact, gasUnsafe, overriddenUnsafe, u32.toNumber(), f32.toNumber(), api.createType('AccountData'), raw.subarray(0, 10));
+}
+
+async function tx (api: ApiPromise, pairs: TestKeyringMapBizinikiwi): Promise<void> {
+  // transfer, also allows for bigint inputs here
+  const transfer = api.tx.balances.transferAllowDeath(pairs.bob.address, BigInt(123456789));
+
+  console.log('transfer casted', transfer as IMethod<AnyTuple>, transfer as IExtrinsic<AnyTuple>);
+
+  // simple "return the hash" variant
+  console.log('hash:', (await transfer.signAndSend(pairs.alice)).toHex());
+
+  // passing options, but waiting for hash
+  const nonce = await api.query.system['accountNonce']<Index>(pairs.alice.address);
+
+  (await api.tx.balances
+    .transferAllowDeath(pairs.bob.address, 12345)
+    .signAndSend(pairs.alice, { nonce })
+  ).toHex();
+
+  // just with the callback
+  await api.tx.balances
+    .transferAllowDeath(pairs.bob.address, 12345)
+    .signAndSend(pairs.alice, ({ status }: SubmittableResult) => console.log(status.type));
+
+  // with options and the callback
+  const nonce2 = await api.query.system['accountNonce'](pairs.alice.address);
+  const unsub2 = await api.tx.balances
+    .transferAllowDeath(pairs.bob.address, 12345)
+    .signAndSend(pairs.alice, { nonce: nonce2 }, ({ status }: SubmittableResult): void => {
+      console.log('transfer status:', status.type);
+
+      unsub2();
+    });
+
+  // it allows for query & then using the submittable
+  const second = api.tx.democracy.second(123);
+
+  await second.signAndSend('123', (result) => console.log(result));
+
+  // it handles enum inputs correctly
+  await api.tx.democracy['proxyVote'](123, { Split: { nay: 456, yay: 123 } }).signAndSend(pairs.alice);
+
+  // is
+  if (api.tx.balances.transferAllowDeath.is(second)) {
+    const [recipientId, balance] = second.args;
+
+    // should be LookupSource & Balance types
+    console.log(recipientId.toHuman(), balance.toNumber());
+  }
+}
+
+async function at (api: ApiPromise): Promise<void> {
+  const apiAt = await api.at('0x1234');
+
+  // get old balances
+  console.log(await apiAt.query.balances['freeBalance']('0x1234'));
+
+  // get some constants
+  console.log(apiAt.consts.balances.existentialDeposit);
+}
+
+async function main (): Promise<void> {
+  const api = await ApiPromise.create();
+  const pairs = createTestPairs();
+
+  await Promise.all([
+    calls(api),
+    consts(api),
+    derive(api),
+    errors(api),
+    events(api),
+    query(api, pairs),
+    queryExtra(api),
+    queryMulti(api, pairs),
+    rpc(api),
+    types(api),
+    tx(api, pairs),
+    at(api)
+  ]);
+}
+
+main().catch(console.error);

package/build-deno/index.ts

@@ -0,0 +1,4 @@
+
+import './packageDetect.ts';
+
+export * from './bundle.ts';

package/build-deno/mod.ts

@@ -0,0 +1,2 @@
+
+export * from './index.ts';

package/build-deno/packageDetect.ts

@@ -0,0 +1,12 @@
+
+
+import { packageInfo as deriveInfo } from 'https://deno.land/x/pezkuwi/api-derive/packageInfo.ts';
+import { packageInfo as coreInfo } from 'https://deno.land/x/pezkuwi/rpc-core/packageInfo.ts';
+import { packageInfo as providerInfo } from 'https://deno.land/x/pezkuwi/rpc-provider/packageInfo.ts';
+import { packageInfo as typesInfo } from 'https://deno.land/x/pezkuwi/types/packageInfo.ts';
+import { packageInfo as knownInfo } from 'https://deno.land/x/pezkuwi/types-known/packageInfo.ts';
+import { detectPackage } from 'https://deno.land/x/pezkuwi/util/mod.ts';
+
+import { packageInfo } from './packageInfo.ts';
+
+detectPackage(packageInfo, null, [coreInfo, deriveInfo, knownInfo, providerInfo, typesInfo]);

package/build-deno/packageInfo.ts

@@ -0,0 +1,3 @@
+
+
+export const packageInfo = { name: '@pezkuwi/api', path: new URL(import.meta.url).pathname, type: 'deno', version: '16.5.8' };

package/build-deno/promise/Api.ts

@@ -0,0 +1,212 @@
+
+import type { ApiOptions, UnsubscribePromise } from '../types/index.ts';
+import type { CombinatorCallback, CombinatorFunction } from './Combinator.ts';
+
+import { noop, objectSpread } from 'https://deno.land/x/pezkuwi/util/mod.ts';
+
+import { ApiBase } from '../base/index.ts';
+import { Combinator } from './Combinator.ts';
+import { promiseTracker, toPromiseMethod } from './decorateMethod.ts';
+
+/**
+ * # @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 'https://deno.land/x/pezkuwi/api/promise/index.ts';
+ *
+ * // 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 'https://deno.land/x/pezkuwi/api/mod.ts';
+ *
+ * // 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 'https://deno.land/x/pezkuwi/api/promise/index.ts';
+ *
+ * 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 class ApiPromise extends ApiBase<'promise'> {
+  #isReadyPromise: Promise<ApiPromise>;
+  #isReadyOrErrorPromise: Promise<ApiPromise>;
+
+  /**
+   * @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 'https://deno.land/x/pezkuwi/api/promise/index.ts';
+   *
+   * new Api().isReady.then((api) => {
+   *   api.rpc.subscribeNewHeads((header) => {
+   *     console.log(`new block #${header.number.toNumber()}`);
+   *   });
+   * });
+   * ```
+   */
+  constructor (options?: ApiOptions) {
+    super(options, 'promise', toPromiseMethod);
+
+    this.#isReadyPromise = new Promise((resolve): void => {
+      super.once('ready', () => resolve(this));
+    });
+
+    this.#isReadyOrErrorPromise = new Promise((resolve, reject): void => {
+      const tracker = promiseTracker(resolve, reject);
+
+      super.once('ready', () => tracker.resolve(this));
+      super.once('error', (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 'https://deno.land/x/pezkuwi/api/promise/index.ts';
+   *
+   * Api.create().then(async (api) => {
+   *   const timestamp = await api.query.timestamp.now();
+   *
+   *   console.log(`lastest block timestamp ${timestamp}`);
+   * });
+   * ```
+   */
+  public static create (options?: ApiOptions): Promise<ApiPromise> {
+    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(noop);
+
+    return instance.isReady;
+  }
+
+  /**
+   * @description Promise that resolves the first time we are connected and loaded
+   */
+  public get isReady (): Promise<ApiPromise> {
+    return this.#isReadyPromise;
+  }
+
+  /**
+   * @description Promise that resolves if we can connect, or reject if there is an error
+   */
+  public get isReadyOrError (): Promise<ApiPromise> {
+    return this.#isReadyOrErrorPromise;
+  }
+
+  /**
+   * @description Returns a clone of this ApiPromise instance (new underlying provider connection)
+   */
+  public clone (): ApiPromise {
+    return new ApiPromise(
+      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
+  public async combineLatest <T extends any[] = any[]> (fns: (CombinatorFunction | [CombinatorFunction, ...any[]])[], callback: CombinatorCallback<T>): UnsubscribePromise {
+    const combinator = new Combinator(fns, callback);
+
+    return (): void => {
+      combinator.unsubscribe();
+    };
+  }
+}

package/build-deno/promise/Combinator.ts

@@ -0,0 +1,89 @@
+
+import type { Callback } from 'https://deno.land/x/pezkuwi/types/types/index.ts';
+import type { UnsubscribePromise } from '../types/index.ts';
+
+import { isFunction, noop } from 'https://deno.land/x/pezkuwi/util/mod.ts';
+
+export type CombinatorCallback <T extends unknown[]> = Callback<T>;
+
+export type CombinatorFunction = (cb: Callback<any>) => UnsubscribePromise;
+
+export class Combinator<T extends unknown[] = unknown[]> {
+  #allHasFired = false;
+  #callback: CombinatorCallback<T>;
+  #fired: boolean[] = [];
+  #fns: CombinatorFunction[] = [];
+  #isActive = true;
+  #results: unknown[] = [];
+  #subscriptions: UnsubscribePromise[] = [];
+
+  constructor (fns: (CombinatorFunction | [CombinatorFunction, ...unknown[]])[], callback: CombinatorCallback<T>) {
+    this.#callback = callback;
+
+    // eslint-disable-next-line @typescript-eslint/no-floating-promises, @typescript-eslint/require-await
+    this.#subscriptions = fns.map(async (input, index): UnsubscribePromise => {
+      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 as Function)(...args, this._createCallback(index));
+    });
+  }
+
+  protected _allHasFired (): boolean {
+    this.#allHasFired ||= this.#fired.filter((hasFired): boolean => !hasFired).length === 0;
+
+    return this.#allHasFired;
+  }
+
+  protected _createCallback (index: number): (value: any) => void {
+    return (value: unknown): void => {
+      this.#fired[index] = true;
+      this.#results[index] = value;
+
+      this._triggerUpdate();
+    };
+  }
+
+  protected _triggerUpdate (): void {
+    if (!this.#isActive || !isFunction(this.#callback) || !this._allHasFired()) {
+      return;
+    }
+
+    try {
+      Promise
+        .resolve(this.#callback(this.#results as T))
+        .catch(noop);
+    } catch {
+      // swallow, we don't want the handler to trip us up
+    }
+  }
+
+  public unsubscribe (): void {
+    if (!this.#isActive) {
+      return;
+    }
+
+    this.#isActive = false;
+
+    Promise
+      .all(this.#subscriptions.map(async (subscription): Promise<void> => {
+        try {
+          const unsubscribe = await subscription;
+
+          if (isFunction(unsubscribe)) {
+            unsubscribe();
+          }
+        } catch {
+          // ignore
+        }
+      })).catch(() => {
+        // ignore, already ignored above, should never throw
+      });
+  }
+}