nestworker 1.1.20 → 2.0.4

package/dist/core/worker.pool.js

@@ -0,0 +1,210 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkerPool = void 0;
+const node_worker_threads_1 = require("node:worker_threads");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const PRIORITY_WEIGHT = {
+    HIGH: 3,
+    NORMAL: 2,
+    LOW: 1,
+};
+class WorkerPool {
+    services;
+    size;
+    workers = [];
+    idle = [];
+    queue = [];
+    destroyed = false;
+    active = new Map();
+    constructor(services, size = node_os_1.default.cpus().length) {
+        this.services = services;
+        this.size = size;
+        for (let i = 0; i < this.size; i++) {
+            const worker = this.spawnWorker();
+            this.workers.push(worker);
+            this.idle.push(worker);
+        }
+    }
+    execute(job) {
+        if (this.destroyed) {
+            return Promise.reject(new Error('WorkerPool destroyed'));
+        }
+        return new Promise(async (resolve, reject) => {
+            const task = {
+                job,
+                resolve: resolve,
+                reject,
+            };
+            await this.preemptIfNeeded(task);
+            // ALWAYS enqueue first
+            // otherwise priority is bypassed
+            this.enqueue(task);
+            // process queue
+            this.schedule();
+        });
+    }
+    async preemptIfNeeded(incoming) {
+        if (incoming.job.priority !== 'HIGH') {
+            return false;
+        }
+        for (const [worker, running] of this.active) {
+            if (running.priority === 'LOW') {
+                // stop LOW task
+                await worker.terminate();
+                // requeue interrupted LOW task
+                this.enqueue(running.task);
+                // remove dead worker
+                this.active.delete(worker);
+                const idx = this.workers.indexOf(worker);
+                if (idx >= 0) {
+                    this.workers.splice(idx, 1);
+                }
+                // create replacement worker
+                const replacement = this.spawnWorker();
+                this.workers.push(replacement);
+                // dispatch HIGH immediately
+                this.dispatch(replacement, incoming);
+                return true;
+            }
+        }
+        return false;
+    }
+    enqueue(task) {
+        const weight = PRIORITY_WEIGHT[task.job.priority];
+        let lo = 0;
+        let hi = this.queue.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >>> 1;
+            if (PRIORITY_WEIGHT[this.queue[mid].job.priority] < weight) {
+                hi = mid;
+            }
+            else {
+                lo = mid + 1;
+            }
+        }
+        this.queue.splice(lo, 0, task);
+    }
+    schedule() {
+        if (this.destroyed)
+            return;
+        while (this.idle.length > 0 &&
+            this.queue.length > 0) {
+            const worker = this.idle.pop();
+            // highest priority task first
+            const task = this.queue.shift();
+            this.dispatch(worker, task);
+        }
+    }
+    dispatch(worker, task) {
+        let settled = false;
+        let timeoutHandle;
+        const cleanup = () => {
+            worker.removeListener('message', onMessage);
+            worker.removeListener('error', onError);
+            worker.removeListener('exit', onExit);
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+            }
+        };
+        const recycle = () => {
+            cleanup();
+            if (this.destroyed)
+                return;
+            this.idle.push(worker);
+            // continue processing
+            this.schedule();
+        };
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            Promise.resolve(fn())
+                .catch(() => { })
+                .finally(() => {
+                recycle();
+            });
+        };
+        const onMessage = (result) => {
+            settle(() => {
+                if (result.ok) {
+                    task.resolve(result.data);
+                }
+                else {
+                    task.reject(new Error(result.error?.message ??
+                        'Worker error'));
+                }
+            });
+        };
+        const onError = async (err) => {
+            settle(async () => {
+                task.reject(err);
+                await this.replaceWorker(worker);
+            });
+        };
+        const onExit = async (code) => {
+            if (this.destroyed)
+                return;
+            settle(async () => {
+                task.reject(new Error(`Worker exited unexpectedly with code ${code} ` +
+                    `while running "${task.job.serviceName}.${task.job.methodName}"`));
+                await this.replaceWorker(worker);
+            });
+        };
+        worker.once('message', onMessage);
+        worker.once('error', onError);
+        worker.once('exit', onExit);
+        if (task.job.timeout &&
+            task.job.timeout > 0) {
+            timeoutHandle = setTimeout(async () => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                task.reject(new Error(`Task "${task.job.serviceName}.${task.job.methodName}" timed out after ${task.job.timeout}ms`));
+                try {
+                    await worker.terminate();
+                }
+                catch { }
+                await this.replaceWorker(worker);
+                this.schedule();
+            }, task.job.timeout);
+        }
+        worker.postMessage(task.job);
+    }
+    spawnWorker() {
+        return new node_worker_threads_1.Worker(node_path_1.default.resolve(__dirname, '../worker/worker-runtime.js'), {
+            workerData: {
+                services: this.services,
+            },
+        });
+    }
+    async replaceWorker(oldWorker) {
+        const workerIndex = this.workers.indexOf(oldWorker);
+        if (workerIndex >= 0) {
+            this.workers.splice(workerIndex, 1);
+        }
+        const idleIndex = this.idle.indexOf(oldWorker);
+        if (idleIndex >= 0) {
+            this.idle.splice(idleIndex, 1);
+        }
+        const newWorker = this.spawnWorker();
+        this.workers.push(newWorker);
+        this.idle.push(newWorker);
+    }
+    async destroy() {
+        this.destroyed = true;
+        for (const queued of this.queue) {
+            queued.reject(new Error('WorkerPool destroyed'));
+        }
+        this.queue.length = 0;
+        await Promise.allSettled(this.workers.map((worker) => worker.terminate()));
+        this.workers.length = 0;
+        this.idle.length = 0;
+    }
+}
+exports.WorkerPool = WorkerPool;
+//# sourceMappingURL=worker.pool.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"worker.pool.js","sourceRoot":"","sources":["../../src/core/worker.pool.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,87 @@
+import { OnModuleDestroy } from '@nestjs/common';
+import { WorkerDiscoveryService } from '../discovery/discovery.service';
+import type { TaskPriority, WorkerModuleOptions } from './worker.interfaces';
+/**
+ * WorkerService
+ *
+ * Main entry point for executing worker-thread tasks.
+ *
+ * Features:
+ * - Lazy worker pool initialization
+ * - Automatic worker discovery
+ * - Priority queue support
+ * - Timeout support
+ * - Worker thread execution
+ * - NestJS dependency integration
+ *
+ * Lifecycle:
+ * 1. Discovers worker-enabled services
+ * 2. Serializes metadata for worker runtime
+ * 3. Creates WorkerPool
+ * 4. Dispatches tasks to workers
+ * 5. Handles graceful shutdown
+ *
+ * Example:
+ *
+ * ```ts
+ * await workerService.run(
+ *   'ImageService',
+ *   'resizeImage',
+ *   [500],
+ *   {
+ *     priority: 'HIGH',
+ *     timeout: 5000,
+ *   },
+ * );
+ * ```
+ */
+export declare class WorkerService implements OnModuleDestroy {
+    private readonly discovery;
+    private readonly options;
+    private pool;
+    private readonly taskOptions;
+    constructor(discovery: WorkerDiscoveryService, options: WorkerModuleOptions);
+    private initPool;
+    /**
+     * Executes a worker task.
+     *
+     * Parameters:
+     * - serviceName: target service
+     * - methodName: target method
+     * - args: serialized arguments
+     * - overrides: runtime priority/timeout overrides
+     *
+     * Priority:
+     * - HIGH
+     * - NORMAL
+     * - LOW
+     *
+     * Timeout:
+     * Automatically terminates timed-out workers.
+     *
+     * Example:
+     *
+     * ```ts
+     * await workerService.run(
+     *   'ImageService',
+     *   'generateThumbnail',
+     *   [1920, 1080],
+     *   {
+     *     priority: 'HIGH',
+     *     timeout: 3000,
+     *   },
+     * );
+     * ```
+     */
+    run<T = unknown>(serviceName: string, methodName: string, args?: unknown[], overrides?: {
+        priority?: TaskPriority;
+        timeout?: number;
+    }): Promise<T>;
+    /**
+     * Gracefully shuts down worker pool.
+     *
+     * Called automatically by NestJS
+     * during application shutdown.
+     */
+    onModuleDestroy(): Promise<void>;
+}

