@ohos-ports/azle 0.33.0-beta.0

package/src/stable/test/benchmarks/index.ts

@@ -0,0 +1,273 @@
+import { execSync } from 'child_process';
+import { readFile, writeFile } from 'fs/promises';
+import { join } from 'path';
+
+import { jsonParse, jsonStringify } from '#lib/index';
+import { getCanisterId } from '#utils/dfx';
+import { getDfxRoot } from '#utils/dfx_root';
+
+// @ts-ignore We would have to add "resolveJsonModule": true to every test tsconfig.json file
+import { version } from '../../../../package.json';
+
+type BenchmarkEntry = {
+    method_name: string;
+    instructions: bigint | number;
+    timestamp: bigint | number;
+};
+
+type CanisterBenchmark = {
+    current: {
+        version: string;
+        benchmarks: BenchmarkEntry[];
+    };
+    previous: {
+        version: string;
+        benchmarks: BenchmarkEntry[];
+    };
+};
+
+type BenchmarksJson = {
+    [canisterName: string]: CanisterBenchmark;
+};
+
+export async function recordsBenchmarksForCanisters(
+    canisterNames: string[]
+): Promise<void> {
+    const existingBenchmarks = await getBenchmarksJson();
+    const updatedBenchmarks = await updateBenchmarksForCanisters(
+        canisterNames,
+        existingBenchmarks
+    );
+    await writeBenchmarkResults(canisterNames, updatedBenchmarks);
+}
+
+async function updateBenchmarksForCanisters(
+    canisterNames: string[],
+    existingBenchmarks: BenchmarksJson
+): Promise<BenchmarksJson> {
+    return canisterNames.reduce(async (accPromise, canisterName) => {
+        const acc = await accPromise;
+        const canisterId = getCanisterId(canisterName);
+        const currentBenchmarks: BenchmarkEntry[] = JSON.parse(
+            execSync(
+                `dfx canister call ${canisterId} _azle_get_benchmarks --output json --candid ${join(__dirname, '_azle_get_benchmarks.did')}`,
+                {
+                    cwd: getDfxRoot(),
+                    encoding: 'utf-8'
+                }
+            )
+        );
+
+        const previousCurrentVersion = acc[canisterName]?.current.version;
+        const shouldUpdatePrevious = previousCurrentVersion !== version;
+
+        return {
+            ...acc,
+            [canisterName]: {
+                previous: shouldUpdatePrevious
+                    ? (acc[canisterName]?.current ?? {
+                          version: 'No previous benchmarks',
+                          benchmarks: []
+                      })
+                    : acc[canisterName]?.previous,
+                current: {
+                    version,
+                    benchmarks: currentBenchmarks
+                }
+            }
+        };
+    }, Promise.resolve(existingBenchmarks));
+}
+
+async function writeBenchmarkResults(
+    canisterNames: string[],
+    updatedBenchmarks: BenchmarksJson
+): Promise<void> {
+    await writeBenchmarksMarkdown(canisterNames, updatedBenchmarks);
+    await writeBenchmarksJson(updatedBenchmarks);
+}
+
+async function writeBenchmarksMarkdown(
+    canisterNames: string[],
+    updatedBenchmarks: BenchmarksJson
+): Promise<void> {
+    const markdownContent =
+        canisterNames
+            .map((canisterName) => {
+                const { current, previous } = updatedBenchmarks[canisterName];
+                const benchmarkTables = {
+                    current: createBenchmarksTable(
+                        current.benchmarks,
+                        previous.benchmarks
+                    ),
+                    previous: createBenchmarksTable(previous.benchmarks, [])
+                };
+
+                return (
+                    `# Benchmarks for ${canisterName}\n\n` +
+                    `## Current benchmarks Azle version: ${current.version}\n` +
+                    `${benchmarkTables.current}\n\n` +
+                    `## Baseline benchmarks Azle version: ${previous.version}\n` +
+                    `${benchmarkTables.previous}\n\n`
+                );
+            })
+            .join('') + createNote();
+
+    await writeFile(`benchmarks.md`, markdownContent);
+}
+
+async function writeBenchmarksJson(
+    updatedBenchmarks: BenchmarksJson
+): Promise<void> {
+    await writeFile(
+        `benchmarks.json`,
+        `${jsonStringify(updatedBenchmarks, undefined, 4)}\n`
+    );
+}
+
+async function getBenchmarksJson(): Promise<BenchmarksJson> {
+    const filePath = 'benchmarks.json';
+
+    try {
+        const fileContent = await readFile(filePath, 'utf-8');
+        return jsonParse(fileContent);
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+            return {};
+        }
+        throw error; // Re-throw if it's a different error
+    }
+}
+
+function createBenchmarksTable(
+    currentBenchmarks: BenchmarkEntry[],
+    previousBenchmarks: BenchmarkEntry[]
+): string {
+    if (currentBenchmarks.length === 0) {
+        return 'No benchmarks reported';
+    }
+
+    const hasChanges = previousBenchmarks.length > 0;
+    const tableHeader = createTableHeader(hasChanges);
+    const tableRows = createTableRows(
+        currentBenchmarks,
+        previousBenchmarks,
+        hasChanges
+    );
+
+    return `${tableHeader}${tableRows}`;
+}
+
+function createTableHeader(hasChanges: boolean): string {
+    const baseHeader =
+        '| Id | Method Name | Instructions | Cycles | USD | USD/Million Calls |';
+    const changeHeader = hasChanges ? ' Change |' : '';
+    const separator =
+        '\n|-----------|-------------|------------|--------|-----|--------------|';
+    const changeSeparator = hasChanges ? '-------|' : '';
+
+    return `${baseHeader}${changeHeader}${separator}${changeSeparator}\n`;
+}
+
+function createTableRows(
+    currentBenchmarks: BenchmarkEntry[],
+    previousBenchmarks: BenchmarkEntry[],
+    hasChanges: boolean
+): string {
+    return currentBenchmarks
+        .map((currentBenchmark, index) =>
+            createTableRow(
+                currentBenchmark,
+                index,
+                previousBenchmarks[index],
+                hasChanges
+            )
+        )
+        .join('\n');
+}
+
+function createTableRow(
+    currentBenchmark: BenchmarkEntry,
+    index: number,
+    previousBenchmark: BenchmarkEntry | undefined,
+    hasChanges: boolean
+): string {
+    const executionNumber = index;
+    const methodName = currentBenchmark.method_name;
+    const instructions = BigInt(currentBenchmark.instructions);
+    const cycles = calculateCycles(instructions);
+    const usd = calculateUSD(cycles);
+    const usdPerMillion = usd * 1_000_000;
+
+    const baseRow = `| ${executionNumber} | ${methodName} | ${formatWithUnderscores(
+        instructions
+    )} | ${formatWithUnderscores(cycles)} | $${usd.toFixed(
+        10
+    )} | $${formatWithUnderscores(usdPerMillion, 2)}`;
+
+    if (!hasChanges) {
+        return `${baseRow} |`;
+    }
+
+    const change = previousBenchmark
+        ? calculateChange(instructions, BigInt(previousBenchmark.instructions))
+        : '';
+
+    return `${baseRow} | ${change} |`;
+}
+
+function createNote(): string {
+    return `
+
+---
+
+**Note on calculations:**
+- All calculations assume a 13-node subnet
+- Cycles are calculated using the formula: base_fee + per_instruction_fee \\* number_of_instructions
+- base_fee: 5_000_000 cycles
+- per_instruction_fee: 1 cycle
+- USD value is derived from the total cycles, where 1 trillion cycles = 1 XDR, and 1 XDR = $1.37 (as of June 27, 2025)
+
+For the most up-to-date XDR to USD conversion rate, please refer to the [IMF website](https://www.imf.org/external/np/fin/data/rms_sdrv.aspx).
+For the most current fee information, please check the [official documentation](https://internetcomputer.org/docs/references/cycles-cost-formulas).`;
+}
+
+function calculateCycles(instructions: bigint): bigint {
+    const baseFee = 5_000_000n;
+    const perInstructionFee = 1n;
+
+    return baseFee + perInstructionFee * instructions;
+}
+
+function calculateUSD(cycles: bigint): number {
+    const cyclesPerXDR = 1_000_000_000_000; // 1 trillion cycles = 1 XDR
+    const usdPerXDR = 1.37; // As of June 27, 2025
+    return (Number(cycles) / cyclesPerXDR) * usdPerXDR;
+}
+
+function calculateChange(current: bigint, previous: bigint): string {
+    const diff = current - previous;
+    const color = diff < 0 ? 'green' : 'red';
+    return `<font color="${color}">${
+        diff > 0 ? '+' : ''
+    }${formatWithUnderscores(diff)}</font>`;
+}
+
+function formatWithUnderscores(
+    value: bigint | number,
+    decimalPlaces?: number
+): string {
+    const [integerPart, decimalPart] = value.toString().split('.');
+    const formattedIntegerPart = integerPart.replace(
+        /\B(?=(\d{3})+(?!\d))/g,
+        '_'
+    );
+    if (decimalPart !== undefined && decimalPlaces !== undefined) {
+        const truncatedDecimalPart = decimalPart.slice(0, decimalPlaces);
+        return `${formattedIntegerPart}.${truncatedDecimalPart}`;
+    }
+    if (decimalPart !== undefined) {
+        return `${formattedIntegerPart}.${decimalPart}`;
+    }
+    return formattedIntegerPart;
+}

