quickjs-emscripten-sync 1.3.0 → 1.5.1

package/README.md

@@ -12,6 +12,7 @@ This library wraps [quickjs-emscripten](https://github.com/justjake/quickjs-emsc
   - Functions
   - Classes and instances
   - Objects with prototypes and any property descriptors
+  - Promises
 - Expose objects as a global object in QuickJS
 - Marshaling limitation for specific objects
 - Register a pair of objects that will be considered the same between the browser and QuickJS
@@ -32,10 +33,10 @@ class Cls {
   }
 }
 
-const vm = (await getQuickJS()).createVm();
-const arena = new Arena(vm, { isMarshalable: true });
+const ctx = (await getQuickJS()).newContext();
+const arena = new Arena(ctx, { isMarshalable: true });
 
-// We can pass objects to the VM and run code safely
+// We can pass objects to the context and run code safely
 const exposed = {
   Cls,
   cls: new Cls(),
@@ -48,12 +49,12 @@ arena.evalCode(`cls.field`);          // returns 0
 arena.evalCode(`cls.method()`);       // returns 1
 arena.evalCode(`cls.field`);          // returns 1
 
-arena.evalCode(`syncedCls.field`);     // returns 0
-exposed.syncedCls.method();            // returns 1
-arena.evalCode(`syncedCls.field`);     // returns 1
+arena.evalCode(`syncedCls.field`);    // returns 0
+exposed.syncedCls.method();           // returns 1
+arena.evalCode(`syncedCls.field`);    // returns 1
 
 arena.dispose();
-vm.dispose();
+ctx.dispose();
 ```
 
 [Example code](src/index.test.ts) is available as the unit test code.
@@ -72,15 +73,14 @@ import { getQuickJS } from "quickjs-emscripten";
 import { Arena } from "quickjs-emscripten-sync";
 
 (async function() {
-  const quickjs = await getQuickJS();
-  const vm = quickjs.createVm();
+  const ctx = (await getQuickJS()).newContext();
 
   // init Arena
   // ⚠️ Marshaling is opt-in for security reasons.
   // ⚠️ Be careful when activating marshalling.
-  const arena = new Arena(vm, { isMarshalable: true });
+  const arena = new Arena(ctx, { isMarshalable: true });
 
-  // expose objects as global objects in QuickJS VM
+  // expose objects as global objects in QuickJS context
   arena.expose({
     console: {
       log: console.log
@@ -99,15 +99,15 @@ import { Arena } from "quickjs-emscripten-sync";
   data.hoge = "changed!";
   console.log(arena.evalCode(`data.hoge`)); // "changed!"
 
-  // Don't forget calling arena.dispose() before disposing QuickJS VM!
+  // Don't forget calling arena.dispose() before disposing QuickJS context!
   arena.dispose();
-  vm.dispose();
+  ctx.dispose();
 })();
 ```
 
 ## Marshaling Limitations
 
-Objects are automatically converted when they cross between the host and the QuickJS VM. The conversion of a host's object to a VM handle is called marshaling, and the conversion of a VM handle to a host's object is called unmarshaling.
+Objects are automatically converted when they cross between the host and the QuickJS context. The conversion of a host's object to a handle is called marshaling, and the conversion of a handle to a host's object is called unmarshaling.
 
 And for marshalling, it is possible to control whether the conversion is performed or not.
 
@@ -116,7 +116,7 @@ For example, exposing the host's global object to QuickJS is very heavy and dang
 ```js
 import { Arena, complexity } from "quickjs-emscripten-sync";
 
-const arena = new Arena(vm, {
+const arena = new Arena(ctx, {
   isMarshalable: (target: any) => {
     // prevent passing globalThis to QuickJS
     if (target === window) return false;
@@ -183,32 +183,55 @@ By default, quickjs-emscripten-sync doesn't prevent any marshaling, even in such
 
 ### `Arena`
 
-The Arena class manages all generated handles at once by quickjs-emscripten and automatically converts objects between the host and the QuickJS VM.
+The Arena class manages all generated handles at once by quickjs-emscripten and automatically converts objects between the host and the QuickJS context.
 
-#### `new Arena(vm: QuickJSVm, options?: Options)`
+#### `new Arena(ctx: QuickJSContext, options?: Options)`
 
-Constructs a new Arena instance. It requires a quickjs-emscripten VM initialized with `quickjs.createVM()`.
+Constructs a new Arena instance. It requires a quickjs-emscripten context initialized with `quickjs.newContext()`.
 
 Options accepted:
 
 ```ts
 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?: boolean | "json" | ((target: any) => boolean | "json");
+  /** Pre-registered pairs 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.
+   */
   registeredObjects?: Iterable<[any, QuickJSHandle | string]>;
+  /** Register functions to convert an object to a QuickJS handle. */
+  customMarshaller?: Iterable<
+    (target: unknown, ctx: QuickJSContext) => QuickJSHandle | undefined
+  >;
+  /** Register functions to convert a QuickJS handle to an object. */
+  customUnmarshaller?: Iterable<
+    (target: QuickJSHandle, ctx: QuickJSContext) => any
+  >;
+  /** A callback that returns a boolean value that determines whether an object is wrappable by proxies. If returns false, note that the object cannot be synchronized between the host and the QuickJS even if arena.sync is used. */
+  isWrappable?: (target: any) => boolean;
+  /** A callback that returns a boolean value that determines whether an QuickJS handle is wrappable by proxies. If returns false, note that the handle cannot be synchronized between the host and the QuickJS even if arena.sync is used. */
+  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;
 }
 ```
 
-- **`isMarshalable`**: Determines how marshalling will be done when sending objects from the host to the VM. **Make sure to set the marshalling to be the minimum necessary as it may reduce the security of your application.** [Please read the section on security above.](#security-warning)
-   - `"json"` (**default**, safety): Target object will be serialized as JSON in host and then parsed in VM. Functions and classes will be lost in the process.
-   - `false` (safety): Target object will not be always marshalled as `undefined`.
-   - `(target: any) => boolean | "json"` (recoomended): You can control marshalling mode for each objects. If you want to do marshalling, usually use this method. Allow partial marshalling by returning `true` only for some objects.
-   - `true` (**risky and not recommended**): Target object will be always marshaled. This setting may reduce security.
-- **`registeredObjects`**: 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`](src/default.ts). If you want to add a new pair to this, please do the following:
+Notes:
+
+**`isMarshalable`**: Determines how marshalling will be done when sending objects from the host to the context. **Make sure to set the marshalling to be the minimum necessary as it may reduce the security of your application.** [Please read the section on security above.](#security-warning)
+
+ - `"json"` (**default**, safety): Target object will be serialized as JSON in host and then parsed in context. Functions and classes will be lost in the process.
+ - `false` (safety): Target object will not be always marshalled as `undefined`.
+ - `(target: any) => boolean | "json"` (recoomended): You can control marshalling mode for each objects. If you want to do marshalling, usually use this method. Allow partial marshalling by returning `true` only for some objects.
+ - `true` (**risky and not recommended**): Target object will be always marshaled. This setting may reduce security.
+
+**`registeredObjects`**: You can pre-register a pair of objects that will be considered the same between the host and the QuickJS context. This will be used automatically during the conversion. By default, it will be registered automatically with [`defaultRegisteredObjects`](src/default.ts). If you want to add a new pair to this, please do the following:
 
 ```js
 import { defaultRegisteredObjects } from "quickjs-emscripten-sync";
 
-const arena = new Arena(vm, {
+const arena = new Arena(ctx, {
   registeredObjects: [
     ...defaultRegisteredObjects,
     [Math, "Math"]
@@ -216,36 +239,36 @@ const arena = new Arena(vm, {
 });
 ```
 
-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.
+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 context.
 
 #### `dispose()`
 
-Dispose of the arena and managed handles. This method won't dispose the VM itself, so the VM has to be disposed of manually.
+Dispose of the arena and managed handles. This method won't dispose the context itself, so the context has to be disposed of manually.
 
 #### `evalCode<T = any>(code: string): T | undefined`
 
-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.
+Evaluate JS code in the context 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.
 
 #### `executePendingJobs(): number`
 
-Almost same as `vm.executePendingJobs()`, but it converts and re-throws error objects when an error is thrown during evaluation.
+Almost same as `ctx.runtime.executePendingJobs()`, but it converts and re-throws error objects when an error is thrown during evaluation.
 
 #### `expose(obj: { [k: string]: any })`
 
-Expose objects as global objects in the VM.
+Expose objects as global objects in the context.
 
-By default, exposed objects are not synchronized between the host and the VM.
+By default, exposed objects are not synchronized between the host and the context.
 If you want to sync an objects, first wrap the object with `sync` method, and then expose the wrapped object.
 
 #### `sync<T>(target: T): T`
 
-Enables sync for the object between the host and the VM and returns objects wrapped with proxies.
+Enables sync for the object between the host and the context 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.
+The return value is necessary in order to reflect changes to the object from the host to the context. Please note that setting a value in the field or deleting a field in the original object will not synchronize it.
 
 #### `register(target: any, code: string | QuickJSHandle)`
 
-Register a pair of objects that will be considered the same between the host and the QuickJS VM.
+Register a pair of objects that will be considered the same between the host and the QuickJS context.
 
 #### `unregisterAll(targets: Iterable<[any, string | QuickJSHandle]>)`
 
@@ -271,9 +294,9 @@ Measure the complexity of an object as you traverse the field and prototype chai
 
 ### How to work
 
-quickjs-emscripten can execute JS code safely, but it requires to deal with a lot of handles and lifetimes. Also, when destroying the VM, any un-destroyed handle will result in an error.
+quickjs-emscripten can execute JS code safely, but it requires to deal with a lot of handles and lifetimes. Also, when destroying the context, any un-destroyed handle will result in an error.
 
-quickjs-emscripten-sync will automatically manage all handles once generated by QuickJS VM in an Arena class.
+quickjs-emscripten-sync will automatically manage all handles once generated by QuickJS context in an Arena class.
 And it will automatically "marshal" objects as handles and "unmarshal" handles as objects to enable seamless data exchange between the browser and QuickJS. It recursively traverses the object properties and prototype chain to transform objects. A function is called after its arguments and this arg are automatically converted for the environment in which the function is defined. The return value will be automatically converted to match the environment of the caller.
 Most objects are wrapped by proxies during conversion, allowing "set" and "delete" operations on objects to be synchronized between the browser and QuickJS.
 
@@ -281,7 +304,7 @@ Most objects are wrapped by proxies during conversion, allowing "set" and "delet
 
 #### Class constructor
 
-When initializing a new instance, it is not possible to fully proxy this arg (a.k.a. `new.target`) inside the class constructor. Therefore, after the constructor call, the fields set for this are re-set to this on the VM side. Therefore, there may be some edge cases where the constructor may not work properly.
+When initializing a new instance, it is not possible to fully proxy this arg (a.k.a. `new.target`) inside the class constructor. Therefore, after the constructor call, the fields set for this are re-set to this on the context side. Therefore, there may be some edge cases where the constructor may not work properly.
 
 ```js
 class Cls {

package/dist/index.d.ts

@@ -1,14 +1,14 @@
+import type { QuickJSContext } from 'quickjs-emscripten';
 import type { QuickJSDeferredPromise } from 'quickjs-emscripten';
-import { QuickJSHandle } from 'quickjs-emscripten';
-import { QuickJSVm } from 'quickjs-emscripten';
-import type { SuccessOrFail } from 'quickjs-emscripten/dist/vm-interface';
-import type { VmCallResult } from 'quickjs-emscripten/dist/vm-interface';
+import type { QuickJSHandle } from 'quickjs-emscripten';
+import type { SuccessOrFail } from 'quickjs-emscripten';
+import type { VmCallResult } from 'quickjs-emscripten';
 
 /**
  * The Arena class manages all generated handles at once by quickjs-emscripten and automatically converts objects between the host and the QuickJS VM.
  */
 export declare class Arena {
-    vm: QuickJSVm;
+    context: QuickJSContext;
     _map: VMMap;
     _registeredMap: VMMap;
     _registeredMapDispose: Set<any>;
@@ -17,8 +17,8 @@ export declare class Arena {
     _symbol: symbol;
     _symbolHandle: QuickJSHandle;
     _options?: Options;
-    /** Constructs a new Arena instance. It requires a quickjs-emscripten VM initialized with `quickjs.createVM()`. */
-    constructor(vm: QuickJSVm, options?: Options);
+    /** Constructs a new Arena instance. It requires a quickjs-emscripten context initialized with `quickjs.newContext()`. */
+    constructor(ctx: QuickJSContext, options?: Options);
     /**
      * Dispose of the arena and managed handles. This method won't dispose the VM itself, so the VM has to be disposed of manually.
      */
@@ -85,7 +85,7 @@ export declare class Arena {
     _unwrapHandle(target: QuickJSHandle): [QuickJSHandle, boolean];
 }
 
-export declare function call(vm: QuickJSVm, code: string, thisArg?: QuickJSHandle, ...args: QuickJSHandle[]): QuickJSHandle;
+export declare function call(ctx: QuickJSContext, code: string, thisArg?: QuickJSHandle, ...args: QuickJSHandle[]): QuickJSHandle;
 
 /**
  * Measure the complexity of an object as you traverse the field and prototype chain. If max is specified, when the complexity reaches max, the traversal is terminated and it returns the max. In this function, one object and function are counted as a complexity of 1, and primitives are not counted as a complexity.
@@ -99,49 +99,61 @@ export declare function consumeAll<T extends QuickJSHandle[], K>(handles: T, cb:
  */
 export declare const defaultRegisteredObjects: [any, string][];
 
-export declare function eq(vm: QuickJSVm, a: QuickJSHandle, b: QuickJSHandle): boolean;
+export declare function eq(ctx: QuickJSContext, a: QuickJSHandle, b: QuickJSHandle): boolean;
 
 export declare function isES2015Class(cls: any): cls is new (...args: any[]) => any;
 
-export declare function isHandleObject(vm: QuickJSVm, a: QuickJSHandle): boolean;
+export declare function isHandleObject(ctx: QuickJSContext, h: QuickJSHandle): boolean;
 
 export declare function isObject(value: any): value is object | Function;
 
-export declare function json(vm: QuickJSVm, target: any): QuickJSHandle;
+export declare function json(ctx: QuickJSContext, target: any): QuickJSHandle;
 
 export declare function marshal(target: unknown, options: Options_2): QuickJSHandle;
 
 export declare 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?: 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`.
+    /** Pre-registered pairs 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.
      */
     registeredObjects?: Iterable<[any, QuickJSHandle | string]>;
+    /** Register functions to convert an object to a QuickJS handle. */
+    customMarshaller?: Iterable<(target: unknown, ctx: QuickJSContext) => QuickJSHandle | undefined>;
+    /** Register functions to convert a QuickJS handle to an object. */
+    customUnmarshaller?: Iterable<(target: QuickJSHandle, ctx: QuickJSContext) => any>;
+    /** A callback that returns a boolean value that determines whether an object is wrappable by proxies. If returns false, note that the object cannot be synchronized between the host and the QuickJS even if arena.sync is used. */
+    isWrappable?: (target: any) => boolean;
+    /** A callback that returns a boolean value that determines whether an QuickJS handle is wrappable by proxies. If returns false, note that the handle cannot be synchronized between the host and the QuickJS even if arena.sync is used. */
+    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;
 };
 
 declare type Options_2 = {
-    vm: QuickJSVm;
+    ctx: QuickJSContext;
     unmarshal: (handle: QuickJSHandle) => unknown;
     isMarshalable?: (target: unknown) => boolean | "json";
     find: (target: unknown) => QuickJSHandle | undefined;
     pre: (target: unknown, handle: QuickJSHandle | QuickJSDeferredPromise, mode: true | "json" | undefined) => QuickJSHandle | undefined;
     preApply?: (target: Function, thisArg: unknown, args: unknown[]) => any;
+    custom?: Iterable<(obj: unknown, ctx: QuickJSContext) => QuickJSHandle | undefined>;
 };
 
 declare type Options_3 = {
-    vm: QuickJSVm;
+    ctx: QuickJSContext;
     /** marshal returns handle and boolean indicates that the handle should be disposed after use */
     marshal: (target: unknown) => [QuickJSHandle, boolean];
     find: (handle: QuickJSHandle) => unknown | undefined;
     pre: <T = unknown>(target: T, handle: QuickJSHandle) => T | undefined;
+    custom?: Iterable<(obj: QuickJSHandle, ctx: QuickJSContext) => any>;
 };
 
 export declare function unmarshal(handle: QuickJSHandle, options: Options_3): any;
 
 export declare class VMMap {
-    vm: QuickJSVm;
+    ctx: QuickJSContext;
     _map1: Map<any, number>;
     _map2: Map<any, number>;
     _map3: Map<number, QuickJSHandle>;
@@ -153,7 +165,7 @@ export declare class VMMap {
     _mapDelete: QuickJSHandle;
     _mapClear: QuickJSHandle;
     _counter: number;
-    constructor(vm: QuickJSVm);
+    constructor(ctx: QuickJSContext);
     set(key: any, handle: QuickJSHandle, key2?: any, handle2?: QuickJSHandle): boolean;
     merge(iteratable: Iterable<[any, QuickJSHandle | undefined] | [any, QuickJSHandle | undefined, any, QuickJSHandle | undefined]> | undefined): void;
     get(key: any): QuickJSHandle | undefined;
@@ -166,12 +178,7 @@ export declare class VMMap {
     clear(): void;
     dispose(): void;
     get size(): number;
-    [Symbol.iterator](): Iterator<[
-    any,
-    QuickJSHandle,
-    any,
-    QuickJSHandle | undefined
-    ]>;
+    [Symbol.iterator](): Iterator<[any, QuickJSHandle, any, QuickJSHandle | undefined]>;
     _get2(num: number): any;
     _call(fn: QuickJSHandle, thisArg: QuickJSHandle | undefined, ...args: QuickJSHandle[]): QuickJSHandle;
 }