@ohos-ports/azle 0.33.0-beta.0

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

@@ -0,0 +1,405 @@
+import { GenericIdlFuncArgs, IDL } from '@dfinity/candid';
+
+import { toFuncArgs } from '#lib/func';
+import { MethodMeta } from '#utils/types';
+
+import { idlToString } from '../did_file';
+import { handleUncaughtError } from '../error';
+import {
+    CanisterMethodMode,
+    executeAndReplyWithCandidSerde
+} from '../execute_and_reply_with_candid_serde';
+import { InitOptions } from './init';
+import { InspectMessageOptions } from './inspect_message';
+import { PostUpgradeOptions } from './post_upgrade';
+import { QueryOptions } from './query';
+import { UpdateOptions } from './update';
+
+type CanisterClass = {
+    constructor: (new () => unknown) & {
+        _azleCanisterClassMeta: CanisterClassMeta | undefined;
+    };
+};
+
+export type CanisterClassMeta = {
+    callbacks: {
+        [key: string]: () => Promise<void>;
+    };
+    canisterMethodIdlParamTypes: { [key: string]: IDL.FuncClass };
+    canisterMethodsIndex: number;
+    initAndPostUpgradeIdlTypes: GenericIdlFuncArgs;
+    methodMeta: MethodMeta;
+};
+
+export type MethodType<This, Args extends unknown[], Return> = (
+    this: This,
+    ...args: Args
+) => Return;
+
+export type DecoratorFunction<This, Args extends unknown[], Return> = (
+    originalMethod: OriginalMethod<This, Args, Return>,
+    context: Context<This, Args, Return>
+) => void;
+
+export type OriginalMethod<This, Args extends unknown[], Return> = MethodType<
+    This,
+    Args,
+    Return
+>;
+
+export type Context<
+    This,
+    Args extends unknown[],
+    Return
+> = ClassMethodDecoratorContext<This, MethodType<This, Args, Return>>;
+
+/**
+ * @internal
+ *
+ * This is the entry point for our overloaded decorator functions before calling the common implementation.
+ * It handles determining which overload we are using and then either calling the common implementation or
+ * returning a decorator function which calls the common implementation.
+ */
+export function decoratorArgumentsHandler<This, Args extends unknown[], Return>(
+    canisterMethodMode: CanisterMethodMode,
+    param1?:
+        | OriginalMethod<This, Args, Return>
+        | IDL.Type[]
+        | InspectMessageOptions,
+    param2?:
+        | Context<This, Args, Return>
+        | IDL.Type
+        | InitOptions
+        | PostUpgradeOptions,
+    param3?: QueryOptions | UpdateOptions
+): void | DecoratorFunction<This, Args, Return> {
+    const decoratorIsOverloadedWithoutParams =
+        isDecoratorOverloadedWithoutParams(param1, param2);
+
+    if (decoratorIsOverloadedWithoutParams === true) {
+        const originalMethod = param1 as OriginalMethod<This, Args, Return>;
+        const context = param2 as Context<This, Args, Return>;
+
+        return decoratorImplementation(
+            canisterMethodMode,
+            originalMethod,
+            context
+        );
+    } else {
+        const paramIdlTypes = toFuncArgs(
+            canisterMethodMode === 'query' ||
+                canisterMethodMode === 'update' ||
+                canisterMethodMode === 'init' ||
+                canisterMethodMode === 'postUpgrade'
+                ? (param1 as IDL.Type[])
+                : undefined
+        );
+        const returnIdlType = (
+            canisterMethodMode === 'query' || canisterMethodMode === 'update'
+                ? param2
+                : undefined
+        ) as IDL.Type | undefined;
+        const options = (
+            canisterMethodMode === 'inspectMessage'
+                ? param1
+                : canisterMethodMode === 'init' ||
+                    canisterMethodMode === 'postUpgrade'
+                  ? param2
+                  : param3
+        ) as
+            | QueryOptions
+            | UpdateOptions
+            | InitOptions
+            | PostUpgradeOptions
+            | InspectMessageOptions
+            | undefined;
+
+        return (
+            originalMethod: OriginalMethod<This, Args, Return>,
+            context: Context<This, Args, Return>
+        ): void => {
+            return decoratorImplementation(
+                canisterMethodMode,
+                originalMethod,
+                context,
+                paramIdlTypes,
+                returnIdlType,
+                options
+            );
+        };
+    }
+}
+
+/**
+ * @internal
+ *
+ * The common implementation for all of our exposed canister method decorators.
+ */
+function decoratorImplementation<This, Args extends unknown[], Return>(
+    canisterMethodMode: CanisterMethodMode,
+    originalMethod: OriginalMethod<This, Args, Return>,
+    context: Context<This, Args, Return>,
+    paramIdlTypes?: GenericIdlFuncArgs,
+    returnIdlType?: IDL.Type,
+    options?: QueryOptions | UpdateOptions | InitOptions | PostUpgradeOptions
+): void {
+    context.addInitializer(function () {
+        let defaultCanisterClassMeta: CanisterClassMeta = {
+            callbacks: {},
+            canisterMethodIdlParamTypes: {},
+            canisterMethodsIndex: 0,
+            initAndPostUpgradeIdlTypes: [],
+            methodMeta: {
+                queries: [],
+                updates: []
+            }
+        };
+
+        // The instantiation of the canister class that occurs in getCanisterClassMeta
+        // will set the initial value of this.constructor._azleCanisterClassMeta.
+        // this.constructor._azleCanisterClassMeta will be the same reference throughout
+        // all instantiations of exported canister classes. If the canister class has not been
+        // exported as the default export from the main entrypoint of the canister,
+        // then this.constructor._azleCanisterClassMeta will be undefined, and we will
+        // then just use a default value that will be thrown away at the end of this function scope.
+        // This handles the case of the developer instantiating a class with canister method
+        // decorators, but not exporting that class from the main entrypoint.
+        // We only ever want canister methods to be registered if they were exported
+        // from the main entrypoint defined in dfx.json.
+        let canisterClassMeta =
+            (this as CanisterClass).constructor._azleCanisterClassMeta ??
+            defaultCanisterClassMeta;
+
+        const name = context.name as string;
+
+        const index = canisterClassMeta.canisterMethodsIndex++;
+        const indexString = index.toString();
+
+        if (canisterMethodMode === 'query') {
+            throwIfMethodAlreadyDefined(
+                `@query ${name}`,
+                canisterClassMeta.methodMeta.queries?.find(
+                    (queryMethod) => queryMethod.name === name
+                ) !== undefined
+            );
+
+            canisterClassMeta.methodMeta.queries?.push({
+                name,
+                index,
+                composite: (options as QueryOptions)?.composite ?? false,
+                hidden: (options as QueryOptions)?.hidden ?? false
+            });
+
+            canisterClassMeta.canisterMethodIdlParamTypes[name] = IDL.Func(
+                paramIdlTypes ?? [],
+                returnIdlType === undefined ? [] : [returnIdlType],
+                ['query']
+            );
+        }
+
+        if (canisterMethodMode === 'update') {
+            throwIfMethodAlreadyDefined(
+                `@update ${name}`,
+                canisterClassMeta.methodMeta.updates?.find(
+                    (updateMethod) => updateMethod.name === name
+                ) !== undefined
+            );
+
+            canisterClassMeta.methodMeta.updates?.push({
+                name,
+                index,
+                hidden: (options as UpdateOptions)?.hidden ?? false
+            });
+
+            canisterClassMeta.canisterMethodIdlParamTypes[name] = IDL.Func(
+                paramIdlTypes ?? [],
+                returnIdlType === undefined ? [] : [returnIdlType]
+            );
+        }
+
+        if (canisterMethodMode === 'init') {
+            throwIfMethodAlreadyDefined(
+                '@init',
+                canisterClassMeta.methodMeta.init !== undefined
+            );
+
+            canisterClassMeta.methodMeta.init = {
+                name,
+                index
+            };
+
+            const postUpgradeDefined =
+                canisterClassMeta.methodMeta.post_upgrade !== undefined;
+
+            if (postUpgradeDefined === true) {
+                verifyInitAndPostUpgradeHaveTheSameParams(
+                    paramIdlTypes ?? [],
+                    canisterClassMeta.initAndPostUpgradeIdlTypes
+                );
+            } else {
+                canisterClassMeta.initAndPostUpgradeIdlTypes =
+                    paramIdlTypes ?? [];
+            }
+        }
+
+        if (canisterMethodMode === 'postUpgrade') {
+            throwIfMethodAlreadyDefined(
+                '@postUpgrade',
+                canisterClassMeta.methodMeta.post_upgrade !== undefined
+            );
+
+            canisterClassMeta.methodMeta.post_upgrade = {
+                name,
+                index
+            };
+
+            const initDefined = canisterClassMeta.methodMeta.init !== undefined;
+
+            if (initDefined === true) {
+                verifyInitAndPostUpgradeHaveTheSameParams(
+                    paramIdlTypes ?? [],
+                    canisterClassMeta.initAndPostUpgradeIdlTypes
+                );
+            } else {
+                canisterClassMeta.initAndPostUpgradeIdlTypes =
+                    paramIdlTypes ?? [];
+            }
+        }
+
+        if (canisterMethodMode === 'preUpgrade') {
+            throwIfMethodAlreadyDefined(
+                '@preUpgrade',
+                canisterClassMeta.methodMeta.pre_upgrade !== undefined
+            );
+
+            canisterClassMeta.methodMeta.pre_upgrade = {
+                name,
+                index
+            };
+        }
+
+        if (canisterMethodMode === 'inspectMessage') {
+            throwIfMethodAlreadyDefined(
+                '@inspectMessage',
+                canisterClassMeta.methodMeta.inspect_message !== undefined
+            );
+
+            canisterClassMeta.methodMeta.inspect_message = {
+                name,
+                index
+            };
+        }
+
+        if (canisterMethodMode === 'heartbeat') {
+            throwIfMethodAlreadyDefined(
+                '@heartbeat',
+                canisterClassMeta.methodMeta.heartbeat !== undefined
+            );
+
+            canisterClassMeta.methodMeta.heartbeat = {
+                name,
+                index
+            };
+        }
+
+        if (canisterMethodMode === 'onLowWasmMemory') {
+            throwIfMethodAlreadyDefined(
+                '@onLowWasmMemory',
+                canisterClassMeta.methodMeta.on_low_wasm_memory !== undefined
+            );
+
+            canisterClassMeta.methodMeta.on_low_wasm_memory = {
+                name,
+                index
+            };
+        }
+
+        canisterClassMeta.callbacks[indexString] = async (): Promise<void> => {
+            try {
+                await executeAndReplyWithCandidSerde(
+                    canisterMethodMode,
+                    originalMethod.bind(this),
+                    paramIdlTypes ?? [],
+                    returnIdlType,
+                    options?.manual ?? false,
+                    canisterClassMeta.canisterMethodIdlParamTypes
+                );
+            } catch (error) {
+                handleUncaughtError(error);
+            }
+        };
+    });
+}
+
+/**
+ * @internal
+ *
+ * Determines if the params are from a pure decorator function without our own parameter currying.
+ */
+function isDecoratorOverloadedWithoutParams<
+    This,
+    Args extends unknown[],
+    Return
+>(
+    param1?:
+        | MethodType<This, Args, Return>
+        | IDL.Type[]
+        | InspectMessageOptions,
+    param2?:
+        | ClassMethodDecoratorContext<This, MethodType<This, Args, Return>>
+        | IDL.Type
+        | InitOptions
+        | PostUpgradeOptions
+): boolean {
+    return (
+        typeof param1 === 'function' &&
+        param2 !== undefined &&
+        'kind' in param2 &&
+        param2.kind === 'method' &&
+        param2.metadata !== undefined &&
+        param2.name !== undefined
+    );
+}
+
+/**
+ * @internal
+ *
+ * Uses the candid string of the `@init` and `@postUpgrade` methods to verify that
+ * they have matching parameter signatures.
+ *
+ * @param idlTypes - Array of IDL function types representing canister methods
+ * @throws {Error} If methods have mismatched parameters or if invalid number of methods
+ */
+function verifyInitAndPostUpgradeHaveTheSameParams(
+    a: GenericIdlFuncArgs,
+    b: GenericIdlFuncArgs
+): void {
+    const aSignature = idlToString(IDL.Func(a, []));
+    const bSignature = idlToString(IDL.Func(b, []));
+
+    if (aSignature !== bSignature) {
+        throw new Error(
+            `'@init' and '@postUpgrade' methods must have the same parameters.\nFound:\n${aSignature}\n${bSignature}`
+        );
+    }
+}
+
+/**
+ * @internal
+ *
+ * Throws an error if a method is already defined in the class.
+ *
+ * @param methodName - The name of the method
+ * @param isDefined - Whether the method is already defined
+ * @throws {Error} If the method is already defined
+ */
+function throwIfMethodAlreadyDefined(
+    methodName: string,
+    isDefined: boolean
+): void {
+    if (isDefined === true) {
+        throw new Error(
+            `'${methodName}' method can only have one definition in the canister`
+        );
+    }
+}

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