package/dist/core/worker.service.js

@@ -0,0 +1,133 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkerService = void 0;
+const common_1 = require("@nestjs/common");
+const worker_pool_1 = require("./worker.pool");
+const discovery_service_1 = require("../discovery/discovery.service");
+const di_serializer_1 = require("../di/di-serializer");
+/**
+ * WorkerService
+ *
+ * Main entry point for executing worker-thread tasks.
+ *
+ * Features:
+ * - Lazy worker pool initialization
+ * - Automatic worker discovery
+ * - Priority queue support
+ * - Timeout support
+ * - Worker thread execution
+ * - NestJS dependency integration
+ *
+ * Lifecycle:
+ * 1. Discovers worker-enabled services
+ * 2. Serializes metadata for worker runtime
+ * 3. Creates WorkerPool
+ * 4. Dispatches tasks to workers
+ * 5. Handles graceful shutdown
+ *
+ * Example:
+ *
+ * ```ts
+ * await workerService.run(
+ *   'ImageService',
+ *   'resizeImage',
+ *   [500],
+ *   {
+ *     priority: 'HIGH',
+ *     timeout: 5000,
+ *   },
+ * );
+ * ```
+ */
+let WorkerService = class WorkerService {
+    discovery;
+    options;
+    pool = null;
+    taskOptions = new Map();
+    constructor(discovery, options) {
+        this.discovery = discovery;
+        this.options = options;
+    }
+    initPool() {
+        if (this.pool)
+            return;
+        const tasks = this.discovery.scan();
+        for (const task of tasks) {
+            this.taskOptions.set(`${task.serviceName}.${task.methodName}`, { priority: task.priority, timeout: task.timeout });
+        }
+        const serialized = (0, di_serializer_1.serializeForWorker)(tasks);
+        this.pool = new worker_pool_1.WorkerPool(serialized, this.options.poolSize);
+    }
+    /**
+     * Executes a worker task.
+     *
+     * Parameters:
+     * - serviceName: target service
+     * - methodName: target method
+     * - args: serialized arguments
+     * - overrides: runtime priority/timeout overrides
+     *
+     * Priority:
+     * - HIGH
+     * - NORMAL
+     * - LOW
+     *
+     * Timeout:
+     * Automatically terminates timed-out workers.
+     *
+     * Example:
+     *
+     * ```ts
+     * await workerService.run(
+     *   'ImageService',
+     *   'generateThumbnail',
+     *   [1920, 1080],
+     *   {
+     *     priority: 'HIGH',
+     *     timeout: 3000,
+     *   },
+     * );
+     * ```
+     */
+    run(serviceName, methodName, args = [], overrides = {}) {
+        this.initPool();
+        const key = `${serviceName}.${methodName}`;
+        const defaults = this.taskOptions.get(key) ??
+            { priority: 'NORMAL' };
+        return this.pool.execute({
+            serviceName,
+            methodName,
+            args,
+            priority: overrides.priority ?? defaults.priority,
+            timeout: overrides.timeout ?? defaults.timeout,
+        });
+    }
+    /**
+     * Gracefully shuts down worker pool.
+     *
+     * Called automatically by NestJS
+     * during application shutdown.
+     */
+    async onModuleDestroy() {
+        await this.pool?.destroy();
+    }
+};
+exports.WorkerService = WorkerService;
+exports.WorkerService = WorkerService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)('WORKER_OPTIONS')),
+    __metadata("design:paramtypes", [discovery_service_1.WorkerDiscoveryService, Object])
+], WorkerService);
+//# sourceMappingURL=worker.service.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"worker.service.js","sourceRoot":"","sources":["../../src/core/worker.service.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAAmE;AACnE,+CAAyC;AACzC,sEAAsE;AACtE,uDAAuD;AAGvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEI,IAAM,aAAa,GAAnB,MAAM,aAAa;IAWL;IAEA;IAZX,IAAI,GAAsB,IAAI,CAAC;IACtB,WAAW,GAAG,IAAI,GAAG,EAMnC,CAAC;IAEJ,YACmB,SAAiC,EAEjC,OAA4B;QAF5B,cAAS,GAAT,SAAS,CAAwB;QAEjC,YAAO,GAAP,OAAO,CAAqB;IAE/C,CAAC;IAEO,QAAQ;QACd,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO;QAEtB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QAEpC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,WAAW,CAAC,GAAG,CAClB,GAAG,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,UAAU,EAAE,EACxC,EAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAC,CACjD,CAAC;QACJ,CAAC;QAED,MAAM,UAAU,GAAG,IAAA,kCAAkB,EAAC,KAAK,CAAC,CAAC;QAE7C,IAAI,CAAC,IAAI,GAAG,IAAI,wBAAU,CAAC,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChE,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,GAAG,CACD,WAAmB,EACnB,UAAkB,EAClB,OAAkB,EAAE,EACpB,YAA2D,EAAE;QAE7D,IAAI,CAAC,QAAQ,EAAE,CAAC;QAEhB,MAAM,GAAG,GAAG,GAAG,WAAW,IAAI,UAAU,EAAE,CAAC;QAE3C,MAAM,QAAQ,GACZ,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC;YACzB,EAAC,QAAQ,EAAE,QAAwB,EAAC,CAAC;QAEvC,OAAO,IAAI,CAAC,IAAK,CAAC,OAAO,CAAI;YAC3B,WAAW;YACX,UAAU;YACV,IAAI;YACJ,QAAQ,EAAE,SAAS,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ;YACjD,OAAO,EAAE,SAAS,CAAC,OAAO,IAAI,QAAQ,CAAC,OAAO;SAC/C,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,eAAe;QACnB,MAAM,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC;IAC7B,CAAC;CACF,CAAA;AAjGY,sCAAa;wBAAb,aAAa;IADzB,IAAA,mBAAU,GAAE;IAaR,WAAA,IAAA,eAAM,EAAC,gBAAgB,CAAC,CAAA;qCADG,0CAAsB;GAXzC,aAAa,CAiGzB"}

