quickjs-emscripten-sync 1.8.4 → 1.9.1

package/src/vmutil.ts

@@ -3,38 +3,108 @@ import type {
   QuickJSContext,
   QuickJSHandle,
   QuickJSDeferredPromise,
+  SuccessOrFail,
 } from "quickjs-emscripten";
 
+/**
+ * Unwrap a VM result, disposing the error handle on failure.
+ *
+ * `ctx.unwrapResult` throws the error handle without disposing it, which leaks
+ * the handle. Under memory pressure the leak cascades: reading the error needs
+ * the VM, which is already exhausted, so cleanup is skipped entirely. Here we
+ * read the error host-side, always dispose the handle, then throw a host Error.
+ */
+export function unwrapResult<T>(ctx: QuickJSContext, result: SuccessOrFail<T, QuickJSHandle>): T {
+  if ("error" in result && result.error) {
+    const { error } = result;
+    let dumped: any;
+    try {
+      dumped = ctx.dump(error);
+    } catch {
+      // VM may be unable to read the error (e.g. out of memory); fall back below.
+    } finally {
+      if (error.alive) error.dispose();
+    }
+    const err = new Error(
+      typeof dumped === "object" && dumped && "message" in dumped
+        ? String(dumped.message)
+        : dumped !== undefined
+        ? String(dumped)
+        : "quickjs-emscripten-sync: VM evaluation failed",
+    );
+    if (typeof dumped === "object" && dumped) {
+      if ("name" in dumped) err.name = String(dumped.name);
+      if ("stack" in dumped) err.stack = String(dumped.stack);
+    }
+    throw err;
+  }
+  return result.value;
+}
+
 export function fn(
   ctx: QuickJSContext,
   code: string,
 ): ((thisArg: QuickJSHandle | undefined, ...args: QuickJSHandle[]) => QuickJSHandle) & Disposable {
-  const handle = ctx.unwrapResult(ctx.evalCode(code));
+  const handle = unwrapResult(ctx, ctx.evalCode(code));
   const f: any = (thisArg: QuickJSHandle | undefined, ...args: QuickJSHandle[]): any => {
-    return ctx.unwrapResult(ctx.callFunction(handle, thisArg ?? ctx.undefined, ...args));
+    return unwrapResult(ctx, ctx.callFunction(handle, thisArg ?? ctx.undefined, ...args));
   };
   const disposeFn = () => handle.dispose();
   f.dispose = disposeFn;
   f[Symbol.dispose] = disposeFn;
-  f.alive = true;
   Object.defineProperty(f, "alive", {
     get: () => handle.alive,
   });
   return f;
 }
 
