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

package/bin/cli.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+import { cli } from '../cli.mjs'
+cli(process.cwd(), process.argv)

package/cli.cjs

@@ -0,0 +1,75 @@
+'use strict';
+
+var commander = require('commander');
+var load = require('./schema/load.cjs');
+var path = require('path');
+var generate = require('./client/generate.cjs');
+var writer = require('./output/writer.cjs');
+var colorConsole = require('./util/color-console.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 path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
+
+function cli(workingDirectory, args) {
+    const program = new commander.Command();
+    program
+        .command('generate')
+        .description('Generates a TypeScript client for the given application.json file')
+        .requiredOption('-a --application <path>', 'Specifies the application.json file')
+        .requiredOption('-o --output <path>', 'Specifies the output file path')
+        .action(async ({ application, output }) => {
+        const fs = await import('fs');
+        const resolvedAppJsonPath = path__namespace.resolve(workingDirectory, application);
+        const resolvedOutPath = path__namespace.resolve(workingDirectory, output);
+        const resolvedOutDir = path__namespace.dirname(resolvedOutPath);
+        colorConsole.colorConsole.info `Reading application.json file from path ${resolvedAppJsonPath}`;
+        const spec = await load.loadApplicationJson(resolvedAppJsonPath);
+        colorConsole.colorConsole.info `Generating TS client for ${spec.contract.name}`;
+        const parts = generate.generate(spec);
+        if (!fs.existsSync(resolvedOutDir)) {
+            colorConsole.colorConsole.warn `Output directory ${resolvedOutDir} does not exist and will be created.`;
+            fs.mkdirSync(resolvedOutDir, { recursive: true });
+        }
+        colorConsole.colorConsole.info `Writing TS client to ${resolvedOutPath}`;
+        const file = fs.createWriteStream(resolvedOutPath, {
+            flags: 'w',
+        });
+        writer.writeDocumentPartsToStream(parts, file);
+        colorConsole.colorConsole.success `Operation completed successfully`;
+    })
+        .configureOutput({
+        writeErr(str) {
+            colorConsole.colorConsole.error `${str}`;
+        },
+    });
+    try {
+        program.parse(args);
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            colorConsole.colorConsole.error `Unhandled error: \n\n${err.stack}`;
+        }
+        else {
+            colorConsole.colorConsole.error `Unhandled error: \n\n${err}`;
+        }
+        process.exit(-1);
+    }
+}
+
+exports.cli = cli;

package/cli.d.ts

@@ -1,2 +1 @@
 export declare function cli(workingDirectory: string, args: string[]): void;
-//# sourceMappingURL=cli.d.ts.map

package/cli.mjs

@@ -0,0 +1,54 @@
+import { Command } from 'commander';
+import { loadApplicationJson } from './schema/load.mjs';
+import * as path from 'path';
+import { generate } from './client/generate.mjs';
+import { writeDocumentPartsToStream } from './output/writer.mjs';
+import { colorConsole } from './util/color-console.mjs';
+
+function cli(workingDirectory, args) {
+    const program = new Command();
+    program
+        .command('generate')
+        .description('Generates a TypeScript client for the given application.json file')
+        .requiredOption('-a --application <path>', 'Specifies the application.json file')
+        .requiredOption('-o --output <path>', 'Specifies the output file path')
+        .action(async ({ application, output }) => {
+        const fs = await import('fs');
+        const resolvedAppJsonPath = path.resolve(workingDirectory, application);
+        const resolvedOutPath = path.resolve(workingDirectory, output);
+        const resolvedOutDir = path.dirname(resolvedOutPath);
+        colorConsole.info `Reading application.json file from path ${resolvedAppJsonPath}`;
+        const spec = await loadApplicationJson(resolvedAppJsonPath);
+        colorConsole.info `Generating TS client for ${spec.contract.name}`;
+        const parts = generate(spec);
+        if (!fs.existsSync(resolvedOutDir)) {
+            colorConsole.warn `Output directory ${resolvedOutDir} does not exist and will be created.`;
+            fs.mkdirSync(resolvedOutDir, { recursive: true });
+        }
+        colorConsole.info `Writing TS client to ${resolvedOutPath}`;
+        const file = fs.createWriteStream(resolvedOutPath, {
+            flags: 'w',
+        });
+        writeDocumentPartsToStream(parts, file);
+        colorConsole.success `Operation completed successfully`;
+    })
+        .configureOutput({
+        writeErr(str) {
+            colorConsole.error `${str}`;
+        },
+    });
+    try {
+        program.parse(args);
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            colorConsole.error `Unhandled error: \n\n${err.stack}`;
+        }
+        else {
+            colorConsole.error `Unhandled error: \n\n${err}`;
+        }
+        process.exit(-1);
+    }
+}
+
+export { cli };

package/client/app-types.cjs