@@ -0,0 +1,71 @@
+import { IDL } from '@dfinity/candid';
+
+import {
+    Context,
+    decoratorArgumentsHandler,
+    DecoratorFunction,
+    OriginalMethod
+} from '.';
+
+export type InitOptions = {
+    manual?: boolean;
+};
+
+/**
+ * Decorator to mark a method as the initialization entry point.
+ *
+ * @remarks
+ *
+ * Canister initialization generally happens once per canister lifecycle.
+ *
+ * Only one `@init` method is allowed per canister.
+ *
+ * - **State**: read-write
+ *
+ * - **Replication**: yes
+ *
+ * - **Async**: no
+ *
+ * - **Instruction limit**: [300_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#system-api-init).
+ */
+export function init<This, Args extends unknown[], Return>(
+    originalMethod: OriginalMethod<This, Args, Return>,
+    context: Context<This, Args, Return>
+): void;
+
+/**
+ * Decorator to mark a method as the initialization entry point.
+ *
+ * @param paramIdlTypes - Optional array of Candid IDL types for the decorated method parameters. The runtime arguments will be decoded using these types
+ * @param options - Optional configuration object
+ * @param options.manual - Optional flag to indicate manual handling of the decorated method's runtime arguments. This is meant to be used with `msgArgData` and `IDL.decode`, skipping automatic Candid decoding of the runtime arguments
+ *
+ * @remarks
+ *
+ * Canister initialization generally happens once per canister lifecycle.
+ *
+ * Only one `@init` method is allowed per canister.
+ *
+ * - **State**: read-write
+ *
+ * - **Replication**: yes
+ *
+ * - **Async**: no
+ *
+ * - **Instruction limit**: [300_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#system-api-init).
+ */
+export function init<This, Args extends unknown[], Return>(
+    paramIdlTypes?: IDL.Type[],
+    options?: InitOptions
+): DecoratorFunction<This, Args, Return>;
+
+export function init<This, Args extends unknown[], Return>(
+    param1?: OriginalMethod<This, Args, Return> | IDL.Type[],
+    param2?: Context<This, Args, Return> | InitOptions
+): void | DecoratorFunction<This, Args, Return> {
+    return decoratorArgumentsHandler('init', param1, param2);
+}

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

