gen-typescript-from-tolk-dev 0.1.0

package/src/emit-pack-unpack.ts

@@ -0,0 +1,280 @@
+import type { Ty } from './abi-types';
+import { CodegenCtx, RUNTIME } from './codegen-ctx';
+import { emitTsType, emitDictKVTypeArgs, emitUnionLabelAndValue } from './emit-ts-types';
+import { OutBuf, safeJsIdent } from './formatting';
+import { CantGeneratePackUnpack, NonStandardDictKey } from './unsupported-errors';
+import { createLabelsForUnion, renderTy } from './types-kernel';
+
+// Emit a TS "load {ty} from slice `s`" expression.
+// Parameter `fieldPath` is used for error messages only: e.g. when an input opcode is incorrect,
+// the fired Error will contain struct/field name.
+export function emitLoadExpr(ctx: CodegenCtx, fieldPath: string, ty: Ty): string {
+    switch (ty.kind) {
+        case 'int':
+        case 'builder':
+        case 'slice':
+        case 'unknown':
+        case 'callable': {
+            let hint = ty.kind === 'int' ? ' (not int32/uint64/etc.)' :
+                       ty.kind === 'builder' || ty.kind === 'slice' ? ' (it can be used for writing only)' :
+                       '';
+            throw new CantGeneratePackUnpack(`'${fieldPath}' is '${renderTy(ty)}'${hint}`);
+        }
+
+        case 'intN':        return `s.loadIntBig(${ty.n})`;
+        case 'uintN':       return `s.loadUintBig(${ty.n})`;
+        case 'varintN':     return `s.loadVarIntBig(${Math.log2(ty.n)})`;
+        case 'varuintN':    return `s.loadVarUintBig(${Math.log2(ty.n)})`;
+        case 'coins':       return `s.loadCoins()`;
+        case 'bool':        return `s.loadBoolean()`;
+        case 'cell':        return `s.loadRef()`;
+        case 'string':      return `s.loadStringRefTail()`;
+        case 'remaining':   return `${RUNTIME.loadTolkRemaining}(s)`;
+        case 'address':     return `s.loadAddress()`;
+        case 'addressOpt':  return `s.loadMaybeAddress()`;
+        case 'addressExt':  return `s.loadExternalAddress()`;
+        case 'addressAny':  return `${RUNTIME.loadTolkAddressAny}(s)`;
+        case 'bitsN':       return `${RUNTIME.loadTolkBitsN}(s, ${ty.n})`;
+        case 'nullLiteral': return `null`;
+        case 'void':        return `void 0`;
+        case 'nullable':    return `s.loadBoolean() ? ${emitLoadExpr(ctx, fieldPath, ty.inner)} : null`;
+        case 'cellOf':      return `${RUNTIME.loadCellRef}<${emitTsType(ctx, ty.inner)}>(s, ${emitLoadCallback(ctx, fieldPath, ty.inner)})`;
+        case 'arrayOf':     return `${RUNTIME.loadArrayOf}<${emitTsType(ctx, ty.inner)}>(s, ${emitLoadCallback(ctx, fieldPath + '[ith]', ty.inner)})`;
+        case 'lispListOf':  return `${RUNTIME.loadLispListOf}<${emitTsType(ctx, ty.inner)}>(s, ${emitLoadCallback(ctx, fieldPath + '[ith]', ty.inner)})`;
+        case 'tensor':      return `[${ty.items.map((item, i) => emitLoadExpr(ctx, `${fieldPath}[${i}]`, item)).join(', ')}]`;
+        case 'shapedTuple': return `[${ty.items.map((item, i) => emitLoadExpr(ctx, `${fieldPath}[${i}]`, item)).join(', ')}]`;
+        case 'mapKV':       return `c.Dictionary.load<${emitDictKVTypeArgs(ctx, ty.k, ty.v)}>(${emitDictKVSerializers(ctx, fieldPath, ty.k, ty.v)}, s)`;
+        case 'EnumRef':     return `${ty.enumName}.fromSlice(s)`;
+        case 'StructRef': {
+            if (ty.typeArgs) {
+                const cb = ty.typeArgs.map((ta) => emitLoadCallback(ctx, fieldPath, ta)).join(', ');
+                return `${safeJsIdent(ty.structName)}.fromSlice<${ty.typeArgs.map((ta) => emitTsType(ctx, ta)).join(', ')}>(s, ${cb})`;
+            }
+            return `${safeJsIdent(ty.structName)}.fromSlice(s)`;
+        }
+        case 'AliasRef': {
+            if (ty.typeArgs) {
+                const cb = ty.typeArgs.map((ta) => emitLoadCallback(ctx, fieldPath, ta)).join(', ');
+                return `${safeJsIdent(ty.aliasName)}.fromSlice<${ty.typeArgs.map((ta) => emitTsType(ctx, ta)).join(', ')}>(s, ${cb})`;
+            }
+            return `${safeJsIdent(ty.aliasName)}.fromSlice(s)`;
+        }
+        case 'genericT': return `loadFn_${ty.nameT}(s)`;
+        case 'union': {
+            const variants = createLabelsForUnion(ctx.symbols, ty.variants);
+            const isEither01 = variants.length === 2 && variants[0].prefixStr === '0b0' && variants[1].prefixStr === '0b1';
+            if (isEither01) {
+                const l = emitUnionLabelAndValue(variants[0], emitLoadExpr(ctx, fieldPath, variants[0].variantTy));
+                const r = emitUnionLabelAndValue(variants[1], emitLoadExpr(ctx, fieldPath, variants[1].variantTy));
+                return `s.loadBoolean() ? ${r} : ${l}`;
+            }
+            let buf = new OutBuf();
+            for (let v of variants) {
+                const checkFn = v.isPrefixImplicit ? RUNTIME.lookupPrefixAndEat : RUNTIME.lookupPrefix;
+                const body = emitUnionLabelAndValue(v, emitLoadExpr(ctx, fieldPath, v.variantTy));
+                buf.push(`${checkFn}(s, ${v.prefixStr}, ${v.prefixLen}) ? ${body} :`);
+                if (v.isPrefixImplicit) {
+                    ctx.has_implicitUnionPrefix = true;
+                }
+                if (v.prefixStr === variants[0].prefixStr) {
+                    buf.indent();
+                }
+            }
+            buf.push(`${RUNTIME.throwNonePrefixMatch}('${fieldPath}')`);
+            return buf.toString();
+        }
+    }
+}
+
+// Emit a TS "load {ty} from slice `s`" callback (not expression).
+// Callbacks are passed for generics (user-defined generic types and built-ins),
+// e.g., `loadCellRef<T>(s, {callbackForT})`.
+// We could just emit `(s) => loadExprForT(s)`, but to produce less boilerplate, shorten common cases:
+// not `(s) => SomeStruct.fromSlice(s)` but `SomeStruct.fromSlice` as a valid callback.
+export function emitLoadCallback(ctx: CodegenCtx, fieldPath: string, ty: Ty): string {
+    if (ty.kind === 'addressAny')   return RUNTIME.loadTolkAddressAny;
+    if (ty.kind === 'remaining')    return RUNTIME.loadTolkRemaining;
+    if (ty.kind === 'EnumRef')      return `${ty.enumName}.fromSlice`;
+    if (ty.kind === 'genericT')     return `loadFn_${ty.nameT}`;
+    if (ty.kind === 'StructRef' && !ty.typeArgs) return `${safeJsIdent(ty.structName)}.fromSlice`;
+    if (ty.kind === 'AliasRef' && !ty.typeArgs)  return `${safeJsIdent(ty.aliasName)}.fromSlice`;
+
+    return OutBuf.onNewLine(`(s) => ${emitLoadExpr(ctx, fieldPath, ty)}`);
+}
+
+// Emit a TS "store {expr of type ty} into builder `b`" statement.
+// Parameter `tsExpr` is a valid expression: "self.field", "v" (inside a callback), and other.
+export function emitStoreStatement(ctx: CodegenCtx, tsExpr: string, ty: Ty): string {
+    switch (ty.kind) {
+        case 'int':
+        case 'unknown':
+        case 'nullLiteral':
+        case 'callable': {
+            let hint = ty.kind === 'int' ? ' (not int32/uint64/etc.)' : '';
+            throw new CantGeneratePackUnpack(`'${tsExpr}' is '${renderTy(ty)}'${hint}`);
+        }
+
+        case 'intN':        return `b.storeInt(${tsExpr}, ${ty.n});`;
+        case 'uintN':       return `b.storeUint(${tsExpr}, ${ty.n});`;
+        case 'varintN':     return `b.storeVarInt(${tsExpr}, ${Math.log2(ty.n)});`;
+        case 'varuintN':    return `b.storeVarUint(${tsExpr}, ${Math.log2(ty.n)});`;
+        case 'coins':       return `b.storeCoins(${tsExpr});`;
+        case 'bool':        return `b.storeBit(${tsExpr});`;
+        case 'cell':        return `b.storeRef(${tsExpr});`;
+        case 'builder':     return `b.storeBuilder(${tsExpr});`;
+        case 'slice':       return `b.storeSlice(${tsExpr});`;
+        case 'string':      return `b.storeStringRefTail(${tsExpr});`;
+        case 'remaining':   return `${RUNTIME.storeTolkRemaining}(${tsExpr}, b);`;
+        case 'address':     return `b.storeAddress(${tsExpr});`;
+        case 'addressOpt':  return `b.storeAddress(${tsExpr});`;
+        case 'addressExt':  return `b.storeAddress(${tsExpr});`;
+        case 'addressAny':  return `${RUNTIME.storeTolkAddressAny}(${tsExpr}, b);`;
+        case 'bitsN':       return `${RUNTIME.storeTolkBitsN}(${tsExpr}, ${ty.n}, b);`;
+        case 'void':        return ``;
+        case 'nullable':    return `${RUNTIME.storeTolkNullable}<${emitTsType(ctx, ty.inner)}>(${tsExpr}, b, ${emitStoreCallback(ctx, ty.inner)});`;
+        case 'cellOf':      return `${RUNTIME.storeCellRef}<${emitTsType(ctx, ty.inner)}>(${tsExpr}, b, ${emitStoreCallback(ctx, ty.inner)});`;
+        case 'arrayOf':     return `${RUNTIME.storeArrayOf}<${emitTsType(ctx, ty.inner)}>(${tsExpr}, b, ${emitStoreCallback(ctx, ty.inner)});`;
+        case 'lispListOf':  return `${RUNTIME.storeLispListOf}<${emitTsType(ctx, ty.inner)}>(${tsExpr}, b, ${emitStoreCallback(ctx, ty.inner)});`;
+        case 'tensor':      return ty.items.length ? ty.items.map((_, i) => emitStoreStatement(ctx, `${tsExpr}[${i}]`, ty.items[i])).join('\n') : `{}`;
+        case 'shapedTuple': return ty.items.length ? ty.items.map((_, i) => emitStoreStatement(ctx, `${tsExpr}[${i}]`, ty.items[i])).join('\n') : `{}`;
+        case 'mapKV':       return `b.storeDict<${emitDictKVTypeArgs(ctx, ty.k, ty.v)}>(${tsExpr}, ${emitDictKVSerializers(ctx, tsExpr, ty.k, ty.v)});`;
+        case 'EnumRef':     return `${ty.enumName}.store(${tsExpr}, b);`;
+        case 'StructRef': {
+            if (ty.typeArgs) {
+                const cb = ty.typeArgs.map(ta => emitStoreCallback(ctx, ta)).join(', ');
+                return `${safeJsIdent(ty.structName)}.store<${ty.typeArgs.map(ta => emitTsType(ctx, ta)).join(', ')}>(${tsExpr}, b, ${cb});`;
+            }
+            return `${safeJsIdent(ty.structName)}.store(${tsExpr}, b);`;
+        }
+        case 'AliasRef': {
+            if (ty.typeArgs) {
+                const cb = ty.typeArgs.map(ta => emitStoreCallback(ctx, ta)).join(', ');
+                return `${safeJsIdent(ty.aliasName)}.store<${ty.typeArgs.map(ta => emitTsType(ctx, ta)).join(', ')}>(${tsExpr}, b, ${cb});`;
+            }
+            return `${safeJsIdent(ty.aliasName)}.store(${tsExpr}, b);`;
+        }
+        case 'genericT': return `storeFn_${ty.nameT}(${tsExpr}, b);`;
+        case 'union': {
+            const buf = new OutBuf();
+            const variants = createLabelsForUnion(ctx.symbols, ty.variants);
+            const hasNull = variants.find(v => v.variantTy.kind === 'nullLiteral');
+            if (hasNull) {
+                buf.push(`if (${tsExpr} === null) {`);
+                buf.push(`b.storeUint(${hasNull.prefixStr}, ${hasNull.prefixLen});`);
+                buf.push(`} else switch (${tsExpr}.$) {`);
+            } else {
+                buf.push(`switch (${tsExpr}.$) {`);
+            }
+            for (let v of variants) {
+                if (v.variantTy.kind === 'nullLiteral') continue;
+                buf.push(`case '${v.labelStr}':`).indent();
+                if (v.isPrefixImplicit) {
+                    buf.push(`b.storeUint(${v.prefixStr}, ${v.prefixLen});`);
+                }
+                buf.push(emitStoreStatement(ctx, v.hasValueField ? `${tsExpr}.value` : tsExpr, v.variantTy));
+                buf.push('break;').outdent();
+            }
+            buf.push('}');
+            return buf.toString();
+        }
+    }
+}
+
+// Emit a TS "store {expr of type ty} into builder `b`" callback (not expression).
+// Callbacks are passed for generics (user-defined generic types and built-ins),
+// e.g., `storeTolkNullable<T>(s, {callbackForT})`.
+export function emitStoreCallback(ctx: CodegenCtx, ty: Ty): string {
+    if (ty.kind === 'addressAny')   return RUNTIME.storeTolkAddressAny;
+    if (ty.kind === 'remaining')    return RUNTIME.storeTolkRemaining;
+    if (ty.kind === 'EnumRef')      return `${ty.enumName}.store`;
+    if (ty.kind === 'genericT')     return `storeFn_${ty.nameT}`;
+    if (ty.kind === 'StructRef' && !ty.typeArgs) return `${safeJsIdent(ty.structName)}.store`;
+    if (ty.kind === 'AliasRef' && !ty.typeArgs)  return `${safeJsIdent(ty.aliasName)}.store`;
+
+    // for simple statements, drop trailing `;` and use it as an expression:
+    // not `(v,b) => { b.storeInt(v, 8); }` but `(v,b) => b.storeInt(v, 8)`
+    let stmt = emitStoreStatement(ctx, 'v', ty);
+    if (stmt.indexOf(';') !== stmt.length - 1 || stmt.includes('\n') || stmt.includes('{')) {
+        stmt = '{ ' + stmt + ' }'
+    } else if (stmt[stmt.length - 1] === ';') {
+        stmt = stmt.substring(0, stmt.length - 1)
+    }
+    return OutBuf.onNewLine(`(v,b) => ${stmt}`);
+}
+
+// Emit a TS "make a cell from {expr}" expression.
+// It's essentially beginCell + call storing callback + endCell.
+// Parameter `tsExpr` is a valid expression: "self.field", "v" (inside a callback), and other.
+export function emitMakeCellFromExpr(ctx: CodegenCtx, tsExpr: string, ty: Ty, disableShortHand = false): string {
+    if (disableShortHand) {
+        return `${RUNTIME.makeCellFrom}<${emitTsType(ctx, ty)}>(${tsExpr}, ${emitStoreCallback(ctx, ty)})`;
+    }
+    switch (ty.kind) {
+        case 'EnumRef': {
+            return `${safeJsIdent(ty.enumName)}.toCell(${tsExpr})`;
+        }
+        case 'StructRef': {
+            if (ty.typeArgs) {
+                const cb = ty.typeArgs.map(ta => emitStoreCallback(ctx, ta)).join(', ');
+                return `${safeJsIdent(ty.structName)}.toCell<${ty.typeArgs.map(ta => emitTsType(ctx, ta)).join(', ')}>(${tsExpr}, ${cb})`;
+            }
+            return `${safeJsIdent(ty.structName)}.toCell(${tsExpr})`;
+        }
+        case 'AliasRef': {
+            if (ty.typeArgs) {
+                const cb = ty.typeArgs.map(ta => emitStoreCallback(ctx, ta)).join(', ');
+                return `${safeJsIdent(ty.aliasName)}.toCell<${ty.typeArgs.map(ta => emitTsType(ctx, ta)).join(', ')}>(${tsExpr}, ${cb})`;
+            }
+            return `${safeJsIdent(ty.aliasName)}.toCell(${tsExpr})`;
+        }
+        default:
+            return emitMakeCellFromExpr(ctx, tsExpr, ty, true);
+    }
+}
+
+// Emit a TS "StructName.create({bodyArg})" expression.
+// For instance, sendXXX and fromStorage methods accept struct fields and call create()
+// in order to enrich passed fields with `$` tag and default values.
+export function emitCallToCreateMethodExpr(ctx: CodegenCtx, bodyArg: string, ty: Ty) {
+    if (ty.kind === 'StructRef') {
+        let structRef = ctx.symbols.getStruct(ty.structName);
+        if (structRef.fields.length === 0) {
+            bodyArg = '';       // create() is without arguments, body is an empty object
+        }
+        if (ty.typeArgs) {
+            return `${safeJsIdent(ty.structName)}.create<${ty.typeArgs.map(ta => emitTsType(ctx, ta)).join(', ')}>(${bodyArg})`;
+        }
+        return `${safeJsIdent(ty.structName)}.create(${bodyArg})`;
+    }
+    throw new Error(`can not emit create() call for ${ty.kind}`);
+}
+
+// Emit a key (de)serializer for c.Dictionary<K, V>.
+// Only a strict subset of KeyT is allowed by the @ton/core library.
+// For others, we can not generate wrappers at all (not only to/from cell, but even declarations).
+function emitDictKeySerializer(ctx: CodegenCtx, fieldPath: string, tyK: Ty): string {
+    if (tyK.kind === 'intN')     return `c.Dictionary.Keys.BigInt(${tyK.n})`;
+    if (tyK.kind === 'uintN')    return `c.Dictionary.Keys.BigUint(${tyK.n})`;
+    if (tyK.kind === 'address')  return `c.Dictionary.Keys.Address()`;
+
+    throw new NonStandardDictKey(`'${fieldPath}' is 'map<${renderTy(tyK)}, ...>': such a non-standard map key can not be handled by @ton/core library`);
+}
+
+// Emit a value (de)serializer for c.Dictionary<K, V>.
+// Unlike keys, @ton/core allows arbitrary values (passing custom (de)serializers).
+// For common cases, use a built-in one; for others, create a custom.
+function emitDictValueSerializer(ctx: CodegenCtx, fieldPath: string, tyV: Ty): string {
+    if (tyV.kind === 'intN')     return `c.Dictionary.Values.BigInt(${tyV.n})`;
+    if (tyV.kind === 'uintN')    return `c.Dictionary.Values.BigUint(${tyV.n})`;
+    if (tyV.kind === 'coins')    return `c.Dictionary.Values.BigVarUint(4)`;
+    if (tyV.kind === 'bool')     return `c.Dictionary.Values.Bool()`;
+    if (tyV.kind === 'cell')     return `c.Dictionary.Values.Cell()`;
+
+    ctx.has_customDictV = true;
+    return `${RUNTIME.createDictionaryValue}<${emitTsType(ctx, tyV)}>(${emitLoadCallback(ctx, fieldPath, tyV)}, ${emitStoreCallback(ctx, tyV)})`;
+}
+
+// Emit (de)serializers for c.Dictionary<K, V> (two arguments separated by a comma).
+export function emitDictKVSerializers(ctx: CodegenCtx, fieldPath: string, tyK: Ty, tyV: Ty): string {
+    return emitDictKeySerializer(ctx, fieldPath, tyK) + ', ' + emitDictValueSerializer(ctx, fieldPath, tyV);
+}