@@ -0,0 +1,152 @@
+'use strict';
+
+var writer = require('../output/writer.cjs');
+var algokit = require('@algorandfoundation/algokit-utils');
+var getEquivalentType = require('./helpers/get-equivalent-type.cjs');
+var sanitization = require('../util/sanitization.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* appTypes(ctx) {
+    const { app, methodSignatureToUniqueName, name } = ctx;
+    yield* writer.jsDoc(`Defines the types of available calls and state of the ${name} smart contract.`);
+    yield `export type ${name} = {`;
+    yield writer.IncIndent;
+    yield* writer.jsDoc('Maps method signatures / names to their argument and return types.');
+    yield 'methods:';
+    yield writer.IncIndent;
+    for (const method of app.contract.methods) {
+        const methodSig = algokit__namespace.getABIMethodSignature(method);
+        const uniqueName = methodSignatureToUniqueName[methodSig];
+        yield `& Record<'${methodSig}'${methodSig !== uniqueName ? ` | '${uniqueName}'` : ''}, {`;
+        yield writer.IncIndent;
+        yield `argsObj: {`;
+        yield writer.IncIndent;
+        const argsMeta = method.args.map((arg) => ({
+            ...arg,
+            hasDefault: app.hints?.[methodSig]?.default_arguments?.[arg.name],
+            tsType: getEquivalentType.getEquivalentType(arg.type, 'input'),
+        }));
+        for (const arg of argsMeta) {
+            if (arg.desc)
+                yield* writer.jsDoc(arg.desc);
+            yield `${sanitization.makeSafePropertyIdentifier(arg.name)}${arg.hasDefault ? '?' : ''}: ${arg.tsType}`;
+        }
+        yield writer.DecIndentAndCloseBlock;
+        yield* writer.inline(`argsTuple: [`, argsMeta
+            .map((arg) => `${sanitization.makeSafeVariableIdentifier(arg.name)}: ${getEquivalentType.getEquivalentType(arg.type, 'input')}${arg.hasDefault ? ' | undefined' : ''}`)
+            .join(', '), ']');
+        const outputStruct = ctx.app.hints?.[methodSig]?.structs?.output;
+        if (method.returns.desc)
+            yield* writer.jsDoc(method.returns.desc);
+        if (outputStruct) {
+            yield `returns: ${sanitization.makeSafeTypeIdentifier(outputStruct.name)}`;
+        }
+        else {
+            yield `returns: ${getEquivalentType.getEquivalentType(method.returns.type ?? 'void', 'output')}`;
+        }
+        yield writer.DecIndent;
+        yield '}>';
+    }
+    yield writer.DecIndent;
+    yield* appState(ctx);
+    yield writer.DecIndentAndCloseBlock;
+    yield* writer.jsDoc('Defines the possible abi call signatures');
+    yield `export type ${name}Sig = keyof ${name}['methods']`;
+    yield* writer.jsDoc('Defines an object containing all relevant parameters for a single call to the contract. Where TSignature is undefined, a' +
+        ' bare call is made');
+    yield `export type TypedCallParams<TSignature extends ${name}Sig | undefined> = {`;
+    yield writer.IncIndent;
+    yield 'method: TSignature';
+    yield 'methodArgs: TSignature extends undefined ? undefined : Array<ABIAppCallArg | undefined>';
+    yield writer.DecIndent;
+    yield '} & AppClientCallCoreParams & CoreAppCallArgs';
+    yield* writer.jsDoc('Defines the arguments required for a bare call');
+    yield `export type BareCallArgs = Omit<RawAppCallArgs, keyof CoreAppCallArgs>`;
+    yield* structs(ctx);
+    yield* writer.jsDoc(`Maps a method signature from the ${name} smart contract to the method's arguments in either tuple of struct form`);
+    yield `export type MethodArgs<TSignature extends ${name}Sig> = ${name}['methods'][TSignature]['argsObj' | 'argsTuple']`;
+    yield* writer.jsDoc(`Maps a method signature from the ${name} smart contract to the method's return type`);
+    yield `export type MethodReturn<TSignature extends ${name}Sig> = ${name}['methods'][TSignature]['returns']`;
+    yield writer.NewLine;
+}
+function* structs({ app }) {
+    if (app.hints === undefined)
+        return;
+    for (const methodHint of Object.values(app.hints)) {
+        if (methodHint.structs === undefined)
+            continue;
+        for (const struct of Object.values(methodHint.structs)) {
+            yield* writer.jsDoc(`Represents a ${struct.name} result as a struct`);
+            yield `export type ${sanitization.makeSafeTypeIdentifier(struct.name)} = {`;
+            yield writer.IncIndent;
+            for (const [key, type] of struct.elements) {
+                yield `${sanitization.makeSafePropertyIdentifier(key)}: ${getEquivalentType.getEquivalentType(type, 'output')}`;
+            }
+            yield writer.DecIndentAndCloseBlock;
+            yield* writer.jsDoc(`Converts the tuple representation of a ${struct.name} to the struct representation`);
+            yield* writer.inline(`export function ${sanitization.makeSafeTypeIdentifier(struct.name)}(`, `[${struct.elements.map(([key]) => sanitization.makeSafeVariableIdentifier(key)).join(', ')}]: `, `[${struct.elements.map(([_, type]) => getEquivalentType.getEquivalentType(type, 'output')).join(', ')}] ) {`);
+            yield writer.IncIndent;
+            yield `return {`;
+            yield writer.IncIndent;
+            for (const [key] of struct.elements) {
+                const prop = sanitization.makeSafePropertyIdentifier(key);
+                const param = sanitization.makeSafeVariableIdentifier(key);
+                yield `${prop}${prop !== param ? `: ${param}` : ''},`;
+            }
+            yield writer.DecIndentAndCloseBlock;
+            yield writer.DecIndentAndCloseBlock;
+        }
+    }
+}
+function* appState({ app }) {
+    const hasLocal = app.schema.local?.declared && Object.keys(app.schema.local.declared).length;
+    const hasGlobal = app.schema.global?.declared && Object.keys(app.schema.global.declared).length;
+    if (hasLocal || hasGlobal) {
+        yield* writer.jsDoc('Defines the shape of the global and local state of the application.');
+        yield 'state: {';
+        yield writer.IncIndent;
+        if (hasGlobal) {
+            yield 'global: {';
+            yield writer.IncIndent;
+            for (const prop of Object.values(app.schema.global.declared)) {
+                if (prop.descr) {
+                    yield* writer.jsDoc(prop.descr);
+                }
+                yield `'${prop.key}'?: ${prop.type === 'uint64' ? 'IntegerState' : 'BinaryState'}`;
+            }
+            yield writer.DecIndentAndCloseBlock;
+        }
+        if (hasLocal) {
+            yield 'local: {';
+            yield writer.IncIndent;
+            for (const prop of Object.values(app.schema.local.declared)) {
+                if (prop.descr) {
+                    yield* writer.jsDoc(prop.descr);
+                }
+                yield `'${prop.key}'?: ${prop.type === 'uint64' ? 'IntegerState' : 'BinaryState'}`;
+            }
+            yield writer.DecIndentAndCloseBlock;
+        }
+        yield writer.DecIndentAndCloseBlock;
+    }
+}
+
+exports.appTypes = appTypes;

