gen-typescript-from-tolk-dev 0.1.0

package/src/types-kernel.ts

@@ -0,0 +1,215 @@
+import type { Ty, UnionVariant } from './abi-types';
+import { SymTable } from './codegen-ctx';
+
+/*
+    Contains basic functions working with ABI types,
+  which are used both for generating wrappers and dynamic serialization.
+    They do not emit TypeScript expressions and do not depend on CodegenCtx and DynamicCtx.
+ */
+
+// Render intermediate representation back to a valid Tolk type, exactly as it was in original sources.
+export function renderTy(ty: Ty): string {
+    switch (ty.kind) {
+        case 'int':         return `int`;
+        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 `bool`;
+        case 'cell':        return `cell`;
+        case 'builder':     return `builder`;
+        case 'slice':       return `slice`;
+        case 'string':      return `string`;
+        case 'remaining':   return `RemainingBitsAndRefs`;
+        case 'address':     return `address`;
+        case 'addressOpt':  return `address?`;
+        case 'addressExt':  return `ext_address`;
+        case 'addressAny':  return `any_address`;
+        case 'bitsN':       return `bits${ty.n}`;
+        case 'nullLiteral': return `null`;
+        case 'callable':    return `continuation`;
+        case 'void':        return `void`;
+        case 'unknown':     return `unknown`;
+        case 'nullable':    return `${renderTy(ty.inner)}?`;
+        case 'cellOf':      return `Cell<${renderTy(ty.inner)}>`;
+        case 'arrayOf':     return `array<${renderTy(ty.inner)}>`;
+        case 'lispListOf':  return `lisp_list<${renderTy(ty.inner)}>`;
+        case 'tensor':      return `(${ty.items.map(renderTy).join(', ')})`;
+        case 'shapedTuple': return `[${ty.items.map(renderTy).join(', ')}]`;
+        case 'mapKV':       return `map<${renderTy(ty.k)}, ${renderTy(ty.v)}>`;
+        case 'EnumRef':     return ty.enumName;
+        case 'StructRef':   return ty.structName + (ty.typeArgs ? `<${ty.typeArgs.map(renderTy).join(', ')}>` : '');
+        case 'AliasRef':    return ty.aliasName + (ty.typeArgs ? `<${ty.typeArgs.map(renderTy).join(', ')}>` : '');
+        case 'genericT':    return ty.nameT;
+        case 'union':       return ty.variants.map(v => renderTy(v.variantTy)).join(' | ');
+    }
+}
+
+// Union types from Tolk are represented as union types in TypeScript, with some nuances.
+// For structures, like `A | B`, every struct (TS interface) has its own `$` field,
+// that's why it's emitted directly `type U = A | B`.
+// For primitives, like `int32 | int64`, every type is prefixed with a `$` field (label):
+// `type U = { $: 'int32', value: bigint } | { $: 'int64', value: bigint }`
+// Hence, for every union variant, we calculate whether we need to expose `$ + value`.
+export interface UnionVariantLabeled extends UnionVariant {
+    labelStr: string            // value for implicit or explicit `$`: 'A' / 'B' / 'int32' / etc.
+    hasValueField: boolean      // whether we need `$ + value` (a type has no `$` on its own)
+}
+
+// A "label" is the `$` field in TypeScript output, used to differentiate structs and union variants.
+// Tolk `int32 | int64` -> TS `{ $: 'int32', value: bigint } | { $: 'int64', value: bigint }`.
+// This function creates a string for `$`.
+function createLabel(symbols: SymTable, ty: Ty): string {
+    switch (ty.kind) {
+        case 'int':         return `int`;
+        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 `bool`;
+        case 'cell':        return `cell`;
+        case 'builder':     return `builder`;
+        case 'slice':       return `slice`;
+        case 'string':      return `string`;
+        case 'remaining':   return `RemainingBitsAndRefs`;
+        case 'address':     return `address`;
+        case 'addressOpt':  return `address?`;
+        case 'addressExt':  return `ext_address`;
+        case 'addressAny':  return `any_address`;
+        case 'bitsN':       return `bits${ty.n}`;
+        case 'nullLiteral': return `null`;
+        case 'callable':    return `callable`;
+        case 'void':        return `void`;
+        case 'unknown':     return `unknown`;
+        case 'nullable':    return `${createLabel(symbols, ty.inner)}?`;
+        case 'cellOf':      return `Cell`;
+        case 'arrayOf':     return `array`;
+        case 'lispListOf':  return `lisp_list`;
+        case 'tensor':      return `tensor`;
+        case 'shapedTuple': return `shaped`;
+        case 'mapKV':       return `map`;
+        case 'EnumRef':     return ty.enumName;
+        case 'StructRef':   return ty.structName;
+        case 'AliasRef':    return createLabel(symbols, symbols.getAliasTarget(ty.aliasName));
+        case 'genericT':    return ty.nameT;
+        case 'union':       return ty.variants.map(v => createLabel(symbols, v.variantTy)).join('|');
+    }
+}
+
+// Every Tolk struct is generated as TS `interface` with `$` field.
+// Tolk `struct A { ... }` -> TS `interface A { $: 'A', ... }`.
+// So, Tolk `A | B` is represented as TS `A | B` (unlike primitives),
+// because every struct has its own label.
+function isStructWithItsOwnLabel(symbols: SymTable, ty: Ty): boolean {
+    if (ty.kind === 'StructRef')    return true;
+    if (ty.kind === 'AliasRef')     return isStructWithItsOwnLabel(symbols, symbols.getAliasTarget(ty.aliasName));
+    return false;
+}
+
+// Given a union `T1 | T2 | ...`, calculate a TypeScript representation:
+// whether each variant should be `$ + value` or not, and what string does `$` hold.
+export function createLabelsForUnion(symbols: SymTable, variants: UnionVariant[]): UnionVariantLabeled[] {
+    // in all practical cases, `T_i` is a structure or a primitive;
+    // we try to shorten a label (`createLabel()` is a "simple string of a type"):
+    // - for a generic struct, use `Wrapper`, not `Wrapper<xxx>`
+    // - for `Cell<...>`, use a shorthand `Cell`
+    // - etc.
+    // but if it results in a duplicate (e.g. `Wrapper<int32> | Wrapper<int64>` => ['Wrapper','Wrapper']),
+    // then full-string Tolk types are used, and `value` is always required:
+    // `type U = { $: 'Wrapper<int32>', value: Wrapper<int32> } | ...`
+    let unique: Set<string> = new Set();
+    let hasDuplicates = false;
+    variants.forEach(variant => {
+        let labelStr = createLabel(symbols, variant.variantTy);
+        hasDuplicates ||= unique.has(labelStr);
+        unique.add(labelStr);
+    });
+
+    return variants.map(variant => {
+        let variantTy = variant.variantTy;
+        if (variantTy.kind === 'nullLiteral') {
+            return { ...variant, labelStr: '', hasValueField: false };
+        }
+        return {
+            ...variant,
+            labelStr: hasDuplicates ? renderTy(variantTy) : createLabel(symbols, variantTy),
+            hasValueField: hasDuplicates ? true : !isStructWithItsOwnLabel(symbols, variantTy)
+        };
+    });
+}
+
+// Replace all generic Ts (typeParams) with instantiation (typeArgs) recursively.
+// Example: `(int, T, Wrapper<T?>)` and T=coins => `(int, coins, Wrapper<coins?>)`
+export function instantiateGenerics(ty: Ty, typeParams: string[] | undefined, typeArgs: Ty[]): Ty {
+    if (ty.kind === 'nullable')     return { ...ty, inner: instantiateGenerics(ty.inner, typeParams, typeArgs) };
+    if (ty.kind === 'cellOf')       return { ...ty, inner: instantiateGenerics(ty.inner, typeParams, typeArgs) };
+    if (ty.kind === 'arrayOf')      return { ...ty, inner: instantiateGenerics(ty.inner, typeParams, typeArgs) };
+    if (ty.kind === 'lispListOf')   return { ...ty, inner: instantiateGenerics(ty.inner, typeParams, typeArgs) };
+    if (ty.kind === 'tensor')       return { ...ty, items: ty.items.map(item => instantiateGenerics(item, typeParams, typeArgs)) };
+    if (ty.kind === 'shapedTuple')  return { ...ty, items: ty.items.map(item => instantiateGenerics(item, typeParams, typeArgs)) };
+    if (ty.kind === 'mapKV')        return { ...ty, k: instantiateGenerics(ty.k, typeParams, typeArgs), v: instantiateGenerics(ty.v, typeParams, typeArgs) };
+    if (ty.kind === 'StructRef')    return { ...ty, typeArgs: ty.typeArgs?.map(ta => instantiateGenerics(ta, typeParams, typeArgs)) };
+    if (ty.kind === 'AliasRef')     return { ...ty, typeArgs: ty.typeArgs?.map(ta => instantiateGenerics(ta, typeParams, typeArgs)) };
+    if (ty.kind === 'union')        return { ...ty, variants: ty.variants.map(v => ({ ...v, variantTy: instantiateGenerics(v.variantTy, typeParams, typeArgs) })) };
+    if (ty.kind === 'genericT') {
+        const idx = typeParams?.indexOf(ty.nameT);
+        if (idx === undefined || idx === -1 || idx >= typeArgs.length)
+            throw new Error(`inconsistent generics: could not find type argument for ${ty.nameT}`)
+        return typeArgs[idx]
+    }
+    return ty;
+}
+
+// Calculate, how many stack slots a type occupies.
+export function calcWidthOnStack(symbols: SymTable, ty: Ty): number {
+    switch (ty.kind) {
+        case 'void': {
+            // void is like "unit", equal to an empty tensor
+            return 0;
+        }
+        case 'tensor': {
+            // a tensor is a sum of its elements
+            return ty.items.map(item => calcWidthOnStack(symbols, item)).reduce((p, c) => p + c, 0);
+        }
+        case 'StructRef': {
+            // a struct is a named tensor: fields one by one;
+            // if a struct is generic `Wrapper<T>`, we have typeArgs T=xxx, and replace T in each field
+            // (it works unless `T` is used in unions)
+            const structRef = symbols.getStruct(ty.structName);
+            return structRef.fields.map(f => {
+                const fTy = ty.typeArgs ? instantiateGenerics(f.ty, structRef.typeParams, ty.typeArgs) : f.ty;
+                return calcWidthOnStack(symbols, fTy);
+            }).reduce((p, c) => p + c, 0);
+        }
+        case 'AliasRef': {
+            // an alias is the same as its underlying (target) type;
+            // if an alias is generic `Maybe<T>`, we have typeArgs T=xxx, and replace T in its target
+            const aliasRef = symbols.getAlias(ty.aliasName);
+            const targetTy = ty.typeArgs ? instantiateGenerics(aliasRef.targetTy, aliasRef.typeParams, ty.typeArgs) : aliasRef.targetTy;
+            return calcWidthOnStack(symbols, targetTy);
+        }
+        case 'nullable': {
+            // for primitive nullables (common case), like `int?` and `address?`, it's 1 (TVM value or NULL);
+            // for non-primitive nullables, the compiler inserts stackWidth and stackTypeId
+            return ty.stackWidth ?? 1;
+        }
+        case 'union': {
+            // for union types, the compiler always inserts stackWidth for simplicity (and stackTypeId for each variant)
+            return ty.stackWidth;
+        }
+        case 'genericT': {
+            // all generics must have been instantiated up to this point
+            throw new Error(`unexpected genericT=${ty.nameT} in calcWidthOnStack`);
+        }
+        default: {
+            // almost all types are TVM primitives that occupy 1 stack slot:
+            // - intN is TVM INT
+            // - array<T> is TVM TUPLE
+            // - map<K, V> is TVM DICT or NULL
+            // etc.
+            return 1;
+        }
+    }
+}