package/dist/decorators/worker-task.decorator.d.ts

@@ -0,0 +1,37 @@
+import 'reflect-metadata';
+export declare const WORKER_CLASS_META = "worker:class";
+export declare const WORKER_METHOD_META = "worker:method";
+export declare const WORKER_DEPS_META = "worker:deps";
+export interface WorkerTaskOptions {
+    priority?: 'HIGH' | 'NORMAL' | 'LOW';
+    timeout?: number;
+}
+/**
+ * @WorkerClass() – marks a provider as a container of worker tasks.
+ *
+ * The discovery service scans all NestJS providers for this marker,
+ * then inspects each method for @WorkerTask().
+ *
+ * Declare any injectable deps that your @WorkerTask methods need via
+ * the `deps` option. These are resolved from the live NestJS container,
+ * serialised, and reconstructed inside each worker thread.
+ *
+ * @example
+ *   @WorkerClass({ deps: [ConfigService] })
+ *   export class ImageService { ... }
+ */
+export declare function WorkerClass(options?: {
+    deps?: (abstract new (...a: unknown[]) => unknown)[];
+}): ClassDecorator;
+/**
+ * @WorkerTask() – marks a method to be offloaded to a worker thread.
+ *
+ * The method must be pure with respect to thread-crossing:
+ * its arguments and return value must be structured-clone compatible.
+ * Any NestJS deps it needs should be declared on @WorkerClass({ deps }).
+ *
+ * @example
+ *   @WorkerTask({ priority: 'HIGH', timeout: 5000 })
+ *   resizeImage(value: number): number { ... }
+ */
+export declare function WorkerTask(options?: WorkerTaskOptions): MethodDecorator;

