@algorandfoundation/algokit-client-generator 2.6.0 → 2.6.1-beta.1

package/client/call-client.cjs

@@ -0,0 +1,332 @@
+'use strict';
+
+var algokit = require('@algorandfoundation/algokit-utils');
+var writer = require('../output/writer.cjs');
+var sanitization = require('../util/sanitization.cjs');
+var getCallConfigSummary = require('./helpers/get-call-config-summary.cjs');
+var deployTypes = require('./deploy-types.cjs');
+var callComposer = require('./call-composer.cjs');
+
+function _interopNamespaceDefault(e) {
+    var n = Object.create(null);
+    if (e) {
+        Object.keys(e).forEach(function (k) {
+            if (k !== 'default') {
+                var d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: function () { return e[k]; }
+                });
+            }
+        });
+    }
+    n.default = e;
+    return Object.freeze(n);
+}
+
+var algokit__namespace = /*#__PURE__*/_interopNamespaceDefault(algokit);
+
+function* callClient(ctx) {
+    const { app, name } = ctx;
+    yield* writer.jsDoc(`A client to make calls to the ${app.contract.name} smart contract`);
+    yield `export class ${sanitization.makeSafeTypeIdentifier(app.contract.name)}Client {`;
+    yield writer.IncIndent;
+    yield* writer.jsDoc(`The underlying \`ApplicationClient\` for when you want to have more flexibility`);
+    yield 'public readonly appClient: ApplicationClient';
+    yield writer.NewLine;
+    yield `private readonly sender: SendTransactionFrom | undefined`;
+    yield writer.NewLine;
+    yield* writer.jsDoc({
+        description: `Creates a new instance of \`${sanitization.makeSafeTypeIdentifier(app.contract.name)}Client\``,
+        params: {
+            appDetails: 'appDetails The details to identify the app to deploy',
+            algod: 'An algod client instance',
+        },
+    });
+    yield `constructor(appDetails: AppDetails, private algod: Algodv2) {`;
+    yield writer.IncIndent;
+    yield `this.sender = appDetails.sender`;
+    yield 'this.appClient = algokit.getAppClient({';
+    yield* writer.indent('...appDetails,', 'app: APP_SPEC');
+    yield '}, algod)';
+    yield writer.DecIndent;
+    yield '}';
+    yield writer.NewLine;
+    yield* writer.jsDoc({
+        description: 'Checks for decode errors on the AppCallTransactionResult and maps the return value to the specified generic type',
+        params: {
+            result: 'The AppCallTransactionResult to be mapped',
+            returnValueFormatter: 'An optional delegate to format the return value if required',
+        },
+        returns: 'The smart contract response with an updated return value',
+    });
+    yield* writer.inline(`protected mapReturnValue<TReturn, TResult extends AppCallTransactionResult = AppCallTransactionResult>`, `(result: AppCallTransactionResult, returnValueFormatter?: (value: any) => TReturn): `, `AppCallTransactionResultOfType<TReturn> & TResult {`);
+    yield writer.IncIndent;
+    yield `if(result.return?.decodeError) {`;
+    yield* writer.indent(`throw result.return.decodeError`);
+    yield `}`;
+    yield `const returnValue = result.return?.returnValue !== undefined && returnValueFormatter !== undefined`;
+    yield writer.IncIndent;
+    yield `? returnValueFormatter(result.return.returnValue)`;
+    yield `: result.return?.returnValue as TReturn | undefined`;
+    yield `return { ...result, return: returnValue } as AppCallTransactionResultOfType<TReturn> & TResult`;
+    yield writer.DecIndent;
+    yield writer.DecIndentAndCloseBlock;
+    yield writer.NewLine;
+    yield* writer.jsDoc({
+        description: 'Calls the ABI method with the matching signature using an onCompletion code of NO_OP',
+        params: {
+            typedCallParams: 'An object containing the method signature, args, and any other relevant parameters',
+            returnValueFormatter: 'An optional delegate which when provided will be used to map non-undefined return values to the target type',
+        },
+        returns: 'The result of the smart contract call',
+    });
+    yield `public async call<TSignature extends keyof ${name}['methods']>(typedCallParams: TypedCallParams<TSignature>, returnValueFormatter?: (value: any) => MethodReturn<TSignature>) {`;
+    yield writer.IncIndent;
+    yield `return this.mapReturnValue<MethodReturn<TSignature>>(await this.appClient.call(typedCallParams), returnValueFormatter)`;
+    yield writer.DecIndentAndCloseBlock;
+    yield writer.NewLine;
+    yield* opMethods(ctx);
+    yield* clearState(ctx);
+    yield* noopMethods(ctx);
+    yield* getStateMethods(ctx);
+    yield* callComposer.composeMethod(ctx);
+    yield writer.DecIndentAndCloseBlock;
+}
+function* opMethods(ctx) {
+    const { app, callConfig, name } = ctx;
+    yield* writer.jsDoc({
+        description: `Idempotently deploys the ${app.contract.name} smart contract.`,
+        params: {
+            params: 'The arguments for the contract calls and any additional parameters for the call',
+        },
+        returns: 'The deployment result',
+    });
+    yield `public deploy(params: ${name}DeployArgs & AppClientDeployCoreParams = {}): ReturnType<ApplicationClient['deploy']> {`;
+    yield writer.IncIndent;
+    if (callConfig.createMethods.length)
+        yield `const createArgs = params.createCall?.(${name}CallFactory.create)`;
+    if (callConfig.updateMethods.length)
+        yield `const updateArgs = params.updateCall?.(${name}CallFactory.update)`;
+    if (callConfig.deleteMethods.length)
+        yield `const deleteArgs = params.deleteCall?.(${name}CallFactory.delete)`;
+    yield `return this.appClient.deploy({`;
+    yield writer.IncIndent;
+    yield `...params,`;
+    if (callConfig.updateMethods.length)
+        yield 'updateArgs,';
+    if (callConfig.deleteMethods.length)
+        yield 'deleteArgs,';
+    if (callConfig.createMethods.length) {
+        yield 'createArgs,';
+        yield `createOnCompleteAction: createArgs?.onCompleteAction,`;
+    }
+    yield writer.DecIndent;
+    yield `})`;
+    yield writer.DecIndentAndCloseBlock;
+    yield writer.NewLine;
+    yield* operationMethod(ctx, `Creates a new instance of the ${app.contract.name} smart contract`, callConfig.createMethods, 'create', true);
+    yield* operationMethod(ctx, `Updates an existing instance of the ${app.contract.name} smart contract`, callConfig.updateMethods, 'update', true);
+    yield* operationMethod(ctx, `Deletes an existing instance of the ${app.contract.name} smart contract`, callConfig.deleteMethods, 'delete');
+    yield* operationMethod(ctx, `Opts the user into an existing instance of the ${app.contract.name} smart contract`, callConfig.optInMethods, 'optIn');
+    yield* operationMethod(ctx, `Makes a close out call to an existing instance of the ${app.contract.name} smart contract`, callConfig.closeOutMethods, 'closeOut');
+}
+function* operationMethod({ app, methodSignatureToUniqueName, name }, description, methods, verb, includeCompilation) {
+    let responseTypeGenericParam;
+    switch (verb) {
+        case 'create':
+            responseTypeGenericParam = ', AppCreateCallTransactionResult';
+            break;
+        case 'update':
+            responseTypeGenericParam = ', AppUpdateCallTransactionResult';
+            break;
+        default:
+            responseTypeGenericParam = '';
+            break;
+    }
+    if (methods.length) {
+        yield* writer.jsDoc(`Gets available ${verb} methods`);
+        yield `public get ${verb}() {`;
+        yield writer.IncIndent;
+        yield `const $this = this`;
+        yield `return {`;
+        yield writer.IncIndent;
+        for (const methodSig of methods) {
+            const onComplete = verb === 'create' ? deployTypes.getCreateOnCompleteOptions(methodSig, app) : undefined;
+            if (methodSig === getCallConfigSummary.BARE_CALL) {
+                yield* writer.jsDoc({
+                    description: `${description} using a bare call.`,
+                    params: {
+                        args: `The arguments for the bare call`,
+                    },
+                    returns: `The ${verb} result`,
+                });
+                yield `async bare(args: BareCallArgs & AppClientCallCoreParams ${includeCompilation ? '& AppClientCompilationParams ' : ''}& CoreAppCallArgs${onComplete?.type ? ` & ${onComplete.type}` : ''}${onComplete?.isOptional !== false ? ' = {}' : ''}) {`;
+                yield* writer.indent(`return $this.mapReturnValue<undefined${responseTypeGenericParam}>(await $this.appClient.${verb}(args))`);
+                yield '},';
+            }
+            else {
+                const uniqueName = methodSignatureToUniqueName[methodSig];
+                const method = app.contract.methods.find((m) => algokit__namespace.getABIMethodSignature(m) === methodSig);
+                yield* writer.jsDoc({
+                    description: `${description} using the ${methodSig} ABI method.`,
+                    params: {
+                        args: `The arguments for the smart contract call`,
+                        params: `Any additional parameters for the call`,
+                    },
+                    returns: `The ${verb} result${method?.returns?.desc ? `: ${method.returns.desc}` : ''}`,
+                });
+                yield `async ${sanitization.makeSafeMethodIdentifier(uniqueName)}(args: MethodArgs<'${methodSig}'>, params: AppClientCallCoreParams${includeCompilation ? ' & AppClientCompilationParams' : ''}${onComplete?.type ? ` & ${onComplete.type}` : ''}${onComplete?.isOptional !== false ? ' = {}' : ''}) {`;
+                yield* writer.indent(`return $this.mapReturnValue<MethodReturn<'${methodSig}'>${responseTypeGenericParam}>(await $this.appClient.${verb}(${name}CallFactory.${verb}.${sanitization.makeSafeMethodIdentifier(uniqueName)}(args, params)))`);
+                yield '},';
+            }
+        }
+        yield writer.DecIndentAndCloseBlock;
+        yield writer.DecIndentAndCloseBlock;
+        yield writer.NewLine;
+    }
+}
+function* clearState({ app }) {
+    yield* writer.jsDoc({
+        description: `Makes a clear_state call to an existing instance of the ${app.contract.name} smart contract.`,
+        params: {
+            args: `The arguments for the bare call`,
+        },
+        returns: `The clear_state result`,
+    });
+    yield `public clearState(args: BareCallArgs & AppClientCallCoreParams & CoreAppCallArgs = {}) {`;
+    yield writer.IncIndent;
+    yield `return this.appClient.clearState(args)`;
+    yield writer.DecIndentAndCloseBlock;
+    yield writer.NewLine;
+}
+function* noopMethods({ app, name, callConfig, methodSignatureToUniqueName }) {
+    for (const method of app.contract.methods) {
+        const methodSignature = algokit__namespace.getABIMethodSignature(method);
+        const methodName = sanitization.makeSafeMethodIdentifier(methodSignatureToUniqueName[methodSignature]);
+        // Skip methods which don't support a no_op call config
+        if (!callConfig.callMethods.includes(methodSignature))
+            continue;
+        yield* writer.jsDoc({
+            description: `Calls the ${algokit__namespace.getABIMethodSignature(method)} ABI method.`,
+            abiDescription: method.desc,
+            params: {
+                args: `The arguments for the contract call`,
+                params: `Any additional parameters for the call`,
+            },
+            returns: `The result of the call${method?.returns?.desc ? `: ${method.returns.desc}` : ''}`,
+        });
+        yield `public ${methodName}(args: MethodArgs<'${methodSignature}'>, params: AppClientCallCoreParams & CoreAppCallArgs = {}) {`;
+        yield writer.IncIndent;
+        const outputTypeName = app.hints?.[methodSignature]?.structs?.output?.name;
+        yield `return this.call(${name}CallFactory.${methodName}(args, params)${outputTypeName === undefined ? '' : `, ${sanitization.makeSafeTypeIdentifier(outputTypeName)}`})`;
+        yield writer.DecIndent;
+        yield '}';
+        yield writer.NewLine;
+    }
+}
+function* getStateMethods({ app, name }) {
+    const globalStateValues = app.schema.global?.declared && Object.values(app.schema.global?.declared);
+    const localStateValues = app.schema.local?.declared && Object.values(app.schema.local?.declared);
+    if (globalStateValues?.length || localStateValues?.length) {
+        yield* writer.jsDoc({
+            description: 'Extracts a binary state value out of an AppState dictionary',
+            params: {
+                state: 'The state dictionary containing the state value',
+                key: 'The key of the state value',
+            },
+            returns: 'A BinaryState instance containing the state value, or undefined if the key was not found',
+        });
+        yield `private static getBinaryState(state: AppState, key: string): BinaryState | undefined {`;
+        yield writer.IncIndent;
+        yield `const value = state[key]`;
+        yield `if (!value) return undefined`;
+        yield `if (!('valueRaw' in value))`;
+        yield* writer.indent(`throw new Error(\`Failed to parse state value for \${key}; received an int when expected a byte array\`)`);
+        yield `return {`;
+        yield writer.IncIndent;
+        yield `asString(): string {`;
+        yield* writer.indent(`return value.value`);
+        yield `},`;
+        yield `asByteArray(): Uint8Array {`;
+        yield* writer.indent(`return value.valueRaw`);
+        yield `}`;
+        yield writer.DecIndentAndCloseBlock;
+        yield writer.DecIndentAndCloseBlock;
+        yield writer.NewLine;
+        yield* writer.jsDoc({
+            description: 'Extracts a integer state value out of an AppState dictionary',
+            params: {
+                state: 'The state dictionary containing the state value',
+                key: 'The key of the state value',
+            },
+            returns: 'An IntegerState instance containing the state value, or undefined if the key was not found',
+        });
+        yield `private static getIntegerState(state: AppState, key: string): IntegerState | undefined {`;
+        yield writer.IncIndent;
+        yield `const value = state[key]`;
+        yield `if (!value) return undefined`;
+        yield `if ('valueRaw' in value)`;
+        yield* writer.indent(`throw new Error(\`Failed to parse state value for \${key}; received a byte array when expected a number\`)`);
+        yield `return {`;
+        yield writer.IncIndent;
+        yield `asBigInt() {`;
+        yield* writer.indent(`return typeof value.value === 'bigint' ? value.value : BigInt(value.value)`);
+        yield `},`;
+        yield `asNumber(): number {`;
+        yield* writer.indent(`return typeof value.value === 'bigint' ? Number(value.value) : value.value`);
+        yield `},`;
+        yield writer.DecIndentAndCloseBlock;
+        yield writer.DecIndentAndCloseBlock;
+        yield writer.NewLine;
+    }
+    if (globalStateValues?.length) {
+        yield* writer.jsDoc(`Returns the smart contract's global state wrapped in a strongly typed accessor with options to format the stored value`);
+        yield `public async getGlobalState(): Promise<${name}['state']['global']> {`;
+        yield writer.IncIndent;
+        yield `const state = await this.appClient.getGlobalState()`;
+        yield `return {`;
+        yield writer.IncIndent;
+        for (const stateValue of globalStateValues) {
+            yield `get ${stateValue.key}() {`;
+            if (stateValue.type === 'uint64') {
+                yield* writer.indent(`return ${name}Client.getIntegerState(state, '${stateValue.key}')`);
+            }
+            else {
+                yield* writer.indent(`return ${name}Client.getBinaryState(state, '${stateValue.key}')`);
+            }
+            yield '},';
+        }
+        yield writer.DecIndentAndCloseBlock;
+        yield writer.DecIndentAndCloseBlock;
+        yield writer.NewLine;
+    }
+    if (localStateValues?.length) {
+        yield* writer.jsDoc({
+            description: `Returns the smart contract's local state wrapped in a strongly typed accessor with options to format the stored value`,
+            params: {
+                account: `The address of the account for which to read local state from`,
+            },
+        });
+        yield `public async getLocalState(account: string | SendTransactionFrom): Promise<${name}['state']['local']> {`;
+        yield writer.IncIndent;
+        yield `const state = await this.appClient.getLocalState(account)`;
+        yield `return {`;
+        yield writer.IncIndent;
+        for (const stateValue of localStateValues) {
+            yield `get ${stateValue.key}() {`;
+            if (stateValue.type === 'uint64') {
+                yield* writer.indent(`return ${name}Client.getIntegerState(state, '${stateValue.key}')`);
+            }
+            else {
+                yield* writer.indent(`return ${name}Client.getBinaryState(state, '${stateValue.key}')`);
+            }
+            yield '},';
+        }
+        yield writer.DecIndentAndCloseBlock;
+        yield writer.DecIndentAndCloseBlock;
+        yield writer.NewLine;
+    }
+}
+
+exports.callClient = callClient;

package/client/call-client.d.ts

@@ -1,4 +1,3 @@
 import { DocumentParts } from '../output/writer';
 import { GeneratorContext } from './generator-context';
 export declare function callClient(ctx: GeneratorContext): DocumentParts;
-//# sourceMappingURL=call-client.d.ts.map