quickjs-emscripten-sync 1.10.0 → 1.11.0

package/src/marshal/function.ts

@@ -1,7 +1,7 @@
-import type { QuickJSContext, QuickJSHandle } from "quickjs-emscripten";
+import type { QuickJSAsyncContext, QuickJSContext, QuickJSHandle } from "quickjs-emscripten";
 
 import { isES2015Class, isObject } from "../util";
-import { call } from "../vmutil";
+import { call, consume } from "../vmutil";
 
 import marshalProperties from "./properties";
 
@@ -14,61 +14,110 @@ export default function marshalFunction(
   preApply?: (target: (...args: any[]) => any, thisArg: unknown, args: unknown[]) => any,
   disposeTransient: (handle: QuickJSHandle) => void = () => {},
   prepareReturn: (handle: QuickJSHandle) => QuickJSHandle = h => h,
+  unwrap: (target: unknown) => unknown = t => t,
+  asyncify?: (target: unknown) => boolean,
 ): QuickJSHandle | undefined {
   if (typeof target !== "function") return;
 
-  const raw = ctx
-    .newFunction(target.name, function (...argHandles) {
-      // A plain call (`fn()`) passes the VM global object as `this`. Unmarshalling
-      // it would eagerly deep-copy the entire global graph (hundreds of handles)
-      // on the first call, for a `this` host functions almost never use — and
-      // leaking globalThis to the host is undesirable. So global `this` is passed
-      // to the host function as `undefined`, which differs from plain JS where a
-      // non-strict function sees `this === globalThis` (see README Limitations).
-      // Real method calls still get their receiver unmarshalled.
-      const that = ctx.sameValue(this, ctx.global) ? undefined : unmarshal(this);
-      const args = argHandles.map(a => unmarshal(a));
+  // `target` may be a host-side proxy wrapper; unwrap it before the class check,
+  // because Function.prototype.toString on a callable proxy never matches /^class/.
+  // Computed once here rather than per call to avoid the toString + regex on every
+  // VM→host invocation.
+  const unwrapped = unwrap(target);
+  const isClass = isES2015Class(unwrapped);
 
-      if (isES2015Class(target) && isObject(that)) {
-        // Class constructors cannot be invoked without new expression, and new.target is not changed
-        const result = new target(...args);
-        Object.entries(result).forEach(([key, value]) => {
-          const valueHandle = marshal(value);
-          ctx.setProp(this, key, valueHandle);
-          // setProp dup'd the value into `this`; drop ours if it was transient.
-          disposeTransient(valueHandle);
-        });
-        return this;
-      }
+  // Marshal as an Asyncified function only when the caller opts in for this
+  // target AND the context actually supports it (a plain sync context has no
+  // `newAsyncifiedFunction`, so fall back to the normal function marshalling,
+  // which hands the guest a marshalled Promise as before).
+  const useAsyncify =
+    !!asyncify && asyncify(unwrapped) && "newAsyncifiedFunction" in ctx;
 
-      // The VM disposes whatever we return here. `prepareReturn` dups the
-      // handle when the VMMap retains it, so the map keeps a live copy and
-      // identity (`x === fn()` across calls) survives instead of going stale.
-      return prepareReturn(
-        marshal(
-          preApply
+  const inner = (
+    useAsyncify
+      ? // Asyncify: the VM stack is suspended until the host promise settles, so
+        // the guest receives the resolved value synchronously. Async functions
+        // can never be class constructors, so the class-constructor path is
+        // skipped here.
+        (ctx as QuickJSAsyncContext).newAsyncifiedFunction(target.name, async function (
+          ...argHandles
+        ) {
+          const that = ctx.sameValue(this, ctx.global) ? undefined : unmarshal(this);
+          const args = argHandles.map(a => unmarshal(a));
+
+          // `preApply` wraps the (synchronous) invocation to toggle temporal sync
+          // around it; it returns the host promise, which we await here. Note that
+          // its finally runs as soon as `apply` returns the promise, so temporal
+          // sync is only active for the synchronous portion of the async function,
+          // not across its awaits.
+          const result = await (preApply
             ? preApply(target as (...args: any[]) => any, that, args)
-            : (target as (...args: any[]) => any).apply(that, args),
-        ),
-      );
-    })
-    .consume(handle2 =>
-      // fucntions created by vm.newFunction are not callable as a class constrcutor
-      call(
-        ctx,
-        `Cls => {
-          const fn = function(...args) { return Cls.apply(this, args); };
-          fn.name = Cls.name;
-          fn.length = Cls.length;
-          return fn;
-        }`,
-        undefined,
-        handle2,
-      ),
-    );
+            : (target as (...args: any[]) => any).apply(that, args));
+
+          return prepareReturn(marshal(result));
+        })
+      : ctx.newFunction(target.name, function (...argHandles) {
+          // A plain call (`fn()`) passes the VM global object as `this`. Unmarshalling
+          // it would eagerly deep-copy the entire global graph (hundreds of handles)
+          // on the first call, for a `this` host functions almost never use — and
+          // leaking globalThis to the host is undesirable. So global `this` is passed
+          // to the host function as `undefined`, which differs from plain JS where a
+          // non-strict function sees `this === globalThis` (see README Limitations).
+          // Real method calls still get their receiver unmarshalled.
+          const that = ctx.sameValue(this, ctx.global) ? undefined : unmarshal(this);
+          const args = argHandles.map(a => unmarshal(a));
+
+          if (isClass && isObject(that)) {
+            // Class constructors cannot be invoked without new expression, and new.target is not changed
+            const result = new (target as new (...args: any[]) => any)(...args);
+            Object.entries(result).forEach(([key, value]) => {
+              const valueHandle = marshal(value);
+              ctx.setProp(this, key, valueHandle);
+              // setProp dup'd the value into `this`; drop ours if it was transient.
+              disposeTransient(valueHandle);
+            });
+            return this;
+          }
+
+          // The VM disposes whatever we return here. `prepareReturn` dups the
+          // handle when the VMMap retains it, so the map keeps a live copy and
+          // identity (`x === fn()` across calls) survives instead of going stale.
+          return prepareReturn(
+            marshal(
+              preApply
+                ? preApply(target as (...args: any[]) => any, that, args)
+                : (target as (...args: any[]) => any).apply(that, args),
+            ),
+          );
+        })
+  );
 
-  const handle = preMarshal(target, raw) ?? raw;
-  marshalProperties(ctx, target, raw, marshal, disposeTransient);
+  // `consume` disposes the raw newFunction handle even if `call` throws (the raw
+  // `Lifetime.consume` would skip disposal on throw, leaking the function handle).
+  const raw = consume(inner, handle2 =>
+    // functions created by vm.newFunction are not callable as a class constructor
+    call(
+      ctx,
+      `Cls => {
+        const fn = function(...args) { return Cls.apply(this, args); };
+        fn.name = Cls.name;
+        fn.length = Cls.length;
+        return fn;
+      }`,
+      undefined,
+      handle2,
+    ),
+  );
 
-  return handle;
+  // Own `raw` until `preMarshal` registers it; dispose it if `preMarshal` throws
+  // mid-flight so the wrapped function handle is not orphaned.
+  let ownRaw = true;
+  try {
+    const handle = preMarshal(target, raw) ?? raw;
+    ownRaw = false;
+    marshalProperties(ctx, target, raw, marshal, disposeTransient);
+    return handle;
+  } finally {
+    if (ownRaw && raw.alive) raw.dispose();
+  }
 }

