@gravito/stream 2.0.1 → 2.1.0

package/dist/workers/BinaryWorkerProtocol.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Binary Worker Protocol - Worker 執行緒二進制傳輸協定
+ *
+ * 實作 JSON + TextEncoder/TextDecoder + ArrayBuffer Transfer 方案，
+ * 讓 Main Thread 與 Worker Thread 之間以零拷貝方式傳遞 Job 資料。
+ *
+ * 設計原則：
+ * - 不依賴 CBOR 或外部函式庫，使用 Bun 原生優化的 TextEncoder/TextDecoder
+ * - ArrayBuffer Transfer 確保零拷貝語意（transfer 後原 buffer 失效）
+ * - 呼叫端須自行保留 job 物件引用，以支援潛在的重試機制
+ *
+ * @module workers/BinaryWorkerProtocol
+ */
+import type { SerializedJob } from '../types';
+/**
+ * Binary Protocol 版本號，未來可用於版本協商。
+ */
+export declare const BINARY_PROTOCOL_VERSION = 1;
+/**
+ * 使用 Binary Protocol 傳送給 Worker 的訊息格式。
+ */
+export interface BinaryWorkerMessage {
+    /**
+     * 訊息類型識別符，固定為 'execute-binary'。
+     */
+    type: 'execute-binary';
+    /**
+     * 以 ArrayBuffer 格式包裝的序列化 Job 資料。
+     *
+     * 注意：此 buffer 在 postMessage transfer 後即失效（零拷貝語意）。
+     * Main Thread 應保留原始 job 物件以支援重試，而非依賴此 buffer。
+     */
+    buffer: ArrayBuffer;
+}
+/**
+ * 將 SerializedJob 編碼為可傳輸的 ArrayBuffer。
+ *
+ * 編碼流程：
+ * 1. JSON.stringify(job) — 序列化為 JSON 字串
+ * 2. TextEncoder.encode(json) — 轉換為 UTF-8 Uint8Array
+ * 3. 取出底層 ArrayBuffer 並以 slice 建立獨立副本，確保 buffer 邊界正確
+ *
+ * @param job - 要傳輸的已序列化 Job 物件
+ * @returns 包含 Job 資料的 ArrayBuffer（可作為 transfer list 傳遞給 postMessage）
+ * @throws {Error} 若 job 序列化失敗
+ *
+ * @example
+ * ```typescript
+ * const buffer = encodeJobForTransfer(job)
+ * worker.postMessage({ type: 'execute-binary', buffer }, [buffer])
+ * // buffer 在此之後失效，請勿再使用
+ * ```
+ */
+export declare function encodeJobForTransfer(job: SerializedJob): ArrayBuffer;
+/**
+ * 從 ArrayBuffer 解碼 SerializedJob。
+ *
+ * 解碼流程：
+ * 1. new Uint8Array(buffer) — 建立 buffer 的視圖
+ * 2. TextDecoder.decode(view) — 從 UTF-8 還原 JSON 字串
+ * 3. JSON.parse(json) — 還原為 SerializedJob 物件
+ *
+ * @param buffer - 由 encodeJobForTransfer 產生的 ArrayBuffer
+ * @returns 還原的 SerializedJob 物件
+ * @throws {Error} 若 buffer 為空、JSON 解析失敗或結果不符合 SerializedJob 結構
+ *
+ * @example
+ * ```typescript
+ * self.onmessage = async (event) => {
+ *   if (event.data.type === 'execute-binary') {
+ *     const job = decodeJobFromTransfer(event.data.buffer)
+ *     await executeJob(job)
+ *   }
+ * }
+ * ```
+ */
+export declare function decodeJobFromTransfer(buffer: ArrayBuffer): SerializedJob;

