gen-typescript-from-tolk-dev 0.1.0

package/src/formatting.ts

@@ -0,0 +1,98 @@
+// OutBuf helps to generate TypeScript output with proper indentation.
+export class OutBuf {
+    static TAB = '    '
+
+    static onNewLine(s: string): string {
+        return `{indent}${s}{outdent}`;
+    }
+
+    private static indentNested(input: string, indentLevel: number): string {
+        let result = '';
+        let i = 0;
+
+        while (i < input.length) {
+            if (input.startsWith('{indent}', i)) {
+                result += '\n' + '    '.repeat(++indentLevel);
+                i += 8;
+            } else if (input.startsWith('{outdent}', i)) {
+                result += '\n' + '    '.repeat(--indentLevel);
+                i += 9;
+            } else if (input[i] === '\n') {
+                result += '\n' + '    '.repeat(indentLevel);
+                i++;
+            } else {
+                result += input[i];
+                i++;
+            }
+        }
+
+        return result;
+    }
+
+    private lines = [] as string[];
+    private indentLevel = 0;
+
+    indent() { this.indentLevel++; }
+    outdent() { this.indentLevel--; }
+    emptyLine() { this.lines.push(''); }
+
+    push(line: string) {
+        if (line.includes('{indent}') || line.includes('\n')) {
+            line = OutBuf.indentNested(line.trimEnd(), this.indentLevel);
+            line = line.replace(/\s+\n/g, '\n');
+            line = line.replace(/\n\s+,/g, ',');
+        }
+
+        if (line.startsWith('}') || line.startsWith(']') || line.startsWith(')')) {
+            this.outdent();
+        }
+        this.lines.push(OutBuf.TAB.repeat(this.indentLevel) + line);
+        if (line.endsWith('{') || line.endsWith('[') || line.endsWith('(')) {
+            this.indent();
+        }
+        return this;
+    }
+
+    toString() {
+        return this.lines.join('\n');
+    }
+}
+
+// In Tolk, similar to Kotlin, identifiers (structs, fields, etc.) can be embraced:
+// > struct `foo-bar` { `a()`: int }
+// Such names are incorrect in TS/JS and require special handling.
+function isSafeJsIdent(tolkStructName: string): boolean {
+    return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(tolkStructName);
+}
+
+// In TS, `interface` and `const` can not contain '-' and other invalid symbols,
+// so we mangle them: "foo-bar@" -> "foo_bar_".
+// NB! Keywords, like 'await' or 'function', are also invalid identifiers,
+// but since structs and type aliases are recommended to be named CamelCase in Tolk contracts,
+// we don't expect collisions with JS keywords here.
+export function safeJsIdent(tolkIdentifier: string): string {
+    if (isSafeJsIdent(tolkIdentifier)) {
+        return tolkIdentifier;
+    }
+
+    let safe = tolkIdentifier.replace(/[^a-zA-Z0-9_$]/g, '_');
+    if (/^[0-9]/.test(safe)) {
+        safe = '_' + safe;
+    }
+    return safe;
+}
+
+// In object literals, 'foo-bar' can be used (without mangling to '_') if quoted:
+// > interface A { foo: number, "foo-bar": number }
+// > return { foo: 0, "foo-bar": 123 }
+// Also, `__proto__` requires special handling, but I decided not to take it into account.
+export function safeFieldDecl(fieldName: string): string {
+    return isSafeJsIdent(fieldName) ? fieldName : JSON.stringify(fieldName);
+}
+
+// When accessing object fields, use ["syntax"] for invalid identifiers:
+// > obj.foo
+// > obj["foo-bar"]
+export function safeFieldRead(fieldName: string): string {
+    return isSafeJsIdent(fieldName) ? `.${fieldName}` : `[${JSON.stringify(fieldName)}]`;
+}

package/src/generate-from-abi-json.ts