package/dist/decorators/worker-task.decorator.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKER_DEPS_META = exports.WORKER_METHOD_META = exports.WORKER_CLASS_META = void 0;
+exports.WorkerClass = WorkerClass;
+exports.WorkerTask = WorkerTask;
+require("reflect-metadata");
+exports.WORKER_CLASS_META = 'worker:class';
+exports.WORKER_METHOD_META = 'worker:method';
+exports.WORKER_DEPS_META = 'worker:deps';
+/**
+ * @WorkerClass() – marks a provider as a container of worker tasks.
+ *
+ * The discovery service scans all NestJS providers for this marker,
+ * then inspects each method for @WorkerTask().
+ *
+ * Declare any injectable deps that your @WorkerTask methods need via
+ * the `deps` option. These are resolved from the live NestJS container,
+ * serialised, and reconstructed inside each worker thread.
+ *
+ * @example
+ *   @WorkerClass({ deps: [ConfigService] })
+ *   export class ImageService { ... }
+ */
+function WorkerClass(options = {}) {
+    return (target) => {
+        Reflect.defineMetadata(exports.WORKER_CLASS_META, true, target);
+        if (options.deps?.length) {
+            Reflect.defineMetadata(exports.WORKER_DEPS_META, options.deps, target);
+        }
+    };
+}
+/**
+ * @WorkerTask() – marks a method to be offloaded to a worker thread.
+ *
+ * The method must be pure with respect to thread-crossing:
+ * its arguments and return value must be structured-clone compatible.
+ * Any NestJS deps it needs should be declared on @WorkerClass({ deps }).
+ *
+ * @example
+ *   @WorkerTask({ priority: 'HIGH', timeout: 5000 })
+ *   resizeImage(value: number): number { ... }
+ */
+function WorkerTask(options = {}) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(exports.WORKER_METHOD_META, options, target, propertyKey);
+    };
+}
+//# sourceMappingURL=worker-task.decorator.js.map