package/src/marshal/index.ts

@@ -33,6 +33,14 @@ export type Options = {
   // the VMMap retains (for identity, while sync is on) must be dup'd here or its
   // map entry goes stale. Defaults to identity (no-op).
   prepareReturn?: (handle: QuickJSHandle) => QuickJSHandle;
+  // Strip a host-side proxy wrapper from a target. Used to detect a wrapped class
+  // constructor, which would otherwise be hidden behind the proxy. Defaults to identity.
+  unwrap?: (target: unknown) => unknown;
+  // Decide whether a host function should be marshalled as an Asyncified function
+  // (the VM suspends until the host promise settles, so the guest gets the
+  // resolved value synchronously). Called with the unwrapped target. Only takes
+  // effect when the context supports `newAsyncifiedFunction`.
+  asyncify?: (target: unknown) => boolean;
   custom?: Iterable<(obj: unknown, ctx: QuickJSContext) => QuickJSHandle | undefined>;
 };
 
@@ -87,6 +95,8 @@ export function marshal(target: unknown, options: Options): QuickJSHandle {
       options.preApply,
       disposeTransient,
       options.prepareReturn,
+      options.unwrap,
+      options.asyncify,
     ) ??
     marshalMapSet(ctx, target, marshal2, pre2, disposeTransient) ??
     marshalObject(ctx, target, marshal2, pre2, disposeTransient) ??

