References for api augmentation (#4346)

* References for api augmentation * Adjust * Progress... let's see where it leads * It compiles... * Adjust * CC ignore
2021-12-17 12:26:26 +02:00
parent 5062ee602f
commit 664e9e8f26
50 changed files with 720 additions and 129 deletions
@@ -0,0 +1,4 @@
+// Copyright 2017-2021 @polkadot/api-contract authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export { packageInfo } from './packageInfo';
@@ -0,0 +1,9 @@
+// Copyright 2017-2021 @polkadot/api-contract authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { packageInfo as typesInfo } from '@polkadot/types/packageInfo';
+import { detectPackage } from '@polkadot/util';
+
+import { packageInfo } from './packageInfo';
+
+detectPackage(packageInfo, typeof __dirname !== 'undefined' && __dirname, [typesInfo]);
@@ -0,0 +1,6 @@
+// Copyright 2017-2021 @polkadot/api-contract authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import './detectPackage';
+
+export * from './bundle';
@@ -0,0 +1,6 @@
+// Copyright 2017-2021 @polkadot/api-base authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// Auto-generated by @polkadot/dev, do not edit
+
+export const packageInfo = { name: '@polkadot/api-base', version: '6.12.2-11' };
@@ -0,0 +1,67 @@
+// Copyright 2017-2021 @polkadot/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Observable } from 'rxjs';
+import type { AnyFunction, Callback, Codec } from '@polkadot/types/types';
+
+export type Push<T extends readonly unknown[], V> = [...T, V]
+
+export type DropLast<T extends readonly unknown[]> = T extends readonly [...infer U, any?] ? U : [...T];
+
+export type ApiTypes = 'promise' | 'rxjs';
+
+// Returns the inner type of an Observable
+export type ObsInnerType<O extends Observable<any>> = O extends Observable<infer U> ? U : never;
+
+export type VoidFn = () => void;
+
+export type UnsubscribePromise = Promise<VoidFn>;
+
+export type PromiseOrObs<ApiType extends ApiTypes, T> =
+  ApiType extends 'rxjs'
+    ? Observable<T>
+    : Promise<T>;
+
+export type MethodResult<ApiType extends ApiTypes, F extends AnyFunction> =
+  ApiType extends 'rxjs'
+    ? RxResult<F>
+    : PromiseResult<F>;
+
+// Here are the return types of these parts of the api:
+// - api.query.*.*: no exact typings
+// - api.tx.*.*: SubmittableExtrinsic<ApiType extends ApiTypes>
+// - api.derive.*.*: MethodResult<ApiType, F>
+// - api.rpc.*.*: no exact typings (for now, FIXME: should be  MethodResult<ApiType, F>, like in derive)
+
+// These are the types that don't lose type information (used for api.derive.*)
+// Also use these for api.rpc.* https://github.com/polkadot-js/api/issues/1009
+export interface RxResult<F extends AnyFunction> {
+  (...args: Parameters<F>): Observable<ObsInnerType<ReturnType<F>>>;
+  <T>(...args: Parameters<F>): Observable<T>;
+}
+
+export interface PromiseResult<F extends AnyFunction> {
+  (...args: Parameters<F>): Promise<ObsInnerType<ReturnType<F>>>;
+  (...args: Push<Parameters<F>, Callback<ObsInnerType<ReturnType<F>>>>): UnsubscribePromise;
+  <T extends Codec | Codec[]>(...args: Parameters<F>): Promise<T>;
+  <T extends Codec | Codec[]>(...args: Push<Parameters<F>, Callback<T>>): UnsubscribePromise;
+}
+
+// In the abstract `decorateMethod` in Base.ts, we can also pass in some meta-
+// information. This describes it.
+export interface DecorateMethodOptions {
+  methodName?: string;
+  overrideNoSub?: (...args: unknown[]) => Observable<Codec>;
+}
+
+export type DecorateFn <T extends Codec> = (...args: any[]) => Observable<T>;
+
+export interface PaginationOptions<A = unknown> {
+  args: A[];
+  pageSize: number;
+  startKey?: string;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export type DecorateMethod<ApiType extends ApiTypes, T = any> =
+  <M extends (...args: any[]) => Observable<any>>(method: M, options?: DecorateMethodOptions) => T;
@@ -0,0 +1,15 @@
+// Copyright 2017-2021 @polkadot/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { PalletConstantMetadataLatest } from '@polkadot/types/interfaces';
+import type { Codec } from '@polkadot/types/types';
+import type { ApiTypes } from './base';
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export interface AugmentedConst<ApiType extends ApiTypes> {
+  meta: PalletConstantMetadataLatest;
+}
+
+export interface QueryableModuleConsts {
+  [key: string]: Codec;
+}
@@ -0,0 +1,12 @@
+// Copyright 2017-2021 @polkadot/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { IsError } from '@polkadot/types/metadata/decorate/types';
+import type { ApiTypes } from './base';
+
+// 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>;
+}
@@ -0,0 +1,13 @@
+// Copyright 2017-2021 @polkadot/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { IsEvent } from '@polkadot/types/metadata/decorate/types';
+import type { AnyTuple } from '@polkadot/types/types';
+import type { ApiTypes } from './base';
+
+// 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>;
+}
@@ -0,0 +1,10 @@
+// Copyright 2017-2021 @polkadot/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export * from './base';
+export * from './consts';
+export * from './errors';
+export * from './events';
+export * from './rpc';
+export * from './storage';
+export * from './submittable';
@@ -0,0 +1,34 @@
+// Copyright 2017-2021 @polkadot/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Observable } from 'rxjs';
+import type { AnyFunction, Callback, DefinitionRpc } from '@polkadot/types/types';
+
+import { ApiTypes, PromiseResult, Push, RxResult, UnsubscribePromise } from './base';
+
+export type { AugmentedRpc } from '@polkadot/rpc-core/types';
+
+export interface RxRpcResult<F extends AnyFunction> extends RxResult<F> {
+  raw <T> (...args: Parameters<F>): Observable<T>;
+  meta: DefinitionRpc;
+}
+
+export interface PromiseRpcResult<F extends AnyFunction> extends PromiseResult<F> {
+  raw <T> (...args: Parameters<F>): Promise<T>;
+  raw <T> (...args: Push<Parameters<F>, Callback<T>>): UnsubscribePromise;
+  meta: DefinitionRpc;
+}
+
+export type RpcMethodResult<ApiType extends ApiTypes, F extends AnyFunction> = ApiType extends 'rxjs'
+  ? RxRpcResult<F>
+  : PromiseRpcResult<F>;
+
+export type DecoratedRpcSection<ApiType extends ApiTypes, Section> = {
+  [M in keyof Section]: Section[M] extends AnyFunction
+    ? RpcMethodResult<ApiType, Section[M]>
+    : never
+}
+
+export type DecoratedRpc<ApiType extends ApiTypes, AllSections> = {
+  [S in keyof AllSections]: DecoratedRpcSection<ApiType, AllSections[S]>
+}
@@ -0,0 +1,123 @@
+// Copyright 2017-2021 @polkadot/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Observable } from 'rxjs';
+import type { StorageKey, u64 } from '@polkadot/types';
+import type { Hash } from '@polkadot/types/interfaces';
+import type { StorageEntry } from '@polkadot/types/primitive/types';
+import type { AnyFunction, AnyTuple, Callback, Codec, IStorageKey } from '@polkadot/types/types';
+import type { ApiTypes, DropLast, MethodResult, ObsInnerType, PaginationOptions, PromiseOrObs, UnsubscribePromise } from './base';
+
+type AsCodec<R extends Codec | any> = R extends Codec
+  ? R
+  : Codec;
+
+type ReturnCodec<F extends AnyFunction> = AsCodec<ObsInnerType<ReturnType<F>>>;
+
+interface StorageEntryObservableMulti<R extends Codec = Codec> {
+  <T extends Codec = R>(args: (unknown[] | unknown)[]): Observable<T[]>;
+}
+
+interface StorageEntryPromiseMulti<R extends Codec = Codec> {
+  <T extends Codec = R>(args: (unknown[] | unknown)[]): Promise<T[]>;
+  <T extends Codec = R>(args: (unknown[] | unknown)[], callback: Callback<T[]>): UnsubscribePromise;
+}
+
+export interface StorageEntryPromiseOverloads {
+  (arg1?: unknown, arg2?: unknown, arg3?: unknown): Promise<Codec>;
+  <T extends Codec>(arg1?: unknown, arg2?: unknown, arg3?: unknown): Promise<T>;
+  <T extends Codec>(callback: Callback<T>): UnsubscribePromise;
+  <T extends Codec>(arg: unknown, callback: Callback<T>): UnsubscribePromise;
+  <T extends Codec>(arg1: unknown, arg2: unknown, callback: Callback<T>): UnsubscribePromise;
+  <T extends Codec>(arg1: unknown, arg2: unknown, arg3: unknown, callback: Callback<T>): UnsubscribePromise;
+}
+
+export interface StorageEntryPromiseOverloadsAt {
+  (arg1?: unknown, arg2?: unknown, arg3?: unknown): Promise<Codec>;
+  <T extends Codec>(arg1?: unknown, arg2?: unknown, arg3?: unknown): Promise<T>;
+}
+
+// This is the most generic typings we can have for a storage entry function
+export type GenericStorageEntryFunction = (...args: unknown[]) => Observable<Codec>
+
+export type QueryableStorageEntry<ApiType extends ApiTypes, A extends AnyTuple = AnyTuple> =
+  ApiType extends 'rxjs'
+    ? AugmentedQuery<'rxjs', GenericStorageEntryFunction, A>
+    : AugmentedQuery<'promise', GenericStorageEntryFunction, A> & StorageEntryPromiseOverloads;
+
+export type QueryableStorageEntryAt<ApiType extends ApiTypes, A extends AnyTuple = AnyTuple> =
+  ApiType extends 'rxjs'
+    ? AugmentedQueryAt<'rxjs', GenericStorageEntryFunction, A>
+    : AugmentedQueryAt<'promise', GenericStorageEntryFunction, A> & StorageEntryPromiseOverloadsAt;
+
+export interface StorageEntryBase<ApiType extends ApiTypes, F extends AnyFunction, A extends AnyTuple = AnyTuple> extends StorageEntryBaseAt<ApiType, F, A> {
+  /**
+   * @deprecated Use api.at(<blockHash>)
+   */
+  at: <T extends Codec | any = ReturnCodec<F>>(hash: Hash | Uint8Array | string, ...args: Parameters<F>) => PromiseOrObs<ApiType, T>;
+  creator: StorageEntry;
+  /**
+   * @deprecated Use api.at(<blockHash>)
+   */
+  entriesAt: <T extends Codec | any = ReturnCodec<F>, K extends AnyTuple = A>(hash: Hash | Uint8Array | string, ...args: DropLast<Parameters<F>>) => PromiseOrObs<ApiType, [StorageKey<K>, T][]>;
+  entriesPaged: <T extends Codec | any = ReturnCodec<F>, K extends AnyTuple = A>(opts: PaginationOptions<Parameters<F>[0]>) => PromiseOrObs<ApiType, [StorageKey<K>, T][]>;
+  /**
+   * @deprecated Use api.at(<blockHash>)
+   */
+  keysAt: <K extends AnyTuple = A> (hash: Hash | Uint8Array | string, ...args: DropLast<Parameters<F>>) => PromiseOrObs<ApiType, StorageKey<K>[]>;
+  keysPaged: <K extends AnyTuple = A> (opts: PaginationOptions<Parameters<F>[0]>) => PromiseOrObs<ApiType, StorageKey<K>[]>;
+  /**
+   * @deprecated The underlying RPC this been marked unsafe and is generally not exposed
+   */
+  range: <T extends Codec | any = ReturnCodec<F>>([from, to]: [Hash | Uint8Array | string, Hash | Uint8Array | string | undefined] | [Hash | Uint8Array | string], ...args: Parameters<F>) => PromiseOrObs<ApiType, [Hash, T][]>;
+  /**
+   * @deprecated Use api.at(<blockHash>)
+   */
+  sizeAt: (hash: Hash | Uint8Array | string, ...args: Parameters<F>) => PromiseOrObs<ApiType, u64>;
+  multi: ApiType extends 'rxjs'
+    ? StorageEntryObservableMulti<ReturnCodec<F>>
+    : StorageEntryPromiseMulti<ReturnCodec<F>>;
+}
+
+export interface StorageEntryBaseAt<ApiType extends ApiTypes, F extends AnyFunction, A extends AnyTuple = AnyTuple> {
+  entries: <T extends Codec | any = ReturnCodec<F>, K extends AnyTuple = A>(...args: DropLast<Parameters<F>>) => PromiseOrObs<ApiType, [StorageKey<K>, T][]>;
+  hash: (...args: Parameters<F>) => PromiseOrObs<ApiType, Hash>;
+  is: (key: IStorageKey<AnyTuple>) => key is IStorageKey<A>;
+  key: (...args: Parameters<F>) => string;
+  keyPrefix: (...args: DropLast<Parameters<F>>) => string;
+  keys: <K extends AnyTuple = A> (...args: DropLast<Parameters<F>>) => PromiseOrObs<ApiType, StorageKey<K>[]>;
+  size: (...args: Parameters<F>) => PromiseOrObs<ApiType, u64>;
+}
+
+export interface QueryableModuleStorage<ApiType extends ApiTypes> {
+  [index: string]: QueryableStorageEntry<ApiType, AnyTuple>;
+}
+
+export interface QueryableModuleStorageAt<ApiType extends ApiTypes> {
+  [index: string]: QueryableStorageEntryAt<ApiType, AnyTuple>;
+}
+
+export type QueryableStorageMultiArg<ApiType extends ApiTypes> =
+  QueryableStorageEntry<ApiType> |
+  [QueryableStorageEntry<ApiType>, ...unknown[]];
+
+export interface QueryableStorageMultiBase<ApiType extends ApiTypes> {
+  <T extends Codec[]>(calls: QueryableStorageMultiArg<ApiType>[]): Observable<T>;
+}
+
+export interface QueryableStorageMultiPromise<ApiType extends ApiTypes> {
+  <T extends Codec[]>(calls: QueryableStorageMultiArg<ApiType>[], callback: Callback<T>): UnsubscribePromise;
+  <T extends Codec[]>(calls: QueryableStorageMultiArg<ApiType>[]): Promise<T>;
+}
+
+export type QueryableStorageMulti<ApiType extends ApiTypes> =
+  ApiType extends 'rxjs'
+    ? QueryableStorageMultiBase<ApiType>
+    : QueryableStorageMultiPromise<ApiType>;
+
+export type AugmentedQuery<ApiType extends ApiTypes, F extends AnyFunction, A extends AnyTuple = AnyTuple> = MethodResult<ApiType, F> & StorageEntryBase<ApiType, F, A>;
+
+export type AugmentedQueryAt<ApiType extends ApiTypes, F extends AnyFunction, A extends AnyTuple = AnyTuple> = MethodResult<ApiType, F> & StorageEntryBaseAt<ApiType, F, A>;
+
+// backwards compatibility-only
+export type AugmentedQueryDoubleMap<ApiType extends ApiTypes, F extends AnyFunction, A extends AnyTuple = AnyTuple> = AugmentedQuery<ApiType, F, A>;
@@ -0,0 +1,82 @@
+// Copyright 2017-2021 @polkadot/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Observable } from 'rxjs';
+import type { AccountId, Address, ApplyExtrinsicResult, DispatchError, DispatchInfo, EventRecord, Extrinsic, ExtrinsicStatus, Hash, RuntimeDispatchInfo } from '@polkadot/types/interfaces';
+import type { AnyFunction, AnyNumber, AnyTuple, Callback, CallBase, Codec, IExtrinsicEra, IKeyringPair, ISubmittableResult, Signer } from '@polkadot/types/types';
+import type { ApiTypes, PromiseOrObs } from './base';
+
+export type AddressOrPair = IKeyringPair | string | AccountId | Address;
+
+export type AugmentedSubmittable<T extends AnyFunction, A extends AnyTuple = AnyTuple> = T & CallBase<A>;
+
+export interface SignerOptions {
+  blockHash: Uint8Array | string;
+  era?: IExtrinsicEra | number;
+  nonce: AnyNumber | Codec;
+  signer?: Signer;
+  tip?: AnyNumber;
+  assetId?: AnyNumber;
+}
+
+export type SubmittableDryRunResult<ApiType extends ApiTypes> =
+  ApiType extends 'rxjs'
+    ? Observable<ApplyExtrinsicResult>
+    : Promise<ApplyExtrinsicResult>;
+
+export interface SubmittableExtrinsicFunction<ApiType extends ApiTypes, A extends AnyTuple = AnyTuple> extends CallBase<A> {
+  (...params: any[]): SubmittableExtrinsic<ApiType>;
+}
+
+export interface SubmittableModuleExtrinsics<ApiType extends ApiTypes> {
+  // only with is<Type> augmentation
+  [index: string]: SubmittableExtrinsicFunction<ApiType>; // | AugmentedIsSubmittable<ApiType, AnyTuple>;
+}
+
+export type SubmittablePaymentResult<ApiType extends ApiTypes> =
+  ApiType extends 'rxjs'
+    ? Observable<RuntimeDispatchInfo>
+    : Promise<RuntimeDispatchInfo>;
+
+export type SubmittableResultResult<ApiType extends ApiTypes, R extends ISubmittableResult = ISubmittableResult> =
+  ApiType extends 'rxjs'
+    ? Observable<R>
+    : Promise<Hash>;
+
+export type SubmittableResultSubscription<ApiType extends ApiTypes, R extends ISubmittableResult = ISubmittableResult> =
+  ApiType extends 'rxjs'
+    ? Observable<R>
+    : Promise<() => void>;
+
+export interface SubmittableResultValue {
+  dispatchError?: DispatchError;
+  dispatchInfo?: DispatchInfo;
+  events?: EventRecord[];
+  internalError?: Error;
+  status: ExtrinsicStatus;
+}
+
+export interface SubmittableExtrinsic<ApiType extends ApiTypes, R extends ISubmittableResult = ISubmittableResult> extends Extrinsic {
+  dryRun (account: AddressOrPair, options?: Partial<SignerOptions>): SubmittableDryRunResult<ApiType>;
+
+  paymentInfo (account: AddressOrPair, options?: Partial<SignerOptions>): SubmittablePaymentResult<ApiType>;
+
+  send (): SubmittableResultResult<ApiType>;
+
+  send (statusCb: Callback<R>): SubmittableResultSubscription<ApiType, R>;
+
+  /**
+   * @deprecated
+   */
+  sign (account: IKeyringPair, _options?: Partial<SignerOptions>): this;
+
+  signAsync (account: AddressOrPair, _options?: Partial<SignerOptions>): PromiseOrObs<ApiType, this>;
+
+  signAndSend (account: AddressOrPair, options?: Partial<SignerOptions>): SubmittableResultResult<ApiType, R>;
+
+  signAndSend (account: AddressOrPair, statusCb: Callback<R>): SubmittableResultSubscription<ApiType>;
+
+  signAndSend (account: AddressOrPair, options: Partial<SignerOptions>, statusCb?: Callback<R>): SubmittableResultSubscription<ApiType, R>;
+
+  withResultTransform (transform: (input: ISubmittableResult) => ISubmittableResult): this;
+}