@@ -0,0 +1,79 @@
+import {
+    Context,
+    decoratorArgumentsHandler,
+    DecoratorFunction,
+    OriginalMethod
+} from '.';
+
+export type InspectMessageOptions = {
+    manual?: boolean;
+};
+
+/**
+ * Decorator to mark a method as the `inspectMessage` entry point.
+ *
+ * @remarks
+ *
+ * The `inspectMessage` entry point will be called just before a call to an `update` entry point.
+ *
+ * The `methodName` of the `update` entry point can be accessed from the first parameter to the decorated method.
+ *
+ * The arguments to the `update` entry point can be accessed from the rest of the parameters to the decorated method.
+ *
+ * Returning true allows the inspected `update` entry point to proceed. Returning anything else will block the `update` entry point from proceeding.
+ *
+ * Only one `@inspectMessage` method is allowed per canister.
+ *
+ * - **State**: read-only
+ *
+ * - **Replication**: none
+ *
+ * - **Async**: no
+ *
+ * - **Instruction limit**: [200_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#system-api-inspect-message).
+ */
+export function inspectMessage<This, Args extends unknown[], Return>(
+    originalMethod: OriginalMethod<This, Args, Return>,
+    context: Context<This, Args, Return>
+): void;
+
+/**
+ * Decorator to mark a method as the `inspectMessage` entry point.
+ *
+ * @param options - Optional configuration object
+ * @param options.manual - Optional flag to indicate manual handling of the method name and runtime arguments of the targeted `update` entry point. This is meant to be used with `msgMethodName`, `msgArgData`, and `IDL.decode`, skipping automatic decoding
+ *
+ * @remarks
+ *
+ * The `inspectMessage` entry point will be called just before a call to an `update` entry point.
+ *
+ * The `methodName` of the `update` entry point can be accessed from the first parameter to the decorated method.
+ *
+ * The arguments to the `update` entry point can be accessed from the rest of the parameters to the decorated method.
+ *
+ * Returning true allows the inspected `update` entry point to proceed. Returning anything else will block the `update` entry point from proceeding.
+ *
+ * Only one `@inspectMessage` method is allowed per canister.
+ *
+ * - **State**: read-only
+ *
+ * - **Replication**: none
+ *
+ * - **Async**: no
+ *
+ * - **Instruction limit**: [200_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#system-api-inspect-message).
+ */
+export function inspectMessage<This, Args extends unknown[], Return>(
+    options?: InspectMessageOptions
+): DecoratorFunction<This, Args, Return>;
+
+export function inspectMessage<This, Args extends unknown[], Return>(
+    param1?: OriginalMethod<This, Args, Return> | InspectMessageOptions,
+    param2?: Context<This, Args, Return>
+): void | DecoratorFunction<This, Args, Return> {
+    return decoratorArgumentsHandler('inspectMessage', param1, param2);
+}

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