+// Compiled functions for `call` can be cached per context, keyed by code: the
+// code passed to `call` is always a constant literal, so recompiling the same
+// helper on every call (isHandleObject, defineProperties, etc.) was a dominant
+// cost. Caching is opt-in per context via `enableFnCache` because cached
+// handles outlive a single call and must be disposed with `disposeFnCache`;
+// the Arena enables it in its constructor and disposes it in `dispose`. For
+// contexts without a cache, `call` keeps its original compile-and-dispose
+// behaviour so standalone callers don't leak handles.
+const fnCache = new WeakMap<QuickJSContext, Map<string, QuickJSHandle>>();
+
+/** Enable per-context caching of compiled functions used by `call`. */
+export function enableFnCache(ctx: QuickJSContext): void {
+  if (!fnCache.has(ctx)) fnCache.set(ctx, new Map());
+}
+
+/** Dispose all compiled functions cached for a context and disable caching. */
+export function disposeFnCache(ctx: QuickJSContext): void {
+  const cache = fnCache.get(ctx);
+  if (!cache) return;
+  for (const handle of cache.values()) {
+    if (handle.alive) handle.dispose();
+  }
+  fnCache.delete(ctx);
+}
+
 export function call(
   ctx: QuickJSContext,
   code: string,
   thisArg?: QuickJSHandle,
   ...args: QuickJSHandle[]
 ): QuickJSHandle {
-  const f = fn(ctx, code);
-  try {
-    return f(thisArg, ...args);
-  } finally {
-    f.dispose();
+  const cache = fnCache.get(ctx);
+  if (!cache) {
+    const f = fn(ctx, code);
+    try {
+      return f(thisArg, ...args);
+    } finally {
+      f.dispose();
+    }
+  }
+
+  let handle = cache.get(code);
+  if (!handle || !handle.alive) {
+    handle = unwrapResult(ctx, ctx.evalCode(code));
+    cache.set(code, handle);
   }
+  return unwrapResult(ctx, ctx.callFunction(handle, thisArg ?? ctx.undefined, ...args));
 }
 
 export function instanceOf(ctx: QuickJSContext, a: QuickJSHandle, b: QuickJSHandle): boolean {
@@ -42,15 +112,30 @@ export function instanceOf(ctx: QuickJSContext, a: QuickJSHandle, b: QuickJSHand
 }
 
 export function isHandleObject(ctx: QuickJSContext, h: QuickJSHandle): boolean {
-  return ctx.dump(
-    call(ctx, `a => typeof a === "object" && a !== null || typeof a === "function"`, undefined, h),
-  );
+  const type = ctx.typeof(h);
+  return type === "function" || (type === "object" && !ctx.sameValue(h, ctx.null));
 }
 
 export function json(ctx: QuickJSContext, target: any): QuickJSHandle {
   const json = JSON.stringify(target);
   if (!json) return ctx.undefined;
-  return call(ctx, `JSON.parse`, undefined, ctx.newString(json));
+  // `call` does not dispose its arguments, so the intermediate string handle
+  // must be consumed here or it leaks on every json marshal.
+  return ctx.newString(json).consume(s => call(ctx, `JSON.parse`, undefined, s));
+}
+
+/**
+ * Run `cb` with `handle`, then dispose `handle` even if `cb` throws.
+ *
+ * Unlike `handle.consume`, which skips disposal when its callback throws, this
+ * helper disposes in a `finally` so error paths don't leak the handle.
+ */
+export function consume<T extends QuickJSHandle, K>(handle: T, cb: (handle: T) => K): K {
+  try {
+    return cb(handle);
+  } finally {
+    if (handle.alive) handle.dispose();
+  }
 }
 
 export function consumeAll<T extends QuickJSHandle[], K>(handles: T, cb: (handles: T) => K): K {

package/src/wrapper.ts

@@ -1,7 +1,7 @@
 import type { QuickJSHandle, QuickJSContext } from "quickjs-emscripten";
 
 import { isObject } from "./util";
-import { call, isHandleObject, mayConsumeAll } from "./vmutil";
+import { call, consume, isHandleObject, mayConsumeAll } from "./vmutil";
 
 export type SyncMode = "both" | "vm" | "host";
 
@@ -15,18 +15,28 @@ export function wrap<T = any>(
   marshal: (target: any) => [QuickJSHandle, boolean],
   syncMode?: (target: T) => SyncMode | undefined,
   wrappable?: (target: unknown) => boolean,
+  syncEnabled = true,
 ): Wrapped<T> | undefined {
-  // promise and date cannot be wrapped
+  // These built-ins rely on internal slots or non-property access, so a proxy
+  // would break them; they are marshalled by value instead of being wrapped.
   if (
     !isObject(target) ||
     target instanceof Promise ||
     target instanceof Date ||
+    target instanceof ArrayBuffer ||
+    ArrayBuffer.isView(target) ||
+    target instanceof Map ||
+    target instanceof Set ||
     (wrappable && !wrappable(target))
   )
     return undefined;
 
   if (isWrapped(target, proxyKeySymbol)) return target;
 
+  // Sync globally disabled: skip the proxy, but still treat the object as
+  // "wrapped" so the rest of the pipeline handles it uniformly.
+  if (!syncEnabled) return target as Wrapped<T>;
+
   const rec = new Proxy(target as any, {
     get(obj, key) {
       return key === proxyKeySymbol ? obj : Reflect.get(obj, key);
@@ -34,7 +44,9 @@ export function wrap<T = any>(
     set(obj, key, value, receiver) {
       const v = unwrap(value, proxyKeySymbol);
       const sync = syncMode?.(receiver) ?? "host";
-      if ((sync !== "vm" && !Reflect.set(obj, key, v, receiver)) || sync === "host" || !ctx.alive)
+      // Set on the target directly (not via `receiver`) so creating a new
+      // property does not re-enter the `defineProperty` trap.
+      if ((sync !== "vm" && !Reflect.set(obj, key, v)) || sync === "host" || !ctx.alive)
         return true;
 
       mayConsumeAll(
@@ -68,6 +80,35 @@ export function wrap<T = any>(
         return true;
       });
     },
+    defineProperty(obj, key, descriptor) {
+      const sync = syncMode?.(rec) ?? "host";
+      const desc: PropertyDescriptor = { ...descriptor };
+      if ("value" in desc) desc.value = unwrap(desc.value, proxyKeySymbol);
+      if (typeof desc.get === "function") desc.get = unwrap(desc.get, proxyKeySymbol);
+      if (typeof desc.set === "function") desc.set = unwrap(desc.set, proxyKeySymbol);
+
+      if (sync !== "vm" && !Reflect.defineProperty(obj, key, desc)) return false;
+      if (sync === "host" || !ctx.alive) return true;
+
+      mayConsumeAll(
+        [marshal(rec), marshal(key), marshal(desc)],
+        (recHandle, keyHandle, descHandle) => {
+          const [handle2, unwrapped] = unwrapHandle(ctx, recHandle, proxyKeySymbolHandle);
+          const define = (h: QuickJSHandle) =>
+            call(
+              ctx,
+              `(o, k, d) => { Object.defineProperty(o, k, d); }`,
+              undefined,
+              h,
+              keyHandle,
+              descHandle,
+            ).dispose();
+          if (unwrapped) handle2.consume(define);
+          else define(handle2);
+        },
+      );
+      return true;
+    },
   }) as Wrapped<T>;
   return rec;
 }
@@ -80,12 +121,16 @@ export function wrapHandle(
   unmarshal: (handle: QuickJSHandle) => any,
   syncMode?: (target: QuickJSHandle) => SyncMode | undefined,
   wrappable?: (target: QuickJSHandle, ctx: QuickJSContext) => boolean,
+  syncEnabled = true,
 ): [Wrapped<QuickJSHandle> | undefined, boolean] {
   if (!isHandleObject(ctx, handle) || (wrappable && !wrappable(handle, ctx)))
     return [undefined, false];
 
   if (isHandleWrapped(ctx, handle, proxyKeySymbolHandle)) return [handle, false];
 
+  // Sync globally disabled: skip the VM-side proxy.
+  if (!syncEnabled) return [handle as Wrapped<QuickJSHandle>, false];
+
   const getSyncMode = (h: QuickJSHandle) => {
     const res = syncMode?.(unmarshal(h));
     if (typeof res === "string") return ctx.newString(res);
@@ -108,23 +153,35 @@ export function wrapHandle(
     Reflect.deleteProperty(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, proxyFuncs) => {
+  const definer = (h: QuickJSHandle, keyHandle: QuickJSHandle, descHandle: QuickJSHandle) => {
+    const target = unmarshal(h);
+    if (!target) return;
+    const key = unmarshal(keyHandle);
+    if (key === "__proto__") return; // for security
+    const desc = unmarshal(descHandle);
+    Object.defineProperty(unwrap(target, proxyKeySymbol), key, desc);
+  };
+
+  const proxyFuncs = 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]);
+      case 4:
+        return definer(args[0], args[1], args[2]);
+    }
+    return ctx.undefined;
+  });
+  // Use the exception-safe consume so proxyFuncs is disposed even if compiling
+  // the proxy below throws (e.g. under memory pressure).
+  return consume(proxyFuncs, proxyFuncs => [
+    call(
+      ctx,
+      `(target, sym, proxyFuncs) => {
           const rec =  new Proxy(target, {
             get(obj, key, receiver) {
               return key === sym ? obj : Reflect.get(obj, key, receiver)
@@ -134,7 +191,7 @@ export function wrapHandle(
                 ? value[sym] ?? value
                 : value;
               const sync = proxyFuncs(1, receiver) ?? "vm";
-              if (sync === "host" || Reflect.set(obj, key, v, receiver)) {
+              if (sync === "host" || Reflect.set(obj, key, v)) {
                 if (sync !== "vm") {
                   proxyFuncs(2, receiver, key, v);
                 }
@@ -150,16 +207,25 @@ export function wrapHandle(
               }
               return true;
             },
+            defineProperty(obj, key, descriptor) {
+              const sync = proxyFuncs(1, rec) ?? "vm";
+              if (sync === "host" || Reflect.defineProperty(obj, key, descriptor)) {
+                if (sync !== "vm") {
+                  proxyFuncs(4, rec, key, descriptor);
+                }
+              }
+              return true;
+            },
           });
           return rec;
         }`,
-        undefined,
-        handle,
-        proxyKeySymbolHandle,
-        proxyFuncs,
-      ) as Wrapped<QuickJSHandle>,
-      true,
-    ]);
+      undefined,
+      handle,
+      proxyKeySymbolHandle,
+      proxyFuncs,
+    ) as Wrapped<QuickJSHandle>,
+    true,
+  ]);
 }
 
 export function unwrap<T>(obj: T, key: string | symbol): T {
@@ -187,8 +253,9 @@ export function isHandleWrapped(
   return !!ctx.dump(
     call(
       ctx,
-      // promise and date cannot be wrapped
-      `(a, s) => (a instanceof Promise) || (a instanceof Date) || (typeof a === "object" && a !== null || typeof a === "function") && !!a[s]`,
+      // Built-ins that must not be wrapped (internal slots / non-property access)
+      // report as "wrapped" so wrapHandle leaves them alone.
+      `(a, s) => (a instanceof Promise) || (a instanceof Date) || (a instanceof ArrayBuffer) || (ArrayBuffer.isView(a)) || (a instanceof Map) || (a instanceof Set) || (typeof a === "object" && a !== null || typeof a === "function") && !!a[s]`,
       undefined,
       handle,
       key,