package/dist/workers/BunWorker.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Bun Worker Implementation.
+ *
+ * Executes jobs in isolated Bun Worker Threads to provide context isolation,
+ * error containment, and leverages Bun's performance optimizations.
+ *
+ * Key advantages over Node.js Worker Threads:
+ * - Native TypeScript support (no compilation needed)
+ * - 2-241x faster message passing for common patterns
+ * - Memory-efficient with `smol` mode
+ * - Built-in module preloading
+ *
+ * @public
+ */
+import type { SerializedJob } from '../types';
+/**
+ * Configuration options for the Bun Worker.
+ */
+export interface BunWorkerConfig {
+    /**
+     * Maximum execution time for a job in milliseconds.
+     *
+     * Jobs exceeding this duration will be forcefully terminated.
+     * @default 30000 (30 seconds)
+     */
+    maxExecutionTime?: number;
+    /**
+     * Maximum memory limit for the worker in MB.
+     *
+     * Note: Bun's memory management differs from Node.js.
+     * This is advisory and may not be strictly enforced.
+     * @default undefined (unlimited)
+     */
+    maxMemory?: number;
+    /**
+     * Whether to isolate contexts for each job.
+     *
+     * If `true`, a new Worker is created for every job execution.
+     * If `false`, the Worker is reused across multiple jobs.
+     * @default false
+     */
+    isolateContexts?: boolean;
+    /**
+     * Idle timeout for the Worker in milliseconds.
+     *
+     * The worker will be terminated if it remains idle for this duration to save resources.
+     * @default 60000 (60 seconds)
+     */
+    idleTimeout?: number;
+    /**
+     * Enable Bun's memory-saving mode with minimal performance tradeoff.
+     *
+     * Reduces memory footprint by approximately 20-30% per worker.
+     * @default false
+     */
+    smol?: boolean;
+    /**
+     * Modules to preload before worker starts.
+     *
+     * Useful for large libraries or frequently used dependencies.
+     * Can be a single path or array of paths.
+     * @default undefined
+     */
+    preload?: string | string[];
+    /**
+     * Enable debugging for this worker (opens inspector port).
+     *
+     * Useful for debugging worker code.
+     * @default undefined
+     */
+    inspectPort?: number;
+}
+/**
+ * Bun Worker.
+ *
+ * Manages the lifecycle of a Bun Worker Thread for job execution.
+ * Provides features like:
+ * - Context Isolation: Run code in a separate thread.
+ * - Timeout Enforcement: Terminate hangs or long-running jobs.
+ * - Memory Optimization: Native support for memory-efficient mode (`smol`).
+ * - Error Containment: Worker crashes do not crash the main application.
+ * - Performance: Leverages Bun's optimized message passing.
+ *
+ * @example
+ * ```typescript
+ * const worker = new BunWorker({
+ *   maxExecutionTime: 30000,
+ *   maxMemory: 512,
+ *   isolateContexts: true,
+ *   smol: true
+ * });
+ *
+ * await worker.execute(serializedJob);
+ * await worker.terminate();
+ * ```
+ */
+export declare class BunWorker {
+    private worker;
+    private state;
+    private config;
+    private idleTimer;
+    private executionTimer;
+    /**
+     * Creates a BunWorker instance.
+     *
+     * @param config - Configuration options for the worker.
+     */
+    constructor(config?: BunWorkerConfig);
+    /**
+     * Initializes the Bun Worker.
+     *
+     * @returns The active Worker instance.
+     * @throws {Error} If worker initialization fails or times out.
+     */
+    private initWorker;
+    /**
+     * Executes a job in the isolated Bun worker.
+     *
+     * @param job - The serialized job data to execute.
+     * @throws {Error} If execution fails, times out, or the worker crashes.
+     */
+    execute(job: SerializedJob): Promise<void>;
+    /**
+     * Internal method to send execution message to the worker thread.
+     *
+     * 使用 Binary Protocol（ArrayBuffer Transfer）傳遞 Job 資料：
+     * 1. 將 job 編碼為 ArrayBuffer（JSON + TextEncoder）
+     * 2. 透過 postMessage transfer list 零拷貝傳遞給 Worker
+     * 3. 注意：buffer transfer 後即失效，但 job 引用仍有效（支援重試）
+     *
+     * @param worker - The worker instance.
+     * @param job - Job data（保留此引用以支援潛在重試，不依賴已 transfer 的 buffer）
+     */
+    private executeInWorker;
+    /**
+     * Creates a promise that rejects after the configured timeout.
+     */
+    private createTimeoutPromise;
+    /**
+     * Starts the idle timer to auto-terminate the worker.
+     */
+    private startIdleTimer;
+    /**
+     * Terminates the Worker immediately.
+     *
+     * Stops any running job and releases resources.
+     */
+    terminate(): Promise<void>;
+    /**
+     * Gets the current state of the worker.
+     *
+     * @returns The current `WorkerState`.
+     */
+    getState(): string;
+    /**
+     * Checks if the worker is ready to accept a job.
+     *
+     * @returns `true` if ready, `false` otherwise.
+     */
+    isReady(): boolean;
+    /**
+     * Checks if the worker is currently executing a job.
+     *
+     * @returns `true` if busy, `false` otherwise.
+     */
+    isBusy(): boolean;
+    /**
+     * Unreferences the worker, allowing the process to exit even if worker is running.
+     *
+     * Bun-specific optimization for background workers.
+     */
+    unref(): void;
+    /**
+     * Re-references the worker, preventing process exit while worker is running.
+     *
+     * Bun-specific optimization for background workers.
+     */
+    ref(): void;
+}

