@componentor/quickjs-emscripten 0.31.26 → 0.31.28

package/dist/index.d.mts

@@ -1,11 +1,98 @@
 import { QuickJSWASMModule, AsyncRuntimeOptions, QuickJSAsyncRuntime, ContextOptions, QuickJSAsyncContext } from '@componentor/quickjs-emscripten-core';
 export * from '@componentor/quickjs-emscripten-core';
 export { newQuickJSAsyncWASMModule, newQuickJSWASMModule } from './variants.mjs';
+import { WorkerEnabledContextOptions, WorkerEnabledContext } from '@componentor/quickjs-emscripten-worker-pool';
+export { MultiThreadingNotSupportedError, PoolDisposedError, PoolStats, QueueFullError, QuickJSWorkerPool, SessionEvalOptions, TaskHandle, WorkerCrashError, WorkerEnabledContext, WorkerEnabledContextOptions, WorkerEnabledContextResult, WorkerPoolContext, WorkerPoolContextResult, WorkerPoolEvalOptions, WorkerPoolOptions, WorkerPoolVariant, WorkerSession, WorkerTask, WorkerTaskCancelledError, WorkerTaskError, WorkerTaskResult, WorkerTaskTimeoutError, detectPlatform, getDefaultPoolSize, getWorkerPool, getWorkerPoolSync, isMultiThreadingSupported, newWorkerEnabledContext, newWorkerPool, newWorkerPoolContext } from '@componentor/quickjs-emscripten-worker-pool';
 export { default as DEBUG_SYNC } from '@componentor/quickjs-wasmfile-debug-sync';
 export { default as RELEASE_SYNC } from '@componentor/quickjs-wasmfile-release-sync';
 export { default as DEBUG_ASYNC } from '@componentor/quickjs-wasmfile-debug-asyncify';
 export { default as RELEASE_ASYNC } from '@componentor/quickjs-wasmfile-release-asyncify';
 
+/**
+ * Global configuration for worker pool contexts.
+ * These settings are used as defaults when calling {@link newWorkerAsyncContext}.
+ */
+interface WorkerPoolConfig {
+    /**
+     * Whether worker pool is enabled.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Number of workers in the pool.
+     * @default navigator.hardwareConcurrency or 4
+     */
+    poolSize?: number;
+    /**
+     * Bootstrap code that runs on each worker during initialization.
+     * Use this to set up shared state like mocks, utilities, etc.
+     *
+     * @example
+     * ```typescript
+     * configureWorkerPool({
+     *   bootstrapCode: `
+     *     globalThis.mockFetch = (url) => ({ status: 200, url })
+     *   `
+     * })
+     * ```
+     */
+    bootstrapCode?: string;
+    /**
+     * Whether to use a session for state persistence.
+     * - false (default): Parallel execution, each eval may hit different worker
+     * - true: Sequential execution, all evals go to same worker (state persists)
+     * @default false
+     */
+    useSession?: boolean;
+    /**
+     * Enable verbose logging for debugging.
+     * @default false
+     */
+    verbose?: boolean;
+    /**
+     * Default timeout for code execution in milliseconds.
+     * @default 0 (no timeout)
+     */
+    defaultTimeout?: number;
+}
+/**
+ * Configure the global worker pool settings.
+ *
+ * Call this before creating worker contexts to set up default worker pool options.
+ * These settings are used as defaults when calling {@link newWorkerAsyncContext}.
+ *
+ * @example
+ * ```typescript
+ * import { configureWorkerPool, newWorkerAsyncContext } from "@componentor/quickjs-emscripten"
+ *
+ * // Configure once at startup
+ * configureWorkerPool({
+ *   poolSize: 4,
+ *   bootstrapCode: `
+ *     globalThis.mockFetch = (url) => ({ status: 200, url })
+ *   `
+ * })
+ *
+ * // Create worker context - uses global config!
+ * const ctx = await newWorkerAsyncContext()
+ *
+ * // Parallel execution across workers
+ * const results = await Promise.all([
+ *   ctx.evalCodeAsync('mockFetch("/api/1")'),
+ *   ctx.evalCodeAsync('mockFetch("/api/2")'),
+ *   ctx.evalCodeAsync('mockFetch("/api/3")'),
+ * ])
+ * ```
+ */
+declare function configureWorkerPool(config: WorkerPoolConfig): void;
+/**
+ * Get the current global worker pool configuration.
+ */
+declare function getWorkerPoolConfig(): WorkerPoolConfig;
+/**
+ * Reset the global worker pool configuration to defaults.
+ */
+declare function resetWorkerPoolConfig(): void;
 /**
  * Get a shared singleton {@link QuickJSWASMModule}. Use this to evaluate code
  * or create Javascript environments.
@@ -41,8 +128,7 @@ declare function getQuickJSSync(): QuickJSWASMModule;
  */
 declare function newAsyncRuntime(options?: AsyncRuntimeOptions): Promise<QuickJSAsyncRuntime>;
 /**
- * Create a new {@link QuickJSAsyncContext} (with an associated runtime) in an
- * separate WebAssembly module.
+ * Create a new {@link QuickJSAsyncContext} in a separate WebAssembly module.
  *
  * Each context is isolated in a separate WebAssembly module, so that errors in
  * one runtime cannot contaminate another runtime, and each runtime can execute
@@ -51,7 +137,72 @@ declare function newAsyncRuntime(options?: AsyncRuntimeOptions): Promise<QuickJS
  * Note that there is a hard limit on the number of WebAssembly modules in older
  * versions of v8:
  * https://bugs.chromium.org/p/v8/issues/detail?id=12076
+ *
+ * For parallel execution across workers, use {@link newWorkerAsyncContext} instead.
  */
 declare function newAsyncContext(options?: ContextOptions): Promise<QuickJSAsyncContext>;
