@ohos-ports/azle 0.33.0-beta.0

package/src/stable/lib/ic_apis/msg_reject_msg.ts

@@ -0,0 +1,24 @@
+/**
+ * Returns the reject message from the last unsuccesful inter-canister call.
+ *
+ * @returns The reject message
+ *
+ * @remarks
+ *
+ * - Will trap if there is no reject message available (if `msgRejectCode()` is `0`)
+ *
+ * - **Call Context**:
+ *   - after an unsuccessful inter-canister await
+ *   - after an unsuccessful inter-canister await from a composite query
+ */
+export function msgRejectMsg(): string {
+    if (globalThis._azleIcExperimental !== undefined) {
+        return globalThis._azleIcExperimental.msgRejectMsg();
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return globalThis._azleIc.msgRejectMsg();
+    }
+
+    return '';
+}

package/src/stable/lib/ic_apis/msg_reply.ts

@@ -0,0 +1,34 @@
+/**
+ * Replies to the current call with raw Candid encoded bytes.
+ *
+ * @param data - The raw bytes to reply with
+ *
+ * @returns void
+ *
+ * @remarks
+ *
+ * - Used in canister methods marked with { manual: true }
+ * - The data must be pre-encoded (e.g. using IDL.encode) before being passed to this function
+ *
+ * - **Call Context**:
+ *   - \@update
+ *   - \@query, replicated and non-replicated
+ *   - \@query(..., { composite: true })
+ *   - after a successful inter-canister await
+ *   - after an unsuccessful inter-canister await
+ *   - after a successful inter-canister await from a composite query
+ *   - after an unsuccessful inter-canister await from a composite query
+ */
+export function msgReply(data: Uint8Array): void {
+    if (globalThis._azleIcExperimental !== undefined) {
+        globalThis._azleIcExperimental.msgReply(
+            data.buffer instanceof ArrayBuffer
+                ? data.buffer
+                : new Uint8Array(data).buffer
+        );
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        globalThis._azleIc.msgReply(data);
+    }
+}

package/src/stable/lib/ic_apis/performance_counter.ts

@@ -0,0 +1,31 @@
+/**
+ * Returns the value of the specified performance counter.
+ *
+ * @param counterType - A supported performance counter type. The available types are:
+ *   - 0: current execution instruction counter. The number of WebAssembly instructions the canister has executed since the beginning of the current message execution
+ *   - 1: call context instruction counter. The number of WebAssembly instructions the canister has executed within the call context of the current message execution since call context creation. The counter monotonically increases across all message executions in the call context until the corresponding call context is removed.
+ *
+ * @returns The performance counter value. Represented as a u64 (max size 2^64 - 1)
+ *
+ * @remarks
+ *
+ *  - Consider using `counterType` `1` in most cases; it measures across inter-canister awaits
+ *
+ * - **Call Context**:
+ *   - any
+ */
+export function performanceCounter(counterType: number): bigint {
+    if (globalThis._azleIcExperimental !== undefined) {
+        return BigInt(
+            globalThis._azleIcExperimental.performanceCounter(
+                counterType.toString()
+            )
+        );
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return globalThis._azleIc.performanceCounter(counterType);
+    }
+
+    return 0n;
+}

package/src/stable/lib/ic_apis/rand_seed.ts