package/src/unsupported-errors.ts

@@ -0,0 +1,82 @@
+import type { Ty } from './abi-types';
+import { renderTy } from './types-kernel'
+
+// Fired when LSP (temporary used for parsing Tolk files into ABI)
+// can not be initialized, or has unresolved types, or other errors while parsing Tolk sources.
+export class CantParseInputTolkFile extends Error {
+    constructor(message: string) {
+        super(message);
+    }
+}
+
+// Fired when TyRef contains unresolved symbols,
+// e.g. { kind: 'StructRef', structName: 'non-existing' }
+export class SymbolNotFound extends Error {
+    constructor(symbolKind: string, notFoundName: string) {
+        super(`${symbolKind} ${notFoundName} not found`);
+    }
+}
+
+// Fired if serialization to/from cells can not be applied to a specific type/struct.
+// E.g., a struct contains `int` (not int32/uint64): it's used only in contract getters.
+// For such structs, `fromSlice`/`store` is just `throw` with description
+// (the overall process of generating wrappers continues, only a specific struct can't be serialized).
+export class CantGeneratePackUnpack extends Error {
+    constructor(message: string) {
+        super(message);
+    }
+}
+
+// `Dictionary<K, V>` from @ton/core allows only predefined KeyT.
+// For others, we can not generate wrappers at all (not only to/from cell, but even declarations).
+export class NonStandardDictKey extends Error {
+    constructor(message: string) {
+        super(message);
+    }
+}
+
+// Some types, like callables/lambdas, can not be used in get methods, we can't generate wrappers then.
+export class NotSupportedTypeOnStack extends Error {
+    constructor(ty: Ty, fieldPath: string) {
+        super(`'${fieldPath}' can not be used in get methods, because it contains '${renderTy(ty)}'`);
+    }
+}
+
+// This error is fired "to the outer world".
+export class CantGenerateWrappersAtAll extends Error {
+    constructor(where: string, prevEx: any) {
+        super(`${where}: [${prevEx.constructor.name}] ${prevEx.message ?? prevEx.toString()}`);
+    }
+}
+
+// This error is fired when invalid input is passed into dynamic serialization.
+// For example, passed an object instead of a number, a field is missing, etc.
+export class InvalidDynamicInput extends Error {
+    constructor(msg: string) {
+        super(msg);
+    }
+}
+
+// This error is fired when dynamic serialization (from a JS object to a cell) failed.
+// For example, passed an object instead of a number, a field is missing, etc.
+export class CantPackDynamic extends Error {
+    constructor(fieldPath: string, msg: string) {
+        super(`cannot serialize '${fieldPath}' dynamically: ${msg}`);
+    }
+}
+
+// This error is fired when dynamic deserialization (from a cell into a JS object) failed.
+// For example, none of union prefixes match.
+export class CantUnpackDynamic extends Error {
+    constructor(fieldPath: string, msg: string) {
+        super(`cannot deserialize '${fieldPath}' dynamically: ${msg}`);
+    }
+}
+
+// This error is fired when dynamic calling get method (from a JS object to a TVM tuple) failed.
+// For example, passed an object instead of a number, a field is missing, etc.
+export class CantCallGetMethodDynamic extends Error {
+    constructor(getMethodName: string, msg: string) {
+        super(`cannot call get method '${getMethodName}' dynamically: ${msg}`);
+    }
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+    "compilerOptions": {
+        "target": "ES2020",
+        "outDir": "dist",
+        "module": "commonjs",
+        "declaration": true,
+        "esModuleInterop": true,
+        "forceConsistentCasingInFileNames": true,
+        "strict": true,
+        "skipLibCheck": true,
+        "baseUrl": "."
+    }
+}