quickjs-emscripten-sync 1.8.4 → 1.9.1

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { Intrinsics } from 'quickjs-emscripten';
+import { QuickJSAsyncContext } from 'quickjs-emscripten';
 import { QuickJSContext } from 'quickjs-emscripten';
 import { QuickJSDeferredPromise } from 'quickjs-emscripten';
 import { QuickJSHandle } from 'quickjs-emscripten';
@@ -13,6 +14,7 @@ export declare class Arena {
     _map: VMMap;
     _registeredMap: VMMap;
     _registeredMapDispose: Set<any>;
+    _transientHandles: Set<QuickJSHandle>;
     _sync: Set<any>;
     _temporalSync: Set<any>;
     _symbol: symbol;
@@ -24,6 +26,8 @@ export declare class Arena {
      * 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(): void;
+    /** Allows `using arena = new Arena(...)` to dispose the arena automatically. */
+    [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.
      */
@@ -199,8 +203,12 @@ export declare class Arena {
     _unwrapResult<T>(result: SuccessOrFail<T, QuickJSHandle>): T;
     _unwrapResultAndUnmarshal(result: VmCallResult<QuickJSHandle> | undefined): any;
     _isMarshalable: (t: unknown) => boolean | "json";
+    _marshalByReference: (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;
+    _registerTransient: (handle: QuickJSHandle) => void;
+    _disposeTransient: (handle: QuickJSHandle) => void;
     _marshalPreApply: (target: (...args: any[]) => any, that: unknown, args: unknown[]) => void;
     _marshal: (target: any) => [QuickJSHandle, boolean];
     _preUnmarshal: (t: any, h: QuickJSHandle) => Wrapped<any>;
@@ -215,6 +223,23 @@ export declare class Arena {
     _unwrapHandle(target: QuickJSHandle): [QuickJSHandle, boolean];
 }
 
+/**
+ * An Arena backed by a {@link QuickJSAsyncContext}. In addition to everything
+ * `Arena` offers, it can evaluate code asynchronously with `evalCodeAsync`,
+ * which lets the VM await host promises (e.g. async module loaders or async
+ * functions exposed from the host) without manually pumping pending jobs.
+ */
+export declare class AsyncArena extends Arena {
+    asyncContext: QuickJSAsyncContext;
+    constructor(ctx: QuickJSAsyncContext, options?: Options);
+    /**
+     * 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.
+     */
+    evalCodeAsync<T = any>(code: string, filename?: string): Promise<T>;
+}
+
 export declare function call(ctx: QuickJSContext, code: string, thisArg?: QuickJSHandle, ...args: QuickJSHandle[]): QuickJSHandle;
 
 /**
@@ -261,13 +286,21 @@ export declare 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;
+    /** 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;
 };
 
 declare type Options_2 = {
     ctx: QuickJSContext;
     unmarshal: (handle: QuickJSHandle) => unknown;
     isMarshalable?: (target: unknown) => boolean | "json";
+    marshalByReference?: (target: unknown) => boolean;
+    registerHostRef?: (target: unknown, handle: QuickJSHandle) => QuickJSHandle;
     find: (target: unknown) => QuickJSHandle | undefined;
+    registerTransient?: (handle: QuickJSHandle) => void;
+    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;
     custom?: Iterable<(obj: unknown, ctx: QuickJSContext) => QuickJSHandle | undefined>;
@@ -280,6 +313,8 @@ declare type Options_3 = {
     find: (handle: QuickJSHandle) => unknown | undefined;
     pre: <T = unknown>(target: T, handle: QuickJSHandle) => T | undefined;
     custom?: Iterable<(obj: QuickJSHandle, ctx: QuickJSContext) => any>;
+    /** When true, resolve opaque HostRef handles back to their host value. */
+    hostRef?: boolean;
 };
 
 declare type QuickJSContextEx = QuickJSContext & {
@@ -288,19 +323,28 @@ declare type QuickJSContextEx = QuickJSContext & {
 
 export declare function unmarshal(handle: QuickJSHandle, options: Options_3): any;
 
+/**
+ * Bidirectional map between host values and QuickJS handles.
+ *
+ * Each registered pair gets a numeric id. A value may be registered under two
+ * keys (e.g. a proxy-wrapped object and the underlying object), each with its
+ * own handle, so every lookup direction is backed by an explicit map and id
+ * reverse-lookups, keeping `delete` O(1).
+ */
 export declare class VMMap {
     ctx: QuickJSContext;
-    _map1: Map<any, number>;
-    _map2: Map<any, number>;
-    _map3: Map<number, QuickJSHandle>;
-    _map4: Map<number, QuickJSHandle>;
-    _counterMap: Map<number, any>;
+    _keyToId: Map<any, number>;
+    _key2ToId: Map<any, number>;
+    _idToHandle: Map<number, QuickJSHandle>;
+    _idToHandle2: Map<number, QuickJSHandle>;
+    _idToKey: Map<number, any>;
+    _idToKey2: Map<number, any>;
     _disposables: Set<QuickJSHandle>;
     _mapGet: QuickJSHandle;
     _mapSet: QuickJSHandle;
     _mapDelete: QuickJSHandle;
     _mapClear: QuickJSHandle;
-    _counter: number;
+    _nextId: number;
     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;
@@ -315,7 +359,6 @@ export declare class VMMap {
     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;
 }