@@ -0,0 +1,40 @@
+/**
+ * Synchronously sets the seed for the Cryptographically Secure Pseudo-Random Number Generator (CSPRNG) used by Azle's implementation of `crypto.getRandomValues`.
+ *
+ * @param seed - The 32 byte seed for the CSPRNG used by Azle's implementation of `crypto.getRandomValues`
+ *
+ * @returns void
+ *
+ * @remarks
+ *
+ * Azle provides CSPRNG functionality through its implementation of `crypto.getRandomValues`.
+ * The underlying CSPRNG must use an appropriate seed for its security properties to hold.
+ * By default Azle will use a delay-0 timer under-the-hood in `@init` and `@postUpgrade` to set the seed with randomness obtained
+ * from the management canister's `raw_rand` method.
+ *
+ * Keep in mind that you should not rely on random bytes obtained from `crypto.getRandomValues` during
+ * the execution of your own `@init` or `@postUpgrade` methods, due to the delay-0 timer running after the completion
+ * of `@init` and `@postUpgrade`.
+ *
+ * This `randSeed` function exists for cases where you want to ensure that `crypto.getRandomValues` uses a specific seed.
+ * It is generally a best practice on ICP to seed on a regular basis, depending on your application's needs.
+ *
+ * The management canister's `raw_rand` method provides an excellent source of randomness.
+ * It is a prime candidate for your own seeding, though you may seed from whatever source you like.
+ *
+ * - **Call Context**:
+ *   - any
+ */
+export function randSeed(seed: Uint8Array): void {
+    if (globalThis._azleIcExperimental !== undefined) {
+        globalThis._azleIcExperimental.randSeed(
+            seed.buffer instanceof ArrayBuffer
+                ? seed.buffer
+                : new Uint8Array(seed).buffer
+        );
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        globalThis._azleIc.randSeed(seed);
+    }
+}

package/src/stable/lib/ic_apis/set_timer.ts

@@ -0,0 +1,80 @@
+import { handleUncaughtError, validateUnsignedInteger } from '../error';
+
+/**
+ * Sets a one-time callback to be executed after a specified delay.
+ *
+ * @param delay - The time to wait before execution, in seconds. Maximum size 2^53 - 1
+ * @param callback - The callback to execute. Can be async
+ * @param asyncCleanup - If `true` (the default), another timer will be set with delay `0` to delete the global state created internally by Azle for this timer invocation. If your timer's callback does not trap, the extra timer is technically unnecessary. This is set to `true` by default for extra safety. This was designed for Azle's internal use, and you most likely should not attempt to change it
+ *
+ * @returns The timer ID (used with `clearTimer` to cancel the timer before it executes)
+ *
+ * @remarks
+ * - Timers are not persisted across canister upgrades
+ * - Timers are deactivated in the following cases
+ *   - Changes to the canister's Wasm module
+ *     - management canister
+ *       - `install_code`
+ *       - `install_chunked_code`
+ *       - `uninstall_code`
+ *     - When the canister runs out of cycles
+ * - Traps if `delay` + `time()` is more than 2^64 - 1 (u64) nanoseconds
+ *
+ * - **Call Context**:
+ *   - \@init
+ *   - \@postUpgrade
+ *   - \@preUpgrade
+ *   - \@update
+ *   - \@heartbeat
+ *   - timer
+ *   - after a successful inter-canister await
+ *   - after an unsuccessful inter-canister await
+ */
+export function setTimer(
+    delay: number,
+    callback: () => void | Promise<void>
+): bigint {
+    if (
+        globalThis._azleIc === undefined &&
+        globalThis._azleIcExperimental === undefined
+    ) {
+        return 0n;
+    }
+
+    validateUnsignedInteger('setTimer delay', 53, delay);
+
+    const timerId =
+        globalThis._azleIcExperimental !== undefined
+            ? BigInt(globalThis._azleIcExperimental.setTimer(delay.toString()))
+            : globalThis._azleIc !== undefined
+              ? globalThis._azleIc.setTimer(delay)
+              : ((): never => {
+                    throw new Error(
+                        'Neither globalThis._azleIc nor globalThis._azleIcExperimental are defined'
+                    );
+                })();
+
+    if (globalThis._azleDispatch === undefined) {
+        throw new Error('globalThis._azleDispatch is undefined');
+    }
+
+    globalThis._azleDispatch({
+        type: 'SET_AZLE_TIMER_CALLBACK',
+        payload: {
+            timerId,
+            timerCallback: async (): Promise<void> => {
+                try {
+                    await callback();
+                } catch (error) {
+                    handleUncaughtError(error);
+                }
+            }
+        },
+        location: {
+            filepath: 'azle/src/stable/lib/ic_apis/set_timer.ts',
+            functionName: 'setTimer'
+        }
+    });
+
+    return timerId;
+}

