atomic-queues 2.2.0 → 3.0.0

package/dist/workers/entity-worker-manager.d.ts

@@ -0,0 +1,35 @@
+import { OnModuleInit, OnApplicationShutdown } from '@nestjs/common';
+import { IAtomicQueuesModuleConfig, ISerializedMessage } from '../domain';
+import { HandlerExecutor } from '../services/handler-executor';
+import { WalService } from '../wal';
+export declare class EntityWorkerManager implements OnModuleInit, OnApplicationShutdown {
+    private readonly config;
+    private readonly handlerExecutor;
+    private readonly walService?;
+    private readonly logger;
+    private readonly workers;
+    private readonly isClusterMode;
+    private readonly serverId;
+    private readonly maxTotalWorkers;
+    private readonly maxTotalQueueDepth;
+    private readonly pendingResults;
+    private onTeardownCallback;
+    constructor(config: IAtomicQueuesModuleConfig, handlerExecutor: HandlerExecutor, walService?: WalService | undefined);
+    onModuleInit(): Promise<void>;
+    setOnTeardown(callback: (entityKey: string) => void): void;
+    onApplicationShutdown(): Promise<void>;
+    private get walEnabled();
+    enqueue(entityKey: string, message: ISerializedMessage): Promise<void>;
+    enqueueAndWait<R = unknown>(entityKey: string, message: ISerializedMessage, timeout: number, signal?: AbortSignal): Promise<R>;
+    spawn(entityKey: string): boolean;
+    teardown(entityKey: string): Promise<void>;
+    hasWorker(entityKey: string): boolean;
+    listWorkers(): string[];
+    workerCount(): number;
+    totalQueueDepth(): number;
+    private spawnWorker;
+    private resolveResult;
+    private rejectResult;
+    private handleWorkerIdle;
+}
+//# sourceMappingURL=entity-worker-manager.d.ts.map

package/dist/workers/entity-worker-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-worker-manager.d.ts","sourceRoot":"","sources":["../../src/workers/entity-worker-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,YAAY,EACZ,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE1E,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAMpC,qBACa,mBAAoB,YAAW,YAAY,EAAE,qBAAqB;IAgB7C,OAAO,CAAC,QAAQ,CAAC,MAAM;IACrD,OAAO,CAAC,QAAQ,CAAC,eAAe;IACpB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAjB1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAC/D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAE5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAG3B;IAEJ,OAAO,CAAC,kBAAkB,CAA8C;gBAGvB,MAAM,EAAE,yBAAyB,EAC/D,eAAe,EAAE,eAAe,EACpB,UAAU,CAAC,EAAE,UAAU,YAAA;IAQhD,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBnC,aAAa,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAIpD,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B5C,OAAO,KAAK,UAAU,GAErB;IAEK,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB5E,cAAc,CAAC,CAAC,GAAG,OAAO,EACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,CAAC,CAAC;IA+Cb,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAM3B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUhD,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIrC,WAAW,IAAI,MAAM,EAAE;IAIvB,WAAW,IAAI,MAAM;IAIrB,eAAe,IAAI,MAAM;IAYzB,OAAO,CAAC,WAAW;IAsCnB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,gBAAgB;CAYzB"}

package/dist/workers/entity-worker-manager.js

