quickjs-emscripten-sync 1.2.0 → 1.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 rot1024
+Copyright (c) 2022 rot1024
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -1,6 +1,8 @@
 # quickjs-emscripten-sync
 
-We can build a plugin system that works safely in the web browser!
+[![CI](https://github.com/reearth/quickjs-emscripten-sync/actions/workflows/ci.yml/badge.svg)](https://github.com/reearth/quickjs-emscripten-sync/actions/workflows/main.yml) [![codecov](https://codecov.io/gh/reearth/quickjs-emscripten-sync/branch/main/graph/badge.svg)](https://codecov.io/gh/reearth/quickjs-emscripten-sync)
+
+Build a secure plugin system in web browsers
 
 This library wraps [quickjs-emscripten](https://github.com/justjake/quickjs-emscripten) and provides a way to sync object state between the browser and sandboxed QuickJS.
 
@@ -31,7 +33,7 @@ class Cls {
 }
 
 const vm = (await getQuickJS()).createVm();
-const arena = new Arena(vm);
+const arena = new Arena(vm, { isMarshalable: true });
 
 // We can pass objects to the VM and run code safely
 const exposed = {
@@ -41,10 +43,10 @@ const exposed = {
 };
 arena.expose(exposed);
 
-arena.evalCode(`cls instanceof Cls`)); // returns true
-arena.evalCode(`cls.field`));          // returns 0
-arena.evalCode(`cls.method()`));       // returns 1
-arena.evalCode(`cls.field`));          // returns 1
+arena.evalCode(`cls instanceof Cls`); // returns true
+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
@@ -74,7 +76,9 @@ import { Arena } from "quickjs-emscripten-sync";
   const vm = quickjs.createVm();
 
   // init Arena
-  const arena = new Arena(vm);
+  // ⚠️ Marshaling is opt-in for security reasons.
+  // ⚠️ Be careful when activating marshalling.
+  const arena = new Arena(vm, { isMarshalable: true });
 
   // expose objects as global objects in QuickJS VM
   arena.expose({
@@ -87,12 +91,12 @@ import { Arena } from "quickjs-emscripten-sync";
 
   // expose objects but also enable sync
   const data = arena.sync({ hoge: "foo" });
-  const exposed = arena.expose({ data });
+  arena.expose({ data });
 
   arena.evalCode(`data.hoge = "bar"`);
   // eval code and operations to exposed objects are automatically synced
   console.log(data.hoge); // "bar"
-  exposed.hoge = "changed!";
+  data.hoge = "changed!";
   console.log(arena.evalCode(`data.hoge`)); // "changed!"
 
   // Don't forget calling arena.dispose() before disposing QuickJS VM!

package/dist/index.d.ts

@@ -1,22 +1,9 @@
-import { QuickJSHandle, QuickJSVm } from "quickjs-emscripten";
-import { SuccessOrFail, VmCallResult } from "quickjs-emscripten/dist/vm-interface";
-import VMMap from "./vmmap";
-import marshal from "./marshal";
-import unmarshal from "./unmarshal";
-import { Wrapped } from "./wrapper";
-import { complexity, isES2015Class, isObject, walkObject } from "./util";
-import { call, eq, isHandleObject, json, consumeAll } from "./vmutil";
-import { defaultRegisteredObjects } from "./default";
-export { VMMap, defaultRegisteredObjects, marshal, unmarshal, complexity, isES2015Class, isObject, walkObject, call, eq, isHandleObject, json, consumeAll, };
-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`.
-     *
-     * 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]>;
-};
+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';
+
 /**
  * The Arena class manages all generated handles at once by quickjs-emscripten and automatically converts objects between the host and the QuickJS VM.
  */
@@ -83,7 +70,7 @@ export declare class Arena {
     _unwrapResultAndUnmarshal(result: VmCallResult<QuickJSHandle> | undefined): any;
     _isMarshalable: (t: unknown) => boolean | "json";
     _marshalFind: (t: unknown) => QuickJSHandle | undefined;
-    _marshalPre: (t: unknown, h: QuickJSHandle, mode: true | "json" | undefined) => Wrapped<QuickJSHandle> | undefined;
+    _marshalPre: (t: unknown, h: QuickJSHandle | QuickJSDeferredPromise, mode: true | "json" | undefined) => Wrapped<QuickJSHandle> | undefined;
     _marshalPreApply: (target: Function, that: unknown, args: unknown[]) => void;
     _marshal: (target: any) => [QuickJSHandle, boolean];
     _preUnmarshal: (t: any, h: QuickJSHandle) => Wrapped<any>;
@@ -97,3 +84,102 @@ export declare class Arena {
     _wrapHandle(handle: QuickJSHandle): [Wrapped<QuickJSHandle> | undefined, boolean];
     _unwrapHandle(target: QuickJSHandle): [QuickJSHandle, boolean];
 }
+
+export declare function call(vm: QuickJSVm, 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.
+ */
+export declare function complexity(value: any, max?: number): number;
+
+export declare function consumeAll<T extends QuickJSHandle[], K>(handles: T, cb: (handles: T) => K): K;
+
+/**
+ * Default value of registeredObjects option of the Arena class constructor.
+ */
+export declare const defaultRegisteredObjects: [any, string][];
+
+export declare function eq(vm: QuickJSVm, 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 isObject(value: any): value is object | Function;
+
+export declare function json(vm: QuickJSVm, 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`.
+     *
+     * 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]>;
+};
+
+declare type Options_2 = {
+    vm: QuickJSVm;
+    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;
+};
+
+declare type Options_3 = {
+    vm: QuickJSVm;
+    /** 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;
+};
+
+export declare function unmarshal(handle: QuickJSHandle, options: Options_3): any;
+
+export declare class VMMap {
+    vm: QuickJSVm;
+    _map1: Map<any, number>;
+    _map2: Map<any, number>;
+    _map3: Map<number, QuickJSHandle>;
+    _map4: Map<number, QuickJSHandle>;
+    _counterMap: Map<number, any>;
+    _disposables: Set<QuickJSHandle>;
+    _mapGet: QuickJSHandle;
+    _mapSet: QuickJSHandle;
+    _mapDelete: QuickJSHandle;
+    _mapClear: QuickJSHandle;
+    _counter: number;
+    constructor(vm: QuickJSVm);
+    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;
+    getByHandle(handle: QuickJSHandle): any;
+    has(key: any): boolean;
+    hasHandle(handle: QuickJSHandle): boolean;
+    keys(): IterableIterator<any>;
+    delete(key: any, dispose?: boolean): void;
+    deleteByHandle(handle: QuickJSHandle, dispose?: boolean): void;
+    clear(): void;
+    dispose(): void;
+    get size(): number;
+    [Symbol.iterator](): Iterator<[
+    any,
+    QuickJSHandle,
+    any,
+    QuickJSHandle | undefined
+    ]>;
+    _get2(num: number): any;
+    _call(fn: QuickJSHandle, thisArg: QuickJSHandle | undefined, ...args: QuickJSHandle[]): QuickJSHandle;
+}
+
+export declare function walkObject(value: any, callback?: (target: any, set: Set<any>) => boolean | void): Set<any>;
+
+declare type Wrapped<T> = T & {
+    __qes_wrapped: never;
+};
+
+export { }