nestworker 2.0.8 → 2.1.0

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

@@ -1,36 +1,115 @@
+import type { AsyncLocalStorage } from 'node:async_hooks';
 export type TaskPriority = 'HIGH' | 'NORMAL' | 'LOW';
 export interface WorkerJob {
+    jobId: string;
     serviceName: string;
     methodName: string;
     args: unknown[];
-    /** Sourced from @WorkerTask({ priority }) — used by WorkerPool to sort the queue */
     priority: TaskPriority;
-    /** Sourced from @WorkerTask({ timeout }) — rejects the job after this many ms */
     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;
 }
 export interface WorkerResult<T = unknown> {
+    type: 'result';
     ok: boolean;
     data?: T;
-    error?: {
-        message: string;
-        stack?: string;
-    };
+    error?: SerializedError;
+}
+export interface SerializedError {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: string | number;
+    /** Any extra own enumerable properties on the original error */
+    extra?: Record<string, unknown>;
+}
+export interface WorkerAbortMessage {
+    type: 'abort';
+    abortSignalId: string;
+}
+export interface ProxyServiceDescriptor {
+    propertyKey: string;
+    methodNames: string[];
+}
+export interface IpcInvokeRequest {
+    type: 'ipc:invoke';
+    callId: string;
+    propertyKey: string;
+    methodName: string;
+    args: unknown[];
+}
+export interface IpcInvokeResponse {
+    type: 'ipc:result';
+    callId: string;
+    ok: boolean;
+    data?: unknown;
+    error?: string;
+}
+export interface WorkerReadySignal {
+    type: 'worker:ready';
+}
+export type WorkerInboundMessage = WorkerJob | IpcInvokeResponse | WorkerAbortMessage;
+export type WorkerOutboundMessage = WorkerResult | IpcInvokeRequest | WorkerReadySignal;
+export interface DeadLetterEvent {
+    jobId: string;
+    serviceName: string;
+    methodName: string;
+    args: unknown[];
+    attempts: number;
+    error: SerializedError;
+    failedAt: Date;
 }
 export interface DiscoveredTask {
     serviceName: string;
     methodName: string;
     priority: TaskPriority;
     timeout?: number;
-    /** Bound method on the live main-thread instance */
+    retry?: number;
+    retryDelay?: number;
     fn: (...args: unknown[]) => unknown;
-    /** Class constructor — used to locate the compiled file and read metadata */
     metatype: new (...args: unknown[]) => unknown;
-    /** Live main-thread service instance — used to locate dep property keys */
     instance: unknown;
-    /** Resolved dep instances from the NestJS container, in declaration order */
     deps: unknown[];
+    proxyInstances: ProxyInstance[];
+}
+export interface ProxyInstance {
+    propertyKey: string;
+    methodNames: string[];
+    instance: Record<string, (...args: unknown[]) => unknown>;
 }
 export interface WorkerModuleOptions {
     /** Number of worker threads. Defaults to os.cpus().length */
     poolSize?: number;
+    /**
+     * How long (ms) to wait for in-flight jobs to finish before force-killing
+     * workers on application shutdown. Defaults to 30_000.
+     */
+    shutdownTimeout?: number;
+    /**
+     * AsyncLocalStorage instances whose current store should be propagated
+     * into worker tasks. Pass the same ALS instances you use in your app.
+     */
+    asyncLocalStorages?: AsyncLocalStorage<unknown>[];
+}
+export interface WorkerModuleAsyncOptions {
+    inject?: unknown[];
+    useFactory: (...args: unknown[]) => WorkerModuleOptions | Promise<WorkerModuleOptions>;
+}
+export interface PoolStats {
+    poolSize: number;
+    idle: number;
+    busy: number;
+    queued: number;
+    warmingUp: number;
 }

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

@@ -1,15 +1,25 @@
 import { DynamicModule } from '@nestjs/common';