package/dist/workers/SandboxedWorker.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Sandboxed Worker Implementation.
+ *
+ * Executes jobs in isolated Worker Threads to provide context isolation,
+ * error containment, and resource limits.
+ *
+ * @public
+ */
+import type { SerializedJob } from '../types';
+/**
+ * Configuration options for the Sandboxed Worker.
+ */
+export interface SandboxedWorkerConfig {
+    /**
+     * Maximum execution time for a job in milliseconds.
+     *
+     * Jobs exceeding this duration will be forcefully terminated.
+     * @default 30000 (30 seconds)
+     */
+    maxExecutionTime?: number;
+    /**
+     * Maximum memory limit for the worker in MB.
+     *
+     * If the worker exceeds this limit, it will be terminated and restarted.
+     * Note: Relies on `resourceLimits` which may vary by platform.
+     * @default undefined (unlimited)
+     */
+    maxMemory?: number;
+    /**
+     * Whether to isolate contexts for each job.
+     *
+     * If `true`, a new Worker Thread is created for every job execution.
+     * If `false`, the Worker Thread is reused across multiple jobs.
+     * @default false
+     */
+    isolateContexts?: boolean;
+    /**
+     * Idle timeout for the Worker Thread in milliseconds.
+     *
+     * The worker will be terminated if it remains idle for this duration to save resources.
+     * @default 60000 (60 seconds)
+     */
+    idleTimeout?: number;
+}
+/**
+ * Sandboxed Worker.
+ *
+ * Manages the lifecycle of a Node.js Worker Thread for job execution.
+ * Provides features like:
+ * - Context Isolation: Run code in a separate thread.
+ * - Timeout Enforcement: Terminate hangs or long-running jobs.
+ * - Memory Limits: Prevent OOM issues affecting the main process.
+ * - Error Containment: Worker crashes do not crash the main application.
+ *
+ * @example
+ * ```typescript
+ * const worker = new SandboxedWorker({
+ *   maxExecutionTime: 30000,
+ *   maxMemory: 512,
+ *   isolateContexts: true
+ * });
+ *
+ * await worker.execute(serializedJob);
+ * await worker.terminate();
+ * ```
+ */
+export declare class SandboxedWorker {
+    private worker;
+    private state;
+    private config;
+    private idleTimer;
+    private executionTimer;
+    /**
+     * Creates a SandboxedWorker instance.
+     *
+     * @param config - Configuration options for the worker.
+     */
+    constructor(config?: SandboxedWorkerConfig);
+    /**
+     * Initializes the Worker Thread.
+     *
+     * @returns The active Worker Thread instance.
+     * @throws {Error} If worker initialization fails or times out.
+     */
+    private initWorker;
+    /**
+     * Executes a job in the sandboxed environment.
+     *
+     * @param job - The serialized job data to execute.
+     * @throws {Error} If execution fails, times out, or the worker crashes.
+     */
+    execute(job: SerializedJob): Promise<void>;
+    /**
+     * Internal method to send execution message to the worker thread.
+     *
+     * @param worker - The worker thread instance.
+     * @param job - Job data.
+     */
+    private executeInWorker;
+    /**
+     * Creates a promise that rejects after the configured timeout.
+     */
+    private createTimeoutPromise;
+    /**
+     * Starts the idle timer to auto-terminate the worker.
+     */
+    private startIdleTimer;
+    /**
+     * Terminates the Worker Thread immediately.
+     *
+     * Stops any running job and releases resources.
+     */
+    terminate(): Promise<void>;
+    /**
+     * Gets the current state of the worker.
+     *
+     * @returns The current `WorkerState`.
+     */
+    getState(): string;
+    /**
+     * Checks if the worker is ready to accept a job.
+     *
+     * @returns `true` if ready, `false` otherwise.
+     */
+    isReady(): boolean;
+    /**
+     * Checks if the worker is currently executing a job.
+     *
+     * @returns `true` if busy, `false` otherwise.
+     */
+    isBusy(): boolean;
+}

