@ohos-ports/azle 0.33.0-beta.0

package/src/stable/build/index.ts

@@ -0,0 +1,282 @@
+import { IOType } from 'child_process';
+import { join } from 'path';
+
+import { generateLicenses } from '#build/commands/dev/template/generate_licenses';
+import {
+    experimentalMessageCli,
+    experimentalMessageDfxJson
+} from '#build/utils/experimental_message';
+import { runCommand as runBuildCommand } from '#commands/build/index';
+import { runCommand as runCleanCommand } from '#commands/clean';
+import { runCommand as runDevAuditCommand } from '#commands/dev/audit';
+import { runCommand as runDevSetupCommand } from '#commands/dev/setup/index';
+import { runCommand as runExperimentalDevTemplateCommand } from '#commands/dev/template/experimental';
+import { runCommand as runDevTemplateCommand } from '#commands/dev/template/stable';
+import { runCommand as runExtensionInstallCommand } from '#commands/extension/install';
+import { runCommand as runGenerateCommand } from '#commands/generate/index';
+import { runCommand as runNewCommand } from '#commands/new';
+import { runCommand as runVersionCommand } from '#commands/version';
+import { getCanisterConfig } from '#utils/get_canister_config';
+import { AZLE_ROOT } from '#utils/global_paths';
+import {
+    CanisterConfig,
+    Command,
+    ExperimentalCommand,
+    SubCommand
+} from '#utils/types';
+
+import { version as azleVersion } from '../../../package.json';
+
+export async function build(): Promise<void> {
+    const command = process.argv[2] as
+        | Command
+        | ExperimentalCommand
+        | undefined;
+
+    if (command === undefined) {
+        throw new Error(
+            `No command found when running azle. Running azle should start like this: azle [commandName]`
+        );
+    }
+
+    const ioType = process.env.AZLE_VERBOSE === 'true' ? 'inherit' : 'pipe';
+
+    if (command === 'extension') {
+        await handleExtensionCommand(ioType);
+
+        return;
+    }
+
+    if (command === 'dev') {
+        await handleDevCommand(ioType);
+
+        return;
+    }
+
+    if (command === 'build') {
+        await handleBuildCommand(ioType);
+
+        return;
+    }
+
+    if (command === '--version') {
+        runVersionCommand();
+
+        return;
+    }
+
+    if (command === 'clean') {
+        await runCleanCommand();
+
+        return;
+    }
+
+    if (command === 'new') {
+        await handleNewCommand();
+
+        return;
+    }
+
+    if (command === 'generate') {
+        await handleGenerateCommand();
+
+        return;
+    }
+
+    if (command === 'post-install') {
+        // This block is reserved for future post-install steps.
+        // Currently, no actions are required.
+        return;
+    }
+
+    if (command === 'upload-assets') {
+        throw new Error(experimentalMessageDfxJson(`the ${command} command`));
+    }
+
+    throwIfInvalidCommand(command);
+}
+
+export function throwIfInvalidCommand(command: string): void {
+    throw new Error(
+        `Invalid command found when running azle. Running azle ${command} is not valid`
+    );
+}
+
+async function handleExtensionCommand(ioType: IOType): Promise<void> {
+    const subCommand = process.argv[3] as SubCommand['extension'];
+
+    if (subCommand === 'install') {
+        handleExtensionInstallCommand(ioType);
+
+        return;
+    }
+
+    throwIfInvalidCommand(`extension ${subCommand}`);
+}
+
+function handleExtensionInstallCommand(ioType: IOType): void {
+    runExtensionInstallCommand(ioType);
+}
+
+async function handleDevCommand(ioType: IOType): Promise<void> {
+    const subCommand = process.argv[3] as SubCommand['dev'];
+
+    if (subCommand === 'audit') {
+        await runDevAuditCommand(ioType);
+
+        return;
+    }
+
+    if (subCommand === 'setup') {
+        handleDevSetupCommand();
+
+        return;
+    }
+
+    if (subCommand === 'template') {
+        await handleDevTemplateCommand(ioType);
+
+        return;
+    }
+
+    throwIfInvalidCommand(`dev ${subCommand}`);
+}
+
+export async function handleDevSetupCommand(): Promise<void> {
+    // About the ordering:
+    // rust must come before any other dependencies that depend on cargo/rust.
+    // cargo-auditable must come before all other dependencies that produce binaries from cargo.
+    const dfx = process.argv.includes('--dfx');
+    const node = process.argv.includes('--node');
+    const rust = process.argv.includes('--rust');
+    const cargoAuditable = process.argv.includes('--cargo-auditable');
+    const cargoAudit = process.argv.includes('--cargo-audit');
+    const cargoBundleLicenses = process.argv.includes(
+        '--cargo-bundle-licenses'
+    );
+    const cargoDeny = process.argv.includes('--cargo-deny');
+    const wasi2ic = process.argv.includes('--wasi2ic');
+
+    if (
+        dfx === false &&
+        node === false &&
+        rust === false &&
+        cargoAuditable === false &&
+        cargoAudit === false &&
+        cargoBundleLicenses === false &&
+        cargoDeny === false &&
+        wasi2ic === false
+    ) {
+        await runDevSetupCommand({
+            dfx: true,
+            node: true,
+            rust: true,
+            'cargo-auditable': true,
+            'cargo-audit': true,
+            'cargo-bundle-licenses': true,
+            'cargo-deny': true,
+            wasi2ic: true
+        });
+    } else {
+        await runDevSetupCommand({
+            dfx,
+            node,
+            rust,
+            'cargo-auditable': cargoAuditable,
+            'cargo-audit': cargoAudit,
+            'cargo-bundle-licenses': cargoBundleLicenses,
+            'cargo-deny': cargoDeny,
+            wasi2ic
+        });
+    }
+}
+
+async function handleDevTemplateCommand(ioType: IOType): Promise<void> {
+    const all = process.argv.includes('--all');
+    const experimental = process.argv.includes('--experimental');
+
+    if (all === true) {
+        await runDevTemplateCommand('inherit');
+        await runExperimentalDevTemplateCommand('inherit');
+    } else if (experimental === true) {
+        await runExperimentalDevTemplateCommand('inherit');
+    } else {
+        await runDevTemplateCommand('inherit');
+    }
+
+    generateLicenses(ioType);
+}
+
+async function handleBuildCommand(ioType: IOType): Promise<void> {
+    const canisterName = process.argv[3];
+    const canisterConfig = await getCanisterConfig(canisterName);
+
+    checkForExperimentalDfxJsonFields(canisterConfig);
+
+    await runBuildCommand(canisterName, canisterConfig, ioType);
+}
+
+async function handleNewCommand(): Promise<void> {
+    const experimental = process.argv.includes('--experimental');
+    const httpServer = process.argv.includes('--http-server');
+    const projectName =
+        httpServer === true ? 'hello_world_http_server' : 'hello_world';
+
+    if (httpServer === true && experimental === false) {
+        throw new Error(experimentalMessageCli('the --http-server option'));
+    }
+    const templatePath = join(
+        AZLE_ROOT,
+        'examples',
+        httpServer === true ? 'experimental' : 'stable',
+        'demo',
+        projectName
+    );
+
+    await runNewCommand(
+        azleVersion,
+        templatePath,
+        httpServer === true,
+        experimental === true
+    );
+}
+
+async function handleGenerateCommand(): Promise<void> {
+    const candidPath = process.argv[3];
+
+    await runGenerateCommand(candidPath);
+}
+
+function checkForExperimentalDfxJsonFields(
+    canisterConfig: CanisterConfig
+): void {
+    if (canisterConfig.custom?.assets !== undefined) {
+        throw new Error(
+            experimentalMessageDfxJson('the assets field in your dfx.json file')
+        );
+    }
+
+    if (canisterConfig.custom?.build_assets !== undefined) {
+        throw new Error(
+            experimentalMessageDfxJson(
+                'the build_assets field in your dfx.json file'
+            )
+        );
+    }
+
+    if (canisterConfig.custom?.esm_aliases !== undefined) {
+        throw new Error(
+            experimentalMessageDfxJson(
+                'the esm_aliases field in your dfx.json file'
+            )
+        );
+    }
+
+    if (canisterConfig.custom?.esm_externals !== undefined) {
+        throw new Error(
+            experimentalMessageDfxJson(
+                'the esm_externals field in your dfx.json file'
+            )
+        );
+    }
+}

