quickjs-emscripten-sync 1.5.2 → 1.7.0

package/dist/index.d.ts

@@ -1,8 +1,9 @@
+import { Intrinsics } from 'quickjs-emscripten';
 import { QuickJSContext } from 'quickjs-emscripten';
-import type { QuickJSDeferredPromise } from 'quickjs-emscripten';
-import type { QuickJSHandle } from 'quickjs-emscripten';
-import type { SuccessOrFail } from 'quickjs-emscripten';
-import type { VmCallResult } from 'quickjs-emscripten';
+import { QuickJSDeferredPromise } from 'quickjs-emscripten';
+import { QuickJSHandle } from 'quickjs-emscripten';
+import { SuccessOrFail } from 'quickjs-emscripten';
+import { VmCallResult } from 'quickjs-emscripten';
 
 /**
  * The Arena class manages all generated handles at once by quickjs-emscripten and automatically converts objects between the host and the QuickJS VM.
@@ -27,10 +28,141 @@ export declare class Arena {
      * Evaluate JS code in the VM and get the result as an object on the host side. It also converts and re-throws error objects when an error is thrown during evaluation.
      */
     evalCode<T = any>(code: string): T;
+    /**
+     * Evaluate ES module code in the VM and get the module's exports.
+     *
+     * Requires quickjs-emscripten >= 0.29.0 for export access.
+     *
+     * @param code - The ES module code to evaluate
+     * @param filename - Optional filename for debugging purposes (default: "module.js")
+     * @returns The module's exports object, or a Promise resolving to exports if using top-level await
+     *
+     * @example
+     * ```js
+     * // Simple module with exports
+     * const exports = arena.evalModule(`
+     *   export const value = 42;
+     *   export function greet(name) {
+     *     return "Hello, " + name;
+     *   }
+     * `);
+     * console.log(exports.value); // 42
+     * console.log(exports.greet("World")); // "Hello, World"
+     *
+     * // Module with default export
+     * const mod = arena.evalModule('export default function(x) { return x * 2; }');
+     * console.log(mod.default(21)); // 42
+     *
+     * // Module with top-level await
+     * const promise = arena.evalModule('export const data = await Promise.resolve(123);');
+     * arena.executePendingJobs();
+     * const exports = await promise;
+     * console.log(exports.data); // 123
+     * ```
+     */
+    evalModule<T = any>(code: string, filename?: string): T | Promise<T>;
     /**
      * Almost same as `vm.executePendingJobs()`, but it converts and re-throws error objects when an error is thrown during evaluation.
      */
     executePendingJobs(maxJobsToExecute?: number): number;
+    /**
+     * Set the max memory this runtime can allocate.
+     * To remove the limit, set to `-1`.
+     *
+     * This is useful for preventing runaway memory usage in untrusted code.
+     *
+     * @param limitBytes - Maximum memory in bytes, or -1 to remove limit
+     *
+     * @example
+     * ```js
+     * // Limit sandbox to 10MB
+     * arena.setMemoryLimit(10 * 1024 * 1024);
+     *
+     * try {
+     *   arena.evalCode(`const huge = new Array(1000000000);`);
+     * } catch (e) {
+     *   console.log("Memory limit exceeded");
+     * }
+     * ```
+     */
+    setMemoryLimit(limitBytes: number): void;
+    /**
+     * Set the max stack size for this runtime, in bytes.
+     * To remove the limit, set to `0`.
+     *
+     * This is useful for preventing stack overflow from deeply nested calls or recursion.
+     *
+     * @param stackSize - Maximum stack size in bytes, or 0 to remove limit
+     *
+     * @example
+     * ```js
+     * // Limit stack to 512KB
+     * arena.setMaxStackSize(512 * 1024);
+     *
+     * try {
+     *   arena.evalCode(`function recurse() { recurse(); } recurse();`);
+     * } catch (e) {
+     *   console.log("Stack overflow prevented");
+     * }
+     * ```
+     */
+    setMaxStackSize(stackSize: number): void;
+    /**
+     * Get detailed memory usage statistics for this runtime.
+     *
+     * @returns An object containing detailed memory allocation information
+     *
+     * @example
+     * ```js
+     * const stats = arena.getMemoryUsage();
+     * console.log(`Memory used: ${stats.memory_used_size} bytes`);
+     * console.log(`Object count: ${stats.obj_count}`);
+     * console.log(`Memory limit: ${stats.malloc_limit}`);
+     * ```
+     */
+    getMemoryUsage(): {
+        malloc_limit: number;
+        memory_used_size: number;
+        malloc_count: number;
+        memory_used_count: number;
+        atom_count: number;
+        atom_size: number;
+        str_count: number;
+        str_size: number;
+        obj_count: number;
+        obj_size: number;
+        prop_count: number;
+        prop_size: number;
+        shape_count: number;
+        shape_size: number;
+        js_func_count: number;
+        js_func_size: number;
+        js_func_code_size: number;
+        js_func_pc2line_count: number;
+        js_func_pc2line_size: number;
+        c_func_count: number;
+        array_count: number;
+        fast_array_count: number;
+        fast_array_elements: number;
+        binary_object_count: number;
+        binary_object_size: number;
+    };
+    /**
+     * Get a human-readable description of memory usage in this runtime.
+     *
+     * @returns A formatted string showing memory statistics
+     *
+     * @example
+     * ```js
+     * console.log(arena.dumpMemoryUsage());
+     * // Output:
+     * // QuickJS memory usage:
+     * //   malloc_limit: 4294967295
+     * //   memory_used_size: 67078
+     * //   ...
+     * ```
+     */
+    dumpMemoryUsage(): string;
     /**
      * Expose objects as global objects in the VM.
      *
@@ -101,6 +233,8 @@ export declare const defaultRegisteredObjects: [any, string][];
 
 export declare function eq(ctx: QuickJSContext, a: QuickJSHandle, b: QuickJSHandle): boolean;
 
+export { Intrinsics }
+
 export declare function isES2015Class(cls: any): cls is new (...args: any[]) => any;
 
 export declare function isHandleObject(ctx: QuickJSContext, h: QuickJSHandle): boolean;
@@ -178,7 +312,7 @@ export declare class VMMap {
     getByHandle(handle: QuickJSHandle): any;
     has(key: any): boolean;
     hasHandle(handle: QuickJSHandle): boolean;
-    keys(): IterableIterator<any>;
+    keys(): MapIterator<any>;
     delete(key: any, dispose?: boolean): void;
     deleteByHandle(handle: QuickJSHandle, dispose?: boolean): void;
     clear(): void;