quickjs-emscripten-sync 1.9.1 → 1.11.0

package/README.md

@@ -6,6 +6,9 @@
 
 quickjs-emscripten-sync wraps [quickjs-emscripten](https://github.com/justjake/quickjs-emscripten) and keeps object state in sync between the host (browser or Node.js) and a sandboxed QuickJS VM, so you can exchange values across the boundary as if they were plain JavaScript objects.
 
+> [!TIP]
+> **Want a higher-level, batteries-included plugin system?** Check out [**@reearth/zushi**](https://github.com/reearth/zushi) — a framework-agnostic plugin runtime that runs untrusted plugin code in an isolated WASM backend (QuickJS built in), exposes a host-defined API, and renders plugin UI in sandboxed iframes. quickjs-emscripten-sync provides the low-level host↔VM sync primitives; zushi builds a full plugin runtime on top.
+
 ## Features
 
 - Exchange and synchronize values between the host and QuickJS seamlessly:
@@ -226,6 +229,14 @@ type Options = {
    * "Passing objects by reference" below.
    */
   marshalByReference?: (target: any) => boolean;
+
+  /**
+   * Marshal selected async host functions as *asyncified* functions, so the VM
+   * suspends until the host promise settles and the guest receives the resolved
+   * value synchronously. Only effective with an `AsyncArena`. See "Asyncified
+   * host functions" below.
+   */
+  asyncify?: boolean | ((target: (...args: any[]) => any) => boolean);
 };
 ```
 
@@ -369,6 +380,40 @@ ctx.dispose();
 
 Evaluate JS code asynchronously and return the result on the host. Like `evalCode`, it converts and re-throws errors thrown during evaluation.
 
+#### Asyncified host functions
+
+Normally an async host function is marshalled like any other function, so the guest receives a marshalled `Promise`:
+
+```js
+const ctx = await newAsyncContext();
+const arena = new AsyncArena(ctx, { isMarshalable: true });
+
+arena.expose({ fetchSync: async () => "result" });
+await arena.evalCodeAsync(`typeof fetchSync()`); // "object" (a Promise)
+```
+
+With the `asyncify` option, selected async functions are marshalled through QuickJS's [Asyncify](https://emscripten.org/docs/porting/asyncify.html) support instead. When the guest calls one, the VM suspends until the host promise settles and the guest receives the **resolved value synchronously**, as if the call were blocking:
+
+```js
+const arena = new AsyncArena(ctx, { isMarshalable: true, asyncify: true });
+
+arena.expose({ fetchSync: async () => "result" });
+await arena.evalCodeAsync(`const v = fetchSync(); typeof v`); // "string"
+await arena.evalCodeAsync(`fetchSync()`); // "result"
+```
+
+`asyncify` accepts:
+
+- `true` — asyncify every host function that is *declared* async, auto-detected via `Object.prototype.toString.call(fn) === "[object AsyncFunction]"`. Functions transpiled to ES5 (e.g. Babel/TypeScript targeting older runtimes) are plain functions that return a promise and are **not** detected — use the predicate form for those.
+- `(target) => boolean` — asyncify exactly the functions for which it returns `true`. Called with the unwrapped target, like `isMarshalable`.
+- absent / `false` — current behavior; async functions yield a `Promise` in the guest.
+
+Constraints (imposed by Emscripten Asyncify):
+
+- Asyncified functions only work when evaluation is entered through an async entry point (`evalCodeAsync`). Calling one during a synchronous `evalCode` throws `Error: Function unexpectedly returned a Promise`.
+- Only **one** suspended call is allowed at a time. Concurrent suspension (e.g. two asyncified calls awaiting simultaneously) throws a runtime error from quickjs-emscripten. Sequential calls are fine.
+- The option requires a `QuickJSAsyncContext` (from `newAsyncContext()`). On a plain synchronous context it is silently ignored and async functions behave as before (Promise).
+
 ### `defaultRegisteredObjects: [any, string][]`
 
 The default value of the `registeredObjects` option.
@@ -402,6 +447,15 @@ Only the `set`, `deleteProperty`, and `defineProperty` operations on objects are
 
 `Date`, `Map`, `Set`, `ArrayBuffer`, and typed arrays are marshalled by value (a snapshot copy is created on the other side). They are not proxied, so later mutations are not synchronized, and self-referential `Map`/`Set` are not supported.
 
+### `this` on plain calls
+
+When an exposed host function is called plainly from the VM (`fn()`, not `obj.fn()`), the host function receives `this === undefined`. This differs from plain JavaScript, where a non-strict function called this way would see `this === globalThis`. The VM global object is intentionally **not** marshalled to the host: doing so would eagerly deep-copy the entire global graph on the first call and would leak `globalThis` across the boundary. Method calls are unaffected — `obj.fn()` still receives `obj` as `this`.
+
+```js
+arena.expose({ whoAmI() { return this; } });
+arena.evalCode(`whoAmI()`); // undefined (not globalThis)
+```
+
 ## License
 
 [MIT License](LICENSE)

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { ContextEvalOptions } from 'quickjs-emscripten';
+import { InterruptHandler } from 'quickjs-emscripten';
 import { Intrinsics } from 'quickjs-emscripten';
 import { QuickJSAsyncContext } from 'quickjs-emscripten';
 import { QuickJSContext } from 'quickjs-emscripten';
@@ -19,6 +21,7 @@ export declare class Arena {
     _temporalSync: Set<any>;
     _symbol: symbol;
     _symbolHandle: QuickJSHandle;
+    _wrapHandleImpl: WrapHandle;
     _options?: Options;
     /** Constructs a new Arena instance. It requires a quickjs-emscripten context initialized with `quickjs.newContext()`. */
     constructor(ctx: QuickJSContext, options?: Options);
@@ -30,8 +33,14 @@ export declare class Arena {
     [Symbol.dispose](): void;
     /**
      * 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.
+     *
+     * @param code - The JS code to evaluate
+     * @param filename - Optional filename used in error stacks and for debugging
+     * @param options - Optional eval options forwarded to quickjs-emscripten's
+     *   `evalCode`, either an `EvalFlags` bitmask (`number`) or a
+     *   {@link ContextEvalOptions} object (e.g. `{ strict: true }`)
      */
-    evalCode<T = any>(code: string): T;
+    evalCode<T = any>(code: string, filename?: string, options?: number | ContextEvalOptions): T;
     /**
      * Evaluate ES module code in the VM and get the module's exports.
      *
@@ -39,6 +48,10 @@ export declare class Arena {
      *
      * @param code - The ES module code to evaluate
      * @param filename - Optional filename for debugging purposes (default: "module.js")
+     * @param options - Optional {@link ContextEvalOptions}. `type` is always forced
+     *   to `"module"`, so any `type` in `options` is overridden. A numeric
+     *   `EvalFlags` bitmask cannot be merged with the forced module type and is
+     *   therefore not supported here; if a number is passed it is ignored.
      * @returns The module's exports object, or a Promise resolving to exports if using top-level await
      *
      * @example
@@ -64,7 +77,7 @@ export declare class Arena {
      * console.log(exports.data); // 123
      * ```
      */
-    evalModule<T = any>(code: string, filename?: string): T | Promise<T>;
+    evalModule<T = any>(code: string, filename?: string, options?: number | ContextEvalOptions): T | Promise<T>;
     /**
      * Almost same as `vm.executePendingJobs()`, but it converts and re-throws error objects when an error is thrown during evaluation.
      */
@@ -111,6 +124,39 @@ export declare class Arena {
      * ```
      */
     setMaxStackSize(stackSize: number): void;
+    /**
+     * Set a callback which is regularly called by the QuickJS engine when it is
+     * executing code. This callback can be used to implement an execution
+     * timeout: return `true` from the handler to interrupt the running code.
+     *
+     * This is useful for preventing runaway CPU usage (e.g. infinite loops) in
+     * untrusted code.
+     *
+     * @param cb - The interrupt handler. Return `true` to interrupt execution.
+     *
+     * @example
+     * ```js
+     * // Interrupt evaluation after 1 second
+     * const deadline = Date.now() + 1000;
+     * arena.setInterruptHandler(() => Date.now() > deadline);
+     *
+     * try {
+     *   arena.evalCode(`while (true) {}`);
+     * } catch (e) {
+     *   console.log("Execution interrupted");
+     * }
+     * ```
+     */
+    setInterruptHandler(cb: InterruptHandler): void;
+    /**
+     * Remove the interrupt handler previously set with `setInterruptHandler`.
+     *
+     * @example
+     * ```js
+     * arena.removeInterruptHandler();
+     * ```
+     */
+    removeInterruptHandler(): void;
     /**
      * Get detailed memory usage statistics for this runtime.
      *
@@ -204,6 +250,7 @@ export declare class Arena {
     _unwrapResultAndUnmarshal(result: VmCallResult<QuickJSHandle> | undefined): any;
     _isMarshalable: (t: unknown) => boolean | "json";
     _marshalByReference: (t: unknown) => boolean;
+    _asyncify: (t: unknown) => boolean;
     _registerHostRef: (t: unknown, handle: QuickJSHandle) => QuickJSHandle;
     _marshalFind: (t: unknown) => QuickJSHandle | undefined;
     _marshalPre: (t: unknown, h: QuickJSHandle | QuickJSDeferredPromise, mode: true | "json" | undefined) => Wrapped<QuickJSHandle> | undefined;
@@ -211,6 +258,7 @@ export declare class Arena {
     _disposeTransient: (handle: QuickJSHandle) => void;
     _marshalPreApply: (target: (...args: any[]) => any, that: unknown, args: unknown[]) => void;
     _marshal: (target: any) => [QuickJSHandle, boolean];
+    _prepareMarshalReturn: (h: QuickJSHandle) => QuickJSHandle;
     _preUnmarshal: (t: any, h: QuickJSHandle) => Wrapped<any>;
     _unmarshalFind: (h: QuickJSHandle) => unknown;
     _unmarshal: (handle: QuickJSHandle) => any;
@@ -236,8 +284,14 @@ export declare class AsyncArena extends Arena {
      * Evaluate JS code asynchronously in the VM and get the result on the host
      * side. Like `evalCode`, it converts and re-throws errors thrown during
      * evaluation. Use this when the code awaits host-provided promises.
+     *
+     * @param code - The JS code to evaluate
+     * @param filename - Optional filename used in error stacks and for debugging
+     * @param options - Optional eval options forwarded to quickjs-emscripten's
+     *   `evalCodeAsync`, either an `EvalFlags` bitmask (`number`) or a
+     *   {@link ContextEvalOptions} object (e.g. `{ strict: true }`)
      */
-    evalCodeAsync<T = any>(code: string, filename?: string): Promise<T>;
+    evalCodeAsync<T = any>(code: string, filename?: string, options?: number | ContextEvalOptions): Promise<T>;
 }
 
 export declare function call(ctx: QuickJSContext, code: string, thisArg?: QuickJSHandle, ...args: QuickJSHandle[]): QuickJSHandle;
@@ -249,11 +303,15 @@ export declare function complexity(value: any, max?: number): number;
 
 export declare function consumeAll<T extends QuickJSHandle[], K>(handles: T, cb: (handles: T) => K): K;
 
+export { ContextEvalOptions }
+
 /**
  * Default value of registeredObjects option of the Arena class constructor.
  */
 export declare const defaultRegisteredObjects: [any, string][];
 
+export { InterruptHandler }
+
 export { Intrinsics }
 
 export declare function isES2015Class(cls: any): cls is new (...args: any[]) => any;
@@ -290,6 +348,34 @@ export declare type Options = {
     syncEnabled?: boolean;
     /** A callback that returns whether an object should be passed to the VM by reference (as an opaque HostRef) instead of being marshalled by value/proxy. The guest cannot read such objects, but can hold them and pass them back to the host, where they resolve to the original object. */
     marshalByReference?: (target: any) => boolean;
+    /**
+     * Marshal selected host functions as *asyncified* functions. Normally an async
+     * host function is marshalled like any other function, so the guest receives a
+     * marshalled `Promise`. When a function is asyncified, the QuickJS VM instead
+     * suspends until the host promise settles and the guest receives the resolved
+     * value synchronously (as if the call were blocking).
+     *
+     * - `true`: asyncify every host function that is *declared* async, auto-detected
+     *   via `Object.prototype.toString.call(fn) === "[object AsyncFunction]"`. Note
+     *   that functions transpiled to ES5 (e.g. by Babel/TypeScript targeting older
+     *   runtimes) are plain functions returning a promise and are **not** detected —
+     *   use the predicate form for those.
+     * - predicate: asyncify exactly the functions for which it returns `true`. It is
+     *   called with the *unwrapped* target (the original function, not a sync proxy),
+     *   like `isMarshalable`.
+     * - absent/`false`: current behavior; async functions yield a `Promise` in the guest.
+     *
+     * Constraints (Emscripten Asyncify):
+     * - Asyncified functions only work when evaluation is entered through an async
+     *   entry point ({@link AsyncArena.evalCodeAsync}). Calling one during a
+     *   synchronous `evalCode` fails with `Error: Function unexpectedly returned a Promise`.
+     * - Only ONE suspended call is allowed at a time; concurrent suspension throws a
+     *   runtime error from quickjs-emscripten.
+     * - If the context does not support `newAsyncifiedFunction` (a plain sync context
+     *   from `getQuickJS().newContext()`), this option is silently ignored and async
+     *   functions behave as today (Promise).
+     */
+    asyncify?: boolean | ((target: (...args: any[]) => any) => boolean);
 };
 
 declare type Options_2 = {
@@ -303,6 +389,9 @@ declare type Options_2 = {
     disposeTransient?: (handle: QuickJSHandle) => void;
     pre: (target: unknown, handle: QuickJSHandle | QuickJSDeferredPromise, mode: true | "json" | undefined) => QuickJSHandle | undefined;
     preApply?: (target: (...args: any[]) => any, thisArg: unknown, args: unknown[]) => any;
+    prepareReturn?: (handle: QuickJSHandle) => QuickJSHandle;
+    unwrap?: (target: unknown) => unknown;
+    asyncify?: (target: unknown) => boolean;
     custom?: Iterable<(obj: unknown, ctx: QuickJSContext) => QuickJSHandle | undefined>;
 };
 
@@ -364,6 +453,13 @@ export declare class VMMap {
 
 export declare function walkObject(value: any, callback?: (target: any, set: Set<any>) => boolean | void): Set<any>;
 
+declare type WrapHandle = {
+    /** Wrap a VM handle with the shared proxyFuncs, like the old `wrapHandle`. */
+    wrapHandle: (handle: QuickJSHandle) => [Wrapped<QuickJSHandle> | undefined, boolean];
+    /** Dispose the shared proxyFuncs handle. Call exactly once, at Arena dispose. */
+    dispose: () => void;
+};
+
 declare type Wrapped<T> = T & {
     __qes_wrapped: never;
 };