+/**
+ * Options for creating a worker-enabled async context.
+ */
+interface WorkerAsyncContextOptions extends WorkerEnabledContextOptions {
+    /**
+     * Context options for the local QuickJS context.
+     */
+    contextOptions?: ContextOptions;
+}
+/**
+ * Create a new {@link WorkerEnabledContext} for parallel execution across workers.
+ *
+ * This is the recommended way to use QuickJS with parallel execution. Each
+ * `evalCodeAsync` call can be distributed to different workers for parallelism.
+ *
+ * Uses global config from {@link configureWorkerPool} as defaults, which can
+ * be overridden by passing options.
+ *
+ * @example
+ * ```typescript
+ * // Simple usage with defaults
+ * const ctx = await newWorkerAsyncContext()
+ *
+ * // Parallel execution
+ * const results = await Promise.all([
+ *   ctx.evalCodeAsync('1 + 1'),
+ *   ctx.evalCodeAsync('2 + 2'),
+ *   ctx.evalCodeAsync('3 + 3'),
+ * ])
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With bootstrap code for mocks
+ * const ctx = await newWorkerAsyncContext({
+ *   poolSize: 8,
+ *   bootstrapCode: `
+ *     globalThis.mockFetch = (url) => ({ status: 200, url })
+ *   `,
+ * })
+ * ```
+ *
+ * @param options Worker pool and context options (overrides global config)
+ * @returns A new WorkerEnabledContext instance
+ */
+declare function newWorkerAsyncContext(options?: WorkerAsyncContextOptions): Promise<WorkerEnabledContext>;
+/**
+ * Check if multi-threading is supported in the current environment.
+ *
+ * Returns true if SharedArrayBuffer is available (required for Web Workers
+ * to share memory). In browsers, this requires COOP/COEP headers to be set.
+ * In Node.js, this is typically always available.
+ *
+ * @example
+ * ```typescript
+ * if (canUseWorkers()) {
+ *   console.log('Parallel execution available!')
+ * } else {
+ *   console.log('Falling back to single-threaded execution')
+ * }
+ * ```
+ */
+declare function canUseWorkers(): boolean;
 
-export { getQuickJS, getQuickJSSync, newAsyncContext, newAsyncRuntime };
+export { type WorkerAsyncContextOptions, type WorkerPoolConfig, canUseWorkers, configureWorkerPool, getQuickJS, getQuickJSSync, getWorkerPoolConfig, newAsyncContext, newAsyncRuntime, newWorkerAsyncContext, resetWorkerPoolConfig };