package/dist/decorators/worker-task.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-task.decorator.js","sourceRoot":"","sources":["../../src/decorators/worker-task.decorator.ts"],"names":[],"mappings":";;;AAyBA,kCASC;AAaD,gCAIC;AAnDD,4BAA0B;AAEb,QAAA,iBAAiB,GAAG,cAAc,CAAC;AACnC,QAAA,kBAAkB,GAAG,eAAe,CAAC;AACrC,QAAA,gBAAgB,GAAG,aAAa,CAAC;AAO9C;;;;;;;;;;;;;GAaG;AACH,SAAgB,WAAW,CACzB,UAAoE,EAAE;IAEtE,OAAO,CAAC,MAAM,EAAE,EAAE;QAChB,OAAO,CAAC,cAAc,CAAC,yBAAiB,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QACxD,IAAI,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;YACzB,OAAO,CAAC,cAAc,CAAC,wBAAgB,EAAE,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACjE,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,UAAU,CAAC,UAA6B,EAAE;IACxD,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE;QAC7B,OAAO,CAAC,cAAc,CAAC,0BAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IAC3E,CAAC,CAAC;AACJ,CAAC"}

package/dist/di/di-serializer.d.ts

@@ -0,0 +1,18 @@
+import type { DiscoveredTask } from '../core/worker.interfaces';
+import type { SerializedService } from './worker-container';
+/**
+ * serializeForWorker – converts the live NestJS service graph into a
+ * structured-clone-safe SerializedService[] payload for workerData.
+ *
+ * KEY DESIGN DECISION: class source extraction instead of file paths.
+ *
+ * We cannot pass filePaths to workers because require(filePath) inside a
+ * worker thread re-executes the compiled .ts output which imports @nestjs/common
+ * at the top level — crashing the isolated worker context.
+ *
+ * Instead we extract each class's constructor and prototype methods as plain JS
+ * source strings on the main thread (where NestJS is fully loaded), then send
+ * those strings via workerData. WorkerContainer eval()s them in the worker —
+ * no require(), no NestJS imports, no crash.
+ */
+export declare function serializeForWorker(tasks: DiscoveredTask[]): SerializedService[];

