quickjs-emscripten-sync 1.9.1 → 1.11.0

package/src/index.ts

@@ -6,13 +6,17 @@ import type {
   SuccessOrFail,
   VmCallResult,
   Intrinsics,
+  ContextEvalOptions,
+  InterruptHandler,
 } from "quickjs-emscripten";
 
-import { wrapContext, QuickJSContextEx } from "./contextex";
+import type { QuickJSContextEx } from "./contextex";
+import { wrapContext } from "./contextex";
 import { defaultRegisteredObjects } from "./default";
 import marshal from "./marshal";
 import unmarshal from "./unmarshal";
 import unmarshalHostRef from "./unmarshal/hostref";
+import unmarshalPrimitive from "./unmarshal/primitive";
 import { complexity, isES2015Class, isObject, walkObject } from "./util";
 import VMMap from "./vmmap";
 import {
@@ -26,7 +30,8 @@ import {
   enableFnCache,
   disposeFnCache,
 } from "./vmutil";
-import { wrap, wrapHandle, unwrap, unwrapHandle, Wrapped } from "./wrapper";
+import type { Wrapped, WrapHandle } from "./wrapper";
+import { wrap, createWrapHandle, unwrap, unwrapHandle } from "./wrapper";
 
 export {
   VMMap,
@@ -43,7 +48,7 @@ export {
   consumeAll,
 };
 
-export type { Intrinsics };
+export type { Intrinsics, ContextEvalOptions, InterruptHandler };
 
 export type Options = {
   /** A callback that returns a boolean value that determines whether an object is marshalled or not. If false, no marshaling will be done and undefined will be passed to the QuickJS VM, otherwise marshaling will be done. By default, all objects will be marshalled. */
@@ -69,6 +74,34 @@ export type Options = {
   syncEnabled?: boolean;
   /** A callback that returns whether an object should be passed to the VM by reference (as an opaque HostRef) instead of being marshalled by value/proxy. The guest cannot read such objects, but can hold them and pass them back to the host, where they resolve to the original object. */
   marshalByReference?: (target: any) => boolean;
+  /**
+   * Marshal selected host functions as *asyncified* functions. Normally an async
+   * host function is marshalled like any other function, so the guest receives a
+   * marshalled `Promise`. When a function is asyncified, the QuickJS VM instead
+   * suspends until the host promise settles and the guest receives the resolved
+   * value synchronously (as if the call were blocking).
+   *
+   * - `true`: asyncify every host function that is *declared* async, auto-detected
+   *   via `Object.prototype.toString.call(fn) === "[object AsyncFunction]"`. Note
+   *   that functions transpiled to ES5 (e.g. by Babel/TypeScript targeting older
+   *   runtimes) are plain functions returning a promise and are **not** detected —
+   *   use the predicate form for those.
+   * - predicate: asyncify exactly the functions for which it returns `true`. It is
+   *   called with the *unwrapped* target (the original function, not a sync proxy),
+   *   like `isMarshalable`.
+   * - absent/`false`: current behavior; async functions yield a `Promise` in the guest.
+   *
+   * Constraints (Emscripten Asyncify):
+   * - Asyncified functions only work when evaluation is entered through an async
+   *   entry point ({@link AsyncArena.evalCodeAsync}). Calling one during a
+   *   synchronous `evalCode` fails with `Error: Function unexpectedly returned a Promise`.
+   * - Only ONE suspended call is allowed at a time; concurrent suspension throws a
+   *   runtime error from quickjs-emscripten.
+   * - If the context does not support `newAsyncifiedFunction` (a plain sync context
+   *   from `getQuickJS().newContext()`), this option is silently ignored and async
+   *   functions behave as today (Promise).
+   */
+  asyncify?: boolean | ((target: (...args: any[]) => any) => boolean);
 };
 
 /**
@@ -91,6 +124,7 @@ export class Arena {
   _temporalSync = new Set<any>();
   _symbol = Symbol();
   _symbolHandle: QuickJSHandle;
+  _wrapHandleImpl: WrapHandle;
   _options?: Options;
 
   /** Constructs a new Arena instance. It requires a quickjs-emscripten context initialized with `quickjs.newContext()`. */
@@ -107,6 +141,17 @@ export class Arena {
     enableFnCache(this.context);
     this._options = options;
     this._symbolHandle = ctx.unwrapResult(ctx.evalCode(`Symbol()`));
+    // One proxyFuncs handle shared by every wrapped handle for the Arena's
+    // lifetime, instead of allocating a fresh VM function per wrap.
+    this._wrapHandleImpl = createWrapHandle(
+      this.context,
+      this._symbol,
+      this._symbolHandle,
+      this._unmarshal,
+      this._syncMode,
+      this._options?.isHandleWrappable,
+      this._options?.syncEnabled ?? true,
+    );
     this._map = new VMMap(ctx);
     this._registeredMap = new VMMap(ctx);
     this.registerAll(options?.registeredObjects ?? defaultRegisteredObjects);
@@ -122,6 +167,7 @@ export class Arena {
     this._transientHandles.clear();
     this._map.dispose();
     this._registeredMap.dispose();
+    this._wrapHandleImpl.dispose();
     this._symbolHandle.dispose();
     disposeFnCache(this.context);
     this.context.disposeEx?.();
@@ -134,9 +180,15 @@ export 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.
+   *
+   * @param code - The JS code to evaluate
+   * @param filename - Optional filename used in error stacks and for debugging
+   * @param options - Optional eval options forwarded to quickjs-emscripten's
+   *   `evalCode`, either an `EvalFlags` bitmask (`number`) or a
+   *   {@link ContextEvalOptions} object (e.g. `{ strict: true }`)
    */
-  evalCode<T = any>(code: string): T {
-    const handle = this.context.evalCode(code);
+  evalCode<T = any>(code: string, filename?: string, options?: number | ContextEvalOptions): T {
+    const handle = this.context.evalCode(code, filename, options);
     return this._unwrapResultAndUnmarshal(handle);
   }
 
@@ -147,6 +199,10 @@ export class Arena {
    *
    * @param code - The ES module code to evaluate
    * @param filename - Optional filename for debugging purposes (default: "module.js")
+   * @param options - Optional {@link ContextEvalOptions}. `type` is always forced
+   *   to `"module"`, so any `type` in `options` is overridden. A numeric
+   *   `EvalFlags` bitmask cannot be merged with the forced module type and is
+   *   therefore not supported here; if a number is passed it is ignored.
    * @returns The module's exports object, or a Promise resolving to exports if using top-level await
    *
    * @example
@@ -172,8 +228,15 @@ export class Arena {
    * console.log(exports.data); // 123
    * ```
    */
-  evalModule<T = any>(code: string, filename = "module.js"): T | Promise<T> {
-    const handle = this.context.evalCode(code, filename, { type: "module" });
+  evalModule<T = any>(
+    code: string,
+    filename = "module.js",
+    options?: number | ContextEvalOptions,
+  ): T | Promise<T> {
+    const handle = this.context.evalCode(code, filename, {
+      ...(typeof options === "number" ? {} : options),
+      type: "module",
+    });
     return this._unwrapResultAndUnmarshal(handle);
   }
 
@@ -236,6 +299,45 @@ export class Arena {
     this.context.runtime.setMaxStackSize(stackSize);
   }
 
+  /**
+   * Set a callback which is regularly called by the QuickJS engine when it is
+   * executing code. This callback can be used to implement an execution
+   * timeout: return `true` from the handler to interrupt the running code.
+   *
+   * This is useful for preventing runaway CPU usage (e.g. infinite loops) in
+   * untrusted code.
+   *
+   * @param cb - The interrupt handler. Return `true` to interrupt execution.
+   *
+   * @example
+   * ```js
+   * // Interrupt evaluation after 1 second
+   * const deadline = Date.now() + 1000;
+   * arena.setInterruptHandler(() => Date.now() > deadline);
+   *
+   * try {
+   *   arena.evalCode(`while (true) {}`);
+   * } catch (e) {
+   *   console.log("Execution interrupted");
+   * }
+   * ```
+   */
+  setInterruptHandler(cb: InterruptHandler): void {
+    this.context.runtime.setInterruptHandler(cb);
+  }
+
+  /**
+   * Remove the interrupt handler previously set with `setInterruptHandler`.
+   *
+   * @example
+   * ```js
+   * arena.removeInterruptHandler();
+   * ```
+   */
+  removeInterruptHandler(): void {
+    this.context.runtime.removeInterruptHandler();
+  }
+
   /**
    * Get detailed memory usage statistics for this runtime.
    *
@@ -407,6 +509,15 @@ export class Arena {
     return !!this._options?.marshalByReference?.(this._unwrap(t));
   };
 
+  _asyncify = (t: unknown): boolean => {
+    const a = this._options?.asyncify;
+    if (!a) return false;
+    const target = this._unwrap(t);
+    if (typeof a === "function") return typeof target === "function" && a(target as any);
+    // `a === true`: auto-detect functions declared with `async`.
+    return Object.prototype.toString.call(target) === "[object AsyncFunction]";
+  };
+
   // Register an opaque HostRef handle by its host value without wrapping it.
   _registerHostRef = (t: unknown, handle: QuickJSHandle): QuickJSHandle => {
     const u = this._unwrap(t);
@@ -490,6 +601,9 @@ export class Arena {
       registerTransient: this._registerTransient,
       disposeTransient: this._disposeTransient,
       preApply: this._marshalPreApply,
+      prepareReturn: this._prepareMarshalReturn,
+      unwrap: t => this._unwrap(t),
+      asyncify: this._options?.asyncify ? this._asyncify : undefined,
       custom: this._options?.customMarshaller,
     });
 
@@ -498,7 +612,27 @@ export class Arena {
     this._transientHandles.delete(handle);
 
     const syncEnabled = this._options?.syncEnabled ?? true;
-    return [handle, !syncEnabled || !this._map.hasHandle(handle)];
+    // A non-object (primitive) handle is never retained in `_map` (registered
+    // primitives already returned above via `_registeredMap`), so skip the
+    // `hasHandle` VM roundtrip and mark it disposable directly.
+    if (!syncEnabled || !isObject(target)) return [handle, true];
+    return [handle, !this._map.hasHandle(handle)];
+  };
+
+  _prepareMarshalReturn = (h: QuickJSHandle): QuickJSHandle => {
+    // A host function's return value is disposed by the VM once it is consumed.
+    // When sync is on, the VMMap retains object handles for identity, so the
+    // handle we hand back is the one the map owns: returning it directly would
+    // let the VM dispose the map's copy, leaving a stale entry that breaks
+    // `x === fn()` identity across calls. Hand the VM a dup instead and keep
+    // ours alive. With sync off, handles are not retained, so this is a no-op.
+    const syncEnabled = this._options?.syncEnabled ?? true;
+    // Only object handles are retained in `_map`; a primitive return can never
+    // be in the map, so `isHandleObject` (a cheap typeof) skips the `hasHandle`
+    // VM roundtrip for primitive returns from host functions.
+    return syncEnabled && h.alive && isHandleObject(this.context, h) && this._map.hasHandle(h)
+      ? h.dup()
+      : h;
   };
 
   _preUnmarshal = (t: any, h: QuickJSHandle): Wrapped<any> => {
@@ -510,6 +644,14 @@ export class Arena {
   };
 
   _unmarshal = (handle: QuickJSHandle): any => {
+    // Primitives (undefined/number/string/boolean/bigint/null) are resolved by a
+    // cheap host-side `ctx.typeof`, skipping the `_registeredMap` VM lookup,
+    // HostRef resolution, and `_wrapHandle`. The VMMap only ever keys objects and
+    // symbols, so a primitive handle can never match `getByHandle`; symbols fall
+    // through `unmarshalPrimitive` and still reach the lookup below.
+    const [primitive, ok] = unmarshalPrimitive(this.context, handle);
+    if (ok) return primitive;
+
     const registered = this._registeredMap.getByHandle(handle);
     if (typeof registered !== "undefined") {
       return registered;
@@ -521,15 +663,29 @@ export class Arena {
       if (ref) return ref.value;
     }
 
-    const [wrappedHandle] = this._wrapHandle(handle);
-    return unmarshal(wrappedHandle ?? handle, {
-      ctx: this.context,
-      marshal: this._marshal,
-      find: this._unmarshalFind,
-      pre: this._preUnmarshal,
-      custom: this._options?.customUnmarshaller,
-      hostRef: !!this._options?.marshalByReference,
-    });
+    const [wrappedHandle, wrapped] = this._wrapHandle(handle);
+    let done = false;
+    try {
+      const result = unmarshal(wrappedHandle ?? handle, {
+        ctx: this.context,
+        marshal: this._marshal,
+        find: this._unmarshalFind,
+        pre: this._preUnmarshal,
+        custom: this._options?.customUnmarshaller,
+        hostRef: !!this._options?.marshalByReference,
+      });
+      done = true;
+      return result;
+    } finally {
+      // A mid-flight abort (e.g. an OOM inside the unmarshal chain) can throw
+      // before the freshly created proxy handle was registered in the map,
+      // orphaning it. Dispose it here; if it was already registered the map
+      // skips it (alive check) at dispose. Disposing a handle never allocates,
+      // so this is safe even under an active memory limit.
+      if (!done && wrapped && wrappedHandle?.alive && wrappedHandle !== handle) {
+        wrappedHandle.dispose();
+      }
+    }
   };
 
   _register(
@@ -543,24 +699,41 @@ export class Arena {
     }
 
     let wrappedT = this._wrap(t);
-    const [wrappedH] = this._wrapHandle(h);
+    // `wrappedHNew` is true when `_wrapHandle` allocated a fresh VM proxy (which
+    // we own) rather than returning the original handle. If registration fails
+    // or throws mid-flight (e.g. an OOM in `map.set`), that proxy would be
+    // orphaned, so the finally below disposes it.
+    const [wrappedH, wrappedHNew] = this._wrapHandle(h);
     const isPromise = t instanceof Promise;
     if (!wrappedH || (!wrappedT && !isPromise)) return; // t or h is not an object
     if (isPromise) wrappedT = t;
 
     const unwrappedT = this._unwrap(t);
-    const [unwrappedH, unwrapped] = this._unwrapHandle(h);
-
-    const res = map.set(wrappedT, wrappedH, unwrappedT, unwrappedH);
-    if (!res) {
-      // already registered
-      if (unwrapped) unwrappedH.dispose();
-      throw new Error("already registered");
-    } else if (sync) {
-      this._sync.add(unwrappedT);
+    let unwrappedH: QuickJSHandle | undefined;
+    let unwrapped = false;
+    let done = false;
+    try {
+      [unwrappedH, unwrapped] = this._unwrapHandle(h);
+
+      const res = map.set(wrappedT, wrappedH, unwrappedT, unwrappedH);
+      if (!res) {
+        // already registered
+        throw new Error("already registered");
+      } else if (sync) {
+        this._sync.add(unwrappedT);
+      }
+
+      done = true;
+      return [wrappedT, wrappedH];
+    } finally {
+      if (!done) {
+        // `map.set` did not take ownership (it threw or returned false): dispose
+        // the handles we created so they are not orphaned. A non-new `wrappedH`
+        // and a non-wrapped `unwrappedH` are the caller's handle `h`, left alone.
+        if (wrappedHNew && wrappedH.alive) wrappedH.dispose();
+        if (unwrapped && unwrappedH?.alive) unwrappedH.dispose();
+      }
     }
-
-    return [wrappedT, wrappedH];
   }
 
   _syncMode = (obj: any): "both" | undefined => {
@@ -591,16 +764,7 @@ export class Arena {
   };
 
   _wrapHandle(handle: QuickJSHandle): [Wrapped<QuickJSHandle> | undefined, boolean] {
-    return wrapHandle(
-      this.context,
-      handle,
-      this._symbol,
-      this._symbolHandle,
-      this._unmarshal,
-      this._syncMode,
-      this._options?.isHandleWrappable,
-      this._options?.syncEnabled ?? true,
-    );
+    return this._wrapHandleImpl.wrapHandle(handle);
   }
 
   _unwrapHandle(target: QuickJSHandle): [QuickJSHandle, boolean] {
@@ -626,9 +790,19 @@ export class AsyncArena extends Arena {
    * Evaluate JS code asynchronously in the VM and get the result on the host
    * side. Like `evalCode`, it converts and re-throws errors thrown during
    * evaluation. Use this when the code awaits host-provided promises.
+   *
+   * @param code - The JS code to evaluate
+   * @param filename - Optional filename used in error stacks and for debugging
+   * @param options - Optional eval options forwarded to quickjs-emscripten's
+   *   `evalCodeAsync`, either an `EvalFlags` bitmask (`number`) or a
+   *   {@link ContextEvalOptions} object (e.g. `{ strict: true }`)
    */
-  async evalCodeAsync<T = any>(code: string, filename?: string): Promise<T> {
-    const result = await this.asyncContext.evalCodeAsync(code, filename);
+  async evalCodeAsync<T = any>(
+    code: string,
+    filename?: string,
+    options?: number | ContextEvalOptions,
+  ): Promise<T> {
+    const result = await this.asyncContext.evalCodeAsync(code, filename, options);
     return this._unwrapResultAndUnmarshal(result);
   }
 }

package/src/marshal/custom.ts

@@ -1,6 +1,6 @@
 import type { QuickJSContext, QuickJSHandle } from "quickjs-emscripten";
 
-import { call, consumeAll } from "../vmutil";
+import { call, consume, consumeAll } from "../vmutil";
 
 export default function marshalCustom(
   ctx: QuickJSContext,
@@ -13,24 +13,33 @@ export default function marshalCustom(
     handle = c(target, ctx);
     if (handle) break;
   }
-  return handle ? preMarshal(target, handle) ?? handle : undefined;
+  if (!handle) return undefined;
+  // Own the custom-marshalled handle until `preMarshal` registers it; dispose it
+  // if `preMarshal` throws mid-flight so it is not orphaned.
+  let owned = true;
+  try {
+    const result = preMarshal(target, handle) ?? handle;
+    owned = false;
+    return result;
+  } finally {
+    if (owned && handle.alive) handle.dispose();
+  }
 }
 
 export function symbol(target: unknown, ctx: QuickJSContext): QuickJSHandle | undefined {
   if (typeof target !== "symbol") return;
-  const handle = call(
-    ctx,
-    "d => Symbol(d)",
-    undefined,
-    target.description ? ctx.newString(target.description) : ctx.undefined,
-  );
-  return handle;
+  // `call` does not dispose its arguments, so the description string handle must
+  // be consumed here or it leaks on every symbol marshal.
+  return target.description
+    ? consume(ctx.newString(target.description), d => call(ctx, "d => Symbol(d)", undefined, d))
+    : call(ctx, "d => Symbol(d)", undefined, ctx.undefined);
 }
 
 export function date(target: unknown, ctx: QuickJSContext): QuickJSHandle | undefined {
   if (!(target instanceof Date)) return;
-  const handle = call(ctx, "d => new Date(d)", undefined, ctx.newNumber(target.getTime()));
-  return handle;
+  // `call` does not dispose its arguments, so the time number handle is consumed
+  // here rather than leaked.
+  return consume(ctx.newNumber(target.getTime()), d => call(ctx, "d => new Date(d)", undefined, d));
 }
 
 export function arrayBuffer(target: unknown, ctx: QuickJSContext): QuickJSHandle | undefined {

package/src/marshal/function.test.ts

@@ -1,4 +1,5 @@
-import { getQuickJS, QuickJSHandle } from "quickjs-emscripten";
+import type { QuickJSHandle } from "quickjs-emscripten";
+import { getQuickJS } from "quickjs-emscripten";
 import { expect, test, vi } from "vitest";
 
 import { json, call } from "../vmutil";
@@ -8,8 +9,10 @@ import marshalFunction from "./function";
 test("normal func", async () => {
   const ctx = (await getQuickJS()).newContext();
 
-  const marshal = vi.fn(v => json(ctx, v));
-  const unmarshal = vi.fn(v => (ctx.sameValue(v, ctx.global) ? undefined : ctx.dump(v)));
+  const marshal = vi.fn((v) => json(ctx, v));
+  const unmarshal = vi.fn((v) =>
+    ctx.sameValue(v, ctx.global) ? undefined : ctx.dump(v),
+  );
   const preMarshal = vi.fn((_, a) => a);
   const innerfn = vi.fn((..._args: any[]) => "hoge");
   const fn = (...args: any[]) => innerfn(...args);
@@ -30,10 +33,12 @@ test("normal func", async () => {
   expect(ctx.dump(result)).toBe("hoge");
   expect(innerfn).toBeCalledWith(1, true);
   expect(marshal).toHaveBeenLastCalledWith("hoge");
-  expect(unmarshal).toBeCalledTimes(3);
-  expect(unmarshal.mock.results[0].value).toBe(undefined); // this
-  expect(unmarshal.mock.results[1].value).toBe(1);
-  expect(unmarshal.mock.results[2].value).toBe(true);
+  // `this` coerces to the VM global for a plain call, which marshalFunction
+  // treats as undefined without unmarshalling it, so only the two args are
+  // unmarshalled.
+  expect(unmarshal).toBeCalledTimes(2);
+  expect(unmarshal.mock.results[0].value).toBe(1);
+  expect(unmarshal.mock.results[1].value).toBe(true);
 
   handle.dispose();
   ctx.dispose();
@@ -41,7 +46,7 @@ test("normal func", async () => {
 
 test("func which has properties", async () => {
   const ctx = (await getQuickJS()).newContext();
-  const marshal = vi.fn(v => json(ctx, v));
+  const marshal = vi.fn((v) => json(ctx, v));
 
   const fn = () => {};
   fn.hoge = "foo";
@@ -50,7 +55,7 @@ test("func which has properties", async () => {
     ctx,
     fn,
     marshal,
-    v => ctx.dump(v),
+    (v) => ctx.dump(v),
     (_, a) => a,
   );
   if (!handle) throw new Error("handle is undefined");
@@ -91,16 +96,20 @@ test("class", async () => {
   if (!handle) throw new Error("handle is undefined");
 
   const newA = ctx.unwrapResult(ctx.evalCode(`A => new A(100)`));
-  const instance = ctx.unwrapResult(ctx.callFunction(newA, ctx.undefined, handle));
+  const instance = ctx.unwrapResult(
+    ctx.callFunction(newA, ctx.undefined, handle),
+  );
 
   expect(ctx.dump(ctx.getProp(handle, "name"))).toBe("A");
   expect(ctx.dump(ctx.getProp(handle, "length"))).toBe(1);
-  expect(ctx.dump(call(ctx, "(cls, i) => i instanceof cls", undefined, handle, instance))).toBe(
-    true,
-  );
+  expect(
+    ctx.dump(
+      call(ctx, "(cls, i) => i instanceof cls", undefined, handle, instance),
+    ),
+  ).toBe(true);
   expect(ctx.dump(ctx.getProp(instance, "a"))).toBe(100);
 
-  disposables.forEach(d => d.dispose());
+  disposables.forEach((d) => d.dispose());
   instance.dispose();
   newA.dispose();
   handle.dispose();
@@ -115,19 +124,34 @@ test("preApply", async () => {
     if (typeof v === "number") return ctx.newNumber(v);
     return ctx.null;
   };
-  const unmarshal = (v: QuickJSHandle) => (ctx.typeof(v) === "object" ? that : ctx.dump(v));
-  const preApply = vi.fn((a: (...args: any[]) => any, b: any, c: any[]) => a.apply(b, c) + "!");
+  const unmarshal = (v: QuickJSHandle) =>
+    ctx.typeof(v) === "object" ? that : ctx.dump(v);
+  const preApply = vi.fn(
+    (a: (...args: any[]) => any, b: any, c: any[]) => a.apply(b, c) + "!",
+  );
   const that = {};
   const thatHandle = ctx.newObject();
 
   const fn = () => "foo";
-  const handle = marshalFunction(ctx, fn, marshal, unmarshal, (_, a) => a, preApply);
+  const handle = marshalFunction(
+    ctx,
+    fn,
+    marshal,
+    unmarshal,
+    (_, a) => a,
+    preApply,
+  );
   if (!handle) throw new Error("handle is undefined");
 
   expect(preApply).toBeCalledTimes(0);
 
   const res = ctx.unwrapResult(
-    ctx.callFunction(handle, thatHandle, ctx.newNumber(100), ctx.newString("hoge")),
+    ctx.callFunction(
+      handle,
+      thatHandle,
+      ctx.newNumber(100),
+      ctx.newString("hoge"),
+    ),
   );
 
   expect(preApply).toBeCalledTimes(1);