package/src/emit-stack-rw.ts

@@ -0,0 +1,239 @@
+import type { Ty } from './abi-types';
+import { CodegenCtx, RUNTIME, SymTable } from './codegen-ctx';
+import { emitTsType, emitDictKVTypeArgs } from './emit-ts-types';
+import { OutBuf, safeFieldDecl } from './formatting';
+import { emitDictKVSerializers, emitLoadCallback, emitMakeCellFromExpr } from './emit-pack-unpack';
+import { NotSupportedTypeOnStack } from './unsupported-errors';
+import { calcWidthOnStack, createLabelsForUnion, instantiateGenerics } from './types-kernel'
+
+// Emit a TS "read {ty} from a stack `r`" expression.
+// Parameter `fieldPath` is used for error messages only.
+// Used to read getters return value, since contract getters work via the stack, not serialization.
+export function emitStackReadExpr(ctx: CodegenCtx, fieldPath: string, ty: Ty, unTupleIfW = false): string {
+    ctx.stackReadsUnknown       ||= ty.kind === 'unknown';
+    ctx.stackReadsArrayOf       ||= ty.kind === 'arrayOf';
+    ctx.stackReadsLispListOf    ||= ty.kind === 'lispListOf';
+    ctx.stackReadsSnakeString   ||= ty.kind === 'string';
+    ctx.stackReadsTuple         ||= ty.kind === 'arrayOf' || ty.kind === 'lispListOf' || ty.kind === 'shapedTuple';
+    ctx.stackReadsMapKV         ||= ty.kind === 'mapKV';
+    ctx.stackReadsBuilder       ||= ty.kind === 'builder';
+    ctx.stackReadsNullable      ||= ty.kind === 'nullable' && ty.stackTypeId === undefined;
+    ctx.stackReadsWideNullable  ||= ty.kind === 'nullable' && ty.stackTypeId !== undefined;
+    ctx.stackReadsUnionType     ||= ty.kind === 'union';
+    ctx.stackReadsCellRef       ||= ty.kind === 'cellOf';
+    ctx.stackReadsNullLiteral   ||= ty.kind === 'nullLiteral';
+
+    if (unTupleIfW) {       // inside `array<T>` or `[T, ...]`, if T is non-primitive, it's a sub-tuple
+        let wOnStack = calcWidthOnStack(ctx.symbols, ty);
+        if (wOnStack !== 1) {
+            return `r.readTuple<${emitTsType(ctx, ty)}>(${wOnStack}, ${emitStackReadCallback(ctx, fieldPath, ty, false)})`;
+        }
+    }
+
+    switch (ty.kind) {
+        case 'int':
+        case 'intN':
+        case 'uintN':
+        case 'varintN':
+        case 'varuintN':
+        case 'coins':       return `r.readBigInt()`;
+        case 'bool':        return `r.readBoolean()`;
+        case 'cell':        return `r.readCell()`;
+        case 'builder':     return `r.readBuilder()`;
+        case 'slice':       return `r.readSlice()`;
+        case 'string':      return `r.readSnakeString()`;
+        case 'remaining':   return `r.readSlice()`;
+        case 'address':     return `r.readSlice().loadAddress()`;
+        case 'addressOpt':  return emitStackReadExpr(ctx, fieldPath, { kind: 'nullable', inner: { kind: 'address' } });
+        case 'addressExt':  return `r.readSlice().loadExternalAddress()`;
+        case 'addressAny':  return `${RUNTIME.loadTolkAddressAny}(r.readSlice())`;
+        case 'bitsN':       return `r.readSlice()`;
+        case 'nullLiteral': return `r.readNullLiteral()`;
+        case 'callable':    throw new NotSupportedTypeOnStack(ty, fieldPath);
+        case 'void':        return `void 0`;
+        case 'unknown':     return `r.readUnknown()`;
+        case 'nullable': {
+            if (ty.stackTypeId) {
+                return `r.readWideNullable<${emitTsType(ctx, ty.inner)}>(${ty.stackWidth}, ${emitStackReadCallback(ctx, fieldPath, ty.inner, false)})`;
+            }
+            return `r.readNullable<${emitTsType(ctx, ty.inner)}>(${emitStackReadCallback(ctx, fieldPath, ty.inner, false)})`;
+        }
+        case 'cellOf':      return `r.readCellRef<${emitTsType(ctx, ty.inner)}>(${emitLoadCallback(ctx, fieldPath + '.ref', ty.inner)})`;
+        case 'arrayOf':     return `r.readArrayOf<${emitTsType(ctx, ty.inner)}>(${emitStackReadCallback(ctx, fieldPath, ty.inner, true)})`;
+        case 'lispListOf':  return `r.readLispListOf<${emitTsType(ctx, ty.inner)}>(${emitStackReadCallback(ctx, fieldPath, ty.inner, true)})`;
+        case 'tensor': {
+            let buf = new OutBuf();
+            buf.push(`[`);
+            for (let i = 0; i < ty.items.length; ++i) {
+                buf.push(emitStackReadExpr(ctx, `${fieldPath}[${i}]`, ty.items[i]) + ',');
+            }
+            buf.push(']');
+            return buf.toString();
+        }
+        case 'shapedTuple': {
+            let buf = new OutBuf();
+            buf.push(`r.readTuple<${emitTsType(ctx, ty)}>(${ty.items.length}, (r) => [`);
+            for (let i = 0; i < ty.items.length; ++i) {
+                buf.push(emitStackReadExpr(ctx, `${fieldPath}[${i}]`, ty.items[i], true) + ',');
+            }
+            buf.push('])');
+            return buf.toString();
+        }
+        case 'mapKV':       return `r.readDictionary<${emitDictKVTypeArgs(ctx, ty.k, ty.v)}>(${emitDictKVSerializers(ctx, fieldPath, ty.k, ty.v)})`;
+        case 'EnumRef':     return `r.readBigInt()`;
+        case 'StructRef': {
+            const structRef = ctx.symbols.getStruct(ty.structName);
+            let buf = new OutBuf();
+            buf.push(`({`);
+            buf.push(`$: '${ty.structName}',`);
+            for (let f of structRef.fields) {
+                const fTy = ty.typeArgs ? instantiateGenerics(f.ty, structRef.typeParams, ty.typeArgs) : f.ty;
+                buf.push(`${safeFieldDecl(f.name)}: ${emitStackReadExpr(ctx, `${fieldPath}.${f.name}`, fTy)},`);
+            }
+            buf.push(`})`);
+            return buf.toString();
+        }
+        case 'AliasRef': {
+            const aliasRef = ctx.symbols.getAlias(ty.aliasName);
+            const targetTy = ty.typeArgs ? instantiateGenerics(aliasRef.targetTy, aliasRef.typeParams, ty.typeArgs) : aliasRef.targetTy;
+            return emitStackReadExpr(ctx, fieldPath, targetTy);
+        }
+        case 'genericT':    throw new Error(`unexpected genericT=${ty.nameT} in '${fieldPath}'`);
+        case 'union': {
+            const variants = createLabelsForUnion(ctx.symbols, ty.variants);
+            let buf = new OutBuf();
+            buf.push(`r.readUnionType<${emitTsType(ctx, ty)}>(${ty.stackWidth}, {`);
+            for (let v of variants) {
+                buf.push(`${v.stackTypeId}: [${v.stackWidth}, ${v.hasValueField ? `'${v.labelStr}'` : 'null'}, ${emitStackReadCallback(ctx, `${fieldPath}#${v.stackTypeId}`, v.variantTy, false)}],`);
+            }
+            buf.push(`})`);
+            return buf.toString();
+        }
+    }
+}
+
+// Emit a TS "read {ty} from a stack `r`" callback (not expression).
+// Callbacks are passed for generics — for example, to read a nullable (when a stack slot is not null).
+function emitStackReadCallback(ctx: CodegenCtx, fieldPath: string, ty: Ty, unTupleIfW: boolean): string {
+    return OutBuf.onNewLine(`(r) => ${emitStackReadExpr(ctx, fieldPath, ty, unTupleIfW)}`);
+}
+
+// Emit a TS "write {expr of type ty} to a stack" expression compatible with @ton/core TupleItem.
+// Used to pass getters arguments, since contract getters work via the stack, not serialization.
+// Parameter `tsExpr` is a valid expression: "p1.field", "p2[0]", "ith" (inside a callback), and other.
+export function emitStackWriteItems(ctx: CodegenCtx, tsExpr: string, ty: Ty, tupleIfW: boolean = false): string[] {
+    if (tupleIfW) {       // inside `array<T>` or `[T, ...]`, if T is non-primitive, it's a sub-tuple
+        if (calcWidthOnStack(ctx.symbols, ty) === 1) {
+            return emitStackWriteItems(ctx, tsExpr, ty, false);
+        }
+        let buf = new OutBuf();
+        buf.push(`{ type: 'tuple', items: [`);
+        for (let line of emitStackWriteItems(ctx, tsExpr, ty, false)) {
+            buf.push(line + ',');
+        }
+        buf.push(`]}`);
+        return [buf.toString()];
+    }
+
+    switch (ty.kind) {
+        case 'int':
+        case 'intN':
+        case 'uintN':
+        case 'varintN':
+        case 'varuintN':
+        case 'coins':       return [`{ type: 'int', value: ${tsExpr} }`];
+        case 'bool':        return [`{ type: 'int', value: (${tsExpr} ? -1n : 0n) }`];
+        case 'cell':        return [`{ type: 'cell', cell: ${tsExpr} }`];
+        case 'builder':     return [`{ type: 'builder', cell: ${emitMakeCellFromExpr(ctx, tsExpr, ty)} }`];
+        case 'slice':       return [`{ type: 'slice', cell: ${RUNTIME.beginCell}().storeSlice(${tsExpr}).endCell() }`];
+        case 'string':      return [`{ type: 'cell', cell: ${RUNTIME.beginCell}().storeStringTail(${tsExpr}).endCell() }`];
+        case 'remaining':   return [`{ type: 'slice', cell: ${emitMakeCellFromExpr(ctx, tsExpr, ty)} }`];
+        case 'address':     return [`{ type: 'slice', cell: ${emitMakeCellFromExpr(ctx, tsExpr, ty)} }`];
+        case 'addressOpt':  return emitStackWriteItems(ctx, tsExpr, { kind: 'nullable', inner: { kind: 'address' } });
+        case 'addressExt':  return [`{ type: 'slice', cell: ${emitMakeCellFromExpr(ctx, tsExpr, ty)} }`];
+        case 'addressAny':  return [`{ type: 'slice', cell: ${emitMakeCellFromExpr(ctx, tsExpr, ty)} }`];
+        case 'bitsN':       return [`{ type: 'slice', cell: ${emitMakeCellFromExpr(ctx, tsExpr, ty)} }`];
+        case 'nullLiteral': return [`{ type: 'null' }`];
+        case 'callable':    throw new NotSupportedTypeOnStack(ty, tsExpr);
+        case 'void':        return [];
+        case 'unknown':     return [tsExpr];
+        case 'nullable': {
+            if (ty.stackTypeId) {
+                let buf = new OutBuf();
+                buf.push(`...(`);
+                buf.push(`${tsExpr} === null ? [`);
+                for (let i = 0; i < ty.stackWidth! - 1; ++i) {
+                    buf.push(`{ type: 'null' },`);
+                }
+                buf.push(`{ type: 'int', value: 0n },`);
+                buf.push(`] : [`);
+                emitStackWriteItems(ctx, tsExpr, ty.inner).forEach(w =>
+                    buf.push(w + ',')
+                );
+                buf.push(`{ type: 'int', value: ${ty.stackTypeId}n },`);
+                buf.push(`]`);
+                buf.push(`) as c.TupleItem[]`);
+                return [buf.toString()];
+            }
+            return [`${tsExpr} === null ? { type: 'null' } : ${emitStackWriteItems(ctx, tsExpr, ty.inner)[0]}`];
+        }
+        case 'cellOf':      return [`{ type: 'cell', cell: ${emitMakeCellFromExpr(ctx, `${tsExpr}.ref`, ty.inner)} }`];
+        case 'arrayOf':     return [`{ type: 'tuple', items: ${tsExpr}.map(${OutBuf.onNewLine(`(ith) => (${emitStackWriteItems(ctx, 'ith', ty.inner, true)})`)})}`];
+        case 'tensor':      return ty.items.flatMap((item, idx) => emitStackWriteItems(ctx, `${tsExpr}[${idx}]`, item));
+        case 'shapedTuple': {
+            let buf = new OutBuf();
+            buf.push(`{ type: 'tuple', items: [`);
+            for (let i = 0; i < ty.items.length; ++i) {
+                buf.push(emitStackWriteItems(ctx, `${tsExpr}[${i}]`, ty.items[i], true)[0] + ',');
+            }
+            buf.push(']}');
+            return [buf.toString()];
+        }
+        case 'lispListOf': {
+            let buf = new OutBuf();
+            buf.push(`${tsExpr}.reduceRight((tail, head) => ({ type: 'tuple', items: [`);
+            buf.push(emitStackWriteItems(ctx, `head`, ty.inner, true)[0] + ',');
+            buf.push('tail');
+            buf.push(`]}), { type: 'null' } as c.TupleItem)`);
+            return [buf.toString()];
+        }
+        case 'mapKV':       return [`${tsExpr}.size === 0 ? { type: 'null' } : { type: 'cell', cell: ${RUNTIME.beginCell}().storeDictDirect<${emitDictKVTypeArgs(ctx, ty.k, ty.v)}>(${tsExpr}, ${emitDictKVSerializers(ctx, tsExpr, ty.k, ty.v)}).endCell() }`];
+        case 'EnumRef':     return [`{ type: 'int', value: ${tsExpr} }`];
+        case 'StructRef': {
+            const structRef = ctx.symbols.getStruct(ty.structName);
+            return structRef.fields.flatMap(f => {
+                const fTy = ty.typeArgs ? instantiateGenerics(f.ty, structRef.typeParams, ty.typeArgs) : f.ty;
+                return emitStackWriteItems(ctx, `${tsExpr}.${f.name}`, fTy);
+            });
+        }
+        case 'AliasRef': {
+            const aliasRef = ctx.symbols.getAlias(ty.aliasName);
+            const targetTy = ty.typeArgs ? instantiateGenerics(aliasRef.targetTy, aliasRef.typeParams, ty.typeArgs) : aliasRef.targetTy;
+            return emitStackWriteItems(ctx, tsExpr, targetTy);
+        }
+        case 'genericT':    throw new Error(`unexpected genericT=${ty.nameT} in '${tsExpr}'`);
+        case 'union': {
+            const variants = createLabelsForUnion(ctx.symbols, ty.variants);
+            variants.sort((a, b) => a.stackTypeId - b.stackTypeId);  // move `null` variant (if exists) to the top
+            let buf = new OutBuf();
+            buf.push(`...(`);
+            for (let v of variants) {
+                if (v.labelStr === '')
+                    buf.push(`${tsExpr} === null ? [`)
+                else
+                    buf.push(`${tsExpr}.$ === '${v.labelStr}' ? [`);
+                for (let i = 0; i < ty.stackWidth - 1 - v.stackWidth; ++i) {
+                    buf.push(`{ type: 'null' },`);
+                }
+                emitStackWriteItems(ctx, v.hasValueField ? tsExpr + '.value' : tsExpr, v.variantTy).forEach(w =>
+                    buf.push(w + ',')
+                );
+                buf.push(`{ type: 'int', value: ${v.stackTypeId}n },`);
+                buf.push(`] :`);
+            }
+            buf.push(`(() => { throw new Error('invalid $ field in a union') })()`);
+            buf.push(`) as c.TupleItem[]`);
+            return [buf.toString()];
+        }
+    }
+}

package/src/emit-ts-types.ts

@@ -0,0 +1,66 @@
+import type { Ty } from './abi-types';
+import { CodegenCtx } from './codegen-ctx';
+import { safeJsIdent } from './formatting';
+import { createLabelsForUnion, UnionVariantLabeled } from './types-kernel';
+
+// Given a union `T1 | T2` after detecting whether each `T_i` should have `$ + value`,
+// stringify it
+export function emitUnionLabelAndValue(label: UnionVariantLabeled, contents: string): string {
+    return label.hasValueField ? `{ $: '${label.labelStr}', value: ${contents} }` : contents;
+}
+
+// Convert any Tolk type (ABI representation) to a corresponding TypeScript type.
+// Tolk `int32` -> TS `bigint`, but for readability, `type int32 = bigint` is created.
+// `c.` is import @ton/core.
+export function emitTsType(ctx: CodegenCtx, ty: Ty): string {
+    if (ty.kind === 'intN')         ctx.intNOccurred.add(`int${ty.n}`);
+    if (ty.kind === 'uintN')        ctx.uintNOccurred.add(`uint${ty.n}`);
+    if (ty.kind === 'varintN')      ctx.varIntNOccurred.add(`varint${ty.n}`);
+    if (ty.kind === 'varuintN')     ctx.varIntNOccurred.add(`varuint${ty.n}`);
+    if (ty.kind === 'bitsN')        ctx.bitsNOccurred.add(`bits${ty.n}`)
+    if (ty.kind === 'remaining')    ctx.has_RemainingBitsAndRefs = true;
+    if (ty.kind === 'addressAny')   ctx.has_addressAny = true;
+    if (ty.kind === 'arrayOf')      ctx.has_arrayOf = true;
+    if (ty.kind === 'lispListOf')   ctx.has_lispListOf = true;
+
+    switch (ty.kind) {
+        case 'int':         return `bigint`;
+        case 'intN':        return `int${ty.n}`;
+        case 'uintN':       return `uint${ty.n}`;
+        case 'varintN':     return `varint${ty.n}`;
+        case 'varuintN':    return `varuint${ty.n}`;
+        case 'coins':       return `coins`;
+        case 'bool':        return `boolean`;
+        case 'cell':        return `c.Cell`;
+        case 'builder':     return `c.Builder`;
+        case 'slice':       return `c.Slice`;
+        case 'string':      return 'string';
+        case 'remaining':   return `RemainingBitsAndRefs`;
+        case 'address':     return `c.Address`;
+        case 'addressOpt':  return `c.Address | null`;
+        case 'addressExt':  return `c.ExternalAddress`;
+        case 'addressAny':  return `any_address`;
+        case 'bitsN':       return `bits${ty.n}`;
+        case 'nullLiteral': return `null`;
+        case 'callable':    return `any`;
+        case 'void':        return `void`;
+        case 'unknown':     return `c.TupleItem`;
+        case 'nullable':    return `${emitTsType(ctx, ty.inner)} | null`;
+        case 'cellOf':      return `CellRef<${emitTsType(ctx, ty.inner)}>`;
+        case 'arrayOf':     return `array<${emitTsType(ctx, ty.inner)}>`;
+        case 'lispListOf':  return `lisp_list<${emitTsType(ctx, ty.inner)}>`;
+        case 'tensor':      return `[${ty.items.map(item => emitTsType(ctx, item)).join(', ')}]`;
+        case 'shapedTuple': return `[${ty.items.map(item => emitTsType(ctx, item)).join(', ')}]`;
+        case 'mapKV':       return `c.Dictionary<${emitDictKVTypeArgs(ctx, ty.k, ty.v)}>`;
+        case 'EnumRef':     return ty.enumName;
+        case 'StructRef':   return safeJsIdent(ty.structName) + (ty.typeArgs ? `<${ty.typeArgs.map(ta => emitTsType(ctx, ta)).join(', ')}>` : '');
+        case 'AliasRef':    return safeJsIdent(ty.aliasName) + (ty.typeArgs ? `<${ty.typeArgs.map(ta => emitTsType(ctx, ta)).join(', ')}>` : '');
+        case 'genericT':    return ty.nameT;
+        case 'union':       return createLabelsForUnion(ctx.symbols, ty.variants).map(v => emitUnionLabelAndValue(v, emitTsType(ctx, v.variantTy))).join(' | ');
+    }
+}
+
+// Emit c.Dictionary<K, V> (K and V — inside brackets, two types separated by comma).
+export function emitDictKVTypeArgs(ctx: CodegenCtx, tyK: Ty, tyV: Ty): string {
+    return emitTsType(ctx, tyK) + ', ' + emitTsType(ctx, tyV);
+}