quickjs-emscripten-sync 1.5.1 → 1.6.0

package/src/index.test.ts

@@ -218,6 +218,42 @@ describe("evalCode", () => {
     arena.dispose();
     ctx.dispose();
   });
+
+  test("async function", async () => {
+    const ctx = (await getQuickJS()).newContext();
+    const arena = new Arena(ctx, { isMarshalable: true });
+
+    const consolelog = vi.fn();
+    arena.expose({
+      console: {
+        log: consolelog,
+      },
+    });
+
+    arena.evalCode(`
+      const someAsyncOperation = async () => "hello";
+      const execute = async () => {
+        try {
+          const res = await someAsyncOperation();
+          console.log(res);
+        } catch (e) {
+          console.log(e);
+        }
+      };
+      execute();
+    `);
+    expect(consolelog).toBeCalledTimes(0);
+    expect(arena.executePendingJobs()).toBe(2);
+
+    arena.executePendingJobs();
+
+    expect(consolelog).toBeCalledTimes(1);
+    expect(consolelog).toBeCalledWith("hello");
+    expect(arena.executePendingJobs()).toBe(0);
+
+    arena.dispose();
+    ctx.dispose();
+  });
 });
 
 describe("expose without sync", () => {
@@ -577,41 +613,301 @@ describe("isMarshalable option", () => {
   });
 });
 