-import type { WorkerModuleOptions } from './worker.interfaces';
-/**
- * WorkerModule – import once at the root of your application.
- *
- * @example
- *   @Module({
- *     imports: [WorkerModule.forRoot()],
- *     providers: [ConfigService, ImageService],
- *   })
- *   export class AppModule {}
- */
+import type { WorkerModuleOptions, WorkerModuleAsyncOptions } from './worker.interfaces';
 export declare class WorkerModule {
+    /**
+     * Register with static options.
+     *
+     * @example
+     *   WorkerModule.forRoot({ poolSize: 4 })
+     */
     static forRoot(options?: WorkerModuleOptions): DynamicModule;
+    /**
+     * Register with async factory — use when options come from ConfigService
+     * or other async providers.
+     *
+     * @example
+     *   WorkerModule.forRootAsync({
+     *     inject: [ConfigService],
+     *     useFactory: (cfg: ConfigService) => ({
+     *       poolSize: cfg.get<number>('WORKER_POOL_SIZE'),
+     *       shutdownTimeout: 30_000,
+     *     }),
+     *   })
+     */
+    static forRootAsync(asyncOptions: WorkerModuleAsyncOptions): DynamicModule;
 }

package/dist/core/worker.module.js

@@ -12,20 +12,17 @@ const common_1 = require("@nestjs/common");
 const core_1 = require("@nestjs/core");
 const worker_service_1 = require("./worker.service");
 const discovery_service_1 = require("../discovery/discovery.service");