package/client/app-types.d.ts

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

package/client/app-types.mjs

@@ -0,0 +1,131 @@
+import { jsDoc, IncIndent, DecIndentAndCloseBlock, inline, DecIndent, NewLine } from '../output/writer.mjs';
+import * as algokit from '@algorandfoundation/algokit-utils';
+import { getEquivalentType } from './helpers/get-equivalent-type.mjs';
+import { makeSafePropertyIdentifier, makeSafeVariableIdentifier, makeSafeTypeIdentifier } from '../util/sanitization.mjs';
+
+function* appTypes(ctx) {
+    const { app, methodSignatureToUniqueName, name } = ctx;
+    yield* jsDoc(`Defines the types of available calls and state of the ${name} smart contract.`);
+    yield `export type ${name} = {`;
+    yield IncIndent;
+    yield* jsDoc('Maps method signatures / names to their argument and return types.');
+    yield 'methods:';
+    yield IncIndent;
+    for (const method of app.contract.methods) {
+        const methodSig = algokit.getABIMethodSignature(method);
+        const uniqueName = methodSignatureToUniqueName[methodSig];
+        yield `& Record<'${methodSig}'${methodSig !== uniqueName ? ` | '${uniqueName}'` : ''}, {`;
+        yield IncIndent;
+        yield `argsObj: {`;
+        yield IncIndent;
+        const argsMeta = method.args.map((arg) => ({
+            ...arg,
+            hasDefault: app.hints?.[methodSig]?.default_arguments?.[arg.name],
+            tsType: getEquivalentType(arg.type, 'input'),
+        }));
+        for (const arg of argsMeta) {
+            if (arg.desc)
+                yield* jsDoc(arg.desc);
+            yield `${makeSafePropertyIdentifier(arg.name)}${arg.hasDefault ? '?' : ''}: ${arg.tsType}`;
+        }
+        yield DecIndentAndCloseBlock;
+        yield* inline(`argsTuple: [`, argsMeta
+            .map((arg) => `${makeSafeVariableIdentifier(arg.name)}: ${getEquivalentType(arg.type, 'input')}${arg.hasDefault ? ' | undefined' : ''}`)
+            .join(', '), ']');
+        const outputStruct = ctx.app.hints?.[methodSig]?.structs?.output;
+        if (method.returns.desc)
+            yield* jsDoc(method.returns.desc);
+        if (outputStruct) {
+            yield `returns: ${makeSafeTypeIdentifier(outputStruct.name)}`;
+        }
+        else {
+            yield `returns: ${getEquivalentType(method.returns.type ?? 'void', 'output')}`;
+        }
+        yield DecIndent;
+        yield '}>';
+    }
+    yield DecIndent;
+    yield* appState(ctx);
+    yield DecIndentAndCloseBlock;
+    yield* jsDoc('Defines the possible abi call signatures');
+    yield `export type ${name}Sig = keyof ${name}['methods']`;
+    yield* jsDoc('Defines an object containing all relevant parameters for a single call to the contract. Where TSignature is undefined, a' +
+        ' bare call is made');
+    yield `export type TypedCallParams<TSignature extends ${name}Sig | undefined> = {`;
+    yield IncIndent;
+    yield 'method: TSignature';
+    yield 'methodArgs: TSignature extends undefined ? undefined : Array<ABIAppCallArg | undefined>';
+    yield DecIndent;
+    yield '} & AppClientCallCoreParams & CoreAppCallArgs';
+    yield* jsDoc('Defines the arguments required for a bare call');
+    yield `export type BareCallArgs = Omit<RawAppCallArgs, keyof CoreAppCallArgs>`;
+    yield* structs(ctx);
+    yield* jsDoc(`Maps a method signature from the ${name} smart contract to the method's arguments in either tuple of struct form`);
+    yield `export type MethodArgs<TSignature extends ${name}Sig> = ${name}['methods'][TSignature]['argsObj' | 'argsTuple']`;
+    yield* jsDoc(`Maps a method signature from the ${name} smart contract to the method's return type`);
+    yield `export type MethodReturn<TSignature extends ${name}Sig> = ${name}['methods'][TSignature]['returns']`;
+    yield NewLine;
+}
+function* structs({ app }) {
+    if (app.hints === undefined)
+        return;
+    for (const methodHint of Object.values(app.hints)) {
+        if (methodHint.structs === undefined)
+            continue;
+        for (const struct of Object.values(methodHint.structs)) {
+            yield* jsDoc(`Represents a ${struct.name} result as a struct`);
+            yield `export type ${makeSafeTypeIdentifier(struct.name)} = {`;
+            yield IncIndent;
+            for (const [key, type] of struct.elements) {
+                yield `${makeSafePropertyIdentifier(key)}: ${getEquivalentType(type, 'output')}`;
+            }
+            yield DecIndentAndCloseBlock;
+            yield* jsDoc(`Converts the tuple representation of a ${struct.name} to the struct representation`);
+            yield* inline(`export function ${makeSafeTypeIdentifier(struct.name)}(`, `[${struct.elements.map(([key]) => makeSafeVariableIdentifier(key)).join(', ')}]: `, `[${struct.elements.map(([_, type]) => getEquivalentType(type, 'output')).join(', ')}] ) {`);
+            yield IncIndent;
+            yield `return {`;
+            yield IncIndent;
+            for (const [key] of struct.elements) {
+                const prop = makeSafePropertyIdentifier(key);
+                const param = makeSafeVariableIdentifier(key);
+                yield `${prop}${prop !== param ? `: ${param}` : ''},`;
+            }
+            yield DecIndentAndCloseBlock;
+            yield DecIndentAndCloseBlock;
+        }
+    }
+}
+function* appState({ app }) {
+    const hasLocal = app.schema.local?.declared && Object.keys(app.schema.local.declared).length;
+    const hasGlobal = app.schema.global?.declared && Object.keys(app.schema.global.declared).length;
+    if (hasLocal || hasGlobal) {
+        yield* jsDoc('Defines the shape of the global and local state of the application.');
+        yield 'state: {';
+        yield IncIndent;
+        if (hasGlobal) {
+            yield 'global: {';
+            yield IncIndent;
+            for (const prop of Object.values(app.schema.global.declared)) {
+                if (prop.descr) {
+                    yield* jsDoc(prop.descr);
+                }
+                yield `'${prop.key}'?: ${prop.type === 'uint64' ? 'IntegerState' : 'BinaryState'}`;
+            }
+            yield DecIndentAndCloseBlock;
+        }
+        if (hasLocal) {
+            yield 'local: {';
+            yield IncIndent;
+            for (const prop of Object.values(app.schema.local.declared)) {
+                if (prop.descr) {
+                    yield* jsDoc(prop.descr);
+                }
+                yield `'${prop.key}'?: ${prop.type === 'uint64' ? 'IntegerState' : 'BinaryState'}`;
+            }
+            yield DecIndentAndCloseBlock;
+        }
+        yield DecIndentAndCloseBlock;
+    }
+}
+
+export { appTypes };