quickjs-emscripten-sync 1.0.0 → 1.3.0

package/src/index.ts

@@ -1,5 +1,9 @@
-import { QuickJSHandle, QuickJSVm } from "quickjs-emscripten";
-import {
+import type {
+  QuickJSDeferredPromise,
+  QuickJSHandle,
+  QuickJSVm,
+} from "quickjs-emscripten";
+import type {
   SuccessOrFail,
   VmCallResult,
 } from "quickjs-emscripten/dist/vm-interface";
@@ -9,11 +13,18 @@ import marshal from "./marshal";
 import unmarshal from "./unmarshal";
 import { wrap, wrapHandle, unwrap, unwrapHandle, Wrapped } from "./wrapper";
 import { complexity, isES2015Class, isObject, walkObject } from "./util";
-import { call, eq, isHandleObject, send, consumeAll } from "./vmutil";
+import {
+  call,
+  eq,
+  isHandleObject,
+  json,
+  consumeAll,
+  mayConsume,
+  handleFrom,
+} from "./vmutil";
 import { defaultRegisteredObjects } from "./default";
 
 export {
-  Arena,
   VMMap,
   defaultRegisteredObjects,
   marshal,
@@ -25,14 +36,14 @@ export {
   call,
   eq,
   isHandleObject,
-  send,
+  json,
   consumeAll,
 };
 
 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. */
-  isMarshalable?: (target: any) => boolean;
-  /** You can pre-register a pair of objects that will be considered the same between the browser and the QuickJS VM. This will be used automatically during the conversion. By default, it will be registered automatically with `defaultRegisteredObjects`.
+  isMarshalable?: boolean | "json" | ((target: any) => boolean | "json");
+  /** You can pre-register a pair of objects that will be considered the same between the host and the QuickJS VM. This will be used automatically during the conversion. By default, it will be registered automatically with `defaultRegisteredObjects`.
    *
    * Instead of a string, you can also pass a QuickJSHandle directly. In that case, however, you have to dispose of them manually when destroying the VM.
    */
@@ -40,9 +51,9 @@ export type Options = {
 };
 
 /**
- * The Arena class manages all generated handles at once by quickjs-emscripten and automatically converts objects between browser and QuickJS.
+ * The Arena class manages all generated handles at once by quickjs-emscripten and automatically converts objects between the host and the QuickJS VM.
  */
-export default class Arena {
+export class Arena {
   vm: QuickJSVm;
   _map: VMMap;
   _registeredMap: VMMap;
@@ -73,10 +84,10 @@ export default class Arena {
   }
 
   /**
-   * Evaluate JS code in the VM and get the result as an object on the browser side. It also converts and re-throws error objects when an error is thrown during evaluation.
+   * 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.
    */
   evalCode<T = any>(code: string): T {
-    let handle = this.vm.evalCode(code);
+    const handle = this.vm.evalCode(code);
     return this._unwrapResultAndUnmarshal(handle);
   }
 
@@ -88,31 +99,39 @@ export default class Arena {
     if ("value" in result) {
       return result.value;
     }
-    throw result.error.consume(err => this._unmarshal(err));
+    throw this._unwrapIfNotSynced(result.error.consume(this._unmarshal));
   }
 
   /**
    * Expose objects as global objects in the VM.
    *
-   * If sync is true, this function returns objects wrapped with proxies. This is necessary in order to reflect changes to the object from the browser side to the VM side. Please note that setting a value in the field or deleting a field in the original object will not synchronize it.
+   * By default, exposed objects are not synchronized between the host and the VM.
+   * If you want to sync an objects, first wrap the object with sync method, and then expose the wrapped object.
+   */
+  expose(obj: { [k: string]: any }) {
+    for (const [key, value] of Object.entries(obj)) {
+      mayConsume(this._marshal(value), (handle) => {
+        this.vm.setProp(this.vm.global, key, handle);
+      });
+    }
+  }
+
+  /**
+   * Enables sync for the object between the host and the VM and returns objects wrapped with proxies.
+   *
+   * The return value is necessary in order to reflect changes to the object from the host to the VM. Please note that setting a value in the field or deleting a field in the original object will not synchronize it.
    */
-  expose<T extends { [k: string]: any }>(obj: T, sync?: boolean): T {
-    const newobject = Object.entries(obj).map(([key, value]) => {
-      const value2 = sync ? this._wrap(value) : value;
-      const handle = this._marshal(value2);
-      if (sync) {
-        walkObject(value2, v => {
-          this._sync.add(this._unwrap(v));
-        });
-      }
-      this.vm.setProp(this.vm.global, key, handle);
-      return [key, value2] as const;
+  sync<T>(target: T): T {
+    const wrapped = this._wrap(target);
+    if (typeof wrapped === "undefined") return target;
+    walkObject(wrapped, (v) => {
+      this._sync.add(this._unwrap(v));
     });
-    return Object.fromEntries(newobject) as T;
+    return wrapped;
   }
 
   /**
-   * Register a pair of objects that will be considered the same between the browser and the QuickJS VM.
+   * Register a pair of objects that will be considered the same between the host and the QuickJS VM.
    *
    * Instead of a string, you can also pass a QuickJSHandle directly. In that case, however, when  you have to dispose them manually when destroying the VM.
    */
@@ -122,6 +141,7 @@ export default class Arena {
       typeof handleOrCode === "string"
         ? this._unwrapResult(this.vm.evalCode(handleOrCode))
         : handleOrCode;
+    if (eq(this.vm, handle, this.vm.undefined)) return;
     if (typeof handleOrCode === "string") {
       this._registeredMapDispose.add(target);
     }
@@ -170,52 +190,85 @@ export default class Arena {
     if ("value" in result) {
       return result.value;
     }
-    throw result.error.consume(err => this._unmarshal(err));
+    throw this._unwrapIfNotSynced(result.error.consume(this._unmarshal));
   }
 
   _unwrapResultAndUnmarshal(
     result: VmCallResult<QuickJSHandle> | undefined
   ): any {
     if (!result) return;
-    return this._unwrapResult(result).consume(h => this._unmarshal(h));
+    return this._unwrapIfNotSynced(
+      this._unwrapResult(result).consume(this._unmarshal)
+    );
   }
 
-  _marshal(target: any): QuickJSHandle {
+  _isMarshalable = (t: unknown): boolean | "json" => {
+    const im = this._options?.isMarshalable;
+    return (typeof im === "function" ? im(this._unwrap(t)) : im) ?? "json";
+  };
+
+  _marshalFind = (t: unknown) => {
+    const unwrappedT = this._unwrap(t);
+    const handle =
+      this._registeredMap.get(t) ??
+      (unwrappedT !== t ? this._registeredMap.get(unwrappedT) : undefined) ??
+      this._map.get(t) ??
+      (unwrappedT !== t ? this._map.get(unwrappedT) : undefined);
+    return handle;
+  };
+
+  _marshalPre = (
+    t: unknown,
+    h: QuickJSHandle | QuickJSDeferredPromise,
+    mode: true | "json" | undefined
+  ): Wrapped<QuickJSHandle> | undefined => {
+    if (mode === "json") return;
+    return this._register(t, handleFrom(h), this._map)?.[1];
+  };
+
+  _marshalPreApply = (
+    target: Function,
+    that: unknown,
+    args: unknown[]
+  ): void => {
+    const unwrapped = isObject(that) ? this._unwrap(that) : undefined;
+    // override sync mode of this object while calling the function
+    if (unwrapped) this._temporalSync.add(unwrapped);
+    try {
+      return target.apply(that, args);
+    } finally {
+      // restore sync mode
+      if (unwrapped) this._temporalSync.delete(unwrapped);
+    }
+  };
+
+  _marshal = (target: any): [QuickJSHandle, boolean] => {
     const registered = this._registeredMap.get(target);
     if (registered) {
-      return registered;
+      return [registered, false];
     }
 
-    const map = new VMMap(this.vm);
-    map.merge(this._map);
-
     const handle = marshal(this._wrap(target) ?? target, {
       vm: this.vm,
-      unmarshal: h => this._unmarshal(h),
-      isMarshalable: t =>
-        this._options?.isMarshalable?.(this._unwrap(t)) ?? true,
-      find: t => this._registeredMap.get(t) ?? map.get(t),
-      pre: (t, h) => this._register(t, h, map)?.[1],
-      preApply: (target, that, args) => {
-        const unwrapped = isObject(that) ? this._unwrap(that) : undefined;
-        // override sync mode of this object while calling the function
-        if (unwrapped) this._temporalSync.add(unwrapped);
-        try {
-          return target.apply(that, args);
-        } finally {
-          // restore sync mode
-          if (unwrapped) this._temporalSync.delete(unwrapped);
-        }
-      },
+      unmarshal: this._unmarshal,
+      isMarshalable: this._isMarshalable,
+      find: this._marshalFind,
+      pre: this._marshalPre,
+      preApply: this._marshalPreApply,
     });
 
-    this._map.merge(map);
-    map.clear();
-    map.dispose();
-    return handle;
-  }
+    return [handle, !this._map.hasHandle(handle)];
+  };
+
+  _preUnmarshal = (t: any, h: QuickJSHandle): Wrapped<any> => {
+    return this._register(t, h, undefined, true)?.[0];
+  };
+
+  _unmarshalFind = (h: QuickJSHandle): unknown => {
+    return this._registeredMap.getByHandle(h) ?? this._map.getByHandle(h);
+  };
 
-  _unmarshal(handle: QuickJSHandle): any {
+  _unmarshal = (handle: QuickJSHandle): any => {
     const registered = this._registeredMap.getByHandle(handle);
     if (typeof registered !== "undefined") {
       return registered;
@@ -224,12 +277,11 @@ export default class Arena {
     const [wrappedHandle] = this._wrapHandle(handle);
     return unmarshal(wrappedHandle ?? handle, {
       vm: this.vm,
-      marshal: (v: any) => this._marshal(v),
-      find: h => this._registeredMap.getByHandle(h) ?? this._map.getByHandle(h),
-      pre: (t: any, h: QuickJSHandle) =>
-        this._register(t, h, undefined, true)?.[0],
+      marshal: this._marshal,
+      find: this._unmarshalFind,
+      pre: this._preUnmarshal,
     });
-  }
+  };
 
   _register(
     t: any,
@@ -260,12 +312,12 @@ export default class Arena {
     return [wrappedT, wrappedH];
   }
 
-  _syncMode(obj: any) {
+  _syncMode = (obj: any): "both" | undefined => {
     const obj2 = this._unwrap(obj);
     return this._sync.has(obj2) || this._temporalSync.has(obj2)
       ? "both"
       : undefined;
-  }
+  };
 
   _wrap<T>(target: T): Wrapped<T> | undefined {
     return wrap(
@@ -273,8 +325,8 @@ export default class Arena {
       target,
       this._symbol,
       this._symbolHandle,
-      t => this._marshal(t),
-      t => this._syncMode(t)
+      this._marshal,
+      this._syncMode
     );
   }
 
@@ -282,6 +334,11 @@ export default class Arena {
     return unwrap(target, this._symbol);
   }
 
+  _unwrapIfNotSynced = <T>(target: T): T => {
+    const unwrapped = this._unwrap(target);
+    return this._sync.has(unwrapped) ? target : unwrapped;
+  };
+
   _wrapHandle(
     handle: QuickJSHandle
   ): [Wrapped<QuickJSHandle> | undefined, boolean] {
@@ -290,8 +347,8 @@ export default class Arena {
       handle,
       this._symbol,
       this._symbolHandle,
-      h => this._unmarshal(h),
-      t => this._syncMode(t)
+      this._unmarshal,
+      this._syncMode
     );
   }
 

package/src/marshal/function.test.ts

@@ -1,16 +1,17 @@
 import { getQuickJS, QuickJSHandle } from "quickjs-emscripten";
-import { send, eq, call } from "../vmutil";
+import { json, eq, call } from "../vmutil";
 import marshalFunction from "./function";
+import { expect, test, vi } from "vitest";
 
 test("normal func", async () => {
   const vm = (await getQuickJS()).createVm();
 
-  const marshal = jest.fn(v => send(vm, v));
-  const unmarshal = jest.fn(v =>
+  const marshal = vi.fn((v) => json(vm, v));
+  const unmarshal = vi.fn((v) =>
     eq(vm, v, vm.global) ? undefined : vm.dump(v)
   );
-  const preMarshal = jest.fn((_, a) => a);
-  const innerfn = jest.fn((..._args: any[]) => "hoge");
+  const preMarshal = vi.fn((_, a) => a);
+  const innerfn = vi.fn((..._args: any[]) => "hoge");
   const fn = (...args: any[]) => innerfn(...args);
 
   const handle = marshalFunction(vm, fn, marshal, unmarshal, preMarshal);
@@ -40,7 +41,7 @@ test("normal func", async () => {
 
 test("func which has properties", async () => {
   const vm = (await getQuickJS()).createVm();
-  const marshal = jest.fn(v => send(vm, v));
+  const marshal = vi.fn((v) => json(vm, v));
 
   const fn = () => {};
   fn.hoge = "foo";
@@ -49,7 +50,7 @@ test("func which has properties", async () => {
     vm,
     fn,
     marshal,
-    v => vm.dump(v),
+    (v) => vm.dump(v),
     (_, a) => a
   );
   if (!handle) throw new Error("handle is undefined");
@@ -101,7 +102,7 @@ test("class", async () => {
   ).toBe(true);
   expect(vm.dump(vm.getProp(instance, "a"))).toBe(100);
 
-  disposables.forEach(d => d.dispose());
+  disposables.forEach((d) => d.dispose());
   instance.dispose();
   newA.dispose();
   handle.dispose();
@@ -118,7 +119,7 @@ test("preApply", async () => {
   };
   const unmarshal = (v: QuickJSHandle) =>
     vm.typeof(v) === "object" ? that : vm.dump(v);
-  const preApply = jest.fn(
+  const preApply = vi.fn(
     (a: Function, b: any, c: any[]) => a.apply(b, c) + "!"
   );
   const that = {};
@@ -152,7 +153,7 @@ test("preApply", async () => {
 
 test("undefined", async () => {
   const vm = (await getQuickJS()).createVm();
-  const f = jest.fn();
+  const f = vi.fn();
 
   expect(marshalFunction(vm, undefined, f, f, f)).toBe(undefined);
   expect(marshalFunction(vm, null, f, f, f)).toBe(undefined);

package/src/marshal/function.ts

@@ -17,9 +17,9 @@ export default function marshalFunction(
   if (typeof target !== "function") return;
 
   const raw = vm
-    .newFunction(target.name, function(...argHandles) {
+    .newFunction(target.name, function (...argHandles) {
       const that = unmarshal(this);
-      const args = argHandles.map(a => unmarshal(a));
+      const args = argHandles.map((a) => unmarshal(a));
 
       if (isES2015Class(target) && isObject(that)) {
         // Class constructors cannot be invoked without new expression, and new.target is not changed
@@ -34,7 +34,7 @@ export default function marshalFunction(
         preApply ? preApply(target, that, args) : target.apply(that, args)
       );
     })
-    .consume(handle2 =>
+    .consume((handle2) =>
       // fucntions created by vm.newFunction are not callable as a class constrcutor
       call(
         vm,

package/src/marshal/index.test.ts

@@ -1,7 +1,10 @@
 import { getQuickJS } from "quickjs-emscripten";
+import { expect, test, vi } from "vitest";
+
 import VMMap from "../vmmap";
-import { instanceOf, call } from "../vmutil";
+import { instanceOf, call, handleFrom, fn } from "../vmutil";
 import marshal from ".";
+import { newDeferred } from "../util";
 
 test("primitive, array, object", async () => {
   const { vm, map, marshal, dispose } = await setup();
@@ -67,7 +70,7 @@ test("arrow function", async () => {
 test("function", async () => {
   const { vm, map, marshal, dispose } = await setup();
 
-  const bar = function(a: number, b: { hoge: number }) {
+  const bar = function (a: number, b: { hoge: number }) {
     return a + b.hoge;
   };
   const handle = marshal(bar);
@@ -90,6 +93,42 @@ test("function", async () => {
   dispose();
 });
 
+test("promise", async () => {
+  const { vm, marshal, dispose } = await setup();
+  const register = fn(
+    vm,
+    `promise => { promise.then(d => notify("resolve", d), d => notify("reject", d)); }`
+  );
+
+  let notified: any;
+  vm.newFunction("notify", (...handles) => {
+    notified = handles.map((h) => vm.dump(h));
+  }).consume((h) => {
+    vm.setProp(vm.global, "notify", h);
+  });
+
+  const deferred = newDeferred();
+  const handle = marshal(deferred.promise);
+  register(undefined, handle);
+
+  deferred.resolve("foo");
+  await deferred.promise;
+  expect(vm.unwrapResult(vm.executePendingJobs())).toBe(1);
+  expect(notified).toEqual(["resolve", "foo"]);
+
+  const deferred2 = newDeferred();
+  const handle2 = marshal(deferred2.promise);
+  register(undefined, handle2);
+
+  deferred2.reject("bar");
+  await expect(deferred2.promise).rejects.toBe("bar");
+  expect(vm.unwrapResult(vm.executePendingJobs())).toBe(1);
+  expect(notified).toEqual(["reject", "bar"]);
+
+  register.dispose();
+  dispose();
+});
+
 test("class", async () => {
   const { vm, map, marshal, dispose } = await setup();
 
@@ -117,6 +156,7 @@ test("class", async () => {
     }
   }
 
+  expect(A.name).toBe("_A"); // class A's name is _A in vitest
   const handle = marshal(A);
   if (!map) throw new Error("map is undefined");
 
@@ -126,15 +166,15 @@ test("class", async () => {
   expect(map.has(A.a)).toBe(true);
   expect(map.has(A.prototype.hoge)).toBe(true);
   expect(
-    map.has(Object.getOwnPropertyDescriptor(A.prototype, "foo")!.get)
+    map.has(Object.getOwnPropertyDescriptor(A.prototype, "foo")?.get)
   ).toBe(true);
   expect(
-    map.has(Object.getOwnPropertyDescriptor(A.prototype, "foo")!.set)
+    map.has(Object.getOwnPropertyDescriptor(A.prototype, "foo")?.set)
   ).toBe(true);
 
   expect(vm.typeof(handle)).toBe("function");
   expect(vm.dump(vm.getProp(handle, "length"))).toBe(1);
-  expect(vm.dump(vm.getProp(handle, "name"))).toBe("A");
+  expect(vm.dump(vm.getProp(handle, "name"))).toBe("_A");
   const staticA = vm.getProp(handle, "a");
   expect(instanceOf(vm, staticA, handle)).toBe(true);
   expect(vm.dump(vm.getProp(staticA, "a"))).toBe(100);
@@ -172,7 +212,7 @@ test("class", async () => {
 });
 
 test("marshalable", async () => {
-  const isMarshalable = jest.fn((a: any) => a !== globalThis);
+  const isMarshalable = vi.fn((a: any) => a !== globalThis);
   const { vm, marshal, dispose } = await setup({
     isMarshalable,
   });
@@ -186,10 +226,34 @@ test("marshalable", async () => {
   dispose();
 });
 
+test("marshalable json", async () => {
+  const isMarshalable = vi.fn(() => "json" as const);
+  const { vm, marshal, dispose } = await setup({
+    isMarshalable,
+  });
+
+  class Hoge {}
+  const target = {
+    a: { c: () => 1, d: new Date(), e: [() => 1, 1, new Hoge()] },
+    b: 1,
+  };
+  const handle = marshal(target);
+
+  expect(vm.dump(handle)).toEqual({
+    a: { d: target.a.d.toISOString(), e: [null, 1, {}] },
+    b: 1,
+  });
+  expect(isMarshalable).toBeCalledTimes(1);
+  expect(isMarshalable).toBeCalledWith(target);
+  expect(isMarshalable).toReturnWith("json");
+
+  dispose();
+});
+
 const setup = async ({
   isMarshalable,
 }: {
-  isMarshalable?: (target: any) => boolean;
+  isMarshalable?: (target: any) => boolean | "json";
 } = {}) => {
   const vm = (await getQuickJS()).createVm();
   const map = new VMMap(vm);
@@ -199,13 +263,14 @@ const setup = async ({
     marshal: (v: any) =>
       marshal(v, {
         vm,
-        unmarshal: h => map.getByHandle(h) ?? vm.dump(h),
+        unmarshal: (h) => map.getByHandle(h) ?? vm.dump(h),
         isMarshalable,
-        pre: (t, h) => {
+        pre: (t, d) => {
+          const h = handleFrom(d);
           map.set(t, h);
           return h;
         },
-        find: t => map.get(t),
+        find: (t) => map.get(t),
       }),
     dispose: () => {
       map.dispose();

package/src/marshal/index.ts

@@ -1,16 +1,25 @@
-import { QuickJSHandle, QuickJSVm } from "quickjs-emscripten";
-import marshalArray from "./array";
+import type {
+  QuickJSDeferredPromise,
+  QuickJSHandle,
+  QuickJSVm,
+} from "quickjs-emscripten";
 import marshalFunction from "./function";
 import marshalObject from "./object";
 import marshalPrimitive from "./primitive";
 import marshalSymbol from "./symbol";
+import marshalJSON from "./json";
+import marshalPromise from "./promise";
 
 export type Options = {
   vm: QuickJSVm;
   unmarshal: (handle: QuickJSHandle) => unknown;
-  isMarshalable?: (target: unknown) => boolean;
+  isMarshalable?: (target: unknown) => boolean | "json";
   find: (target: unknown) => QuickJSHandle | undefined;
-  pre: (target: unknown, handle: QuickJSHandle) => QuickJSHandle | undefined;
+  pre: (
+    target: unknown,
+    handle: QuickJSHandle | QuickJSDeferredPromise,
+    mode: true | "json" | undefined
+  ) => QuickJSHandle | undefined;
   preApply?: (target: Function, thisArg: unknown, args: unknown[]) => any;
 };
 
@@ -29,20 +38,25 @@ export function marshal(target: unknown, options: Options): QuickJSHandle {
     if (handle) return handle;
   }
 
-  if (isMarshalable?.(target) === false) {
+  const marshalable = isMarshalable?.(target);
+  if (marshalable === false) {
     return vm.undefined;
   }
 
-  const marshal2 = (t: unknown) => marshal(t, options);
-
-  const result =
-    marshalSymbol(vm, target, pre) ??
-    marshalArray(vm, target, marshal2, pre) ??
-    marshalFunction(vm, target, marshal2, unmarshal, pre, options.preApply) ??
-    marshalObject(vm, target, marshal2, pre) ??
-    vm.undefined;
+  const pre2 = (target: any, handle: QuickJSHandle | QuickJSDeferredPromise) =>
+    pre(target, handle, marshalable);
+  if (marshalable === "json") {
+    return marshalJSON(vm, target, pre2);
+  }
 
-  return result;
+  const marshal2 = (t: unknown) => marshal(t, options);
+  return (
+    marshalSymbol(vm, target, pre2) ??
+    marshalPromise(vm, target, marshal2, pre2) ??
+    marshalFunction(vm, target, marshal2, unmarshal, pre2, options.preApply) ??
+    marshalObject(vm, target, marshal2, pre2) ??
+    vm.undefined
+  );
 }
 
 export default marshal;