package/src/stable/test/candid_deep_equal.ts

@@ -0,0 +1,99 @@
+import { jsonStringify } from '#lib/json';
+
+/**
+ * @internal
+ *
+ * Checks if two objects are deeply equal.
+ *
+ * @param obj1 The first object to compare.
+ * @param obj2 The second object to compare.
+ * @returns `true` if the objects are deeply equal, `false` otherwise.
+ *
+ * @remarks
+ * It first serializes both objects using our custom jsonStringify function to handle potential problems with Principal or other complex objects with hard to define equality.
+ * then parses them back and performs a recursive comparison.
+ *
+ * This function is only designed to work with Candid types.
+ */
+export function candidDeepEqual(obj1: any, obj2: any): boolean {
+    const obj1Json = normalizeJson(obj1);
+    const obj2Json = normalizeJson(obj2);
+
+    // Handle null cases
+    if (obj1Json === null || obj2Json === null) {
+        return obj1Json === obj2Json;
+    }
+
+    // Check if both are objects
+    if (typeof obj1Json !== 'object' || typeof obj2Json !== 'object') {
+        return obj1Json === obj2Json;
+    }
+
+    // Check if they have the same constructor
+    if (obj1Json.constructor !== obj2Json.constructor) {
+        return false;
+    }
+
+    // Make sure they are both arrays or both objects
+    if (Array.isArray(obj1Json) !== Array.isArray(obj2Json)) {
+        return false;
+    }
+
+    if (Array.isArray(obj1Json)) {
+        return areEqualArrays(obj1Json, obj2Json);
+    }
+
+    return areEqualObjects(obj1Json, obj2Json);
+}
+
+function areEqualArrays(arr1: Array<any>, arr2: Array<any>): boolean {
+    if (arr1.length !== arr2.length) {
+        return false;
+    }
+    for (let i = 0; i < arr1.length; i++) {
+        if (candidDeepEqual(arr1[i], arr2[i]) === false) {
+            return false;
+        }
+    }
+    return true;
+}
+
+function areEqualObjects(obj1Json: any, obj2Json: any): boolean {
+    // Get keys and compare lengths
+    const keys1 = Object.keys(obj1Json);
+    const keys2 = Object.keys(obj2Json);
+    if (keys1.length !== keys2.length) {
+        return false;
+    }
+
+    // Recursively compare all properties
+    for (const key of keys1) {
+        if (
+            keys2.includes(key) === false ||
+            candidDeepEqual(obj1Json[key], obj2Json[key]) === false
+        ) {
+            return false;
+        }
+    }
+
+    return true;
+}
+
+/**
+ * @internal
+ *
+ * Normalizes a JSON object by serializing it and then parsing it back into an object.
+ * This helps handle potential problems with Principal or other complex objects with hard to define equality.
+ *
+ * @param obj The object to normalize.
+ * @returns The normalized object.
+ *
+ * @remarks
+ * We have historically had issues with various candidDeepEqual implementations most tracing back to subtle differences in versions etc that have caused false negatives.
+ * Our jsonStringify takes out a lot of the possible oddities by serializing them into a more standard format.
+ * So until we convert this to jest and use its various equality functions, this should be good enough.
+ */
+function normalizeJson(obj: any): any {
+    const objJsonString = jsonStringify(obj);
+    return JSON.parse(objJsonString);
+}