@@ -0,0 +1,237 @@
+"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); }
+};
+var EntityWorkerManager_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityWorkerManager = void 0;
+const common_1 = require("@nestjs/common");
+const constants_1 = require("../services/constants");
+const handler_executor_1 = require("../services/handler-executor");
+const wal_1 = require("../wal");
+const utils_1 = require("../utils");
+const entity_worker_1 = require("./entity-worker");
+const DEFAULT_IDLE_TIMEOUT = 30000;
+let EntityWorkerManager = EntityWorkerManager_1 = class EntityWorkerManager {
+    constructor(config, handlerExecutor, walService) {
+        this.config = config;
+        this.handlerExecutor = handlerExecutor;
+        this.walService = walService;
+        this.logger = new common_1.Logger(EntityWorkerManager_1.name);
+        this.workers = new Map();
+        this.pendingResults = new Map();
+        this.onTeardownCallback = null;
+        this.isClusterMode = config.grpc?.enabled ?? false;
+        this.serverId = config.grpc?.serverId ?? 'local';
+        this.maxTotalWorkers = config.maxTotalWorkers ?? 10000;
+        this.maxTotalQueueDepth = config.maxTotalQueueDepth ?? 100000;
+    }
+    async onModuleInit() {
+        if (!this.walService || this.config.wal?.enabled === false)
+            return;
+        await this.walService.recover();
+        const pending = await this.walService.getPendingMessages();
+        for (const msg of pending) {
+            const entityKey = `${msg.entityType}:${msg.entityId}`;
+            let worker = this.workers.get(entityKey);
+            if (!worker)
+                worker = this.spawnWorker(entityKey);
+            worker.enqueue(msg);
+        }
+        if (pending.length > 0) {
+            this.logger.log(`WAL recovery: re-dispatched ${pending.length} pending messages`);
+        }
+        this.walService.startCleanup();
+    }
+    setOnTeardown(callback) {
+        this.onTeardownCallback = callback;
+    }
+    async onApplicationShutdown() {
+        if (this.walService) {
+            this.walService.stopCleanup();
+        }
+        const drainPromises = [];
+        for (const [, worker] of this.workers) {
+            drainPromises.push(worker.drain());
+        }
+        await Promise.all(drainPromises);
+        for (const [, worker] of this.workers) {
+            worker.destroy();
+        }
+        this.workers.clear();
+        for (const [, entry] of this.pendingResults) {
+            clearTimeout(entry.timer);
+            entry.reject(new Error('Application shutting down'));
+        }
+        this.pendingResults.clear();
+    }
+    // =========================================================================
+    // PUBLIC API
+    // =========================================================================
+    get walEnabled() {
+        return !!this.walService && this.config.wal?.enabled !== false;
+    }
+    async enqueue(entityKey, message) {
+        if (this.maxTotalWorkers > 0 &&
+            !this.workers.has(entityKey) &&
+            this.workers.size >= this.maxTotalWorkers) {
+            throw new Error('WORKER_LIMIT_EXCEEDED');
+        }
+        if (this.maxTotalQueueDepth > 0 && this.totalQueueDepth() >= this.maxTotalQueueDepth) {
+            throw new Error('QUEUE_DEPTH_EXCEEDED');
+        }
+        if (this.walEnabled) {
+            await this.walService.write(entityKey, message);
+        }
+        let worker = this.workers.get(entityKey);
+        if (!worker) {
+            worker = this.spawnWorker(entityKey);
+        }
+        worker.enqueue(message);
+    }
+    enqueueAndWait(entityKey, message, timeout, signal) {
+        return new Promise((resolve, reject) => {
+            const correlationId = (0, utils_1.fastId)();
+            const taggedMessage = { ...message, correlationId };
+            const cleanup = () => {
+                this.pendingResults.delete(correlationId);
+                clearTimeout(timer);
+            };
+            const timer = setTimeout(() => {
+                this.pendingResults.delete(correlationId);
+                reject(new Error(`Result timeout after ${timeout}ms for ${message.name} on ${entityKey}`));
+            }, timeout);
+            this.pendingResults.set(correlationId, {
+                resolve: resolve,
+                reject,
+                timer,
+            });
+            if (signal) {
+                if (signal.aborted) {
+                    cleanup();
+                    reject(new Error('Stream cancelled by client'));
+                    return;
+                }
+                signal.addEventListener('abort', () => {
+                    if (this.pendingResults.has(correlationId)) {
+                        cleanup();
+                        reject(new Error('Stream cancelled by client'));
+                    }
+                }, { once: true });
+            }
+            this.enqueue(entityKey, taggedMessage).catch((err) => {
+                this.pendingResults.delete(correlationId);
+                clearTimeout(timer);
+                reject(err);
+            });
+        });
+    }
+    spawn(entityKey) {
+        if (this.workers.has(entityKey))
+            return false;
+        this.spawnWorker(entityKey);
+        return true;
+    }
+    async teardown(entityKey) {
+        const worker = this.workers.get(entityKey);
+        if (!worker)
+            return;
+        await worker.drain();
+        worker.destroy();
+        this.workers.delete(entityKey);
+        this.logger.debug(`Worker torn down: ${entityKey}`);
+    }
+    hasWorker(entityKey) {
+        return this.workers.has(entityKey);
+    }
+    listWorkers() {
+        return Array.from(this.workers.keys());
+    }
+    workerCount() {
+        return this.workers.size;
+    }
+    totalQueueDepth() {
+        let total = 0;
+        for (const worker of this.workers.values()) {
+            total += worker.queueDepth;
+        }
+        return total;
+    }
+    // =========================================================================
+    // INTERNAL
+    // =========================================================================
+    spawnWorker(entityKey) {
+        const entityType = entityKey.split(':')[0];
+        const entityConfig = this.config.entities?.[entityType];
+        const idleTimeout = entityConfig?.workerIdleTimeout ?? DEFAULT_IDLE_TIMEOUT;
+        const maxQueueDepth = entityConfig?.workerMaxQueueDepth ?? 0;
+        const worker = new entity_worker_1.EntityWorker(entityKey, async (message, ek) => {
+            if (this.walEnabled) {
+                await this.walService.markDispatched(ek, message.id, 0);
+            }
+            return this.handlerExecutor.execute(message, ek);
+        }, (message, result) => {
+            if (this.walEnabled) {
+                this.walService.markCompleted(entityKey, message.id).catch(() => { });
+            }
+            this.resolveResult(message, result);
+        }, (message, error) => {
+            if (this.walEnabled) {
+                this.walService.markFailed(entityKey, message.id, error.message, error.stack).catch(() => { });
+            }
+            this.rejectResult(message, error);
+        }, (ek) => this.handleWorkerIdle(ek), idleTimeout, maxQueueDepth);
+        this.workers.set(entityKey, worker);
+        this.logger.debug(`Worker spawned: ${entityKey}`);
+        return worker;
+    }
+    resolveResult(message, result) {
+        if (!message.correlationId)
+            return;
+        const pending = this.pendingResults.get(message.correlationId);
+        if (pending) {
+            clearTimeout(pending.timer);
+            this.pendingResults.delete(message.correlationId);
+            pending.resolve(result);
+        }
+    }
+    rejectResult(message, error) {
+        if (!message.correlationId)
+            return;
+        const pending = this.pendingResults.get(message.correlationId);
+        if (pending) {
+            clearTimeout(pending.timer);
+            this.pendingResults.delete(message.correlationId);
+            pending.reject(error);
+        }
+    }
+    handleWorkerIdle(entityKey) {
+        this.logger.debug(`Worker idle: ${entityKey}`);
+        const worker = this.workers.get(entityKey);
+        if (worker && !worker.isProcessing && worker.queueDepth === 0) {
+            worker.destroy();
+            this.workers.delete(entityKey);
+            if (this.onTeardownCallback) {
+                this.onTeardownCallback(entityKey);
+            }
+        }
+    }
+};
+exports.EntityWorkerManager = EntityWorkerManager;
+exports.EntityWorkerManager = EntityWorkerManager = EntityWorkerManager_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(constants_1.ATOMIC_QUEUES_CONFIG)),
+    __param(2, (0, common_1.Optional)()),
+    __metadata("design:paramtypes", [Object, handler_executor_1.HandlerExecutor,
+        wal_1.WalService])
+], EntityWorkerManager);
+//# sourceMappingURL=entity-worker-manager.js.map