package/src/marshal/mapset.ts

@@ -11,27 +11,41 @@ export default function marshalMapSet(
 ): QuickJSHandle | undefined {
   if (target instanceof Map) {
     const raw = call(ctx, "() => new Map()");
-    const handle = preMarshal(target, raw) ?? raw;
-    for (const [k, v] of target) {
-      const kh = marshal(k);
-      const vh = marshal(v);
-      call(ctx, "(m, k, v) => m.set(k, v)", undefined, raw, kh, vh).dispose();
-      // set() has taken its own references; drop ours if they were transient.
-      disposeTransient(kh);
-      disposeTransient(vh);
+    // Own `raw` until `preMarshal` registers it; dispose it if `preMarshal`
+    // throws mid-flight so the fresh Map handle is not orphaned.
+    let ownRaw = true;
+    try {
+      const handle = preMarshal(target, raw) ?? raw;
+      ownRaw = false;
+      for (const [k, v] of target) {
+        const kh = marshal(k);
+        const vh = marshal(v);
+        call(ctx, "(m, k, v) => m.set(k, v)", undefined, raw, kh, vh).dispose();
+        // set() has taken its own references; drop ours if they were transient.
+        disposeTransient(kh);
+        disposeTransient(vh);
+      }
+      return handle;
+    } finally {
+      if (ownRaw && raw.alive) raw.dispose();
     }
-    return handle;
   }
 
   if (target instanceof Set) {
     const raw = call(ctx, "() => new Set()");
-    const handle = preMarshal(target, raw) ?? raw;
-    for (const v of target) {
-      const vh = marshal(v);
-      call(ctx, "(s, v) => s.add(v)", undefined, raw, vh).dispose();
-      // add() has taken its own reference; drop ours if it was transient.
-      disposeTransient(vh);
+    let ownRaw = true;
+    try {
+      const handle = preMarshal(target, raw) ?? raw;
+      ownRaw = false;
+      for (const v of target) {
+        const vh = marshal(v);
+        call(ctx, "(s, v) => s.add(v)", undefined, raw, vh).dispose();
+        // add() has taken its own reference; drop ours if it was transient.
+        disposeTransient(vh);
+      }
+      return handle;
+    } finally {
+      if (ownRaw && raw.alive) raw.dispose();
     }
-    return handle;
   }
 }

package/src/marshal/object.ts

@@ -14,21 +14,30 @@ export default function marshalObject(
   if (typeof target !== "object" || target === null) return;
 
   const raw = Array.isArray(target) ? ctx.newArray() : ctx.newObject();
-  const handle = preMarshal(target, raw) ?? raw;
+  // We own `raw` until `preMarshal` registers it (in the map or the transient
+  // set) or returns it as `handle`. If `preMarshal` throws mid-flight (e.g. an
+  // OOM while creating the proxy), dispose `raw` so it is not orphaned.
+  let ownRaw = true;
+  try {
+    const handle = preMarshal(target, raw) ?? raw;
+    ownRaw = false;
 
-  // prototype
-  const prototype = Object.getPrototypeOf(target);
-  const prototypeHandle =
-    prototype && prototype !== Object.prototype && prototype !== Array.prototype
-      ? marshal(prototype)
-      : undefined;
-  if (prototypeHandle) {
-    call(ctx, "Object.setPrototypeOf", undefined, handle, prototypeHandle).dispose();
-    // setPrototypeOf has taken its own reference; drop ours if it was transient.
-    disposeTransient(prototypeHandle);
-  }
+    // prototype
+    const prototype = Object.getPrototypeOf(target);
+    const prototypeHandle =
+      prototype && prototype !== Object.prototype && prototype !== Array.prototype
+        ? marshal(prototype)
+        : undefined;
+    if (prototypeHandle) {
+      call(ctx, "Object.setPrototypeOf", undefined, handle, prototypeHandle).dispose();
+      // setPrototypeOf has taken its own reference; drop ours if it was transient.
+      disposeTransient(prototypeHandle);
+    }
 
-  marshalProperties(ctx, target, raw, marshal, disposeTransient);
+    marshalProperties(ctx, target, raw, marshal, disposeTransient);
 
-  return handle;
+    return handle;
+  } finally {
+    if (ownRaw && raw.alive) raw.dispose();
+  }
 }

package/src/marshal/promise.test.ts

@@ -1,8 +1,8 @@
-import {
-  getQuickJS,
-  type Disposable,
-  type QuickJSDeferredPromise,
-  type QuickJSHandle,
+import { getQuickJS } from "quickjs-emscripten";
+import type {
+  Disposable,
+  QuickJSDeferredPromise,
+  QuickJSHandle,
 } from "quickjs-emscripten";
 import { expect, test, vi } from "vitest";
 
@@ -15,15 +15,17 @@ const testPromise = (reject: boolean) => async () => {
   const ctx = (await getQuickJS()).newContext();
 
   const disposables: Disposable[] = [];
-  const marshal = vi.fn(v => {
+  const marshal = vi.fn((v) => {
     const handle = json(ctx, v);
     disposables.push(handle);
     return handle;
   });
-  const preMarshal = vi.fn((_: any, a: QuickJSDeferredPromise): QuickJSHandle => {
-    disposables.push(a);
-    return a.handle;
-  });
+  const preMarshal = vi.fn(
+    (_: any, a: QuickJSDeferredPromise): QuickJSHandle => {
+      disposables.push(a);
+      return a.handle;
+    },
+  );
 
   const mockNotify = vi.fn();
   const notify = ctx.newFunction("notify", (handle1, handle2) => {
@@ -77,7 +79,7 @@ const testPromise = (reject: boolean) => async () => {
   expect(marshal).toBeCalledTimes(1);
   expect(marshal.mock.calls).toEqual([["hoge"]]);
 
-  disposables.forEach(h => h.dispose());
+  disposables.forEach((h) => h.dispose());
   ctx.dispose();
 };
 

package/src/marshal/promise.ts

@@ -9,11 +9,19 @@ export default function marshalPromise(
   if (!(target instanceof Promise)) return;
 
   const promise = ctx.newPromise();
+  // Own the deferred promise until `preMarshal` registers it; dispose it (handle
+  // plus resolve/reject callbacks) if `preMarshal` throws mid-flight.
+  let owned = true;
+  try {
+    target.then(
+      d => promise.resolve(marshal(d)),
+      d => promise.reject(marshal(d)),
+    );
 
-  target.then(
-    d => promise.resolve(marshal(d)),
-    d => promise.reject(marshal(d)),
-  );
-
-  return preMarshal(target, promise) ?? promise.handle;
+    const result = preMarshal(target, promise) ?? promise.handle;
+    owned = false;
+    return result;
+  } finally {
+    if (owned && promise.alive) promise.dispose();
+  }
 }

package/src/marshal/properties.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 } from "../vmutil";
@@ -23,7 +24,7 @@ test("works", async () => {
   );
 
   const disposables: QuickJSHandle[] = [];
-  const marshal = vi.fn(t => {
+  const marshal = vi.fn((t) => {
     if (typeof t !== "function") return json(ctx, t);
     const fn = ctx.newFunction("", () => {});
     disposables.push(fn);
@@ -51,7 +52,13 @@ test("works", async () => {
   });
 
   marshalProperties(ctx, obj, handle, marshal);
-  expect(marshal.mock.calls).toEqual([["bar"], [bar], ["foo"], [fooGet], [fooSet]]);
+  expect(marshal.mock.calls).toEqual([
+    ["bar"],
+    [bar],
+    ["foo"],
+    [fooGet],
+    [fooSet],
+  ]);
 
   const expected = ctx.unwrapResult(
     ctx.evalCode(`({
@@ -59,10 +66,12 @@ test("works", async () => {
       foo: { valueType: "undefined", getType: "function", setType: "function", enumerable: false, configurable: true }
     })`),
   );
-  ctx.unwrapResult(ctx.callFunction(descTester, ctx.undefined, handle, expected));
+  ctx.unwrapResult(
+    ctx.callFunction(descTester, ctx.undefined, handle, expected),
+  );
 
   expected.dispose();
-  disposables.forEach(d => d.dispose());
+  disposables.forEach((d) => d.dispose());
   handle.dispose();
   descTester.dispose();
   ctx.dispose();

package/src/marshal/properties.ts

@@ -1,6 +1,6 @@
 import type { QuickJSContext, QuickJSHandle } from "quickjs-emscripten";
 
-import { call } from "../vmutil";
+import { call, consume } from "../vmutil";
 
 export default function marshalProperties(
   ctx: QuickJSContext,
@@ -9,12 +9,55 @@ export default function marshalProperties(
   marshal: (target: unknown) => QuickJSHandle,
   disposeTransient: (handle: QuickJSHandle) => void = () => {},
 ): void {
-  const descs = ctx.newObject();
-  // Property values may be transient (json copies / BigInt) with no owner; once
-  // `Object.defineProperties` has copied them into `handle` the standalone
-  // handles are redundant and disposed below. Owned handles are left untouched.
+  // `descs` aggregates only the properties that need the full descriptor path
+  // (accessors, non-default flags, symbol keys). It is created lazily so plain
+  // objects/arrays skip both the `ctx.newObject()` and the final
+  // `Object.defineProperties` roundtrip entirely.
+  let descs: QuickJSHandle | undefined;
+  // Descriptor-path values may be transient (json copies / BigInt) with no
+  // owner; once `Object.defineProperties` has copied them into `handle` the
+  // standalone handles are redundant and disposed below. Owned handles are left
+  // untouched. Fast-path values are disposed inline (see below).
   const transient: QuickJSHandle[] = [];
+
+  // `ctx.setProp` uses `[[Set]]` semantics, which walks the prototype chain and
+  // would invoke an inherited accessor/setter (or the `__proto__` setter)
+  // instead of creating an own property. That only matters when `marshalObject`
+  // installed a custom prototype (see marshal/object.ts): a default-prototype VM
+  // object (plain object / array) has no shadowing accessors, so `setProp` on a
+  // normal string key is identical to `defineProperty` with all flags true. For
+  // custom-prototype objects (e.g. class instances) we must keep the descriptor
+  // path, which uses `[[DefineOwnProperty]]` semantics.
+  const proto = Object.getPrototypeOf(target);
+  const defaultProto = proto === Object.prototype || proto === Array.prototype;
+
   const cb = (key: string | number | symbol, desc: PropertyDescriptor) => {
+    // Fast path: a plain data property with a string key and all flags at their
+    // defaults, on a default-prototype object, is semantically identical to
+    // `ctx.setProp` on a fresh object/array, so we skip building a descriptor
+    // object. `writable === true` implies a data descriptor (accessors have no
+    // `writable`), so there is no get/set. Symbol keys keep the descriptor path
+    // (setProp string-key fast path does not apply). `__proto__` is excluded
+    // because it resolves to the prototype setter under `[[Set]]`. The value is
+    // copied into `handle` by setProp immediately, so its transient handle can
+    // be disposed right away.
+    if (
+      defaultProto &&
+      typeof key === "string" &&
+      key !== "__proto__" &&
+      desc.writable === true &&
+      desc.enumerable === true &&
+      desc.configurable === true &&
+      desc.get === undefined &&
+      desc.set === undefined
+    ) {
+      const keyHandle = marshal(key);
+      const valueHandle = marshal(desc.value);
+      ctx.setProp(handle, keyHandle, valueHandle);
+      disposeTransient(valueHandle);
+      return;
+    }
+
     const keyHandle = marshal(key);
     const valueHandle = typeof desc.value === "undefined" ? undefined : marshal(desc.value);
     const getHandle = typeof desc.get === "undefined" ? undefined : marshal(desc.get);
@@ -23,7 +66,10 @@ export default function marshalProperties(
     if (getHandle) transient.push(getHandle);
     if (setHandle) transient.push(setHandle);
 
-    ctx.newObject().consume(descObj => {
+    const descsHandle = (descs ??= ctx.newObject());
+    // `consume` disposes the descriptor object even if a `setProp` throws
+    // mid-flight, so the intermediate handle is not orphaned.
+    consume(ctx.newObject(), descObj => {
       Object.entries(desc).forEach(([k, v]) => {
         const v2 =
           k === "value"
@@ -39,7 +85,7 @@ export default function marshalProperties(
           ctx.setProp(descObj, k, v2);
         }
       });
-      ctx.setProp(descs, keyHandle, descObj);
+      ctx.setProp(descsHandle, keyHandle, descObj);
     });
   };
 
@@ -48,11 +94,13 @@ export default function marshalProperties(
     Object.entries(desc).forEach(([k, v]) => cb(k, v));
     Object.getOwnPropertySymbols(desc).forEach(k => cb(k, (desc as any)[k]));
 
-    call(ctx, `Object.defineProperties`, undefined, handle, descs).dispose();
-    // Safe only after defineProperties has dup'd the values into `handle`; `descs`
-    // still holds its own references until its own dispose() in the finally.
-    for (const h of transient) disposeTransient(h);
+    if (descs) {
+      call(ctx, `Object.defineProperties`, undefined, handle, descs).dispose();
+      // Safe only after defineProperties has dup'd the values into `handle`;
+      // `descs` still holds its own references until its own dispose() below.
+      for (const h of transient) disposeTransient(h);
+    }
   } finally {
-    descs.dispose();
+    descs?.dispose();
   }
 }

package/src/unmarshal/custom.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 unmarshalCustom, { defaultCustom } from "./custom";
@@ -9,7 +10,8 @@ test("symbol", async () => {
   const obj = ctx.newObject();
   const handle = ctx.unwrapResult(ctx.evalCode(`Symbol("foobar")`));
 
-  const unmarshal = (h: QuickJSHandle): any => unmarshalCustom(ctx, h, pre, defaultCustom);
+  const unmarshal = (h: QuickJSHandle): any =>
+    unmarshalCustom(ctx, h, pre, defaultCustom);
 
   expect(unmarshal(obj)).toBe(undefined);
   expect(pre).toBeCalledTimes(0);
@@ -32,7 +34,8 @@ test("date", async () => {
   const obj = ctx.newObject();
   const handle = ctx.unwrapResult(ctx.evalCode(`new Date(2022, 7, 26)`));
 
-  const unmarshal = (h: QuickJSHandle): any => unmarshalCustom(ctx, h, pre, defaultCustom);
+  const unmarshal = (h: QuickJSHandle): any =>
+    unmarshalCustom(ctx, h, pre, defaultCustom);
 
   expect(unmarshal(obj)).toBe(undefined);
   expect(pre).toBeCalledTimes(0);