package/src/stable/test/canister_names.ts

@@ -0,0 +1,36 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { getDfxRoot } from '#utils/dfx_root';
+import { DfxJson } from '#utils/types';
+
+/**
+ * Returns the names of all canisters defined in the dfx.json file of the current project.
+ *
+ * @param onlyAzle - If true, only returns canisters of type 'azle'. If false, returns all canisters. Defaults to true.
+ */
+export async function getCanisterNames(
+    onlyAzle: boolean = true
+): Promise<string[]> {
+    const dfxJson = await getDfxJson();
+
+    if (dfxJson.canisters === undefined) {
+        throw new Error('No canisters found in dfx.json');
+    }
+
+    return Object.entries(dfxJson.canisters)
+        .filter(([_, value]) => {
+            if (onlyAzle === false) {
+                return true;
+            }
+
+            return value?.type === 'azle';
+        })
+        .map(([key, _]) => key);
+}
+
+async function getDfxJson(): Promise<DfxJson> {
+    const dfxFile = await readFile(join(getDfxRoot(), 'dfx.json'), 'utf-8');
+
+    return JSON.parse(dfxFile);
+}

package/src/stable/test/fuzz.ts

@@ -0,0 +1,102 @@
+import { spawn } from 'child_process';
+import { CuzzConfig } from 'cuzz';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+import { getCanisterNames } from '.';
+
+export async function runFuzzTests(): Promise<void> {
+    const cuzzConfig = getCuzzConfig();
+
+    const canisterNames = await getCanisterNames();
+    const callDelay = getCallDelay(cuzzConfig);
+
+    await Promise.all(
+        canisterNames.map((canisterName) =>
+            fuzzTestCanister(canisterName, callDelay)
+        )
+    );
+}
+
+export function getCuzzConfig(): CuzzConfig {
+    try {
+        // This is purposefully synchronous so that it can be used in the runTests function
+        // before the test runner is started. runTests must execute synchronously so that jest
+        // can properly register the tests.
+        const cuzzFile = readFileSync(
+            join(process.cwd(), 'cuzz.json'),
+            'utf-8'
+        );
+
+        return JSON.parse(cuzzFile);
+    } catch {
+        return {};
+    }
+}
+
+function getCallDelay(cuzzConfig: CuzzConfig): string {
+    return (
+        process.env.AZLE_FUZZ_CALL_DELAY ??
+        cuzzConfig.callDelay?.toString() ??
+        '.1'
+    );
+}
+
+function fuzzTestCanister(
+    canisterName: string,
+    callDelay: string
+): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+        const baseCuzzArgs = [
+            'exec',
+            '--offline',
+            'cuzz',
+            '--',
+            '--canister-name',
+            canisterName,
+            '--skip-deploy',
+            '--call-delay',
+            callDelay,
+            ...(process.env.AZLE_RUNNING_IN_GITHUB_ACTIONS === 'true'
+                ? []
+                : ['--clear-console']),
+            ...(process.env.AZLE_RUNNING_IN_GITHUB_ACTIONS === 'true'
+                ? ['--silent']
+                : [])
+        ];
+
+        const cuzzArgs = [
+            ...baseCuzzArgs,
+            ...(process.env.AZLE_FUZZ_TERMINAL === 'true'
+                ? ['--terminal']
+                : []),
+            ...(process.env.AZLE_FUZZ_TIME_LIMIT !== undefined
+                ? ['--time-limit', process.env.AZLE_FUZZ_TIME_LIMIT]
+                : [])
+        ];
+
+        const cuzzProcess = spawn('npm', cuzzArgs, {
+            stdio: 'inherit'
+        });
+
+        cuzzProcess.on('exit', (code) => {
+            if (code === 0) {
+                resolve();
+            } else {
+                reject(
+                    new Error(
+                        `Fuzz test for canister ${canisterName} failed with exit code ${code}`
+                    )
+                );
+            }
+        });
+
+        cuzzProcess.on('error', (error) => {
+            reject(
+                new Error(
+                    `Failed to start fuzz test for canister ${canisterName}: ${error.message}`
+                )
+            );
+        });
+    });
+}