package/dist/workers/entity-worker-manager.js.map

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

package/dist/workers/entity-worker.d.ts

@@ -0,0 +1,54 @@
+import { ISerializedMessage } from '../domain';
+/**
+ * A virtual actor — one per entity:entityId.
+ *
+ * Owns a FIFO message queue and processes messages sequentially
+ * on the event loop via the provided processor callback. When idle
+ * for longer than the configured timeout, it signals for teardown.
+ */
+export declare class EntityWorker {
+    readonly entityKey: string;
+    private readonly processor;
+    private readonly onResult;
+    private readonly onError;
+    private readonly onIdle;
+    private readonly idleTimeoutMs;
+    private readonly maxQueueDepth;
+    private readonly logger;
+    private readonly queue;
+    private processing;
+    private idleTimer;
+    private _lastActiveAt;
+    private _totalProcessed;
+    private _totalFailed;
+    constructor(entityKey: string, processor: (message: ISerializedMessage, entityKey: string) => Promise<unknown>, onResult: (message: ISerializedMessage, result: unknown) => void, onError: (message: ISerializedMessage, error: Error) => void, onIdle: (entityKey: string) => void, idleTimeoutMs: number, maxQueueDepth?: number);
+    /**
+     * Enqueue a message. If not currently processing, starts immediately.
+     */
+    enqueue(message: ISerializedMessage): void;
+    /**
+     * Current queue depth (pending messages not yet dispatched).
+     */
+    get queueDepth(): number;
+    /**
+     * Whether the worker is currently executing a handler.
+     */
+    get isProcessing(): boolean;
+    get lastActiveAt(): number;
+    get totalProcessed(): number;
+    get totalFailed(): number;
+    /**
+     * Drain: finish current handler, reject remaining queued messages.
+     * Returns when the current handler (if any) completes.
+     */
+    drain(): Promise<void>;
+    /**
+     * Destroy: clear timers. Call after drain.
+     */
+    destroy(): void;
+    private tryProcess;
+    private executeHandler;
+    private startIdleTimer;
+    private clearIdleTimer;
+}
+//# sourceMappingURL=entity-worker.d.ts.map