package/src/stable/build/utils/dfx.ts

@@ -0,0 +1,10 @@
+import { execSync } from 'child_process';
+
+import { getDfxRoot } from '#utils/dfx_root';
+
+export function getCanisterId(canisterName: string): string {
+    return execSync(
+        `dfx canister --network ${process.env.DFX_NETWORK ?? 'local'} id ${canisterName}`,
+        { cwd: getDfxRoot(), encoding: 'utf-8' }
+    ).trim();
+}

package/src/stable/build/utils/dfx_root.ts

@@ -0,0 +1,34 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Determines the dfx root (directory containing the dfx.json file) for the current project.
+ * First checks the AZLE_DFX_ROOT environment variable.
+ * If not defined, looks for dfx.json in the current working directory.
+ *
+ * @returns {string} The absolute path to the directory containing the dfx.json file
+ * @throws {Error} If AZLE_DFX_ROOT environment variable is not defined and dfx.json is not found in the current directory
+ */
+export function getDfxRoot(): string {
+    if (process.env.AZLE_DFX_ROOT !== undefined) {
+        return process.env.AZLE_DFX_ROOT;
+    }
+
+    if (existsSync(join(process.cwd(), 'dfx.json'))) {
+        return process.cwd();
+    }
+
+    throw new Error(
+        'Unable to locate the dfx.json file. There must be a dfx.json file in the current working directory or the AZLE_DFX_ROOT environment variable must be defined'
+    );
+}
+
+/**
+ * Gets the absolute path to the dfx.json file.
+ *
+ * @returns {string} The absolute path to the dfx.json file
+ * @throws {Error} If the dfx.json directory cannot be determined (inherited from getDfxRoot)
+ */
+export function getDfxJsonPath(): string {
+    return join(getDfxRoot(), 'dfx.json');
+}