package/src/stable/test/get_canister_actor.ts

@@ -0,0 +1,45 @@
+import { HttpAgent, Identity } from '@dfinity/agent';
+import { ActorSubclass } from '@dfinity/agent';
+import { Agent } from '@dfinity/agent';
+import { join } from 'path';
+
+import { getCanisterId } from '#utils/dfx';
+
+type GetCanisterActorOptions = {
+    /** Optional identity for authentication */
+    identity?: Identity;
+    /** Optional pre-configured agent */
+    agent?: Agent;
+    /** Optional parent directory path for the dfx generated files */
+    parentDir?: string;
+};
+
+/**
+ * Creates an actor instance for interacting with a canister
+ * @param canisterName - Name of the canister to create an actor for
+ * @param options - Configuration options
+ * @returns A promise that resolves to the actor instance
+ */
+export async function getCanisterActor<T>(
+    canisterName: string,
+    options: GetCanisterActorOptions = {}
+): Promise<ActorSubclass<T>> {
+    const parentDir = options.parentDir ?? join(process.cwd(), 'test');
+    const { createActor } = await import(
+        join(parentDir, 'dfx_generated', canisterName)
+    );
+
+    const agent =
+        options.agent ??
+        (await HttpAgent.create({
+            host: 'http://127.0.0.1:4943',
+            identity: options.identity,
+            shouldFetchRootKey: true
+        }));
+
+    const actor = createActor(getCanisterId(canisterName), {
+        agent
+    });
+
+    return actor;
+}