@@ -0,0 +1,27 @@
+import { Context, decoratorArgumentsHandler, OriginalMethod } from '.';
+
+/**
+ * Decorator to mark a method as the `onLowWasmMemory` entry point.
+ *
+ * @remarks
+ *
+ * The `onLowWasmMemory` entry point will be called when the canister is running low on Wasm memory.
+ * This is a system method that allows canisters to handle low memory conditions gracefully.
+ *
+ * Only one `onLowWasmMemory` method is allowed per canister.
+ *
+ * // TODO: verify the below info when onLowWasmMemory is fully supported on the IC (see https://forum.dfinity.org/t/how-to-verify-wasm-memory-threshold-is-set-correctly/40670)
+ * - **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)
+ */
+export function onLowWasmMemory<This, Args extends unknown[], Return>(
+    originalMethod: OriginalMethod<This, Args, Return>,
+    context: Context<This, Args, Return>
+): void {
+    decoratorArgumentsHandler('onLowWasmMemory', originalMethod, context);
+}

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

@@ -0,0 +1,73 @@
+import { IDL } from '@dfinity/candid';
+
+import {
+    Context,
+    decoratorArgumentsHandler,
+    DecoratorFunction,
+    OriginalMethod
+} from '.';
+
+export type PostUpgradeOptions = {
+    manual?: boolean;
+};
+
+/**
+ * Decorator to mark a method as the `postUpgrade` entry point.
+ *
+ * @remarks
+ *
+ * Canister upgrades can be performed multiple times per canister lifecycle.
+ *
+ * By default canister upgrades erase the canister's heap memory.
+ *
+ * Only one `@postUpgrade` method is allowed per canister.
+ *
+ * - **State**: read-write
+ *
+ * - **Replication**: yes
+ *
+ * - **Async**: no
+ *
+ * - **Instruction limit**: [300_000_000_000](https://internetcomputer.org/docs/current/developer-docs/smart-contracts/maintain/resource-limits) (shared with `preUpgrade`)
+ */
+export function postUpgrade<This, Args extends unknown[], Return>(
+    originalMethod: OriginalMethod<This, Args, Return>,
+    context: Context<This, Args, Return>
+): void;
+
+/**
+ * Decorator to mark a method as the `postUpgrade` entry point.
+ *
+ * @param paramIdlTypes - Optional array of Candid IDL types for the decorated method parameters. The runtime arguments will be decoded using these types
+ * @param options - Optional configuration object
+ * @param options.manual - Optional flag to indicate manual handling of the decorated method's runtime arguments. This is meant to be used with `msgArgData` and `IDL.decode`, skipping automatic Candid decoding of the runtime arguments
+ *
+ * @remarks
+ *
+ * Canister upgrades can be performed multiple times per canister lifecycle.
+ *
+ * By default canister upgrades erase the canister's heap memory.
+ *
+ * Only one `@postUpgrade` method is allowed per canister.
+ *
+ * - **State**: read-write
+ *
+ * - **Replication**: yes
+ *
+ * - **Async**: no
+ *
+ * - **Instruction limit**: [300_000_000_000](https://internetcomputer.org/docs/current/developer-docs/smart-contracts/maintain/resource-limits) (shared with `@preUpgrade`)
+ *
+ * See [more documentation](https://internetcomputer.org/docs/current/references/ic-interface-spec#system-api-upgrades).
+ */
+export function postUpgrade<This, Args extends unknown[], Return>(
+    paramIdlTypes?: IDL.Type[],
+    options?: PostUpgradeOptions
+): DecoratorFunction<This, Args, Return>;
+
+export function postUpgrade<This, Args extends unknown[], Return>(
+    param1?: OriginalMethod<This, Args, Return> | IDL.Type[],
+    param2?: Context<This, Args, Return> | PostUpgradeOptions
+): void | DecoratorFunction<This, Args, Return> {
+    return decoratorArgumentsHandler('postUpgrade', param1, param2);
+}

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

@@ -0,0 +1,27 @@
+import { Context, decoratorArgumentsHandler, OriginalMethod } from '.';
+
+/**
+ * Decorator to mark a method as the `preUpgrade` entry point.
+ *
+ * @remarks
+ *
+ * The `preUpgrade` method will be called just before the canister is upgraded.
+ *
+ * Only one `@preUpgrade` method is allowed per canister.
+ *
+ * - **State**: read-write
+ *
+ * - **Replication**: yes
+ *
+ * - **Async**: no
+ *
+ * - **Instruction limit**: [300_000_000_000](https://internetcomputer.org/docs/current/developer-docs/smart-contracts/maintain/resource-limits) (shared with `@postUpgrade`)
+ *
+ * See [more documentation](https://internetcomputer.org/docs/current/references/ic-interface-spec#system-api-upgrades).
+ */
+export function preUpgrade<This, Args extends unknown[], Return>(
+    originalMethod: OriginalMethod<This, Args, Return>,
+    context: Context<This, Args, Return>
+): void {
+    decoratorArgumentsHandler('preUpgrade', originalMethod, context);
+}