package/src/stable/build/utils/exec_sync_pretty.ts

@@ -0,0 +1,17 @@
+import { execSync, ExecSyncOptionsWithBufferEncoding } from 'child_process';
+
+export function execSyncPretty(
+    command: string,
+    options?: ExecSyncOptionsWithBufferEncoding,
+    hint?: string
+): Buffer {
+    try {
+        return execSync(command, options ?? {});
+    } catch (error) {
+        if (hint !== undefined) {
+            throw new Error(`${hint}: ${error}`);
+        } else {
+            throw error;
+        }
+    }
+}

package/src/stable/build/utils/experimental_message.ts

@@ -0,0 +1,19 @@
+export function experimentalMessageDfxJson(description: string): string {
+    return `Experimental mode must be enabled to use ${description}. You can enable experimental mode in your dfx.json file like this:
+{
+    "canisters": {
+        "canisterName": {
+            "type": "azle",
+            "main": "index.ts",
+            "custom": {
+                "experimental": true
+            }
+        }
+    }
+}
+`;
+}
+
+export function experimentalMessageCli(description: string): string {
+    return `Experimental mode must be enabled to use ${description}. You can enable experimental mode with the --experimental flag`;
+}

package/src/stable/build/utils/get_canister_config.ts

@@ -0,0 +1,52 @@
+import { existsSync } from 'fs';
+import { readFile } from 'fs/promises';
+
+import { getDfxJsonPath } from '#utils/dfx_root';
+
+import { CanisterConfig, DfxJson } from './types';
+
+export async function getCanisterConfig(
+    canisterName: string
+): Promise<CanisterConfig> {
+    const dfxJsonExample = getDfxJsonExample(canisterName);
+
+    if (!existsSync(getDfxJsonPath())) {
+        throw new Error(
+            `Create a dfx.json file in the current directory with the following format:\n\n${dfxJsonExample}`
+        );
+    }
+
+    const dfxJson: DfxJson = JSON.parse(
+        (await readFile(getDfxJsonPath())).toString()
+    );
+    const canisterConfig = dfxJson.canisters?.[canisterName];
+
+    if (canisterConfig === undefined) {
+        throw new Error(
+            `Make sure your dfx.json contains a property for "${canisterName}". For example:\n\n${dfxJsonExample}`
+        );
+    }
+
+    if (canisterConfig.main === undefined) {
+        throw new Error(
+            `Make sure your dfx.json contains a property for "main". For example:\n\n${dfxJsonExample}`
+        );
+    }
+
+    return canisterConfig;
+}
+
+function getDfxJsonExample(canisterName: string): string {
+    return `{
+    "canisters": {
+        "${canisterName}": {
+            "type": "azle",
+            "main": "index.ts",
+            "custom": {
+                "candid_gen": "automatic"
+            }
+        }
+    }
+}
+`;
+}

