nestworker 2.1.0 → 2.1.3

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
@@ -42,7 +44,7 @@ Enterprise-grade worker thread module for NestJS. Offload CPU-bound work to a ma
 
 | Package | Version |
 |---|---|
-| Node.js | ≥ 16 |
+| Node.js | ≥ 18 (uses the global `structuredClone`, available since Node 17) |
 | `@nestjs/common` | `^10` or `^11` |
 | `@nestjs/core` | `^10` or `^11` |
 | `reflect-metadata` | `^0.1` or `^0.2` |
@@ -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 |
 
@@ -183,7 +186,9 @@ Marks a method to be offloaded to a worker thread.
 | `priority` | `'HIGH' \| 'NORMAL' \| 'LOW'` | `'NORMAL'` | Queue priority |
 | `timeout` | `number` | — | Reject after this many ms |
 | `retry` | `number` | `0` | Extra attempts after first failure |
-| `retryDelay` | `number` | `0` | Ms between retry attempts |
+| `retryDelay` | `number \| (attempt: number) => number` | `0` | Ms between retry attempts. See note below. |
+
+> **`retryDelay` as a function:** functions can't cross the worker boundary, so when a function is supplied it's evaluated on the main thread at discovery time as the average of `fn(1)`, `fn(2)`, `fn(3)` and a warning is logged. For precise control (including exponential backoff) pass a number and recreate the curve with the per-call `RunOptions.retryDelay` override.
 
 ---
 
@@ -219,6 +224,26 @@ workerService.onDead((event) => { ... });   // job exhausted all retries
 
 ---
 
+### `WorkerService.stats()`
+
+Returns a point-in-time snapshot of the pool — used by the health indicator and metrics service, but also useful on its own:
+
+```ts
+const { poolSize, idle, busy, queued, warmingUp } = workerService.stats();
+```
+
+```ts
+interface PoolStats {
+  poolSize:  number;
+  idle:      number;
+  busy:      number;
+  queued:    number;
+  warmingUp: number;
+}
+```
+
+---
+
 ## `deps` vs `proxy`
 
 This is the most important decision when declaring a `@WorkerClass`.
@@ -405,6 +430,29 @@ process(): void {
 
 ---
 
+## OpenTelemetry Trace Propagation
+
+If `@opentelemetry/api` is installed in your app, nestworker captures the active span context on every `run()` and re-activates it inside the worker before the task runs — distributed traces stay continuous across the thread boundary. There is **no hard dependency**: the lookup is a one-shot cached `require()` and silently no-ops when the package isn't present.
+
+```bash
+npm install @opentelemetry/api
+```
+
+```ts
+// Spans created inside @WorkerTask methods will be children of the
+// active span on the main thread at the moment run() was called.
+@WorkerTask()
+async heavyWork(): Promise<void> {
+  const tracer = trace.getTracer('my-app');
+  await tracer.startActiveSpan('heavy-work', async (span) => {
+    // ...
+    span.end();
+  });
+}
+```
+
+---
+
 ## Health Indicator
 
 ```ts
@@ -502,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,50 @@ 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;
+    /** 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;