package/dist/index.d.ts

@@ -1,11 +1,98 @@
 import { QuickJSWASMModule, AsyncRuntimeOptions, QuickJSAsyncRuntime, ContextOptions, QuickJSAsyncContext } from '@componentor/quickjs-emscripten-core';
 export * from '@componentor/quickjs-emscripten-core';
 export { newQuickJSAsyncWASMModule, newQuickJSWASMModule } from './variants.js';
+import { WorkerEnabledContextOptions, WorkerEnabledContext } from '@componentor/quickjs-emscripten-worker-pool';
+export { MultiThreadingNotSupportedError, PoolDisposedError, PoolStats, QueueFullError, QuickJSWorkerPool, SessionEvalOptions, TaskHandle, WorkerCrashError, WorkerEnabledContext, WorkerEnabledContextOptions, WorkerEnabledContextResult, WorkerPoolContext, WorkerPoolContextResult, WorkerPoolEvalOptions, WorkerPoolOptions, WorkerPoolVariant, WorkerSession, WorkerTask, WorkerTaskCancelledError, WorkerTaskError, WorkerTaskResult, WorkerTaskTimeoutError, detectPlatform, getDefaultPoolSize, getWorkerPool, getWorkerPoolSync, isMultiThreadingSupported, newWorkerEnabledContext, newWorkerPool, newWorkerPoolContext } from '@componentor/quickjs-emscripten-worker-pool';
 export { default as DEBUG_SYNC } from '@componentor/quickjs-wasmfile-debug-sync';
 export { default as RELEASE_SYNC } from '@componentor/quickjs-wasmfile-release-sync';
 export { default as DEBUG_ASYNC } from '@componentor/quickjs-wasmfile-debug-asyncify';
 export { default as RELEASE_ASYNC } from '@componentor/quickjs-wasmfile-release-asyncify';
 
+/**
+ * Global configuration for worker pool contexts.
+ * These settings are used as defaults when calling {@link newWorkerAsyncContext}.
+ */
+interface WorkerPoolConfig {
+    /**
+     * Whether worker pool is enabled.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Number of workers in the pool.
+     * @default navigator.hardwareConcurrency or 4
+     */
+    poolSize?: number;
+    /**
+     * Bootstrap code that runs on each worker during initialization.
+     * Use this to set up shared state like mocks, utilities, etc.
+     *
+     * @example
+     * ```typescript
+     * configureWorkerPool({
+     *   bootstrapCode: `
+     *     globalThis.mockFetch = (url) => ({ status: 200, url })
+     *   `
+     * })
+     * ```
+     */
+    bootstrapCode?: string;
+    /**
+     * Whether to use a session for state persistence.
+     * - false (default): Parallel execution, each eval may hit different worker
+     * - true: Sequential execution, all evals go to same worker (state persists)
+     * @default false
+     */
+    useSession?: boolean;
+    /**
+     * Enable verbose logging for debugging.
+     * @default false
+     */
+    verbose?: boolean;
+    /**
+     * Default timeout for code execution in milliseconds.
+     * @default 0 (no timeout)
+     */
+    defaultTimeout?: number;
+}
+/**
+ * Configure the global worker pool settings.
+ *
+ * Call this before creating worker contexts to set up default worker pool options.
+ * These settings are used as defaults when calling {@link newWorkerAsyncContext}.
+ *
+ * @example
+ * ```typescript
+ * import { configureWorkerPool, newWorkerAsyncContext } from "@componentor/quickjs-emscripten"
+ *
+ * // Configure once at startup
+ * configureWorkerPool({
+ *   poolSize: 4,
+ *   bootstrapCode: `
+ *     globalThis.mockFetch = (url) => ({ status: 200, url })
+ *   `
+ * })
+ *
+ * // Create worker context - uses global config!
+ * const ctx = await newWorkerAsyncContext()
+ *
+ * // Parallel execution across workers
+ * const results = await Promise.all([
+ *   ctx.evalCodeAsync('mockFetch("/api/1")'),
+ *   ctx.evalCodeAsync('mockFetch("/api/2")'),
+ *   ctx.evalCodeAsync('mockFetch("/api/3")'),
+ * ])
+ * ```
+ */
+declare function configureWorkerPool(config: WorkerPoolConfig): void;
+/**
+ * Get the current global worker pool configuration.
+ */
+declare function getWorkerPoolConfig(): WorkerPoolConfig;
+/**
+ * Reset the global worker pool configuration to defaults.
+ */
+declare function resetWorkerPoolConfig(): void;
 /**
  * Get a shared singleton {@link QuickJSWASMModule}. Use this to evaluate code
  * or create Javascript environments.
@@ -41,8 +128,7 @@ declare function getQuickJSSync(): QuickJSWASMModule;
  */
 declare function newAsyncRuntime(options?: AsyncRuntimeOptions): Promise<QuickJSAsyncRuntime>;
 /**
- * Create a new {@link QuickJSAsyncContext} (with an associated runtime) in an
- * separate WebAssembly module.
+ * Create a new {@link QuickJSAsyncContext} in a separate WebAssembly module.
  *
  * Each context is isolated in a separate WebAssembly module, so that errors in
  * one runtime cannot contaminate another runtime, and each runtime can execute
@@ -51,7 +137,72 @@ declare function newAsyncRuntime(options?: AsyncRuntimeOptions): Promise<QuickJS
  * Note that there is a hard limit on the number of WebAssembly modules in older
  * versions of v8:
  * https://bugs.chromium.org/p/v8/issues/detail?id=12076
+ *
+ * For parallel execution across workers, use {@link newWorkerAsyncContext} instead.
  */
 declare function newAsyncContext(options?: ContextOptions): Promise<QuickJSAsyncContext>;
