@ohos-ports/azle 0.33.0-beta.0

package/src/stable/lib/did_file/idl_to_string.ts

@@ -0,0 +1,79 @@
+import { IDL } from '@dfinity/candid';
+
+import {
+    CandidTypesDefs,
+    DidVisitor,
+    getDefaultVisitorData,
+    VisitorData,
+    VisitorResult
+} from './visitor';
+
+/**
+ * Converts an IDL type to its string representation in Candid format.
+ *
+ * @param type - The IDL type to convert to a string
+ * @param startingData - Optional visitor data to use during traversal. Defaults to empty visitor data.
+ * @returns The Candid string representation of the type
+ *
+ * @example
+ * const recordType = IDL.Record({ name: IDL.Text, age: IDL.Nat8 });
+ * const candidStr = idlToString(recordType);
+ * // Result: "record { name : text; age : nat8 }"
+ */
+
+export function idlToString(
+    type: IDL.Type,
+    startingData: VisitorData = getDefaultVisitorData()
+): string {
+    const result = type.accept(new DidVisitor(), startingData);
+    return toDidString(result);
+}
+
+/**
+ * @internal
+ *
+ * Converts a Candid type visitor result into a formatted Candid interface definition string.
+ * Used to generate .did files from TypeScript canister definitions.
+ *
+ * @param result - The visitor result containing Candid type definitions and service interface
+ * @returns A formatted string containing the complete Candid interface definition
+ *
+ * @remarks
+ * - Combines named type definitions with the service interface
+ * - Handles recursive type definitions (currently using numeric suffixes)
+ * - Preserves type relationships and structure
+ * - Adds proper newlines for formatting
+ *
+ * @example
+ * const visitorResult = visitCanister(canisterClass);
+ * const didString = toDidString(visitorResult);
+ * // Result:
+ * // type MyRecord = record { field: text };
+ * // service : {
+ * //   method : (MyRecord) -> (bool);
+ * // }
+ */
+export function toDidString(result: VisitorResult): string {
+    // TODO it would be nice to have names for the rec types instead of rec_1, rec_2 etc
+    // TODO Once types have names we should deduplicate the init and post_upgrade param types
+    // TODO maybe even before we have names we should deduplicate all sorts of types
+    // The rust to candid converter we were using did have names, but if two things
+    // had the same shape they got merged into one type that had one of the names.
+    // That might not be the ideal situation, but it is the expected behavior in rust
+
+    const [candid, candidTypeDefs] = result;
+    const candidTypesString = namedTypeToCandidString(candidTypeDefs);
+    return `${candidTypesString + candid}\n`;
+}
+
+function namedTypeToCandidString(newTypes: CandidTypesDefs): string {
+    return Object.entries(newTypes).length > 0
+        ? `${namedTypesToStingArr(newTypes).join('\n')}\n`
+        : '';
+}
+
+function namedTypesToStingArr(newTypes: CandidTypesDefs): string[] {
+    return Object.entries(newTypes).map(
+        ([name, candid]) => `type ${name} = ${candid};`
+    );
+}

package/src/stable/lib/did_file/index.ts

@@ -0,0 +1,2 @@
+export { idlToString } from './idl_to_string';
+export * from './visitor';

package/src/stable/lib/did_file/visitor/did_visitor.ts

