nestworker 2.1.1 → 2.1.4

package/README.md

@@ -23,6 +23,8 @@ Enterprise-grade worker thread module for NestJS. Offload CPU-bound work to a ma
 
 - **Worker pool** — pre-spawned threads, warmed up before the first request
 - **Zero cold start** — pool initialises on `onModuleInit`, not on the first call
+- **Per-worker concurrency** — opt-in pipelining (`concurrency > 1`) keeps each worker busy across awaits and short tasks
+- **Automatic message batching** — jobs and results are coalesced into a single `postMessage` per scheduling pass, amortising `structuredClone` overhead
 - **Priority queue** — `HIGH / NORMAL / LOW`, binary-search sorted; no jobs are ever dropped
 - **Decorator discovery** — `@WorkerClass` + `@WorkerTask` replace all manual registration
 - **deps** — services serialised into the worker via `vm.runInContext()` + snapshot; use for plain config/data helpers
@@ -151,6 +153,7 @@ export class ImageController {
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `poolSize` | `number` | `os.cpus().length` | Worker thread count |
+| `concurrency` | `number` | `1` | Max in-flight jobs **per worker**. Set `> 1` to pipeline jobs so workers don't sit idle between results, or while a task is awaiting I/O (proxy IPC, `fetch`, `fs`, …). Keep at `1` for purely CPU-bound, fully blocking tasks. |
 | `shutdownTimeout` | `number` | `30_000` | Ms to wait for in-flight jobs on shutdown |
 | `asyncLocalStorages` | `AsyncLocalStorage[]` | `[]` | ALS instances to propagate into workers |
 
@@ -547,6 +550,36 @@ await Promise.all([
 
 ---
 
+## Per-Worker Concurrency
+
+By default each worker processes one job at a time. When tasks are short, or
+they `await` I/O (proxy IPC round-trips, `fetch`, `fs`, queue calls), the worker
+sits idle while the main thread processes the previous result. Set
+`concurrency > 1` to pipeline jobs into each worker and keep them saturated:
+
+```ts
+WorkerModule.forRoot({
+  poolSize:    4,   // 4 worker threads
+  concurrency: 8,   // up to 8 in-flight jobs per worker → 32 concurrent jobs
+})
+```
+
+Guidance:
+
+- **CPU-bound, fully blocking tasks** → keep at `1`. Extra concurrency cannot
+  help when the JS thread never yields.
+- **Short tasks (sub-millisecond)** → `2–4` is usually enough to hide the
+  per-job postMessage cost.
+- **Tasks awaiting I/O or proxy calls** → match `concurrency` to your typical
+  in-flight wait depth (e.g. `8–32`).
+
+Internally the pool also coalesces every job it dispatches in a single
+scheduling pass into one `postMessage` envelope per worker, and the worker
+flushes accumulated results once per microtask tick. Batching is automatic —
+there is nothing to configure.
+
+---
+
 ## Constraints
 
 ### Arguments and return values

package/dist/core/worker.interfaces.d.ts

@@ -1,27 +1,22 @@
 import type { AsyncLocalStorage } from 'node:async_hooks';
 export type TaskPriority = 'HIGH' | 'NORMAL' | 'LOW';
 export interface WorkerJob {
-    jobId: string;
+    jobId: number;
     serviceName: string;
     methodName: string;
     args: unknown[];
-    priority: TaskPriority;
-    timeout?: number;
-    /** Retry policy — sourced from @WorkerTask or overridden per call */
-    retry?: number;
-    retryDelay?: number;
-    /** Current attempt index (0 = first attempt) */
-    attempt?: number;
     proxyServices?: ProxyServiceDescriptor[];
     /** ALS context snapshot — restored in worker before task runs */
     alsContext?: Record<string, unknown>;
     /** OTEL trace context — W3C traceparent/tracestate headers */
     traceContext?: Record<string, string>;
     /** AbortSignal is non-transferable; we send the signal ID instead */
-    abortSignalId?: string;
+    abortSignalId?: number;
 }
 export interface WorkerResult<T = unknown> {
     type: 'result';
+    /** ID of the job this result is for (required when concurrency > 1) */
+    jobId?: number;
     ok: boolean;
     data?: T;
     error?: SerializedError;
@@ -36,7 +31,7 @@ export interface SerializedError {
 }
 export interface WorkerAbortMessage {
     type: 'abort';
-    abortSignalId: string;
+    abortSignalId: number;
 }
 export interface ProxyServiceDescriptor {
     propertyKey: string;
@@ -44,14 +39,14 @@ export interface ProxyServiceDescriptor {
 }
 export interface IpcInvokeRequest {
     type: 'ipc:invoke';
-    callId: string;
+    callId: number;
     propertyKey: string;
     methodName: string;
     args: unknown[];
 }
 export interface IpcInvokeResponse {
     type: 'ipc:result';
-    callId: string;
+    callId: number;
     ok: boolean;
     data?: unknown;
     error?: string;
@@ -59,10 +54,18 @@ export interface IpcInvokeResponse {
 export interface WorkerReadySignal {
     type: 'worker:ready';
 }
-export type WorkerInboundMessage = WorkerJob | IpcInvokeResponse | WorkerAbortMessage;
-export type WorkerOutboundMessage = WorkerResult | IpcInvokeRequest | WorkerReadySignal;
+export interface WorkerJobBatch {
+    type: 'batch';
+    jobs: WorkerJob[];
+}
+export interface WorkerResultBatch {
+    type: 'results';
+    results: WorkerResult[];
+}
+export type WorkerInboundMessage = WorkerJob | WorkerJobBatch | IpcInvokeResponse | WorkerAbortMessage;
+export type WorkerOutboundMessage = WorkerResult | WorkerResultBatch | IpcInvokeRequest | WorkerReadySignal;
 export interface DeadLetterEvent {
-    jobId: string;
+    jobId: number;
     serviceName: string;
     methodName: string;
     args: unknown[];
@@ -91,6 +94,18 @@ export interface ProxyInstance {
 export interface WorkerModuleOptions {
     /** Number of worker threads. Defaults to os.cpus().length */
     poolSize?: number;
+    /**
+     * Maximum number of in-flight jobs per worker. Defaults to 1.
+     *
+     * Set > 1 to pipeline jobs into each worker: the main thread will keep
+     * dispatching to a worker as long as its in-flight count is below this
+     * limit, so the worker never sits idle between jobs while the main thread
+     * is processing a result. Significant throughput win for short tasks and
+     * for tasks that await I/O (proxy IPC, fetch, fs, ...).
+     *
+     * Safe to keep at 1 for purely CPU-bound, blocking tasks.
+     */
+    concurrency?: number;
     /**
      * How long (ms) to wait for in-flight jobs to finish before force-killing
      * workers on application shutdown. Defaults to 30_000.

package/dist/core/worker.pool.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'node:events';
-import type { WorkerJob, ProxyInstance, DeadLetterEvent, SerializedError, PoolStats } from './worker.interfaces';
+import type { WorkerJob, TaskPriority, ProxyInstance, DeadLetterEvent, SerializedError, PoolStats } from './worker.interfaces';
 import type { SerializedService } from '../di/worker-container';
 export declare interface WorkerPool {
     on(event: 'dead', listener: (event: DeadLetterEvent) => void): this;
@@ -18,21 +18,62 @@ export declare class WorkerPool extends EventEmitter {
     private readonly size;
     private readonly shutdownTimeout;
     private readonly workers;
+    /**
+     * Available "slots" — each worker is pushed `concurrency` times when it
+     * becomes ready, then popped/pushed as jobs are dispatched/completed.
+     * This naturally supports per-worker pipelining without any per-job
+     * counter bookkeeping.
+     */
     private readonly idle;
     private readonly warmingUp;
     private readonly queue;
+    private queueHead;
     private destroyed;
-    private readonly active;
+    private activeCount;
+    /**
+     * `schedule()` is invoked many times in a single synchronous burst (e.g.
+     * `for (...) ws.run(...)` floods 20k enqueues). Running the dispatch loop
+     * after every enqueue limits us to batches of size 1 per worker — the
+     * whole point of batching is then defeated. Defer to the next microtask
+     * so all synchronously-enqueued jobs land in one schedule pass and get
+     * coalesced into a single postMessage per worker.
+     */
+    private scheduleQueued;
     /** Maps abortSignalId → worker currently running that job */
     private readonly signalWorkerMap;
+    private readonly concurrency;
     private readonly proxyMap;
-    constructor(services: SerializedService[], proxyInstances: ProxyInstance[], size?: number, shutdownTimeout?: number);
-    execute<T = unknown>(job: WorkerJob, signal?: AbortSignal): Promise<T>;
+    constructor(services: SerializedService[], proxyInstances: ProxyInstance[], size?: number, shutdownTimeout?: number, concurrency?: number);
+    execute<T = unknown>(job: WorkerJob, meta: {
+        priority: TaskPriority;
+        timeout?: number;
+        retry?: number;
+        retryDelay?: number;
+    }, signal?: AbortSignal): Promise<T>;
     stats(): PoolStats;
     private spawnWorker;
+    private handleIpcInvoke;
     private enqueue;
     private schedule;
-    private dispatch;
+    /**
+     * Synchronous drain used on the COMPLETION path — when a worker becomes
+     * idle as a result of a result message arriving, we want to hand it the
+     * next queued job in the SAME tick. The microtask-deferred `schedule()`
+     * adds a full microtask hop per round-trip, which dominates throughput
+     * for short tasks with concurrency=1.
+     *
+     * Initial-burst dispatch still goes through the deferred `schedule()` so
+     * synchronous floods of `execute()` calls get coalesced into per-worker
+     * batches.
+     */
+    private dispatchNow;
+    /** Pre-bound for queueMicrotask — avoids closure allocation per schedule. */
+    private readonly drain;
+    private prepareDispatch;
+    /** Called from the persistent message listener when a job result arrives. */
+    private completeJob;
+    private handleFailure;
+    private handleTimeout;
     private handleWorkerError;
     private handleWorkerExit;
     private replaceWorker;