package/src/stable/lib/ic_apis/set_timer_interval.ts

@@ -0,0 +1,87 @@
+import { handleUncaughtError, validateUnsignedInteger } from '../error';
+
+/**
+ * Sets a callback to be executed periodically every specified interval.
+ *
+ * @param interval - The time between executions, in seconds. Maximum size 2^53 - 1
+ * @param callback - The callback to execute. Can be async
+ *
+ * @returns The timer ID (used with `clearTimer` to cancel the timer)
+ *
+ * @remarks
+ * - Timers are not persisted across canister upgrades
+ * - Timers are deactivated in the following cases
+ *   - Changes to the canister's Wasm module
+ *     - management canister
+ *       - `install_code`
+ *       - `install_chunked_code`
+ *       - `uninstall_code`
+ *     - When the canister runs out of cycles
+ * - Traps if `interval` + `time()` is more than 2^64 - 1 (u64) nanoseconds
+ *
+ * - **Call Context**:
+ *   - \@init
+ *   - \@postUpgrade
+ *   - \@preUpgrade
+ *   - \@update
+ *   - \@heartbeat
+ *   - timer
+ *   - after a successful inter-canister await
+ *   - after an unsuccessful inter-canister await
+ */
+export function setTimerInterval(
+    interval: number,
+    callback: () => void | Promise<void>
+): bigint {
+    if (
+        globalThis._azleIc === undefined &&
+        globalThis._azleIcExperimental === undefined
+    ) {
+        return 0n;
+    }
+
+    validateUnsignedInteger('setTimer interval', 53, interval);
+
+    const timerId =
+        globalThis._azleIcExperimental !== undefined
+            ? BigInt(
+                  globalThis._azleIcExperimental.setTimerInterval(
+                      interval.toString()
+                  )
+              )
+            : globalThis._azleIc !== undefined
+              ? globalThis._azleIc.setTimerInterval(interval)
+              : ((): never => {
+                    throw new Error(
+                        'Neither globalThis._azleIc nor globalThis._azleIcExperimental are defined'
+                    );
+                })();
+
+    // We don't call deleteGlobalTimerCallbacks here because the callback
+    // still needs to exist for the next interval callback execution
+    // Deletion of globalThis._azleTimerCallbacks in the context of setTimerInterval
+    // only occurs through calling clearTimer or manual manipulation of globalThis._azleTimerCallbacks
+    if (globalThis._azleDispatch === undefined) {
+        throw new Error('globalThis._azleDispatch is undefined');
+    }
+
+    globalThis._azleDispatch({
+        type: 'SET_AZLE_TIMER_CALLBACK',
+        payload: {
+            timerId,
+            timerCallback: async (): Promise<void> => {
+                try {
+                    await callback();
+                } catch (error) {
+                    handleUncaughtError(error);
+                }
+            }
+        },
+        location: {
+            filepath: 'azle/src/stable/lib/ic_apis/set_timer_interval.ts',
+            functionName: 'setTimerInterval'
+        }
+    });
+
+    return timerId;
+}

package/src/stable/lib/ic_apis/time.ts

@@ -0,0 +1,26 @@
+/**
+ * Gets the current ICP system time.
+ *
+ * @returns The current ICP system time in nanoseconds since the epoch (1970-01-01). Represented as a u64 (max size 2^64 - 1)
+ *
+ * @remarks
+ *
+ * - The time, as observed by the canister, is monotonically increasing, even across canister upgrades
+ * - Within an invocation of one entry point, the time is constant
+ * - The times observed by different canisters are unrelated, and calls from one canister to another may appear to travel "backwards in time"
+ * - The time will likely be close to the real time, though is not guaranteed to be so
+ *
+ * - **Call Context**:
+ *   - any besides start
+ */
+export function time(): bigint {
+    if (globalThis._azleIcExperimental !== undefined) {
+        return BigInt(globalThis._azleIcExperimental.time());
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return globalThis._azleIc.time();
+    }
+
+    return 0n;
+}