package/dist/workers/entity-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-worker.d.ts","sourceRoot":"","sources":["../../src/workers/entity-worker.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C;;;;;;GAMG;AACH,qBAAa,YAAY;aAUL,SAAS,EAAE,MAAM;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAI1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAlBhC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgD;IACvE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4B;IAClD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,aAAa,CAAc;IACnC,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,YAAY,CAAK;gBAGP,SAAS,EAAE,MAAM,EAChB,SAAS,EAAE,CAC1B,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,MAAM,KACd,OAAO,CAAC,OAAO,CAAC,EACJ,QAAQ,EAAE,CAAC,OAAO,EAAE,kBAAkB,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,EAChE,OAAO,EAAE,CAAC,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,EAC5D,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,EACnC,aAAa,EAAE,MAAM,EACrB,aAAa,GAAE,MAAU;IAG5C;;OAEG;IACH,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAY1C;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB5B;;OAEG;IACH,OAAO,IAAI,IAAI;IAQf,OAAO,CAAC,UAAU;YAeJ,cAAc;IAgB5B,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,cAAc;CAMvB"}

package/dist/workers/entity-worker.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityWorker = void 0;
+const common_1 = require("@nestjs/common");
+/**
+ * A virtual actor — one per entity:entityId.
+ *
+ * Owns a FIFO message queue and processes messages sequentially
+ * on the event loop via the provided processor callback. When idle
+ * for longer than the configured timeout, it signals for teardown.
+ */
+class EntityWorker {
+    constructor(entityKey, processor, onResult, onError, onIdle, idleTimeoutMs, maxQueueDepth = 0) {
+        this.entityKey = entityKey;
+        this.processor = processor;
+        this.onResult = onResult;
+        this.onError = onError;
+        this.onIdle = onIdle;
+        this.idleTimeoutMs = idleTimeoutMs;
+        this.maxQueueDepth = maxQueueDepth;
+        this.logger = new common_1.Logger(`EntityWorker:${this.entityKey}`);
+        this.queue = [];
+        this.processing = false;
+        this.idleTimer = null;
+        this._lastActiveAt = Date.now();
+        this._totalProcessed = 0;
+        this._totalFailed = 0;
+    }
+    /**
+     * Enqueue a message. If not currently processing, starts immediately.
+     */
+    enqueue(message) {
+        if (this.maxQueueDepth > 0 && this.queue.length >= this.maxQueueDepth) {
+            throw new Error(`Backpressure: ${this.entityKey} queue depth ${this.queue.length} >= ${this.maxQueueDepth}`);
+        }
+        this.queue.push(message);
+        this.clearIdleTimer();
+        this._lastActiveAt = Date.now();
+        this.tryProcess();
+    }
+    /**
+     * Current queue depth (pending messages not yet dispatched).
+     */
+    get queueDepth() {
+        return this.queue.length;
+    }
+    /**
+     * Whether the worker is currently executing a handler.
+     */
+    get isProcessing() {
+        return this.processing;
+    }
+    get lastActiveAt() {
+        return this._lastActiveAt;
+    }
+    get totalProcessed() {
+        return this._totalProcessed;
+    }
+    get totalFailed() {
+        return this._totalFailed;
+    }
+    /**
+     * Drain: finish current handler, reject remaining queued messages.
+     * Returns when the current handler (if any) completes.
+     */
+    async drain() {
+        this.clearIdleTimer();
+        // Clear pending queue
+        const pending = this.queue.splice(0);
+        for (const msg of pending) {
+            this.onError(msg, new Error('Worker draining'));
+        }
+        // Wait for current handler to finish
+        if (this.processing) {
+            await new Promise((resolve) => {
+                const check = setInterval(() => {
+                    if (!this.processing) {
+                        clearInterval(check);
+                        resolve();
+                    }
+                }, 10);
+            });
+        }
+    }
+    /**
+     * Destroy: clear timers. Call after drain.
+     */
+    destroy() {
+        this.clearIdleTimer();
+    }
+    // =========================================================================
+    // INTERNAL
+    // =========================================================================
+    tryProcess() {
+        if (this.processing)
+            return;
+        if (this.queue.length === 0) {
+            this.startIdleTimer();
+            return;
+        }
+        const message = this.queue.shift();
+        this.processing = true;
+        this._lastActiveAt = Date.now();
+        // Execute on the event loop — async, yields at await points
+        this.executeHandler(message);
+    }
+    async executeHandler(message) {
+        try {
+            const result = await this.processor(message, this.entityKey);
+            this._totalProcessed++;
+            this.onResult(message, result);
+        }
+        catch (err) {
+            this._totalFailed++;
+            this.onError(message, err);
+        }
+        finally {
+            this.processing = false;
+            this._lastActiveAt = Date.now();
+            // Process next message (sequential guarantee)
+            this.tryProcess();
+        }
+    }
+    startIdleTimer() {
+        this.clearIdleTimer();
+        if (this.idleTimeoutMs <= 0)
+            return;
+        this.idleTimer = setTimeout(() => {
+            if (!this.processing && this.queue.length === 0) {
+                this.onIdle(this.entityKey);
+            }
+        }, this.idleTimeoutMs);
+    }
+    clearIdleTimer() {
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+    }
+}
+exports.EntityWorker = EntityWorker;
+//# sourceMappingURL=entity-worker.js.map