package/dist/workers/WorkerFactory.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Worker Factory Implementation.
+ *
+ * Provides runtime-aware worker creation with automatic environment detection.
+ * Abstracts differences between Bun Workers and Node.js Worker Threads,
+ * allowing transparent switching based on the runtime environment.
+ *
+ * @public
+ */
+import { BunWorker, type BunWorkerConfig } from './BunWorker';
+import { SandboxedWorker, type SandboxedWorkerConfig } from './SandboxedWorker';
+/**
+ * Union type for worker configuration.
+ * Accepts both Bun and Node.js specific configs.
+ */
+export type WorkerConfig = BunWorkerConfig | SandboxedWorkerConfig;
+/**
+ * Union type for worker instances.
+ */
+export type Worker = BunWorker | SandboxedWorker;
+/**
+ * Runtime environment type.
+ */
+export type RuntimeEnvironment = 'bun' | 'node' | 'auto';
+/**
+ * Worker Factory Interface.
+ *
+ * Defines the contract for creating workers in different runtime environments.
+ */
+export interface IWorkerFactory {
+    /**
+     * Create a worker appropriate for the current runtime.
+     *
+     * @param config - Configuration for the worker.
+     * @returns A worker instance (BunWorker or SandboxedWorker).
+     */
+    create(config: WorkerConfig): BunWorker | SandboxedWorker;
+    /**
+     * Get the detected runtime environment.
+     *
+     * @returns The runtime environment ('bun' or 'node').
+     */
+    getRuntime(): 'bun' | 'node';
+    /**
+     * Check if running in Bun environment.
+     *
+     * @returns `true` if running on Bun, `false` otherwise.
+     */
+    isBun(): boolean;
+    /**
+     * Check if running in Node.js environment.
+     *
+     * @returns `true` if running on Node.js, `false` otherwise.
+     */
+    isNode(): boolean;
+}
+/**
+ * Runtime-aware Worker Factory.
+ *
+ * Automatically detects the runtime environment (Bun or Node.js) and creates
+ * the appropriate worker type. Provides a unified interface that abstracts
+ * away runtime-specific details.
+ *
+ * @example
+ * ```typescript
+ * // Automatic detection
+ * const factory = new RuntimeAwareWorkerFactory()
+ * const worker = factory.create({ maxExecutionTime: 30000 })
+ *
+ * // Force specific runtime (testing/development)
+ * const bunFactory = new RuntimeAwareWorkerFactory('bun')
+ * const nodeFactory = new RuntimeAwareWorkerFactory('node')
+ * ```
+ */
+export declare class RuntimeAwareWorkerFactory implements IWorkerFactory {
+    private runtime;
+    /**
+     * Creates a RuntimeAwareWorkerFactory instance.
+     *
+     * @param runtimeOverride - Optional override for runtime detection.
+     *   - `'auto'` or undefined: Automatically detect (default)
+     *   - `'bun'`: Force Bun runtime
+     *   - `'node'`: Force Node.js runtime
+     */
+    constructor(runtimeOverride?: RuntimeEnvironment);
+    /**
+     * Automatically detects the runtime environment.
+     *
+     * Detection strategy:
+     * 1. Check for Bun global object
+     * 2. Fall back to Node.js
+     *
+     * @returns The detected runtime ('bun' or 'node').
+     */
+    private detectRuntime;
+    /**
+     * Creates a worker appropriate for the current runtime.
+     *
+     * @param config - Configuration for the worker.
+     * @returns A BunWorker if running on Bun, SandboxedWorker otherwise.
+     */
+    create(config: WorkerConfig): BunWorker | SandboxedWorker;
+    /**
+     * Gets the detected runtime environment.
+     *
+     * @returns The runtime ('bun' or 'node').
+     */
+    getRuntime(): 'bun' | 'node';
+    /**
+     * Checks if running in Bun environment.
+     *
+     * @returns `true` if running on Bun, `false` otherwise.
+     */
+    isBun(): boolean;
+    /**
+     * Checks if running in Node.js environment.
+     *
+     * @returns `true` if running on Node.js, `false` otherwise.
+     */
+    isNode(): boolean;
+}
+/**
+ * Helper function to create a default factory with optional runtime override.
+ *
+ * @param runtimeOverride - Optional runtime override.
+ * @returns A new RuntimeAwareWorkerFactory instance.
+ */
+export declare function createWorkerFactory(runtimeOverride?: RuntimeEnvironment): RuntimeAwareWorkerFactory;