-/**
- * WorkerModule – import once at the root of your application.
- *
- * @example
- *   @Module({
- *     imports: [WorkerModule.forRoot()],
- *     providers: [ConfigService, ImageService],
- *   })
- *   export class AppModule {}
- */
 let WorkerModule = WorkerModule_1 = class WorkerModule {
+    /**
+     * Register with static options.
+     *
+     * @example
+     *   WorkerModule.forRoot({ poolSize: 4 })
+     */
     static forRoot(options = {}) {
         return {
             module: WorkerModule_1,
+            global: true,
             imports: [core_1.DiscoveryModule],
             providers: [
                 { provide: 'WORKER_OPTIONS', useValue: options },
@@ -35,6 +32,37 @@ let WorkerModule = WorkerModule_1 = class WorkerModule {
             exports: [worker_service_1.WorkerService],
         };
     }
+    /**
+     * Register with async factory — use when options come from ConfigService
+     * or other async providers.
+     *
+     * @example
+     *   WorkerModule.forRootAsync({
+     *     inject: [ConfigService],
+     *     useFactory: (cfg: ConfigService) => ({
+     *       poolSize: cfg.get<number>('WORKER_POOL_SIZE'),
+     *       shutdownTimeout: 30_000,
+     *     }),
+     *   })
+     */
+    static forRootAsync(asyncOptions) {
+        const optionsProvider = {
+            provide: 'WORKER_OPTIONS',
+            inject: (asyncOptions.inject ?? []),
+            useFactory: asyncOptions.useFactory,
+        };
+        return {
+            module: WorkerModule_1,
+            global: true,
+            imports: [core_1.DiscoveryModule],
+            providers: [
+                optionsProvider,
+                discovery_service_1.WorkerDiscoveryService,
+                worker_service_1.WorkerService,
+            ],
+            exports: [worker_service_1.WorkerService],
+        };
+    }
 };
 exports.WorkerModule = WorkerModule;
 exports.WorkerModule = WorkerModule = WorkerModule_1 = __decorate([

package/dist/core/worker.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"worker.module.js","sourceRoot":"","sources":["../../src/core/worker.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAuD;AACvD,uCAA+C;AAC/C,qDAAiD;AACjD,sEAAwE;AAGxE;;;;;;;;;GASG;AAEI,IAAM,YAAY,oBAAlB,MAAM,YAAY;IACvB,MAAM,CAAC,OAAO,CAAC,UAA+B,EAAE;QAC9C,OAAO;YACL,MAAM,EAAE,cAAY;YACpB,OAAO,EAAE,CAAC,sBAAe,CAAC;YAC1B,SAAS,EAAE;gBACT,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,OAAO,EAAE;gBAChD,0CAAsB;gBACtB,8BAAa;aACd;YACD,OAAO,EAAE,CAAC,8BAAa,CAAC;SACzB,CAAC;IACJ,CAAC;CACF,CAAA;AAbY,oCAAY;uBAAZ,YAAY;IADxB,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,YAAY,CAaxB"}
+{"version":3,"file":"worker.module.js","sourceRoot":"","sources":["../../src/core/worker.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAiE;AACjE,uCAA+C;AAC/C,qDAAiD;AACjD,sEAAwE;AAIjE,IAAM,YAAY,oBAAlB,MAAM,YAAY;IACvB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,UAA+B,EAAE;QAC9C,OAAO;YACL,MAAM,EAAE,cAAY;YACpB,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,CAAC,sBAAe,CAAC;YAC1B,SAAS,EAAE;gBACT,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,OAAO,EAAE;gBAChD,0CAAsB;gBACtB,8BAAa;aACd;YACD,OAAO,EAAE,CAAC,8BAAa,CAAC;SACzB,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,YAAY,CAAC,YAAsC;QACxD,MAAM,eAAe,GAAa;YAChC,OAAO,EAAE,gBAAgB;YACzB,MAAM,EAAE,CAAC,YAAY,CAAC,MAAM,IAAI,EAAE,CAAY;YAC9C,UAAU,EAAE,YAAY,CAAC,UAAU;SACpC,CAAC;QAEF,OAAO;YACL,MAAM,EAAE,cAAY;YACpB,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,CAAC,sBAAe,CAAC;YAC1B,SAAS,EAAE;gBACT,eAAe;gBACf,0CAAsB;gBACtB,8BAAa;aACd;YACD,OAAO,EAAE,CAAC,8BAAa,CAAC;SACzB,CAAC;IACJ,CAAC;CACF,CAAA;AArDY,oCAAY;uBAAZ,YAAY;IADxB,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,YAAY,CAqDxB"}

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

@@ -1,20 +1,40 @@
-import type { WorkerJob } from './worker.interfaces';
+import { EventEmitter } from 'node:events';
+import type { WorkerJob, ProxyInstance, DeadLetterEvent, SerializedError, PoolStats } from './worker.interfaces';
 import type { SerializedService } from '../di/worker-container';
-export declare class WorkerPool {
+export declare interface WorkerPool {
+    on(event: 'dead', listener: (event: DeadLetterEvent) => void): this;
+    on(event: 'error', listener: (err: Error, job: WorkerJob) => void): this;
+    on(event: 'taskStart', listener: (job: WorkerJob) => void): this;
+    on(event: 'taskEnd', listener: (job: WorkerJob, durationMs: number) => void): this;
+    on(event: 'taskError', listener: (job: WorkerJob, error: SerializedError) => void): this;
+    emit(event: 'dead', payload: DeadLetterEvent): boolean;
+    emit(event: 'error', err: Error, job: WorkerJob): boolean;
+    emit(event: 'taskStart', job: WorkerJob): boolean;
+    emit(event: 'taskEnd', job: WorkerJob, durationMs: number): boolean;
+    emit(event: 'taskError', job: WorkerJob, error: SerializedError): boolean;
+}
+export declare class WorkerPool extends EventEmitter {
     private readonly services;
     private readonly size;
+    private readonly shutdownTimeout;
     private readonly workers;
     private readonly idle;
+    private readonly warmingUp;
     private readonly queue;
     private destroyed;
     private readonly active;
-    constructor(services: SerializedService[], size?: number);
-    execute<T = unknown>(job: WorkerJob): Promise<T>;
-    private preemptIfNeeded;
+    /** Maps abortSignalId → worker currently running that job */
+    private readonly signalWorkerMap;
+    private readonly proxyMap;
+    constructor(services: SerializedService[], proxyInstances: ProxyInstance[], size?: number, shutdownTimeout?: number);
+    execute<T = unknown>(job: WorkerJob, signal?: AbortSignal): Promise<T>;
+    stats(): PoolStats;
+    private spawnWorker;
     private enqueue;
     private schedule;
     private dispatch;
-    private spawnWorker;
+    private handleWorkerError;
+    private handleWorkerExit;
     private replaceWorker;
     destroy(): Promise<void>;
 }