@@ -0,0 +1,135 @@
+import { GenericIdlFuncArgs, IDL } from '@dfinity/candid';
+
+import { visitFunc } from './visit/func';
+import { visitOpt } from './visit/opt';
+import { visitPrimitive } from './visit/primitive';
+import { visitRecord } from './visit/record';
+import { visitRecursive } from './visit/recursive';
+import { visitService } from './visit/service';
+import { visitTuple } from './visit/tuple';
+import { visitVariant } from './visit/variant';
+import { visitVec } from './visit/vec';
+
+/**
+ * Configuration data passed through the Candid type visitor system.
+ * Controls visitor behavior and tracks state during traversal.
+ */
+export type VisitorData = {
+    /** Tracks recursive types to prevent infinite loops */
+    usedRecClasses: IDL.RecClass[];
+    /** Indicates if currently visiting a service definition */
+    isOnService: boolean;
+    /** Indicates if this is the first/primary service being processed */
+    isFirstService: boolean;
+    /** Collection of IDL func argument types for \@init and \@postUpgrade methods */
+    initAndPostUpgradeParamIdlTypes: GenericIdlFuncArgs;
+};
+
+/**
+ * Result tuple returned by visitor operations.
+ * Combines Candid definitions with their associated type definitions.
+ */
+export type VisitorResult = [CandidDef, CandidTypesDefs];
+
+/**
+ * Name of a Candid type definition.
+ * Used as keys in the type definition map.
+ */
+export type TypeName = string;
+
+/**
+ * String representation of a Candid type or definition.
+ * The actual Candid syntax for a type, method, or service.
+ */
+export type CandidDef = string;
+
+/**
+ * Map of named type definitions in a Candid interface.
+ * Keys are type names, values are their Candid definitions.
+ */
+export type CandidTypesDefs = { [key: TypeName]: CandidDef };
+
+/**
+ * Creates default visitor configuration data.
+ * Used to initialize the visitor system for processing a canister's types.
+ *
+ * @returns Fresh VisitorData with empty tracking collections
+ */
+export function getDefaultVisitorData(): VisitorData {
+    return {
+        usedRecClasses: [],
+        isOnService: false,
+        isFirstService: false,
+        initAndPostUpgradeParamIdlTypes: []
+    };
+}
+
+/**
+ * Visitor implementation for converting TypeScript/IDL types to Candid definitions.
+ * Extends the IDL.Visitor to handle all Candid type constructs.
+ *
+ * Used to generate .did interface files from canister class definitions.
+ * Processes types recursively while maintaining proper scoping and type relationships.
+ *
+ * @example
+ * const visitor = new DidVisitor();
+ * const myType = new IDL.Service({...implementation});
+ * const result = myType.accept(visitor, getDefaultVisitorData());
+ * const candidString = toDidString(result);
+ */
+export class DidVisitor extends IDL.Visitor<VisitorData, VisitorResult> {
+    visitService(t: IDL.ServiceClass, data: VisitorData): VisitorResult {
+        return visitService(t, this, data);
+    }
+    visitPrimitive<T>(
+        t: IDL.PrimitiveType<T>,
+        _data: VisitorData
+    ): VisitorResult {
+        return visitPrimitive(t);
+    }
+    visitTuple<T extends any[]>(
+        _t: IDL.TupleClass<T>,
+        components: IDL.Type<any>[],
+        data: VisitorData
+    ): VisitorResult {
+        return visitTuple(components, this, data);
+    }
+    visitOpt<T>(
+        _t: IDL.OptClass<T>,
+        ty: IDL.Type<T>,
+        data: VisitorData
+    ): VisitorResult {
+        return visitOpt(ty, this, data);
+    }
+    visitVec<T>(
+        _t: IDL.VecClass<T>,
+        ty: IDL.Type<T>,
+        data: VisitorData
+    ): VisitorResult {
+        return visitVec(ty, this, data);
+    }
+    visitFunc(t: IDL.FuncClass, data: VisitorData): VisitorResult {
+        return visitFunc(t, this, data);
+    }
+    visitRec<T>(
+        t: IDL.RecClass<T>,
+        ty: IDL.ConstructType<T>,
+        data: VisitorData
+    ): VisitorResult {
+        return visitRecursive(t, ty, this, data);
+    }
+    visitRecord(
+        _t: IDL.RecordClass,
+        fields: [string, IDL.Type<any>][],
+        data: VisitorData
+    ): VisitorResult {
+        return visitRecord(fields, this, data);
+    }
+    visitVariant(
+        _t: IDL.VariantClass,
+        fields: [string, IDL.Type<any>][],
+        data: VisitorData
+    ): VisitorResult {
+        return visitVariant(fields, this, data);
+    }
+}

package/src/stable/lib/did_file/visitor/escape_candid_name.ts

