quickjs-emscripten-sync 1.5.1 → 1.6.0

package/dist/index.d.ts

@@ -1,14 +1,14 @@
-import type { 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 { QuickJSContext } 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.
  */
 export declare class Arena {
-    context: QuickJSContext;
+    context: QuickJSContextEx;
     _map: VMMap;
     _registeredMap: VMMap;
     _registeredMapDispose: Set<any>;
@@ -27,10 +27,125 @@ 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. The module can import/export, but the return value
+     * depends on whether the module exports are accessible (implementation varies by quickjs-emscripten version).
+     * Use this for side effects or when you don't need access to exports.
+     *
+     * @param code - The ES module code to evaluate
+     * @param filename - Optional filename for debugging purposes (default: "module.js")
+     * @returns Undefined in most cases (module side effects are applied)
+     *
+     * @example
+     * ```js
+     * // Execute module code with side effects
+     * arena.expose({ data: { count: 0 } });
+     * arena.evalModule('import { data } from "globals"; data.count = 42;'); // undefined, but data.count is now 42
+     * ```
+     */
+    evalModule(code: string, filename?: string): void;
     /**
      * 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.
      *
@@ -129,6 +244,8 @@ export declare type Options = {
     isHandleWrappable?: (handle: QuickJSHandle, ctx: QuickJSContext) => boolean;
     /** Compatibility with quickjs-emscripten prior to v0.15. Inject code for compatibility into context at Arena class initialization time. */
     compat?: boolean;
+    /** Experimental: use QuickJSContextEx, which wraps existing QuickJSContext. */
+    experimentalContextEx?: boolean;
 };
 
 declare type Options_2 = {
@@ -150,6 +267,10 @@ declare type Options_3 = {
     custom?: Iterable<(obj: QuickJSHandle, ctx: QuickJSContext) => any>;
 };
 
+declare type QuickJSContextEx = QuickJSContext & {
+    disposeEx?: () => void;
+};
+
 export declare function unmarshal(handle: QuickJSHandle, options: Options_3): any;
 
 export declare class VMMap {
@@ -172,7 +293,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;