package/src/stable/lib/ic_apis/trap.ts

@@ -0,0 +1,29 @@
+/**
+ * Terminates the current call with an error message.
+ *
+ * @param message - The reject message that will be returned to the caller
+ *
+ * @returns never - This function never returns as it halts execution
+ *
+ * @remarks
+ *
+ * - Immediately stops execution
+ * - Produces a `CANISTER_ERROR` (5) reject code
+ * - Discards all state changes in the current call
+ *
+ * - **Call Context**:
+ *   - any
+ */
+export function trap(message: string): never {
+    if (globalThis._azleIcExperimental !== undefined) {
+        return globalThis._azleIcExperimental.trap(message);
+    }
+
+    if (globalThis._azleIc !== undefined) {
+        return globalThis._azleIc.trap(message);
+    }
+
+    throw new Error(
+        'Neither globalThis._azleIc nor globalThis._azleIcExperimental are defined'
+    );
+}

package/src/stable/lib/index.ts

@@ -0,0 +1,16 @@
+import './globals';
+export { heartbeat } from './canister_methods/heartbeat';
+export { init } from './canister_methods/init';
+export { inspectMessage } from './canister_methods/inspect_message';
+export { onLowWasmMemory } from './canister_methods/on_low_wasm_memory';
+export { postUpgrade } from './canister_methods/post_upgrade';
+export { preUpgrade } from './canister_methods/pre_upgrade';
+export { query } from './canister_methods/query';
+export { update } from './canister_methods/update';
+export * from './did_file';
+export * from './ic_apis';
+export * from './json';
+export * from './stable_structures/stable_b_tree_map';
+export * from './stable_structures/stable_json';
+export * from '@dfinity/candid';
+export * from '@dfinity/principal';

package/src/stable/lib/json.ts

@@ -0,0 +1,39 @@
+import { jsonReplacer, jsonReviver } from './stable_structures/stable_json';
+
+/**
+ * An ICP-enabled wrapper over `JSON.stringify`, handling special types like `Principal`, `BigInt`, and `Uint8Array` by default.
+ *
+ * @param value - A JavaScript value to be converted; usually an object or array
+ * @param replacer - A function that transforms the results. Defaults to {@link jsonReplacer}
+ * @param space - Adds indentation, white space, and line break characters to the return-value JSON text to make it easier to read
+ *
+ * @returns JavaScript Object Notation (JSON) string
+ */
+export function jsonStringify(
+    value: any,
+    replacer?: (this: any, key: string, value: any) => any,
+    space?: string | number
+): string {
+    return JSON.stringify(value, replacer ?? jsonReplacer, space);
+}
+
+/**
+ * An ICP-enabled wrapper over `JSON.parse`, handling special types like `Principal`, `BigInt`, and `Uint8Array` by default.
+ *
+ * @param text - A JSON string valid for the `reviver` used
+ * @param reviver - A function that transforms the results. This function is called for each member of the object. If a member contains nested objects, the nested objects are transformed before the parent object is. Defaults to {@link jsonReviver}
+ *
+ * @returns The parsed JavaScript value
+ */
+export function jsonParse(
+    text: string,
+    reviver?: (this: any, key: string, value: any) => any
+): any {
+    try {
+        return JSON.parse(text, reviver ?? jsonReviver);
+    } catch (error: any) {
+        throw new Error(
+            `jsonParse: Error parsing JSON: ${error.message}. text: ${text}`
+        );
+    }
+}