-describe("edge cases", () => {
-  test("getter", async () => {
+describe("evalModule", () => {
+  test("module can modify exposed globals", async () => {
     const ctx = (await getQuickJS()).newContext();
     const arena = new Arena(ctx, { isMarshalable: true });
 
-    const called: string[] = [];
-    const obj = { c: 0 };
-    const exposed = {
-      get a() {
-        called.push("a");
-        return {
-          get b() {
-            called.push("b");
-            return obj;
-          },
-        };
-      },
-    };
-    const cb: { current?: () => any } = {};
-    const register = (fn: () => any) => {
-      cb.current = fn;
-    };
+    const data = arena.sync({ count: 0, message: "" });
+    arena.expose({ data });
 
-    arena.expose({ exposed, register });
-    expect(called).toEqual([]);
+    // Module code can have side effects on exposed globals
+    arena.evalModule(`
+      data.count = 42;
+      data.message = "Hello from module";
+    `);
 
-    arena.evalCode(`register(() => exposed.a.b.c);`);
-    expect(cb.current?.()).toBe(0);
-    expect(called).toEqual(["a", "b"]);
+    expect(data.count).toBe(42);
+    expect(data.message).toBe("Hello from module");
 
-    obj.c = 1;
-    expect(cb.current?.()).toBe(1); // this line causes an error when context is disposed
-    expect(called).toEqual(["a", "b", "a", "b"]);
+    arena.dispose();
+    ctx.dispose();
+  });
+
+  test("module with function side effects", async () => {
+    const ctx = (await getQuickJS()).newContext();
+    const arena = new Arena(ctx, { isMarshalable: true });
+
+    const results: number[] = [];
+    arena.expose({
+      results,
+      push: (value: number) => results.push(value),
+    });
+
+    arena.evalModule(`
+      push(1);
+      push(2);
+      push(3);
+    `);
+
+    expect(results).toEqual([1, 2, 3]);
 
     arena.dispose();
-    // ctx.dispose(); // reports an error
+    ctx.dispose();
+  });
+
+  test("module can define and use internal exports", async () => {
+    const ctx = (await getQuickJS()).newContext();
+    const arena = new Arena(ctx, { isMarshalable: true });
+
+    const output = arena.sync({ value: 0 });
+    arena.expose({ output });
+
+    // Module can export and use its own exports internally
+    arena.evalModule(`
+      export function double(x) {
+        return x * 2;
+      }
+
+      export const value = 21;
+
+      // Use the exports internally
+      output.value = double(value);
+    `);
+
+    expect(output.value).toBe(42);
+
+    arena.dispose();
+    ctx.dispose();
+  });
+
+  test("module with custom filename", async () => {
+    const ctx = (await getQuickJS()).newContext();
+    const arena = new Arena(ctx, { isMarshalable: true });
+
+    const state = arena.sync({ executed: false });
+    arena.expose({ state });
+
+    // Test that custom filename doesn't break functionality
+    arena.evalModule(`state.executed = true;`, "custom-module.js");
+
+    expect(state.executed).toBe(true);
+
+    arena.dispose();
+    ctx.dispose();
+  });
+
+  test("module with strict mode", async () => {
+    const ctx = (await getQuickJS()).newContext();
+    const arena = new Arena(ctx, { isMarshalable: true });
+
+    const result = arena.sync({ ok: false });
+    arena.expose({ result });
+
+    // Modules are strict by default
+    arena.evalModule(`
+      // This would fail in strict mode if we tried: undeclaredVariable = 1;
+      result.ok = true;
+    `);
+
+    expect(result.ok).toBe(true);
+
+    arena.dispose();
+    ctx.dispose();
+  });
+});
+
+describe("memory management", () => {
+  test("getMemoryUsage returns statistics", async () => {
+    const ctx = (await getQuickJS()).newContext();
+    const arena = new Arena(ctx, { isMarshalable: true });
+
+    const stats = arena.getMemoryUsage();
+
+    // Check that key properties exist
+    expect(stats).toHaveProperty("memory_used_size");
+    expect(stats).toHaveProperty("malloc_limit");
+    expect(stats).toHaveProperty("obj_count");
+    expect(stats).toHaveProperty("malloc_count");
+
+    // Memory should be used
+    expect(stats.memory_used_size).toBeGreaterThan(0);
+    expect(stats.malloc_count).toBeGreaterThan(0);
+
+    arena.dispose();
+    ctx.dispose();
+  });
+
+  test("getMemoryUsage tracks allocations", async () => {
+    const ctx = (await getQuickJS()).newContext();
+    const arena = new Arena(ctx, { isMarshalable: true });
+
+    const before = arena.getMemoryUsage();
+
+    // Allocate some objects
+    arena.evalCode(`
+      const arr = [];
+      for (let i = 0; i < 100; i++) {
+        arr.push({ id: i, data: "test".repeat(10) });
+      }
+    `);
+
+    const after = arena.getMemoryUsage();
+
+    // Memory usage should increase
+    expect(after.memory_used_size).toBeGreaterThan(before.memory_used_size);
+    expect(after.obj_count).toBeGreaterThan(before.obj_count);
+
+    arena.dispose();
+    ctx.dispose();
+  });
+
+  test("dumpMemoryUsage returns formatted string", async () => {
+    const ctx = (await getQuickJS()).newContext();
+    const arena = new Arena(ctx, { isMarshalable: true });
+
+    const dump = arena.dumpMemoryUsage();
+
+    // Should be a non-empty string
+    expect(typeof dump).toBe("string");
+    expect(dump.length).toBeGreaterThan(0);
+
+    // Should contain key memory metrics (the format varies)
+    expect(dump).toMatch(/memory|malloc/i);
+
+    arena.dispose();
+    ctx.dispose();
+  });
+
+  test("setMemoryLimit enforces memory constraints", async () => {
+    const ctx = (await getQuickJS()).newContext();
+    const arena = new Arena(ctx, { isMarshalable: true });
+
+    // Set a low memory limit (100KB)
+    arena.setMemoryLimit(100 * 1024);
+
+    // Verify limit is set
+    const stats = arena.getMemoryUsage();
+    expect(stats.malloc_limit).toBe(100 * 1024);
+
+    // Try to allocate too much memory
+    expect(() => {
+      arena.evalCode(`
+        const huge = [];
+        for (let i = 0; i < 1000000; i++) {
+          huge.push({ data: "x".repeat(1000) });
+        }
+      `);
+    }).toThrow();
+
+    arena.dispose();
+    ctx.dispose();
+  });
+
+  test("setMemoryLimit can be removed with -1", async () => {
+    const ctx = (await getQuickJS()).newContext();
+    const arena = new Arena(ctx, { isMarshalable: true });
+
+    // Set a limit
+    arena.setMemoryLimit(100 * 1024);
+    expect(arena.getMemoryUsage().malloc_limit).toBe(100 * 1024);
+
+    // Remove the limit
+    arena.setMemoryLimit(-1);
+    const stats = arena.getMemoryUsage();
+    expect(stats.malloc_limit).toBeGreaterThan(100 * 1024);
+
+    arena.dispose();
+    ctx.dispose();
+  });
+
+  test("setMaxStackSize prevents stack overflow", async () => {
+    const ctx = (await getQuickJS()).newContext();
+    const arena = new Arena(ctx, { isMarshalable: true });
+
+    // Set a small stack size (256KB)
+    arena.setMaxStackSize(256 * 1024);
+
+    // Try to cause stack overflow with deep recursion
+    expect(() => {
+      arena.evalCode(`
+        function recurse(n) {
+          if (n > 0) return recurse(n - 1);
+          return n;
+        }
+        recurse(100000);
+      `);
+    }).toThrow();
+
+    arena.dispose();
+    ctx.dispose();
+  });
+
+  test("setMaxStackSize can be removed with 0", async () => {
+    const ctx = (await getQuickJS()).newContext();
+    const arena = new Arena(ctx, { isMarshalable: true });
+
+    // Set a very small stack
+    arena.setMaxStackSize(128 * 1024);
+
+    // This should fail with small stack
+    expect(() => {
+      arena.evalCode(`
+        function recurse(n) {
+          if (n > 0) return recurse(n - 1);
+          return n;
+        }
+        recurse(10000);
+      `);
+    }).toThrow();
+
+    // Remove the limit
+    arena.setMaxStackSize(0);
+
+    // Now it should work (or at least get further)
+    const result = arena.evalCode(`
+      function recurse(n) {
+        if (n > 0) return recurse(n - 1);
+        return n;
+      }
+      recurse(1000);
+    `);
+
+    expect(result).toBe(0);
+
+    arena.dispose();
+    ctx.dispose();
+  });
+
+  test("memory limits work with marshaling", async () => {
+    const ctx = (await getQuickJS()).newContext();
+    const arena = new Arena(ctx, { isMarshalable: true });
+
+    // Set limit
+    arena.setMemoryLimit(200 * 1024);
+
+    const data = arena.sync({ items: [] as any[] });
+    arena.expose({ data });
+
+    // Should be able to add reasonable data
+    arena.evalCode(`
+      for (let i = 0; i < 10; i++) {
+        data.items.push({ id: i });
+      }
+    `);
+
+    expect(data.items.length).toBe(10);
+
+    // But not unlimited data
+    expect(() => {
+      arena.evalCode(`
+        for (let i = 0; i < 100000; i++) {
+          data.items.push({ id: i, data: "x".repeat(1000) });
+        }
+      `);
+    }).toThrow();
+
+    arena.dispose();
+    ctx.dispose();
   });
 });

package/src/index.ts

@@ -6,6 +6,7 @@ import type {
   VmCallResult,
 } from "quickjs-emscripten";
 
+import { wrapContext, QuickJSContextEx } from "./contextex";
 import { defaultRegisteredObjects } from "./default";
 import marshal from "./marshal";
 import unmarshal from "./unmarshal";
@@ -48,13 +49,15 @@ export 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;
 };
 
 /**
  * The Arena class manages all generated handles at once by quickjs-emscripten and automatically converts objects between the host and the QuickJS VM.
  */
 export class Arena {
-  context: QuickJSContext;
+  context: QuickJSContextEx;
   _map: VMMap;
   _registeredMap: VMMap;
   _registeredMapDispose: Set<any> = new Set();
@@ -74,7 +77,7 @@ export class Arena {
       };
     }
 
-    this.context = ctx;
+    this.context = options?.experimentalContextEx ? wrapContext(ctx) : ctx;
     this._options = options;
     this._symbolHandle = ctx.unwrapResult(ctx.evalCode(`Symbol()`));
     this._map = new VMMap(ctx);
@@ -89,6 +92,7 @@ export class Arena {
     this._map.dispose();
     this._registeredMap.dispose();
     this._symbolHandle.dispose();
+    this.context.disposeEx?.();
   }
 
   /**
@@ -99,6 +103,27 @@ export class Arena {
     return this._unwrapResultAndUnmarshal(handle);
   }
 
+  /**
+   * 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 = "module.js"): void {
+    const handle = this.context.evalCode(code, filename, { type: "module" });
+    this._unwrapResultAndUnmarshal(handle);
+  }
+
   /**
    * Almost same as `vm.executePendingJobs()`, but it converts and re-throws error objects when an error is thrown during evaluation.
    */
@@ -110,6 +135,121 @@ export class Arena {
     throw this._unwrapIfNotSynced(result.error.consume(this._unmarshal));
   }
 
+  /**
+   * 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 {
+    this.context.runtime.setMemoryLimit(limitBytes);
+  }
+
+  /**
+   * 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 {
+    this.context.runtime.setMaxStackSize(stackSize);
+  }
+
+  /**
+   * 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;
+  } {
+    const handle = this.context.runtime.computeMemoryUsage();
+    try {
+      return this.context.dump(handle);
+    } finally {
+      handle.dispose();
+    }
+  }
+
+  /**
+   * 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 {
+    return this.context.runtime.dumpMemoryUsage();
+  }
+
   /**
    * Expose objects as global objects in the VM.
    *

package/src/marshal/index.test.ts

@@ -153,7 +153,7 @@ test("class", async () => {
     }
   }
 
-  expect(A.name).toBe("_A"); // class A's name is _A in vitest
+  expect(A.name).toBe("A");
   const handle = marshal(A);
   if (!map) throw new Error("map is undefined");
 
@@ -167,7 +167,7 @@ test("class", async () => {
 
   expect(ctx.typeof(handle)).toBe("function");
   expect(ctx.dump(ctx.getProp(handle, "length"))).toBe(1);
-  expect(ctx.dump(ctx.getProp(handle, "name"))).toBe("_A");
+  expect(ctx.dump(ctx.getProp(handle, "name"))).toBe("A");
   const staticA = ctx.getProp(handle, "a");
   expect(instanceOf(ctx, staticA, handle)).toBe(true);
   expect(ctx.dump(ctx.getProp(staticA, "a"))).toBe(100);

package/src/vmmap.ts

@@ -12,7 +12,7 @@ export default class VMMap {
   _mapSet: QuickJSHandle;
   _mapDelete: QuickJSHandle;
   _mapClear: QuickJSHandle;
-  _counter = 0;
+  _counter = Number.MIN_SAFE_INTEGER;
 
   constructor(ctx: QuickJSContext) {
     this.ctx = ctx;

package/src/wrapper.ts

@@ -1,7 +1,7 @@
 import type { QuickJSHandle, QuickJSContext } from "quickjs-emscripten";
 
 import { isObject } from "./util";
-import { call, isHandleObject, consumeAll, mayConsumeAll } from "./vmutil";
+import { call, isHandleObject, mayConsumeAll } from "./vmutil";
 
 export type SyncMode = "both" | "vm" | "host";
 
@@ -86,32 +86,45 @@ export function wrapHandle(
 
   if (isHandleWrapped(ctx, handle, proxyKeySymbolHandle)) return [handle, false];
 
-  return consumeAll(
-    [
-      ctx.newFunction("getSyncMode", h => {
-        const res = syncMode?.(unmarshal(h));
-        if (typeof res === "string") return ctx.newString(res);
-        return ctx.undefined;
-      }),
-      ctx.newFunction("setter", (h, keyHandle, valueHandle) => {
-        const target = unmarshal(h);
-        if (!target) return;
-        const key = unmarshal(keyHandle);
-        if (key === "__proto__") return; // for security
-        const value = unmarshal(valueHandle);
-        unwrap(target, proxyKeySymbol)[key] = value;
-      }),
-      ctx.newFunction("deleter", (h, keyHandle) => {
-        const target = unmarshal(h);
-        if (!target) return;
-        const key = unmarshal(keyHandle);
-        delete unwrap(target, proxyKeySymbol)[key];
-      }),
-    ],
-    args => [
+  const getSyncMode = (h: QuickJSHandle) => {
+    const res = syncMode?.(unmarshal(h));
+    if (typeof res === "string") return ctx.newString(res);
+    return ctx.undefined;
+  };
+
+  const setter = (h: QuickJSHandle, keyHandle: QuickJSHandle, valueHandle: QuickJSHandle) => {
+    const target = unmarshal(h);
+    if (!target) return;
+    const key = unmarshal(keyHandle);
+    if (key === "__proto__") return; // for security
+    const value = unmarshal(valueHandle);
+    unwrap(target, proxyKeySymbol)[key] = value;
+  };
+
+  const deleter = (h: QuickJSHandle, keyHandle: QuickJSHandle) => {
+    const target = unmarshal(h);
+    if (!target) return;
+    const key = unmarshal(keyHandle);
+    delete unwrap(target, proxyKeySymbol)[key];
+  };
+
+  return ctx
+    .newFunction("proxyFuncs", (t, ...args) => {
+      const name = ctx.getNumber(t);
+      switch (name) {
+        case 1:
+          return getSyncMode(args[0]);
+        case 2:
+          return setter(args[0], args[1], args[2]);
+        case 3:
+          return deleter(args[0], args[1]);
+      }
+      return ctx.undefined;
+    })
+    .consume(proxyFuncs => [
       call(
         ctx,
-        `(target, sym, getSyncMode, setter, deleter) => {
+        `(target, sym, proxyFuncs) => {
           const rec =  new Proxy(target, {
             get(obj, key, receiver) {
               return key === sym ? obj : Reflect.get(obj, key, receiver)
@@ -120,19 +133,19 @@ export function wrapHandle(
               const v = typeof value === "object" && value !== null || typeof value === "function"
                 ? value[sym] ?? value
                 : value;
-              const sync = getSyncMode(receiver) ?? "vm";
+              const sync = proxyFuncs(1, receiver) ?? "vm";
               if (sync === "host" || Reflect.set(obj, key, v, receiver)) {
                 if (sync !== "vm") {
-                  setter(receiver, key, v);
+                  proxyFuncs(2, receiver, key, v);
                 }
               }
               return true;
             },
             deleteProperty(obj, key) {
-              const sync = getSyncMode(rec) ?? "vm";
+              const sync = proxyFuncs(1, rec) ?? "vm";
               if (sync === "host" || Reflect.deleteProperty(obj, key)) {
                 if (sync !== "vm") {
-                  deleter(rec, key);
+                  proxyFuncs(3, rec, key);
                 }
               }
               return true;
@@ -143,11 +156,10 @@ export function wrapHandle(
         undefined,
         handle,
         proxyKeySymbolHandle,
-        ...args,
+        proxyFuncs,
       ) as Wrapped<QuickJSHandle>,
       true,
-    ],
-  );
+    ]);
 }
 
 export function unwrap<T>(obj: T, key: string | symbol): T {