Add api.{errors, events, query, tx}.<method>.<section>.is(...) (#2984)

* api.{event, error}.<section>.is<Type>

* Full generation, with checkTypes

* .is

* Extrinsic with arg type definition

* decorate is

* Call is

* Remove hasOrigin

* Renames

* Query is

* Fix extrinsic is

* Backwards compatibility for generated types

* event with optional AnyTuple

* Cleanups

* Cleanups

* Adjust

* Cleanup

Author: jacogr

packages/api/src/augment/errors.ts

@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import './consts';
+import './errors';
+import './events';
 import './query';
 import './rpc';
 import './tx';

packages/api/src/augment/events.ts

@@ -6,9 +6,9 @@ import type { RpcInterface } from '@polkadot/rpc-core/types';
 import type { Option, Raw, StorageKey, Text, u64 } from '@polkadot/types';
 import type { Call, Hash, RuntimeVersion } from '@polkadot/types/interfaces';
 import type { StorageEntry } from '@polkadot/types/primitive/types';
-import type { AnyFunction, CallFunction, Codec, CodecArg as Arg, DefinitionRpc, DefinitionRpcSub, InterfaceTypes, Registry, RegistryTypes } from '@polkadot/types/types';
+import type { AnyFunction, AnyTuple, CallFunction, Codec, CodecArg as Arg, DefinitionRpc, DefinitionRpcSub, IMethod, InterfaceTypes, IStorageKey, Registry, RegistryTypes } from '@polkadot/types/types';
 import type { SubmittableExtrinsic } from '../submittable/types';
-import type { ApiInterfaceRx, ApiOptions, ApiTypes, DecoratedRpc, DecoratedRpcSection, DecorateMethod, PaginationOptions, QueryableConsts, QueryableModuleStorage, QueryableStorage, QueryableStorageEntry, QueryableStorageMulti, QueryableStorageMultiArg, SubmittableExtrinsicFunction, SubmittableExtrinsics, SubmittableModuleExtrinsics } from '../types';
+import type { ApiInterfaceRx, ApiOptions, ApiTypes, DecoratedErrors, DecoratedEvents, DecoratedRpc, DecoratedRpcSection, DecorateMethod, PaginationOptions, QueryableConsts, QueryableModuleStorage, QueryableStorage, QueryableStorageEntry, QueryableStorageMulti, QueryableStorageMultiArg, SubmittableExtrinsicFunction, SubmittableExtrinsics, SubmittableModuleExtrinsics } from '../types';
 
 import BN from 'bn.js';
 
@@ -57,6 +57,10 @@ export abstract class Decorate<ApiType extends ApiTypes> extends Events {
 
   protected _derive?: ReturnType<Decorate<ApiType>['_decorateDerive']>;
 
+  protected _errors: DecoratedErrors<ApiType> = {} as DecoratedErrors<ApiType>;
+
+  protected _events: DecoratedEvents<ApiType> = {} as DecoratedEvents<ApiType>;
+
   protected _extrinsics?: SubmittableExtrinsics<ApiType>;
 
   protected _extrinsicType: number = EXTRINSIC_DEFAULT_VERSION;
@@ -195,6 +199,8 @@ export abstract class Decorate<ApiType extends ApiTypes> extends Events {
     // this API
     augmentObject('query', this._decorateStorage(decoratedMeta, this._decorateMethod), this._query, fromEmpty);
     augmentObject('consts', decoratedMeta.consts, this._consts, fromEmpty);
+    augmentObject('errors', decoratedMeta.errors, this._errors, fromEmpty);
+    augmentObject('events', decoratedMeta.events, this._events, fromEmpty);
 
     // rx
     augmentObject(null, this._decorateStorage(decoratedMeta, this._rxDecorateMethod), this._rx.query, fromEmpty);
@@ -338,6 +344,10 @@ export abstract class Decorate<ApiType extends ApiTypes> extends Events {
     const decorated = (...params: Arg[]): SubmittableExtrinsic<ApiType> =>
       creator(method(...params));
 
+    // pass through the `.is`
+    decorated.is = (other: IMethod<AnyTuple>) =>
+      method.is(other);
+
     // eslint-disable-next-line @typescript-eslint/no-unsafe-return
     return this._decorateFunctionMeta(method as any, decorated as any) as unknown as SubmittableExtrinsicFunction<ApiType>;
   }
@@ -371,6 +381,9 @@ export abstract class Decorate<ApiType extends ApiTypes> extends Events {
     decorated.hash = decorateMethod((arg1?: Arg, arg2?: Arg): Observable<Hash> =>
       this._rpcCore.state.getStorageHash(getArgs(arg1, arg2)));
 
+    decorated.is = <A extends AnyTuple> (key: IStorageKey<AnyTuple>): key is IStorageKey<A> =>
+      key.section === creator.section && key.method === creator.method;
+
     decorated.key = (arg1?: Arg, arg2?: Arg): string =>
       u8aToHex(compactStripLength(creator(creator.meta.type.isDoubleMap ? [arg1, arg2] : arg1))[1]);
 

packages/api/src/augment/index.ts

@@ -5,7 +5,7 @@ import type { Metadata } from '@polkadot/metadata';
 import type { RpcInterface } from '@polkadot/rpc-core/types';
 import type { Text } from '@polkadot/types';
 import type { Hash, RuntimeVersion } from '@polkadot/types/interfaces';
-import type { ApiInterfaceRx, ApiTypes, DecoratedRpc, QueryableConsts, QueryableStorage, QueryableStorageMulti, SubmittableExtrinsics } from '../types';
+import type { ApiInterfaceRx, ApiTypes, DecoratedErrors, DecoratedEvents, DecoratedRpc, QueryableConsts, QueryableStorage, QueryableStorageMulti, SubmittableExtrinsics } from '../types';
 
 import { assertReturn } from '@polkadot/util';
 
@@ -54,6 +54,20 @@ export abstract class Getters<ApiType extends ApiTypes> extends Init<ApiType> {
     return assertResult(this._derive);
   }
 
+  /**
+   * @description Errors from metadata
+   */
+  public get errors (): DecoratedErrors<ApiType> {
+    return assertResult(this._errors);
+  }
+
+  /**
+   * @description Events from metadata
+   */
+  public get events (): DecoratedEvents<ApiType> {
+    return assertResult(this._events);
+  }
+
   /**
    * @description  Returns the version of extrinsics in-use on this chain
    */

packages/api/src/augment/query.ts

@@ -3,8 +3,9 @@
 
 // Simple non-runnable checks to test type definitions in the editor itself
 
-import type { AccountId, Balance, Header, Index } from '@polkadot/types/interfaces';
-import type { IExtrinsic, IMethod } from '@polkadot/types/types';
+import type { StorageKey } from '@polkadot/types';
+import type { AccountId, Balance, DispatchError, EventRecord, Header, Index } from '@polkadot/types/interfaces';
+import type { AnyTuple, IExtrinsic, IMethod } from '@polkadot/types/types';
 
 import { ApiPromise } from '@polkadot/api';
 import { HeaderExtended } from '@polkadot/api-derive';
@@ -34,6 +35,39 @@ async function derive (api: ApiPromise): Promise<void> {
   console.log('fees', fees);
 }
 
+function errors (api: ApiPromise): void {
+  const someError = {} as DispatchError;
+
+  // existing
+  console.log(api.errors.vesting.AmountLow.is(someError));
+
+  // non-existing error, existing module
+  console.log(api.errors.vesting.Something.is(someError));
+
+  // something random
+  console.log(api.errors.something.Random.is(someError));
+}
+
+function events (api: ApiPromise): void {
+  const eventRecord = {} as EventRecord;
+
+  // existing
+  if (api.events.balances.Transfer.is(eventRecord)) {
+    // the types are correctly expanded
+    const [from, to, amount] = eventRecord.event.data;
+
+    console.log(from.toHuman(), to.toHuman(), amount.toBn());
+  }
+
+  // something random
+  if (api.events.something.Random.is(eventRecord)) {
+    // the types are just codec
+    const [a, b] = eventRecord.event.data;
+
+    console.log(a.toHuman(), b.toHuman());
+  }
+}
+
 async function query (api: ApiPromise, pairs: TestKeyringMap): Promise<void> {
   const intentions = await api.query.staking.bonded();
 
@@ -102,6 +136,16 @@ async function queryExtra (api: ApiPromise, pairs: TestKeyringMap): Promise<void
   const entries = await api.query.system.events.range(['0x12345', '0x7890']);
 
   console.log(`Received ${entries.length} entries, ${entries.map(([hash, events]) => `${hash.toHex()}: ${events.length} events`).join(', ')}`);
+
+  // 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 rpc (api: ApiPromise): Promise<void> {
@@ -143,7 +187,7 @@ async function tx (api: ApiPromise, pairs: TestKeyringMap): Promise<void> {
   // transfer, also allows for BigInt inputs here
   const transfer = api.tx.balances.transfer(pairs.bob.address, 123456789n);
 
-  console.log('transfer casted', transfer as IMethod, transfer as IExtrinsic);
+  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());
@@ -179,6 +223,14 @@ async function tx (api: ApiPromise, pairs: TestKeyringMap): Promise<void> {
 
   // it handles enum inputs correctly
   await api.tx.democracy.proxyVote(123, { Split: { nay: 456, yay: 123 } }).signAndSend(pairs.alice);
+
+  // is
+  if (api.tx.balances.transfer.is(second)) {
+    const [recipientId, balance] = second.args;
+
+    // should be LookupSource & Balance types
+    console.log(recipientId.toHuman(), balance.toNumber());
+  }
 }
 
 async function main (): Promise<void> {
@@ -189,6 +241,8 @@ async function main (): Promise<void> {
   Promise.all([
     consts(api),
     derive(api),
+    errors(api),
+    events(api),
     query(api, pairs),
     queryExtra(api, pairs),
     rpc(api),

packages/api/src/augment/tx.ts

@@ -0,0 +1,16 @@
+// Copyright 2017-2020 @polkadot/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { IsError } from '@polkadot/metadata/decorate/types';
+import type { ApiTypes } from './base';
+
+// In errors we don't need the ApiType, however add it for consistency
+// eslint-disable-next-line @typescript-eslint/no-empty-interface,@typescript-eslint/no-unused-vars
+export interface AugmentedErrors<ApiType extends ApiTypes> { }
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export type AugmentedError<ApiType extends ApiTypes> = IsError;
+
+export interface ModuleErrors<ApiType extends ApiTypes> {
+  [key: string]: AugmentedError<ApiType>;
+}

packages/api/src/base/Decorate.ts

@@ -0,0 +1,17 @@
+// Copyright 2017-2020 @polkadot/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { IsEvent } from '@polkadot/metadata/decorate/types';
+import type { AnyTuple } from '@polkadot/types/types';
+import type { ApiTypes } from './base';
+
+// In events we don't need the ApiType, however add it for consistency
+// eslint-disable-next-line @typescript-eslint/no-empty-interface,@typescript-eslint/no-unused-vars
+export interface AugmentedEvents<ApiType extends ApiTypes> { }
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export type AugmentedEvent<ApiType extends ApiTypes, T extends AnyTuple = AnyTuple> = IsEvent<T>;
+
+export interface ModuleEvents<ApiType extends ApiTypes> {
+  [key: string]: AugmentedEvent<ApiType, AnyTuple>;
+}