package/src/stable/build/utils/global_paths.ts

@@ -0,0 +1,26 @@
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+export const AZLE_ROOT = join(
+    dirname(fileURLToPath(import.meta.url)),
+    '..',
+    '..',
+    '..',
+    '..'
+);
+
+export const AZLE_CARGO_TARGET_DIR = join(AZLE_ROOT, 'target');
+
+export const STABLE_STATIC_CANISTER_TEMPLATE_PATH = join(
+    AZLE_ROOT,
+    'dist',
+    'canister_templates',
+    'stable.wasm'
+);
+
+export const EXPERIMENTAL_STATIC_CANISTER_TEMPLATE_PATH = join(
+    AZLE_ROOT,
+    'dist',
+    'canister_templates',
+    'experimental.wasm'
+);

package/src/stable/build/utils/types.ts

@@ -0,0 +1,87 @@
+export type CandidAndMethodMeta = {
+    candid: string;
+    methodMeta: MethodMeta;
+};
+
+export type CandidGen = 'automatic' | 'custom';
+
+export type CanisterConfig = {
+    type?: 'azle';
+    main?: string;
+    custom?: CustomConfig;
+};
+
+export type CustomConfig = {
+    assets?: never;
+    build_assets?: never;
+    candid_gen?: CandidGen;
+    env?: string[];
+    esm_aliases?: never;
+    esm_externals?: never;
+    experimental?: boolean;
+    test?: {
+        clearHeapMethods?: string[];
+        memorySizeIncreaseExpected?: boolean;
+    };
+};
+
+export type Context = {
+    canisterPath: string;
+    candidPath: string;
+    main: string;
+    wasmBinaryPath: string;
+    wasmData: WasmData;
+};
+
+export type Command =
+    | 'build'
+    | 'clean'
+    | 'dev'
+    | 'extension'
+    | 'generate'
+    | 'new'
+    | 'post-install'
+    | '--version';
+
+export type ExperimentalCommand = 'upload-assets';
+
+type DevSubCommands = {
+    [K in Extract<Command, 'dev'>]: 'audit' | 'setup' | 'template';
+};
+
+type ExtensionSubCommands = {
+    [K in Extract<Command, 'extension'>]: 'install';
+};
+
+export type SubCommand = DevSubCommands & ExtensionSubCommands;
+
+export type DfxJson = {
+    canisters?: {
+        [key: string]: CanisterConfig | undefined;
+    };
+};
+
+export type EnvVars = [string, string][];
+
+export type Method = {
+    name: string;
+    composite?: boolean;
+    index: number;
+    hidden?: boolean;
+};
+
+export type MethodMeta = {
+    queries?: Method[];
+    updates?: Method[];
+    init?: Method;
+    pre_upgrade?: Method;
+    post_upgrade?: Method;
+    heartbeat?: Method;
+    inspect_message?: Method;
+    on_low_wasm_memory?: Method;
+};
+
+export type WasmData = {
+    envVars: EnvVars;
+    mainJsPath: string;
+};

package/src/stable/lib/canister_methods/heartbeat.ts

@@ -0,0 +1,29 @@
+import { Context, decoratorArgumentsHandler, OriginalMethod } from '.';
+
+/**
+ * Decorator to mark a method as the `heartbeat` entry point.
+ *
+ * @remarks
+ *
+ * It is advised to use `setTimer` and `setTimerInterval` instead of the `heartbeat` method.
+ *
+ * The `heartbeat` entry point will be called periodically by the IC (~every second or so).
+ *
+ * Only one `@heartbeat` method is allowed per canister.
+ *
+ * - **State**: read-write
+ *
+ * - **Replication**: yes
+ *
+ * - **Async**: yes
+ *
+ * - **Instruction limit**: [40_000_000_000](https://internetcomputer.org/docs/current/developer-docs/smart-contracts/maintain/resource-limits)
+ *
+ * See [more documentation](https://internetcomputer.org/docs/current/references/ic-interface-spec#heartbeat).
+ */
+export function heartbeat<This, Args extends unknown[], Return>(
+    originalMethod: OriginalMethod<This, Args, Return>,
+    context: Context<This, Args, Return>
+): void {
+    decoratorArgumentsHandler('heartbeat', originalMethod, context);
+}