package/dist/workers/entity-worker.js.map

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

package/dist/workers/index.d.ts

@@ -0,0 +1,4 @@
+export * from './consistent-hash';
+export * from './entity-worker';
+export * from './entity-worker-manager';
+//# sourceMappingURL=index.d.ts.map

package/dist/workers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/workers/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC"}

package/dist/workers/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./consistent-hash"), exports);
+__exportStar(require("./entity-worker"), exports);
+__exportStar(require("./entity-worker-manager"), exports);
+//# sourceMappingURL=index.js.map

package/dist/workers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/workers/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oDAAkC;AAClC,kDAAgC;AAChC,0DAAwC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "atomic-queues",
-  "version": "2.2.0",
-  "description": "Distributed virtual actor runtime for Node.js — sequential per entity, parallel across entities, zero contention",
+  "version": "3.0.0",
+  "description": "Per-entity sequential processing for Node.js — Worker Threads, gRPC cluster, strictly-once delivery",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
@@ -30,7 +30,7 @@
     "pack": "npm run build && npm run copy-package && cd dist && npm pack --ignore-scripts && npm run print:local:instructions",
     "test": "jest --testPathIgnorePatterns integration",
     "test:watch": "jest --watch --testPathIgnorePatterns integration",
-    "test:integration": "jest --testPathPattern integration",
+    "test:integration": "jest --testPathPattern integration --runInBand",
     "lint": "eslint src/**/*.ts",
     "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
     "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\""
@@ -43,7 +43,9 @@
     "virtual-actor",
     "actor-model",
     "distributed",
-    "cqrs"
+    "cqrs",
+    "worker-threads",
+    "grpc"
   ],
   "author": "",
   "license": "MIT",
@@ -63,12 +65,22 @@
     },
     "zod-to-json-schema": {
       "optional": true
+    },
+    "@grpc/grpc-js": {
+      "optional": true
+    },
+    "@grpc/proto-loader": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@grpc/grpc-js": "^1.14.3",
+    "@grpc/proto-loader": "^0.8.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/core": "^11.1.19",
     "@nestjs/cqrs": "^11.0.3",