package/dist/workers/WorkerPool.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Worker Pool Implementation.
+ *
+ * Manages a pool of Sandboxed Workers to provide concurrency control,
+ * worker reuse, load balancing, and health monitoring.
+ *
+ * @public
+ */
+import type { SerializedJob } from '../types';
+import type { SandboxedWorkerConfig } from './SandboxedWorker';
+import { type IWorkerFactory, type RuntimeEnvironment } from './WorkerFactory';
+/**
+ * Configuration options for the Worker Pool.
+ */
+export interface WorkerPoolConfig extends SandboxedWorkerConfig {
+    /**
+     * The maximum number of workers allowed in the pool.
+     *
+     * @default 4
+     */
+    poolSize?: number;
+    /**
+     * The minimum number of workers to keep alive.
+     *
+     * The pool will pre-warm and maintain at least this many ready workers.
+     * @default 0
+     */
+    minWorkers?: number;
+    /**
+     * Interval for performing health checks in milliseconds.
+     *
+     * Periodically scans for and removes terminated or unhealthy workers.
+     * @default 30000 (30 seconds)
+     */
+    healthCheckInterval?: number;
+    /**
+     * Custom worker factory for creating workers.
+     *
+     * If not provided, RuntimeAwareWorkerFactory will be used with the runtime option.
+     * @default undefined
+     */
+    factory?: IWorkerFactory;
+    /**
+     * Runtime environment to use for worker creation.
+     *
+     * - `'auto'` or undefined: Automatically detect (Bun or Node.js)
+     * - `'bun'`: Force Bun runtime
+     * - `'node'`: Force Node.js runtime
+     * - `'bun'`/`'node'`: Only used if factory is not provided
+     *
+     * @default 'auto'
+     */
+    runtime?: RuntimeEnvironment;
+}
+/**
+ * Runtime statistics for the Worker Pool.
+ */
+export interface WorkerPoolStats {
+    /** Total number of workers (ready + busy). */
+    total: number;
+    /** Number of idle workers ready for new jobs. */
+    ready: number;
+    /** Number of workers currently executing jobs. */
+    busy: number;
+    /** Number of workers in terminated state awaiting cleanup. */
+    terminated: number;
+    /** Number of jobs waiting in the queue. */
+    pending: number;
+    /** Total number of successfully completed jobs. */
+    completed: number;
+    /** Total number of failed jobs. */
+    failed: number;
+}
+/**
+ * Worker Pool.
+ *
+ * Orchestrates multiple `SandboxedWorker` or `BunWorker` instances to execute jobs concurrently.
+ * Automatically selects the best worker implementation based on the runtime environment.
+ *
+ * Key features:
+ * - **Concurrency Control**: Limits the number of simultaneous job executions (`poolSize`).
+ * - **Queueing**: Queues jobs when all workers are busy.
+ * - **Lifecycle Management**: Automatically creates, reuses, and terminates workers.
+ * - **Health Monitoring**: Periodically cleans up dead workers and maintains `minWorkers`.
+ * - **Runtime-Aware**: Automatically uses BunWorker on Bun, SandboxedWorker on Node.js.
+ *
+ * @example
+ * ```typescript
+ * // Auto-detection (uses best available runtime)
+ * const pool = new WorkerPool({
+ *   poolSize: 8,
+ *   minWorkers: 2,
+ *   maxExecutionTime: 30000
+ * });
+ *
+ * // Force specific runtime
+ * const bunPool = new WorkerPool({
+ *   runtime: 'bun',
+ *   poolSize: 8
+ * });
+ *
+ * await pool.execute(job);
+ * await pool.shutdown();
+ * ```
+ */
+export declare class WorkerPool {
+    private workers;
+    private factory;
+    private config;
+    private queue;
+    private healthCheckTimer;
+    private stats;
+    /**
+     * Creates a WorkerPool instance.
+     *
+     * @param config - Configuration options for the pool.
+     */
+    constructor(config?: WorkerPoolConfig);
+    /**
+     * Pre-warms the pool by creating the minimum number of workers.
+     */
+    private warmUp;
+    /**
+     * Creates a new Worker (BunWorker or SandboxedWorker) and adds it to the pool.
+     *
+     * Uses the configured factory to create the appropriate worker type
+     * based on the runtime environment.
+     *
+     * @returns The newly created worker.
+     */
+    private createWorker;
+    /**
+     * Retrieves an available worker from the pool.
+     *
+     * Priorities:
+     * 1. Reuse an existing ready worker.
+     * 2. Create a new worker if the pool is not full.
+     * 3. Return `null` if the pool is saturated.
+     *
+     * @returns An available worker or `null`.
+     */
+    private getAvailableWorker;
+    /**
+     * Executes a job using the worker pool.
+     *
+     * If a worker is available, the job starts immediately.
+     * Otherwise, it is added to the pending queue.
+     *
+     * @param job - The serialized job data.
+     * @throws {Error} If execution fails.
+     */
+    execute(job: SerializedJob): Promise<void>;
+    /**
+     * Processes the next job in the queue if a worker is available.
+     */
+    private processQueue;
+    /**
+     * Starts the periodic health check.
+     */
+    private startHealthCheck;
+    /**
+     * Performs a health check on the pool.
+     *
+     * Removes terminated workers and ensures `minWorkers` are available.
+     */
+    private performHealthCheck;
+    /**
+     * Gets the current statistics of the worker pool.
+     *
+     * @returns Snapshot of pool statistics.
+     */
+    getStats(): WorkerPoolStats;
+    /**
+     * Shuts down the worker pool.
+     *
+     * Terminates all workers and rejects any pending jobs.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Waits for all active and pending jobs to complete.
+     *
+     * @param timeout - Maximum wait time in milliseconds. 0 for infinite.
+     * @throws {Error} If the timeout is reached.
+     */
+    waitForCompletion(timeout?: number): Promise<void>;
+}