@@ -0,0 +1,100 @@
+/**
+ * @internal
+ *
+ * Internal list of Candid language keywords that need to be escaped in identifiers.
+ *
+ * These keywords cannot be used as raw identifiers in Candid and must be escaped when used as field names.
+ */
+const CANDID_KEYWORDS = [
+    'blob',
+    'bool',
+    'composite_query',
+    'empty',
+    'float32',
+    'float64',
+    'func',
+    'import',
+    'int',
+    'int16',
+    'int32',
+    'int64',
+    'int8',
+    'nat',
+    'nat16',
+    'nat32',
+    'nat64',
+    'nat8',
+    'null',
+    'oneway',
+    'opt',
+    'principal',
+    'query',
+    'record',
+    'reserved',
+    'service',
+    'text',
+    'type',
+    'variant',
+    'vec'
+];
+
+/**
+ * @internal
+ *
+ * Internal helper that escapes Candid names if they are reserved keywords or contain special characters.
+ *
+ * These names cannot be used as raw identifiers in Candid and must be escaped when used as names.
+ *
+ * @param key - The name to potentially escape
+ * @returns The name, escaped if it's a reserved Candid keyword or contains special characters.
+ *
+ * @example
+ * escapeCandidName('text')     // returns '"text"'
+ * escapeCandidName('myField')  // returns 'myField'
+ * escapeCandidName('3nameWithNumber')  // returns '"3nameWithNumber"'
+ * escapeCandidName('nameWith(Parentheses)')  // returns '"nameWith(Parentheses)"'
+ * escapeCandidName('nameWith"Quotes"')  // returns '"nameWith\\"Quotes\\""'
+ */
+export function escapeCandidName(key: string): string {
+    // Candid name is either an id or a text
+    // <name> ::= <id> | <text>
+
+    // <id>   ::= (A..Z|a..z|_)(A..Z|a..z|_|0..9)*
+    const isId = /^[A-Za-z_][A-Za-z0-9_]*$/.test(key);
+    if (isId === true) {
+        return escapeId(key);
+    }
+
+    // Key is text
+    // <text> ::= "<char>*"
+    return escapeText(key);
+}
+
+function escapeId(key: string): string {
+    if (CANDID_KEYWORDS.includes(key) === true) {
+        return `"${key}"`;
+    }
+    return key;
+}
+
+function escapeText(key: string): string {
+    // TODO: The bellow code enables developers to use method and field names
+    // TODO: that contain "text". We don't currently have a good way to test
+    // TODO: this. See https://github.com/demergent-labs/azle/issues/2823 for
+    // TODO: more details.
+
+    // Escape double quotes and backslashes
+    if (containsBackslashOrQuote(key) === true) {
+        const escapedKey: string = key.replace(
+            /[\\"]/g,
+            (match: string): string => `\\${match}`
+        );
+        return `"${escapedKey}"`;
+    }
+
+    return `"${key}"`;
+}
+
+function containsBackslashOrQuote(key: string): boolean {
+    return ['"', '\\'].some((ch: string) => key.includes(ch) === true);
+}

package/src/stable/lib/did_file/visitor/extract_candid.ts

@@ -0,0 +1,31 @@
+import { CandidDef, CandidTypesDefs } from './did_visitor';
+
+/**
+ * @internal
+ *
+ * Internal helper for the Candid visitor system that combines multiple visitor results.
+ * Separates Candid definitions from their associated type definitions.
+ *
+ * @param paramInfo - Array of visitor results, each containing a Candid definition and its type definitions
+ * @returns Tuple of [Array of Candid definitions, Combined type definitions map]
+ *
+ * @remarks
+ * Used by visitor components to:
+ * - Extract Candid definitions for method parameters, records, variants etc.
+ * - Merge type definitions from multiple visited nodes
+ * - Maintain type relationships in the final Candid interface
+ */
+export function extractCandid(
+    paramInfo: [CandidDef, CandidTypesDefs][]
+): [CandidDef[], CandidTypesDefs] {
+    const paramCandid = paramInfo.map(([candid, _candidTypeDefs]) => {
+        return candid;
+    });
+    const candidTypeDefs = paramInfo.reduce(
+        (acc, [_candid, candidTypeDefs]) => {
+            return { ...acc, ...candidTypeDefs };
+        },
+        {}
+    );
+    return [paramCandid, candidTypeDefs];
+}

package/src/stable/lib/did_file/visitor/index.ts

@@ -0,0 +1 @@
+export * from './did_visitor';

package/src/stable/lib/did_file/visitor/visit/func.ts

@@ -0,0 +1,31 @@
+import { IDL } from '@dfinity/candid';
+
+import { DidVisitor, VisitorData, VisitorResult } from '../did_visitor';
+import { extractCandid } from '../extract_candid';
+
+/**
+ * @internal
+ * Visitor for function types in Candid generation.
+ */
+export function visitFunc(
+    t: IDL.FuncClass,
+    didVisitor: DidVisitor,
+    data: VisitorData
+): VisitorResult {
+    const argsTypes = t.argTypes.map((value) =>
+        value.accept(didVisitor, { ...data, isOnService: false })
+    );
+    const candidArgs = extractCandid(argsTypes);
+    const retsTypes = t.retTypes.map((value) =>
+        value.accept(didVisitor, { ...data, isOnService: false })
+    );
+    const candidRets = extractCandid(retsTypes);
+    const args = candidArgs[0].join(', ');
+    const rets = candidRets[0].join(', ');
+    const annon =
+        t.annotations.length === 0 ? '' : ` ${t.annotations.join(' ')}`;
+    return [
+        `${data.isOnService ? '' : 'func '}(${args}) -> (${rets})${annon}`,
+        { ...candidArgs[1], ...candidRets[1] }
+    ];
+}

package/src/stable/lib/did_file/visitor/visit/opt.ts

@@ -0,0 +1,16 @@
+import { IDL } from '@dfinity/candid';
+
+import { DidVisitor, VisitorData, VisitorResult } from '../did_visitor';
+
+/**
+ * @internal
+ * Visitor for optional types in Candid generation.
+ */
+export function visitOpt<T>(
+    ty: IDL.Type<T>,
+    didVisitor: DidVisitor,
+    data: VisitorData
+): VisitorResult {
+    const candid = ty.accept(didVisitor, { ...data, isOnService: false });
+    return [`opt ${candid[0]}`, candid[1]];
+}

package/src/stable/lib/did_file/visitor/visit/primitive.ts

@@ -0,0 +1,11 @@
+import { IDL } from '@dfinity/candid';
+
+import { VisitorResult } from '../did_visitor';
+
+/**
+ * @internal
+ * Visitor for primitive types in Candid generation.
+ */
+export function visitPrimitive<T>(t: IDL.PrimitiveType<T>): VisitorResult {
+    return [t.display(), {}];
+}

package/src/stable/lib/did_file/visitor/visit/record.ts

@@ -0,0 +1,24 @@
+import { IDL } from '@dfinity/candid';
+
+import { DidVisitor, VisitorData, VisitorResult } from '../did_visitor';
+import { escapeCandidName } from '../escape_candid_name';
+import { extractCandid } from '../extract_candid';
+
+/**
+ * @internal
+ * Visitor for record types in Candid generation.
+ */
+export function visitRecord(
+    fields: [string, IDL.Type<any>][],
+    didVisitor: DidVisitor,
+    data: VisitorData
+): VisitorResult {
+    const candidFields = fields.map(([_key, value]) =>
+        value.accept(didVisitor, { ...data, isOnService: false })
+    );
+    const candid = extractCandid(candidFields);
+    const field_strings = fields.map(
+        ([key, _value], index) => `${escapeCandidName(key)}:${candid[0][index]}`
+    );
+    return [`record {${field_strings.join('; ')}}`, candid[1]];
+}

package/src/stable/lib/did_file/visitor/visit/recursive.ts

@@ -0,0 +1,32 @@
+import { IDL } from '@dfinity/candid';
+
+import { DidVisitor, VisitorData, VisitorResult } from '../did_visitor';
+
+/**
+ * @internal
+ * Visitor for recursive types in Candid generation.
+ */
+export function visitRecursive<T>(
+    t: IDL.RecClass<T>,
+    ty: IDL.ConstructType<T>,
+    didVisitor: DidVisitor,
+    data: VisitorData
+): VisitorResult {
+    // For RecClasses the definition will be the name, that name will
+    // reference the actual definition which will be added to the list of
+    // candid type defs that will get put at the top of the candid file
+    // Everything else will just be the normal inline candid def
+    const usedRecClasses = data.usedRecClasses;
+    if (!usedRecClasses.includes(t)) {
+        const candid = ty.accept(didVisitor, {
+            ...data,
+            usedRecClasses: [...usedRecClasses, t],
+            isOnService: false,
+            isFirstService: false
+        });
+        return [t.name, { ...candid[1], [t.name]: candid[0] }];
+    }
+    // If our list already includes this rec class then just return, we don't
+    // need the list because we will get it when we go through the arm above
+    return [t.name, {}];
+}

package/src/stable/lib/did_file/visitor/visit/service.ts

@@ -0,0 +1,107 @@
+import { IDL } from '@dfinity/candid';
+
+import {
+    CandidDef,
+    CandidTypesDefs,
+    DidVisitor,
+    VisitorData
+} from '../did_visitor';
+import { escapeCandidName } from '../escape_candid_name';
+import { extractCandid } from '../extract_candid';
+
+/**
+ * @internal
+ * Visitor for service definitions in Candid generation.
+ */
+export function visitService(
+    t: IDL.ServiceClass,
+    didVisitor: DidVisitor,
+    data: VisitorData
+): [CandidDef, CandidTypesDefs] {
+    const queryAndUpdateMethods = getQueryAndUpdateMethods(t, didVisitor, data);
+    const initAndPostUpgradeMethodCandid = getInitAndPostUpgradeMethodCandid(
+        didVisitor,
+        data
+    );
+
+    const candidTypes = {
+        ...queryAndUpdateMethods[1],
+        ...initAndPostUpgradeMethodCandid[1]
+    };
+
+    return serviceToCandidString(
+        t,
+        queryAndUpdateMethods[0],
+        initAndPostUpgradeMethodCandid[0],
+        candidTypes,
+        data.isFirstService
+    );
+}
+
+function serviceToCandidString(
+    t: IDL.ServiceClass,
+    canisterMethodCandidStrings: string[],
+    initAndPostUpgradeMethodCandidString: string[],
+    candidTypes: CandidTypesDefs,
+    isFirstService: boolean
+): [CandidDef, CandidTypesDefs] {
+    const tab = isFirstService ? '    ' : '';
+    const func_separator = isFirstService ? '\n' : ' ';
+
+    const funcStrings = canisterMethodCandidStrings
+        .map((value, index) => {
+            return `${tab}${escapeCandidName(t._fields[index][0])}: ${value};`;
+        })
+        .join(func_separator);
+
+    const canisterParamsString = createCanisterParamsString(
+        initAndPostUpgradeMethodCandidString
+    );
+
+    if (isFirstService === true) {
+        return [
+            `service: ${canisterParamsString} -> {\n${funcStrings}\n}`,
+            candidTypes
+        ];
+    }
+    return [`service {${funcStrings}}`, candidTypes];
+}
+
+function getInitAndPostUpgradeMethodCandid(
+    didVisitor: DidVisitor,
+    data: VisitorData
+): [CandidDef[], CandidTypesDefs] {
+    const result = IDL.Func(data.initAndPostUpgradeParamIdlTypes, []).accept(
+        didVisitor,
+        {
+            ...data,
+            isOnService: true,
+            isFirstService: false
+        }
+    );
+    return extractCandid([result]);
+}
+
+function getQueryAndUpdateMethods(
+    t: IDL.ServiceClass,
+    didVisitor: DidVisitor,
+    data: VisitorData
+): [CandidDef[], CandidTypesDefs] {
+    return extractCandid(
+        t._fields.map(([_name, func]) =>
+            func.accept(didVisitor, {
+                ...data,
+                isOnService: true,
+                isFirstService: false
+            })
+        )
+    );
+}
+
+function createCanisterParamsString(initMethodCandidString: string[]): string {
+    const parts = initMethodCandidString[0].split('->');
+    if (parts.length >= 2) {
+        return parts.slice(0, -1).join('->').trim();
+    }
+    return '()'; // If we can't find any init or post upgrade params return empty ()
+}

package/src/stable/lib/did_file/visitor/visit/tuple.ts

@@ -0,0 +1,20 @@
+import { IDL } from '@dfinity/candid';
+
+import { DidVisitor, VisitorData, VisitorResult } from '../did_visitor';
+import { extractCandid } from '../extract_candid';
+
+/**
+ * @internal
+ * Visitor for tuple types in Candid generation.
+ */
+export function visitTuple(
+    components: IDL.Type<any>[],
+    didVisitor: DidVisitor,
+    data: VisitorData
+): VisitorResult {
+    const fields = components.map((value) =>
+        value.accept(didVisitor, { ...data, isOnService: false })
+    );
+    const candid = extractCandid(fields);
+    return [`record {${candid[0].join('; ')}}`, candid[1]];
+}

package/src/stable/lib/did_file/visitor/visit/variant.ts

@@ -0,0 +1,26 @@
+import { IDL } from '@dfinity/candid';
+
+import { DidVisitor, VisitorData, VisitorResult } from '../did_visitor';
+import { escapeCandidName } from '../escape_candid_name';
+import { extractCandid } from '../extract_candid';
+
+/**
+ * @internal
+ * Visitor for variant types in Candid generation.
+ */
+export function visitVariant(
+    fields: [string, IDL.Type<any>][],
+    didVisitor: DidVisitor,
+    data: VisitorData
+): VisitorResult {
+    const candidFields = fields.map(([_key, value]) =>
+        value.accept(didVisitor, { ...data, isOnService: false })
+    );
+    const candid = extractCandid(candidFields);
+    const fields_string = fields.map(
+        ([key, value], index) =>
+            escapeCandidName(key) +
+            (value.name === 'null' ? '' : `:${candid[0][index]}`)
+    );
+    return [`variant {${fields_string.join('; ')}}`, candid[1]];
+}

package/src/stable/lib/did_file/visitor/visit/vec.ts

@@ -0,0 +1,16 @@
+import { IDL } from '@dfinity/candid';
+
+import { DidVisitor, VisitorData, VisitorResult } from '../did_visitor';
+
+/**
+ * @internal
+ * Visitor for vector types in Candid generation.
+ */
+export function visitVec<T>(
+    ty: IDL.Type<T>,
+    didVisitor: DidVisitor,
+    data: VisitorData
+): VisitorResult {
+    const candid = ty.accept(didVisitor, { ...data, isOnService: false });
+    return [`vec ${candid[0]}`, candid[1]];
+}