feat: add syncEnabled option to disable sync globally (closes #31)

When syncEnabled is false, objects are not wrapped with proxies and
marshalled handles are reported as disposable, so arena.sync has no
effect but short-lived objects exchanged across the boundary are not
retained for the arena's whole lifetime. This avoids VM memory growth
when, e.g., a host function returning fresh objects is called in a loop.

Defaults to true, preserving existing behaviour. Re-implements the idea
from #31 on the current codebase, with a test showing object count stays
flat with sync off and grows with it on.

Author: rot1024

README.md

@@ -217,6 +217,8 @@ 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;
+  /** Globally enable sync mode (default `true`). When `false`, objects are not wrapped with proxies and marshalled handles are disposed after use, so `arena.sync` has no effect but objects are not retained for their whole lifetime. Useful to avoid memory growth when frequently exchanging short-lived objects. */
+  syncEnabled?: boolean;
 }
 ```
 

src/index.test.ts

@@ -1037,6 +1037,42 @@ describe("intrinsics configuration", () => {
   });
 });
 
+describe("syncEnabled", () => {
+  const objCount = (ctx: any) => {
+    const h = ctx.runtime.computeMemoryUsage();
+    const c = ctx.dump(h).obj_count as number;
+    h.dispose();
+    return c;
+  };
+
+  const growth = async (syncEnabled: boolean) => {
+    const ctx = (await getQuickJS()).newContext();
+    const arena = new Arena(ctx, { isMarshalable: true, registeredObjects: [], syncEnabled });
+
+    arena.expose({ fnFromHost: () => ({ id: "x", data: Math.random() }) });
+    arena.evalCode(`globalThis.run = () => { for (let i = 0; i < 200; i++) fnFromHost(); }`);
+
+    arena.evalCode(`run()`);
+    const before = objCount(ctx);
+    arena.evalCode(`run()`);
+    const after = objCount(ctx);
+
+    arena.dispose();
+    ctx.dispose();
+    return after - before;
+  };
+
+  test("syncEnabled: false does not retain marshalled objects", async () => {
+    // returned objects are not retained, so repeated runs don't grow memory
+    expect(await growth(false)).toBeLessThan(50);
+  });
+
+  test("syncEnabled: true retains marshalled objects (default)", async () => {
+    // with sync on, every returned object is kept for identity, so memory grows
+    expect(await growth(true)).toBeGreaterThan(150);
+  });
+});
+
 describe("AsyncArena", () => {
   test("evalCodeAsync returns values", async () => {
     const ctx = await newAsyncContext();

src/index.ts

@@ -64,6 +64,8 @@ export type Options = {
   compat?: boolean;
   /** Experimental: use QuickJSContextEx, which wraps existing QuickJSContext. */
   experimentalContextEx?: boolean;
+  /** Globally enable sync mode (default `true`). When `false`, objects are not wrapped with proxies and marshalled handles are disposed after use, so `arena.sync` has no effect but objects are not retained for their whole lifetime. Useful to avoid memory growth when frequently exchanging short-lived objects. */
+  syncEnabled?: boolean;
 };
 
 /**
@@ -433,11 +435,12 @@ export class Arena {
       custom: this._options?.customMarshaller,
     });
 
-    return [handle, !this._map.hasHandle(handle)];
+    const syncEnabled = this._options?.syncEnabled ?? true;
+    return [handle, !syncEnabled || !this._map.hasHandle(handle)];
   };
 
   _preUnmarshal = (t: any, h: QuickJSHandle): Wrapped<any> => {
-    return this._register(t, h, undefined, true)?.[0];
+    return this._register(t, h, undefined, this._options?.syncEnabled ?? true)?.[0];
   };
 
   _unmarshalFind = (h: QuickJSHandle): unknown => {
@@ -505,6 +508,7 @@ export class Arena {
       this._marshal,
       this._syncMode,
       this._options?.isWrappable,
+      this._options?.syncEnabled ?? true,
     );
   }
 
@@ -526,6 +530,7 @@ export class Arena {
       this._unmarshal,
       this._syncMode,
       this._options?.isHandleWrappable,
+      this._options?.syncEnabled ?? true,
     );
   }
 

src/wrapper.ts

@@ -15,6 +15,7 @@ export function wrap<T = any>(
   marshal: (target: any) => [QuickJSHandle, boolean],
   syncMode?: (target: T) => SyncMode | undefined,
   wrappable?: (target: unknown) => boolean,
+  syncEnabled = true,
 ): Wrapped<T> | undefined {
   // 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.
@@ -32,6 +33,10 @@ export function wrap<T = any>(
 
   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);
@@ -85,12 +90,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);