+    "@nestjs/platform-express": "^11.1.19",
+    "@nestjs/testing": "^11.1.19",
     "@types/jest": "^29.5.0",
     "@types/node": "^25.6.0",
     "@types/uuid": "^10.0.0",
@@ -83,6 +95,7 @@
     "rxjs": "^7.8.2",
     "shx": "^0.4.0",
     "ts-jest": "^29.4.9",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "uuid": "^9.0.1"
   },

package/dist/decorators/actor.decorators.d.ts

@@ -1,4 +0,0 @@
-import { ActorOptions } from './interfaces';
-export declare function Actor(entityType: string, options?: Partial<Omit<ActorOptions, 'entityType'>>): ClassDecorator;
-export declare function On(messageClass: Function): MethodDecorator;
-//# sourceMappingURL=actor.decorators.d.ts.map

package/dist/decorators/actor.decorators.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"actor.decorators.d.ts","sourceRoot":"","sources":["../../src/decorators/actor.decorators.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAwB,MAAM,cAAc,CAAC;AAElE,wBAAgB,KAAK,CACnB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC,GAClD,cAAc,CAYhB;AAED,wBAAgB,EAAE,CAAC,YAAY,EAAE,QAAQ,GAAG,eAAe,CAkB1D"}

package/dist/decorators/actor.decorators.js

@@ -1,32 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Actor = Actor;
-exports.On = On;
-const constants_1 = require("./constants");
-function Actor(entityType, options) {
-    return (target) => {
-        const metadata = {
-            entityType,
-            defaultEntityId: options?.defaultEntityId,
-        };
-        Reflect.defineMetadata(constants_1.ACTOR_METADATA, metadata, target);
-        if (!Reflect.hasMetadata('injectable', target)) {
-            Reflect.defineMetadata('injectable', true, target);
-        }
-    };
-}
-function On(messageClass) {
-    return (target, propertyKey, descriptor) => {
-        const methodName = String(propertyKey);
-        const metadata = {
-            messageClass,
-            methodName,
-        };
-        Reflect.defineMetadata(constants_1.ACTOR_HANDLER_METADATA, metadata, target, propertyKey);
-        const existingHandlers = Reflect.getMetadata(constants_1.ACTOR_HANDLERS_METADATA, target.constructor) || [];
-        existingHandlers.push(metadata);
-        Reflect.defineMetadata(constants_1.ACTOR_HANDLERS_METADATA, existingHandlers, target.constructor);
-        return descriptor;
-    };
-}
-//# sourceMappingURL=actor.decorators.js.map

package/dist/decorators/actor.decorators.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"actor.decorators.js","sourceRoot":"","sources":["../../src/decorators/actor.decorators.ts"],"names":[],"mappings":";;AAGA,sBAeC;AAED,gBAkBC;AAtCD,2CAA8F;AAG9F,SAAgB,KAAK,CACnB,UAAkB,EAClB,OAAmD;IAEnD,OAAO,CAAC,MAAgB,EAAE,EAAE;QAC1B,MAAM,QAAQ,GAAiB;YAC7B,UAAU;YACV,eAAe,EAAE,OAAO,EAAE,eAAe;SAC1C,CAAC;QACF,OAAO,CAAC,cAAc,CAAC,0BAAc,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;QAEzD,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,YAAY,EAAE,MAAM,CAAC,EAAE,CAAC;YAC/C,OAAO,CAAC,cAAc,CAAC,YAAY,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QACrD,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,SAAgB,EAAE,CAAC,YAAsB;IACvC,OAAO,CAAC,MAAc,EAAE,WAA4B,EAAE,UAA8B,EAAE,EAAE;QACtF,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;QAEvC,MAAM,QAAQ,GAAyB;YACrC,YAAY;YACZ,UAAU;SACX,CAAC;QAEF,OAAO,CAAC,cAAc,CAAC,kCAAsB,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;QAE9E,MAAM,gBAAgB,GACpB,OAAO,CAAC,WAAW,CAAC,mCAAuB,EAAE,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;QACzE,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAChC,OAAO,CAAC,cAAc,CAAC,mCAAuB,EAAE,gBAAgB,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;QAEtF,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC"}