package/dist/di/di-serializer.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeForWorker = serializeForWorker;
+const worker_task_decorator_1 = require("../decorators/worker-task.decorator");
+/**
+ * serializeForWorker – converts the live NestJS service graph into a
+ * structured-clone-safe SerializedService[] payload for workerData.
+ *
+ * KEY DESIGN DECISION: class source extraction instead of file paths.
+ *
+ * We cannot pass filePaths to workers because require(filePath) inside a
+ * worker thread re-executes the compiled .ts output which imports @nestjs/common
+ * at the top level — crashing the isolated worker context.
+ *
+ * Instead we extract each class's constructor and prototype methods as plain JS
+ * source strings on the main thread (where NestJS is fully loaded), then send
+ * those strings via workerData. WorkerContainer eval()s them in the worker —
+ * no require(), no NestJS imports, no crash.
+ */
+function serializeForWorker(tasks) {
+    const byService = new Map();
+    for (const task of tasks) {
+        if (!byService.has(task.serviceName)) {
+            byService.set(task.serviceName, { representative: task, methods: [] });
+        }
+        byService.get(task.serviceName).methods.push({
+            methodName: task.methodName,
+            priority: task.priority,
+            timeout: task.timeout,
+        });
+    }
+    const result = [];
+    for (const [serviceName, { representative, methods }] of byService) {
+        const { metatype, instance, deps } = representative;
+        const depTypes = Reflect.getMetadata(worker_task_decorator_1.WORKER_DEPS_META, metatype) ?? [];
+        const serializedDeps = depTypes.map((DepType, i) => {
+            const depInstance = deps[i];
+            const propertyKey = findDepPropertyKey(instance, depInstance) ?? camelCase(DepType.name);
+            return {
+                name: DepType.name,
+                classSource: extractClassSource(DepType),
+                snapshot: snapshotInstance(depInstance),
+                propertyKey,
+            };
+        });
+        result.push({
+            name: serviceName,
+            classSource: extractClassSource(metatype),
+            methods,
+            deps: serializedDeps,
+        });
+    }
+    return result;
+}
+/**
+ * Extract a plain, self-contained class source string from a constructor.
+ *
+ * In TypeScript compiled output, Function.prototype.toString() on a class
+ * returns the full class body including all methods — but WITHOUT the
+ * import statements or decorator calls at the top of the file.
+ *
+ * Example output:
+ *   "class ConfigService {
+ *      constructor() { this.config = { MULTIPLIER: '3' }; }
+ *      get(k) { return this.config[k]; }
+ *      getNumber(k) { return Number(this.config[k]); }
+ *    }"
+ *
+ * This is eval()-safe and has no NestJS dependencies.
+ */
+function extractClassSource(metatype) {
+    const src = metatype.toString();
+    // Compiled TS classes always start with "class ClassName"
+    // Strip any leading helper assignments TypeScript sometimes emits
+    const classStart = src.indexOf('class ');
+    if (classStart === -1) {
+        throw new Error(`Could not extract class source for "${metatype.name}". ` +
+            `Ensure the project is compiled with "target": "ES2022" or higher ` +
+            `so classes are emitted as native class declarations, not functions.`);
+    }
+    return src.slice(classStart);
+}
+function findDepPropertyKey(serviceInstance, depInstance) {
+    if (!serviceInstance || typeof serviceInstance !== 'object')
+        return undefined;
+    for (const [key, value] of Object.entries(serviceInstance)) {
+        if (value === depInstance)
+            return key;
+    }
+    return undefined;
+}
+function snapshotInstance(instance) {
+    if (!instance || typeof instance !== 'object')
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(instance)) {
+        if (typeof v === 'function' || typeof v === 'symbol')
+            continue;
+        try {
+            structuredClone(v);
+            out[k] = v;
+        }
+        catch { /* skip non-cloneable */ }
+    }
+    return out;
+}
+function camelCase(name) {
+    return name.charAt(0).toLowerCase() + name.slice(1);
+}
+//# sourceMappingURL=di-serializer.js.map

package/dist/di/di-serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"di-serializer.js","sourceRoot":"","sources":["../../src/di/di-serializer.ts"],"names":[],"mappings":"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"}