@@ -0,0 +1,22 @@
+import type { ContractABI } from './abi';
+import { generateTypeScriptFileForContract } from './generate-ts-wrappers';
+
+function parseContractAbi(value: unknown): ContractABI {
+    if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('ABI JSON must describe an object');
+    }
+    if (typeof (value as { contractName?: unknown }).contractName !== 'string') {
+        throw new Error("ABI JSON must contain a string 'contractName'");
+    }
+    return value as ContractABI;
+}
+
+export function generateTypeScriptFromAbiJson(abiJson: string): string {
+    let parsedJson: unknown;
+    try {
+        parsedJson = JSON.parse(abiJson);
+    } catch (error: any) {
+        throw new Error(`Failed to parse ABI JSON: ${error.message ?? error.toString()}`);
+    }
+    return generateTypeScriptFileForContract(parseContractAbi(parsedJson));
+}

package/src/generate-ts-wrappers.ts

@@ -0,0 +1,477 @@
+import fs from 'fs';
+import type { Ty, ABIStruct, ABIAlias, ABIEnum } from './abi-types';
+import type { ContractABI, ABIGetMethod } from './abi';
+import { CodegenCtx, RUNTIME } from './codegen-ctx';
+import { OutBuf, safeJsIdent, safeFieldDecl, safeFieldRead } from './formatting';
+import { emitTsType, emitUnionLabelAndValue } from './emit-ts-types';
+import { emitLoadExpr, emitStoreStatement, emitMakeCellFromExpr, emitCallToCreateMethodExpr } from './emit-pack-unpack';
+import { emitStackReadExpr, emitStackWriteItems } from './emit-stack-rw';
+import { emitFieldDefault, emitFieldDefaultInComment, isDefaultValueSupported } from './emit-field-defs';
+import { CantGeneratePackUnpack, CantGenerateWrappersAtAll } from './unsupported-errors';
+import { calcWidthOnStack, createLabelsForUnion, instantiateGenerics, renderTy } from './types-kernel'
+
+// Output a struct as a doc comment.
+function renderStructDocComment(s: ABIStruct): string {
+    const genericTs = s.typeParams ? `<${s.typeParams.join(', ')}>` : '';
+    return [
+        '/**',
+        ` > struct${s.prefix ? ` (${s.prefix.prefixStr})` : ''} ${s.name}${genericTs} {`,
+        ...s.fields.map(f => ` >     ${f.name}: ${renderTy(f.ty)}`),
+        ' > }',
+        ' */'
+    ].join('\n')
+}
+
+// Output an alias as a doc comment.
+function renderAliasDocComment(a: ABIAlias): string {
+    const genericTs = a.typeParams ? `<${a.typeParams.join(', ')}>` : '';
+    return [
+        '/**',
+        ` > type ${a.name}${genericTs} = ${renderTy(a.targetTy)}`,
+        ' */'
+    ].join('\n');
+}
+
+// Output an enum as a doc comment.
+function renderEnumDocComment(e: ABIEnum): string {
+    return [
+        '/**',
+        ` > enum ${e.name} { ${e.members.length} variants }`,
+        ' */'
+    ].join('\n');
+}
+
+// If a struct can't be serialized, then its `fromSlice`/`store` is just `throw` with description.
+// Since Tolk code contains many structs (some are used for contract getters, for example),
+// not all of them are intended for serialization, it's expected.
+function renderThrowCantPackUnpack(structName: string, caughtEx: any, isPack: boolean): string {
+    if (!(caughtEx instanceof CantGeneratePackUnpack))
+        throw caughtEx
+
+    const action = isPack ? `pack '${structName}' to cell` : `unpack '${structName}' from cell`;
+    return `throw new Error(\`Can't ${action}, because ${caughtEx.message}\`);`;
+}
+
+// All-in-one: a struct with autogen serializers.
+// Tolk `struct X` -> TS `interface X` { $: 'X'; ...fields } + `const X` with serializers.
+function tolkStructToTypeScript(ctx: CodegenCtx, s: ABIStruct, buf: OutBuf): string {
+    const ps = s.typeParams;
+    const genericTs = ps ? `<${ps.join(', ')}>` : '';
+    const structName = safeJsIdent(s.name);
+    const structTy: Ty = { kind: 'StructRef', structName: s.name, typeArgs: s.typeParams?.map(nameT => ({kind: 'genericT', nameT})) };
+
+    const loadCallbackParams = ps ? ', ' + ps.map(p => `loadFn_${p}: LoadCallback<${p}>`).join(', ') : '';
+    const storeCallbackParams = ps ? ', ' + ps.map(p => `storeFn_${p}: StoreCallback<${p}>`).join(', ') : '';
+
+    buf.push(renderStructDocComment(s));
+    buf.push(`export interface ${structName}${genericTs} {`);
+    buf.push(`readonly $: '${s.name}'`);
+    for (const f of s.fields) {
+        let comment = f.defaultValue ? ` /* = ${emitFieldDefaultInComment(f.defaultValue)} */` : '';
+        buf.push(`${safeFieldDecl(f.name)}: ${emitTsType(ctx, f.ty)}${comment}`);
+    }
+    buf.push('}');
+    buf.emptyLine();
+    buf.push(`export const ${structName} = {`);
+    if (s.prefix) {
+        buf.push(`PREFIX: ${s.prefix.prefixStr},`);
+        buf.emptyLine();
+    }
+    let argsParam = s.fields.length ? 'args: ' + structParameterNoLabel(ctx, s.name) : '';
+    buf.push(`create${genericTs}(${argsParam}): ${structName}${genericTs} {`);
+    buf.push(`return {`);
+    buf.push(`$: '${s.name}',`);
+    for (let f of s.fields.filter(f => f.defaultValue && isDefaultValueSupported(f.ty))) {
+        let needAsAny = f.ty.kind === 'genericT';
+        buf.push(`${safeFieldDecl(f.name)}: ${emitFieldDefault(ctx, f.defaultValue!)}${needAsAny ? ' as any' : ''},`);
+    }
+    if (s.fields.length > 0) {
+        buf.push('...args');
+    }
+    buf.push('}');
+    buf.push(`},`);
+    buf.push(`fromSlice${genericTs}(s: c.Slice${loadCallbackParams}): ${structName}${genericTs} {`);
+    if (s.customPackUnpack?.unpackFromSlice) {
+        buf.push(`return invokeCustomUnpackFromSlice<${structName}>('${s.name}', s);`);
+    } else try {
+        const fieldsLoads = s.fields.map(f =>
+            `${safeFieldDecl(f.name)}: ${emitLoadExpr(ctx, `${structName}${safeFieldRead(f.name)}`, f.ty)},`
+        )
+        if (s.prefix && s.prefix.prefixLen === 32) {
+            buf.push(`${RUNTIME.loadAndCheckPrefix32}(s, ${s.prefix.prefixStr}, '${s.name}');`);
+        } else if (s.prefix) {
+            ctx.has_non32Prefixes = true;
+            buf.push(`${RUNTIME.loadAndCheckPrefix}(s, ${s.prefix.prefixStr}, ${s.prefix.prefixLen}, '${s.name}');`);
+        }
+        buf.push(`return {`);
+        buf.push(`$: '${s.name}',`);
+        fieldsLoads.forEach(l => buf.push(l));
+        buf.push('}');
+    } catch (ex) {
+        buf.push(renderThrowCantPackUnpack(structName, ex, false));
+    }
+    buf.push(`},`);
+    buf.push(`store${genericTs}(self: ${structName}${genericTs}, b: c.Builder${storeCallbackParams}): void {`);
+    if (s.customPackUnpack?.packToBuilder) {
+        buf.push(`invokeCustomPackToBuilder<${structName}>('${s.name}', self, b);`);
+    } else try {
+        const fieldsStores = s.fields.map(f =>
+            emitStoreStatement(ctx, `self${safeFieldRead(f.name)}`, f.ty)
+        );
+        if (s.prefix) {
+            buf.push(`b.storeUint(${s.prefix.prefixStr}, ${s.prefix.prefixLen});`);
+        }
+        fieldsStores.forEach(l => buf.push(l));
+    } catch (ex) {
+        buf.push(renderThrowCantPackUnpack(structName, ex, true))
+    }
+    buf.push(`},`);
+    buf.push(`toCell${genericTs}(self: ${structName}${genericTs}${storeCallbackParams}): c.Cell {`);
+    buf.push(`return ${emitMakeCellFromExpr(ctx, 'self', structTy, true)};`);
+    buf.push('}');
+    buf.push('}');
+    return buf.toString();
+}
+
+// All-in-one: an alias with autogen serializers.
+// Tolk `type X = Y` -> TS `type X = Y` (interchangeable with its underlying type, like in Tolk).
+function tolkAliasToTypeScript(ctx: CodegenCtx, a: ABIAlias, buf: OutBuf): string {
+    const ps = a.typeParams;
+    const genericTs = ps ? `<${ps.join(', ')}>` : '';
+    const aliasName = safeJsIdent(a.name);
+    const aliasTy: Ty = { kind: 'AliasRef', aliasName: a.name, typeArgs: a.typeParams?.map(nameT => ({kind: 'genericT', nameT})) };
+
+    const loadCallbackParams = ps ? ', ' + ps.map(p => `loadFn_${p}: LoadCallback<${p}>`).join(', ') : '';
+    const storeCallbackParams = ps ? ', ' + ps.map(p => `storeFn_${p}: StoreCallback<${p}>`).join(', ') : '';
+
+    ctx.has_customPackUnpack ||= a.customPackUnpack !== undefined;
+
+    buf.push(renderAliasDocComment(a));
+    if (a.targetTy.kind === 'union') {
+        buf.push(`export type ${aliasName}${genericTs} =`).indent();
+        for (const v of createLabelsForUnion(ctx.symbols, a.targetTy.variants)) {
+            buf.push('| ' + emitUnionLabelAndValue(v, emitTsType(ctx, v.variantTy)));
+        }
+        buf.outdent();
+    } else {
+        buf.push(`export type ${aliasName}${genericTs} = ${emitTsType(ctx, a.targetTy)}`);
+    }
+    buf.emptyLine();
+    buf.push(`export const ${aliasName} = {`);
+    buf.push(`fromSlice${genericTs}(s: c.Slice${loadCallbackParams}): ${aliasName}${genericTs} {`);
+    if (a.customPackUnpack?.unpackFromSlice) {
+        buf.push(`return invokeCustomUnpackFromSlice<${aliasName}>('${a.name}', s);`);
+    } else try {
+        buf.push(`return ${emitLoadExpr(ctx, aliasName, a.targetTy)};`);
+    } catch (ex) {
+        buf.push(renderThrowCantPackUnpack(aliasName, ex, false));
+    }
+    buf.push(`},`);
+    buf.push(`store${genericTs}(self: ${aliasName}${genericTs}, b: c.Builder${storeCallbackParams}): void {`);
+    if (a.customPackUnpack?.packToBuilder) {
+        buf.push(`invokeCustomPackToBuilder<${aliasName}>('${a.name}', self, b);`);
+    } else try {
+        buf.push(emitStoreStatement(ctx, 'self', a.targetTy));
+    } catch (ex) {
+        buf.push(renderThrowCantPackUnpack(aliasName, ex, true));
+    }
+    buf.push(`},`);
+    buf.push(`toCell${genericTs}(self: ${aliasName}${genericTs}${storeCallbackParams}): c.Cell {`);
+    buf.push(`return ${emitMakeCellFromExpr(ctx, 'self', aliasTy, true)};`);
+    buf.push('}');
+    buf.push('}');
+    return buf.toString();
+}
+
+// All-in-one: an enum with autogen serializers.
+// Tolk `enum X` -> TS `type X = bigint` + `const X` with members and serializers.
+function tolkEnumToTypeScript(ctx: CodegenCtx, e: ABIEnum, buf: OutBuf): string {
+    const enumName = safeJsIdent(e.name);
+    const enumTy: Ty = { kind: 'EnumRef', enumName: e.name };
+
+    buf.push(renderEnumDocComment(e));
+    buf.push(`export type ${enumName} = bigint`);
+    buf.emptyLine();
+    buf.push(`export const ${enumName} = {`);
+    for (const v of e.members) {
+        let memberName = v.name;
+        if (memberName === 'toCell' || memberName === 'store' || memberName === 'fromSlice') {
+            memberName += '_';
+        }
+        buf.push(`${safeFieldDecl(memberName)}: ${v.value}n,`);
+    }
+    buf.emptyLine();
+    buf.push(`fromSlice(s: c.Slice): ${enumName} {`);
+    if (e.customPackUnpack?.unpackFromSlice) {
+        buf.push(`return invokeCustomUnpackFromSlice<${enumName}>('${e.name}', s);`);
+    } else {
+        buf.push(`return ${emitLoadExpr(ctx, e.name, e.encodedAs)};`);
+    }
+    buf.push(`},`);
+    buf.push(`store(self: ${enumName}, b: c.Builder): void {`);
+    if (e.customPackUnpack?.packToBuilder) {
+        buf.push(`return invokeCustomPackToBuilder<${enumName}>('${e.name}', self, b);`);
+    } else {
+        buf.push(emitStoreStatement(ctx, 'self', e.encodedAs));
+    }
+    buf.push(`},`);
+    buf.push(`toCell(self: ${enumName}): c.Cell {`);
+    buf.push(`return ${emitMakeCellFromExpr(ctx, 'self', enumTy, true)};`);
+    buf.push('}');
+    buf.push('}');
+    return buf.toString();
+}
+
+// Convert "get_wallet_data" to "getWalletData".
+function snakeCaseToCamelCase(snakeString: string): string {
+    return snakeString.replace(/_([a-zA-Z])/g, (_, letter: string) => letter.toUpperCase());
+}
+
+// For sendXXX contract methods, we generate not `(msg: XXX)` but `(body: { ...fields })`,
+// so that on a caller side, one can use `contract.sendXXX({ queryId: 0n, ... })`
+// instead of `contract.sendXXX(XXX.create({ queryId: 0n, ... }))` (although the latter is also acceptable).
+// Note that if a field has a default value, it's declared as optional (`f?: T`, not `f: T`).
+function structParameterNoLabel(ctx: CodegenCtx, structName: string, typeArgs?: Ty[]): string {
+    const structRef = ctx.symbols.getStruct(structName);
+    let declBuf = new OutBuf();
+    declBuf.push(`{`);
+    for (let f of structRef.fields) {
+        let comment = f.defaultValue ? ` /* = ${emitFieldDefaultInComment(f.defaultValue)} */` : '';
+        let fTy = typeArgs ? instantiateGenerics(f.ty, structRef.typeParams, typeArgs) : f.ty;
+        declBuf.push(`${safeFieldDecl(f.name)}${f.defaultValue && isDefaultValueSupported(fTy) ? '?' : ''}: ${emitTsType(ctx, fTy)}${comment}`);
+    }
+    declBuf.push(`}`);
+    return declBuf.toString();
+}
+
+// Generate `static fromStorage()` method for a storage of type {ty}.
+// Most likely, it's a struct, then a caller can just use `MyContract.fromStorage({ fields })`.
+function generateFromStorageMethod(ctx: CodegenCtx, ty: Ty | undefined, contractName: string): string {
+    if (ty == null || ty.kind === 'nullLiteral') {    // means "no storage, don't emit a method"
+        return '';
+    }
+
+    let storageParamT = emitTsType(ctx, ty);
+    let bodyArg = 'emptyStorage';
+    if (ty.kind === 'StructRef') {
+        storageParamT = structParameterNoLabel(ctx, ty.structName, ty.typeArgs);
+        bodyArg = emitCallToCreateMethodExpr(ctx, 'emptyStorage', ty);
+    }
+
+    let buf = new OutBuf();
+    buf.push(`static fromStorage(emptyStorage: ${storageParamT}, deployedOptions?: DeployedAddrOptions) {`);
+    buf.push(`const initialState = {`);
+    buf.push(`code: deployedOptions?.overrideContractCode ?? ${contractName}.CodeCell,`);
+    buf.push(`data: ${emitMakeCellFromExpr(ctx, bodyArg, ty)},`);
+    buf.push(`};`);
+    buf.push(`const address = calculateDeployedAddress(initialState.code, initialState.data, deployedOptions ?? {});`);
+    buf.push(`return new ${contractName}(address, initialState);`);
+    buf.push(`}`);
+    return buf.toString();
+}
+
+// Generate a `createCellOfXXX` static method for a contract class.
+// It's essentially a wrapper for `XXX.toCell(XXX.create(body))`, but quite handy for the end user,
+// to make a cell for TON Connect. In practice, `toCell` is needed almost for messages only.
+function generateCreateCellOfMessageMethod(ctx: CodegenCtx, ty: Ty): string {
+    let functionName = snakeCaseToCamelCase(safeJsIdent(`createCellOf_${renderTy(ty)}`));
+
+    let bodyParamT = emitTsType(ctx, ty);
+    let bodyArg = 'body';
+    if (ty.kind === 'StructRef') {
+        bodyParamT = structParameterNoLabel(ctx, ty.structName, ty.typeArgs);
+        bodyArg = emitCallToCreateMethodExpr(ctx, 'body', ty);
+    }
+
+    let buf = new OutBuf();
+    buf.push(`static ${functionName}(body: ${bodyParamT}) {`);
+    buf.push(`return ${emitMakeCellFromExpr(ctx, bodyArg, ty)};`);
+    buf.push(`}`);
+    return buf.toString();
+}
+
+// Generate a `sendXXX` method for a message of type {ty}.
+// Most likely, it's a struct (an instantiated one also possible), but it can also be an alias for example.
+function generateSendMethod(ctx: CodegenCtx, ty: Ty): string {
+    let functionName = snakeCaseToCamelCase(safeJsIdent(`send_${renderTy(ty)}`));
+
+    let bodyParamT = emitTsType(ctx, ty);
+    let bodyArg = 'body';
+    if (ty.kind === 'StructRef') {
+        bodyParamT = structParameterNoLabel(ctx, ty.structName, ty.typeArgs);
+        bodyArg = emitCallToCreateMethodExpr(ctx, 'body', ty);
+    }
+
+    let buf = new OutBuf();
+    buf.push(`async ${functionName}(provider: ContractProvider, via: Sender, msgValue: coins, body: ${bodyParamT}, extraOptions?: ${RUNTIME.ExtraSendOptions}) {`);
+    buf.push(`return provider.internal(via, {`);
+    buf.push(`value: msgValue,`);
+    buf.push(`body: ${emitMakeCellFromExpr(ctx, bodyArg, ty)},`);
+    buf.push(`...extraOptions`);
+    buf.push(`});`);
+    buf.push(`}`);
+    return buf.toString();
+}
+
+// Generate a `getXXX` method: a contract getter that works off-chain, via the stack.
+function generateGetMethod(ctx: CodegenCtx, getM: ABIGetMethod): string {
+    let functionName = snakeCaseToCamelCase(safeJsIdent('get_' + getM.name));
+    functionName = functionName.replace(/^getGet/, 'get');
+
+    let nParams = getM.parameters.length;
+    let paramNames = getM.parameters.map(p => {
+        let collision = Object.values(RUNTIME).some(n => p.name === n)
+                     || p.name === 'c'         // import @ton/core
+                     || p.name === 'r'         // StackReader in body
+                     || p.name === 'provider'  // implicit parameter
+        return safeJsIdent(collision ? p.name + '_' : p.name)
+    });
+
+    let buf = new OutBuf();
+    let paramsStr = nParams ? `, ${getM.parameters.map((p, i) => 
+        `${paramNames[i]}: ${emitTsType(ctx, p.ty)}${p.defaultValue ? ` = ${emitFieldDefault(ctx, p.defaultValue)}` : ''}`
+    ).join(', ')}` : ''
+    if (getM.returnTy.kind === 'tensor') {
+        buf.push(`async ${functionName}(provider: ContractProvider${paramsStr}): Promise<[`);
+        for (let item of getM.returnTy.items) {
+            buf.push(emitTsType(ctx, item) + ',')
+        }
+        buf.push(']> {')
+    } else {
+        buf.push(`async ${functionName}(provider: ContractProvider${paramsStr}): Promise<${emitTsType(ctx, getM.returnTy)}> {`);
+    }
+    let stackW = calcWidthOnStack(ctx.symbols, getM.returnTy);
+    if (nParams) {
+        buf.push(`const r = ${RUNTIME.StackReader}.fromGetMethod(${stackW}, await provider.get('${getM.name}', [`);
+        let stackWrites = getM.parameters.flatMap((p, i) => emitStackWriteItems(ctx, paramNames[i], p.ty))
+        for (let w of stackWrites) {
+            buf.push(w + ',');
+        }
+        buf.push(`]));`);
+    } else {
+        buf.push(`const r = ${RUNTIME.StackReader}.fromGetMethod(${stackW}, await provider.get('${getM.name}', []));`);
+    }
+    buf.push(`return ${emitStackReadExpr(ctx, 'result', getM.returnTy)};`);
+    buf.push(`}`);
+    return buf.toString();
+}
+
+// Render a template of a TypeScript wrapper.
+function renderTsTemplate(tplStr: string, content: {
+    contractClassName: string
+    flags: Record<string, boolean>      // {{if:flag}} ... {{/if:flag}}
+    slots: Record<string, string>       // {{slot}}
+}): string {
+    // {{if:...}} blocks: keep blank lines before it if true
+    const IF_BLOCK_RE = /(^(?:\s*\n)*)\s*\/\/\s*{{if:(\w+)}}[^\n]*\n([\s\S]+?)^\s*\/\/\s*{{\/if:\2}}[^\n]*/gm;
+    tplStr = tplStr.replace(IF_BLOCK_RE, (_m, leadingBlank: string, name: string, inner: string) =>
+        content.flags[name] ? leadingBlank + inner : ''
+    );
+
+    // {{slot}}: keep indentation, remove a commented marker
+    const SLOT_RE = /(^ *)(?:\/\/\s*)?{{(\w+)}}[^\n]*$/gm;
+    tplStr = tplStr.replace(SLOT_RE, (_m, indent: string, name: string) =>
+        content.slots[name].split('\n').map(l => l.length ? indent + l : '').join('\n')
+    );
+
+    // {{slot}} inlined (without a preceding comment)
+    tplStr = tplStr.replace(/{{(\w+)}}/g, (_m, name: string) => content.slots[name]);
+
+    return tplStr
+        .replace(/\n\s*\n(\s*})/g, '\n$1')          // remove an empty line before closing brace
+        .replace(/\n\s*\n(?:\s*\n)+/g, '\n\n')      // merge 2+ blank lines
+        .replace(/CONTRACT_CLASS_NAME/g, content.contractClassName);
+}
+
+/**
+ * The main function: accepts top-level declarations from Tolk sources (converted to ABI)
+ * and returns the full TypeScript wrapper with all serializers, send, and get methods.
+ * @throws CantGenerateWrappersAtAll
+ */
+export function generateTypeScriptFileForContract(contract: ContractABI): string {
+    let ctx = new CodegenCtx(contract.declarations);
+
+    const declarationsBuf = new OutBuf();
+    for (const n of contract.declarations) {
+        try {
+            if (n.kind === 'Struct')     tolkStructToTypeScript(ctx, n, declarationsBuf);
+            else if (n.kind === 'Alias') tolkAliasToTypeScript(ctx, n, declarationsBuf);
+            else if (n.kind === 'Enum')  tolkEnumToTypeScript(ctx, n, declarationsBuf);
+            declarationsBuf.emptyLine();
+        } catch (ex: any) {
+            throw new CantGenerateWrappersAtAll(`Error while generating ${n.kind.toLowerCase()} '${n.name}'`, ex);
+        }
+    }
+    let packUnpackSerializers = declarationsBuf.toString();
+
+    let createCellsMethodsStr = contract.incomingMessages.map(msg =>
+        generateCreateCellOfMessageMethod(ctx, msg.bodyTy)
+    );
+
+    let sendMethodsStr = contract.incomingMessages.map(msg => {
+        try {
+            return generateSendMethod(ctx, msg.bodyTy);
+        } catch (ex: any) {
+            throw new CantGenerateWrappersAtAll(`Error while generating send method '${renderTy(msg.bodyTy)}'`, ex);
+        }
+    });
+
+    let getMethodsStr = contract.getMethods.map(getM => {
+        try {
+            return generateGetMethod(ctx, getM);
+        } catch (ex: any) {
+            throw new CantGenerateWrappersAtAll(`Error while generating get method '${getM.name}'`, ex);
+        }
+    });
+
+    let intNAliasesStr = ctx.sortOccurred(ctx.intNOccurred).map(intN => `type ${intN} = bigint`);
+    let uintNAliasesStr = ctx.sortOccurred(ctx.uintNOccurred).map(uintN => `type ${uintN} = bigint`);
+    let varIntNAliasesStr = ctx.sortOccurred(ctx.varIntNOccurred).map(varIntN => `type ${varIntN} = bigint`);
+    let sliceAliasesStr = ctx.sortOccurred(ctx.bitsNOccurred).map(bitsN => `type ${bitsN} = c.Slice`);
+
+    let errorCodesStr = contract.thrownErrors.filter(t => t.name).map(t =>
+        `'${t.name}': ${t.errCode},`
+    );
+
+    return renderTsTemplate(fs.readFileSync(__dirname + '/out-template.ts', 'utf-8'), {
+        contractClassName: contract.contractName,
+        flags: {
+            'has_sendDeploy': true,
+            'has_bitsN': ctx.bitsNOccurred.size > 0,
+            'has_varIntN': ctx.varIntNOccurred.size > 0,
+            'has_remaining': ctx.has_RemainingBitsAndRefs,
+            'has_customPackUnpack': ctx.has_customPackUnpack,
+            'has_customDictV': ctx.has_customDictV,
+            'has_implicitUnionPrefix': ctx.has_implicitUnionPrefix,
+            'has_non32Prefixes': ctx.has_non32Prefixes,
+            'has_addressAny': ctx.has_addressAny,
+            'has_arrayOf': ctx.has_arrayOf,
+            'has_lispListOf': ctx.has_lispListOf,
+            'stackReadsUnknown': ctx.stackReadsUnknown,
+            'stackReadsArrayOf': ctx.stackReadsArrayOf,
+            'stackReadsLispListOf': ctx.stackReadsLispListOf,
+            'stackReadsSnakeString': ctx.stackReadsSnakeString,
+            'stackReadsTuple': ctx.stackReadsTuple,
+            'stackReadsMapKV': ctx.stackReadsMapKV,
+            'stackReadsBuilder': ctx.stackReadsBuilder,
+            'stackReadsNullable': ctx.stackReadsNullable,
+            'stackReadsWideNullable': ctx.stackReadsWideNullable,
+            'stackReadsUnionType': ctx.stackReadsUnionType,
+            'stackReadsCellRef': ctx.stackReadsCellRef,
+            'stackReadsNullLiteral': ctx.stackReadsNullLiteral,
+        },
+        slots: {
+            'intNAliases': intNAliasesStr.join('\n'),
+            'uintNAliases': uintNAliasesStr.join('\n'),
+            'varIntNAliases': varIntNAliasesStr.join('\n'),
+            'sliceAliases': sliceAliasesStr.join('\n'),
+            'packUnpackSerializers': packUnpackSerializers,
+            'codeBoc64': contract.codeBoc64,
+            'errorCodes': errorCodesStr.join('\n'),
+            'fromStorageMethod': generateFromStorageMethod(ctx, contract.storage.storageAtDeploymentTy ?? contract.storage.storageTy, contract.contractName),
+            'createCellsMethods': createCellsMethodsStr.join('\n\n'),
+            'sendMethods': sendMethodsStr.join('\n\n'),
+            'getMethods': getMethodsStr.join('\n\n'),
+        }
+    });
+}