+/**
+ * Options for creating a worker-enabled async context.
+ */
+interface WorkerAsyncContextOptions extends WorkerEnabledContextOptions {
+    /**
+     * Context options for the local QuickJS context.
+     */
+    contextOptions?: ContextOptions;
+}
+/**
+ * Create a new {@link WorkerEnabledContext} for parallel execution across workers.
+ *
+ * This is the recommended way to use QuickJS with parallel execution. Each
+ * `evalCodeAsync` call can be distributed to different workers for parallelism.
+ *
+ * Uses global config from {@link configureWorkerPool} as defaults, which can
+ * be overridden by passing options.
+ *
+ * @example
+ * ```typescript
+ * // Simple usage with defaults
+ * const ctx = await newWorkerAsyncContext()
+ *
+ * // Parallel execution
+ * const results = await Promise.all([
+ *   ctx.evalCodeAsync('1 + 1'),
+ *   ctx.evalCodeAsync('2 + 2'),
+ *   ctx.evalCodeAsync('3 + 3'),
+ * ])
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With bootstrap code for mocks
+ * const ctx = await newWorkerAsyncContext({
+ *   poolSize: 8,
+ *   bootstrapCode: `
+ *     globalThis.mockFetch = (url) => ({ status: 200, url })
+ *   `,
+ * })
+ * ```
+ *
+ * @param options Worker pool and context options (overrides global config)
+ * @returns A new WorkerEnabledContext instance
+ */
+declare function newWorkerAsyncContext(options?: WorkerAsyncContextOptions): Promise<WorkerEnabledContext>;
+/**
+ * Check if multi-threading is supported in the current environment.
+ *
+ * Returns true if SharedArrayBuffer is available (required for Web Workers
+ * to share memory). In browsers, this requires COOP/COEP headers to be set.
+ * In Node.js, this is typically always available.
+ *
+ * @example
+ * ```typescript
+ * if (canUseWorkers()) {
+ *   console.log('Parallel execution available!')
+ * } else {
+ *   console.log('Falling back to single-threaded execution')
+ * }
+ * ```
+ */
+declare function canUseWorkers(): boolean;
 
-export { getQuickJS, getQuickJSSync, newAsyncContext, newAsyncRuntime };
+export { type WorkerAsyncContextOptions, type WorkerPoolConfig, canUseWorkers, configureWorkerPool, getQuickJS, getQuickJSSync, getWorkerPoolConfig, newAsyncContext, newAsyncRuntime, newWorkerAsyncContext, resetWorkerPoolConfig };