atomic-queues 1.5.2 → 1.6.0

package/README.md

@@ -27,11 +27,10 @@ Distributed locks (Redlock, advisory locks, optimistic locking) all share the sa
 |---|---|---|
 | **Architecture** | Distributed mutex (quorum-based) | Per-entity queue (sequential) |
 | **Under contention** | Degrades — retry storms, backoff delays | **Constant** — jobs queue up, execute instantly |
-| **Per-entity throughput** | ~20-50 ops/s (heavy contention) | **~200-300 ops/s** (queue-bound, no contention) |
 | **Failure mode** | Silent double-execution (clock drift) | Job stuck in queue (visible, retryable) |
 | **Split-brain risk** | Yes (timing assumptions) | **Impossible** (serial queue) |
-| **Warm-path overhead** | 5-7ms per op (acquire + release) | **0ms** (in-memory hot cache) |
-| **Cold-start** | None | ~2-3ms one-time per entity |
+| **Warm-path overhead** | Acquire + release per op | **0 Redis calls** (in-memory hot cache) |
+| **Cold-start** | None | One-time per entity |
 | **Multi-pod scaling** | Contention increases with pods | **Throughput increases with pods** |
 
 ---
@@ -105,17 +104,12 @@ atomic-queues routes operations through per-entity queues. Same entity → same
 ## Installation
 
 ```bash
-# npm
-npm install atomic-queues bullmq ioredis
-
-# pnpm
-pnpm add atomic-queues bullmq ioredis
-
-# yarn
-yarn add atomic-queues bullmq ioredis
+npm install atomic-queues
 ```
 
-**Peer dependencies:** NestJS 10+, `@nestjs/cqrs` (optional — for auto-routing commands/queries)
+BullMQ, ioredis, and `@nestjs/bullmq` are bundled — no extra installs needed.
+
+**Peer dependencies** (provided by your NestJS app): `@nestjs/common` 10+, `@nestjs/core` 10+, `reflect-metadata`, `rxjs` 7+. Optional: `@nestjs/cqrs` (for auto-routing commands/queries).
 
 ---
 
@@ -150,6 +144,28 @@ export class AppModule {}
 
 > **Tip:** The `entities` config is optional. Without it, default naming applies: `{keyPrefix}:{entityType}:{entityId}:queue`.
 
+<details>
+<summary><strong>Async configuration (ConfigService)</strong></summary>
+
+```typescript
+AtomicQueuesModule.forRootAsync({
+  imports: [ConfigModule],
+  useFactory: (config: ConfigService) => ({
+    redis: { url: config.get('REDIS_URL') },
+    keyPrefix: 'myapp',
+    entities: {
+      account: {
+        queueName: (id) => `account-${id}-queue`,
+        workerName: (id) => `account-${id}-worker`,
+      },
+    },
+  }),
+  inject: [ConfigService],
+}),
+```
+
+</details>
+
 ### 2. Define Commands
 
 ```typescript
@@ -222,18 +238,34 @@ export class AccountService {
 
 ## Commands & Decorators
 
-### `@QueueEntity(entityType)`
+### `@QueueEntity(entityType, entityIdProperty?)`
 
-Marks a command/query class for queue routing.
+Marks a command/query class for queue routing. The optional second argument specifies which property holds the entity ID — this is the simplest approach when you don't want to decorate individual properties.
 
 ```typescript
+// Option 1: Explicit property name (no @QueueEntityId needed)
+@QueueEntity('account', 'accountId')
+export class TransferCommand {
+  constructor(
+    public readonly accountId: string,
+    public readonly toAccountId: string,
+    public readonly amount: number,
+  ) {}
+}
+
+// Option 2: Rely on module-level defaultEntityId from entities config
 @QueueEntity('account')
-export class TransferCommand { ... }
+export class DepositCommand {
+  constructor(
+    public readonly accountId: string,  // Matched by entities.account.defaultEntityId
+    public readonly amount: number,
+  ) {}
+}
 ```
 
 ### `@QueueEntityId()`
 
-Marks the property that contains the entity ID. One per class.
+Marks the property that contains the entity ID. One per class. Use this when you need per-command control over which property is the entity ID, or when you can't use the two-argument `@QueueEntity` shorthand.
 
 ```typescript
 @QueueEntity('account')
@@ -246,6 +278,8 @@ export class TransferCommand {
 }
 ```
 
+> **Entity ID resolution order:** `@QueueEntityId()` decorator > `@QueueEntity('type', 'prop')` second argument > `@WorkerProcessor({ defaultEntityId })` > `entities[type].defaultEntityId` in module config.
+
 ### `@WorkerProcessor(options)`
 
 Optional. Define a processor class for custom job handling on top of CQRS auto-routing.
@@ -302,7 +336,12 @@ AtomicQueuesModule.forRoot({
       workerName: (id) => `account-${id}-worker`,
       maxWorkersPerEntity: 1,
       idleTimeoutSeconds: 15,
+
+      // Fallback property name for entity ID extraction.
+      // Used when a command has no @QueueEntityId() decorator
+      // and no second argument to @QueueEntity().
       defaultEntityId: 'accountId',
+
       workerConfig: {          // Override workerDefaults per entity
         concurrency: 1,
         lockDuration: 60000,
@@ -345,7 +384,7 @@ Workers in atomic-queues have a fully automated lifecycle, distributed across al
                      └──────────────┘
 ```
 
-### Hot Cache (v1.5.0+)
+### Hot Cache
 
 After a worker is confirmed alive, subsequent job arrivals for that entity hit an **in-memory cache** — zero Redis calls on the warm path. This eliminates the per-job Redis overhead that plagues lock-based approaches.
 
@@ -355,9 +394,9 @@ After a worker is confirmed alive, subsequent job arrivals for that entity hit a
 | **Warm** (cache miss) | 1 (`EXISTS`) | First time seeing entity |
 | **Cold** (no worker) | 1 (`SET NX`) | Worker needs creation |
 
-### SpawnQueueService (v1.4.2+)
+### SpawnQueueService
 
-For multi-pod deployments, the `SpawnQueueService` distributes worker creation across all pods via a shared BullMQ spawn queue. In v1.5.0, the **direct local spawn** path bypasses this queue entirely — the pod that first sees a job for a new entity claims it with an atomic `SET NX` and spawns the worker locally, saving hundreds of milliseconds.
+For multi-pod deployments, the `SpawnQueueService` distributes worker creation across all pods via a shared BullMQ spawn queue. The **direct local spawn** path bypasses this queue entirely — the pod that first sees a job for a new entity claims it with an atomic `SET NX` and spawns the worker locally.
 
 ---
 
@@ -526,21 +565,6 @@ export class AccountProcessor {
 
 ## Performance
 
-### Throughput (measured — not estimated)
-
-Tested on a 5-pod Kubernetes cluster (OrbStack), 20 concurrent entities, 12,300 orders:
-
-| Metric | Result |
-|---|---|
-| **Phase 1** — 10,000 orders (50 waves × 200 concurrent) | 167 orders/sec |
-| **Phase 2** — 1,000 orders (workers still draining) | 140 orders/sec |
-| **Phase 4** — 1,000 orders (cold start from zero workers) | 176 orders/sec |
-| **Total deductions processed** | 104,004 |
-| **Stock drift** | **0** (all 20 entities) |
-| **Pod distribution** | 5/5 pods actively creating workers |
-| **Worker creates** | 120 |
-| **Idle closures** | 180 |
-
 ### Why it's fast
 
 1. **Zero contention** — no locks, no retries, no backoff. Jobs queue and execute.
@@ -553,7 +577,7 @@ Tested on a 5-pod Kubernetes cluster (OrbStack), 20 concurrent entities, 12,300
 
 | Use case | Recommendation |
 |---|---|
-| High-throughput entity operations (payments, inventory, game state) | **atomic-queues** |
+| Per-entity operations that must be serialized (payments, inventory, game state) | **atomic-queues** |
 | Rare, low-frequency mutual exclusion (config updates, migrations) | Redlock / advisory locks |
 | Exactly-once semantics with audit trail | **atomic-queues** (BullMQ job IDs) |
 | Sub-millisecond synchronous response required | Redlock (synchronous acquire) |

package/dist/decorators/constants.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Metadata keys for decorators
+ */
+export declare const ATOMIC_PROCESSOR_METADATA = "atomic:processor";
+export declare const ENTITY_TYPE_METADATA = "atomic:entity-type";
+export declare const ENTITY_ID_METADATA = "atomic:entity-id";
+export declare const JOB_TYPE_METADATA = "atomic:job-type";
+export declare const WORKER_PROCESSOR_METADATA = "atomic:worker-processor";
+export declare const JOB_HANDLER_METADATA = "atomic:job-handler";
+export declare const ENTITY_SCALER_METADATA = "atomic:entity-scaler";
+export declare const GET_ACTIVE_ENTITIES_METADATA = "atomic:get-active-entities";
+export declare const GET_DESIRED_WORKER_COUNT_METADATA = "atomic:get-desired-worker-count";
+export declare const ON_SPAWN_WORKER_METADATA = "atomic:on-spawn-worker";
+export declare const ON_TERMINATE_WORKER_METADATA = "atomic:on-terminate-worker";
+export declare const JOB_COMMAND_METADATA = "atomic:job-command";
+export declare const JOB_QUERY_METADATA = "atomic:job-query";
+//# sourceMappingURL=constants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/decorators/constants.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,eAAO,MAAM,yBAAyB,qBAAqB,CAAC;AAC5D,eAAO,MAAM,oBAAoB,uBAAuB,CAAC;AACzD,eAAO,MAAM,kBAAkB,qBAAqB,CAAC;AACrD,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AACnD,eAAO,MAAM,yBAAyB,4BAA4B,CAAC;AACnE,eAAO,MAAM,oBAAoB,uBAAuB,CAAC;AACzD,eAAO,MAAM,sBAAsB,yBAAyB,CAAC;AAC7D,eAAO,MAAM,4BAA4B,+BAA+B,CAAC;AACzE,eAAO,MAAM,iCAAiC,oCAAoC,CAAC;AACnF,eAAO,MAAM,wBAAwB,2BAA2B,CAAC;AACjE,eAAO,MAAM,4BAA4B,+BAA+B,CAAC;AACzE,eAAO,MAAM,oBAAoB,uBAAuB,CAAC;AACzD,eAAO,MAAM,kBAAkB,qBAAqB,CAAC"}

package/dist/decorators/constants.js

@@ -0,0 +1,23 @@
+"use strict";
+// =============================================================================
+// METADATA KEYS
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JOB_QUERY_METADATA = exports.JOB_COMMAND_METADATA = exports.ON_TERMINATE_WORKER_METADATA = exports.ON_SPAWN_WORKER_METADATA = exports.GET_DESIRED_WORKER_COUNT_METADATA = exports.GET_ACTIVE_ENTITIES_METADATA = exports.ENTITY_SCALER_METADATA = exports.JOB_HANDLER_METADATA = exports.WORKER_PROCESSOR_METADATA = exports.JOB_TYPE_METADATA = exports.ENTITY_ID_METADATA = exports.ENTITY_TYPE_METADATA = exports.ATOMIC_PROCESSOR_METADATA = void 0;
+/**
+ * Metadata keys for decorators
+ */
+exports.ATOMIC_PROCESSOR_METADATA = 'atomic:processor';
+exports.ENTITY_TYPE_METADATA = 'atomic:entity-type';
+exports.ENTITY_ID_METADATA = 'atomic:entity-id';
+exports.JOB_TYPE_METADATA = 'atomic:job-type';
+exports.WORKER_PROCESSOR_METADATA = 'atomic:worker-processor';
+exports.JOB_HANDLER_METADATA = 'atomic:job-handler';
+exports.ENTITY_SCALER_METADATA = 'atomic:entity-scaler';
+exports.GET_ACTIVE_ENTITIES_METADATA = 'atomic:get-active-entities';
+exports.GET_DESIRED_WORKER_COUNT_METADATA = 'atomic:get-desired-worker-count';
+exports.ON_SPAWN_WORKER_METADATA = 'atomic:on-spawn-worker';
+exports.ON_TERMINATE_WORKER_METADATA = 'atomic:on-terminate-worker';
+exports.JOB_COMMAND_METADATA = 'atomic:job-command';
+exports.JOB_QUERY_METADATA = 'atomic:job-query';
+//# sourceMappingURL=constants.js.map

package/dist/decorators/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/decorators/constants.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,gBAAgB;AAChB,gFAAgF;;;AAEhF;;GAEG;AACU,QAAA,yBAAyB,GAAG,kBAAkB,CAAC;AAC/C,QAAA,oBAAoB,GAAG,oBAAoB,CAAC;AAC5C,QAAA,kBAAkB,GAAG,kBAAkB,CAAC;AACxC,QAAA,iBAAiB,GAAG,iBAAiB,CAAC;AACtC,QAAA,yBAAyB,GAAG,yBAAyB,CAAC;AACtD,QAAA,oBAAoB,GAAG,oBAAoB,CAAC;AAC5C,QAAA,sBAAsB,GAAG,sBAAsB,CAAC;AAChD,QAAA,4BAA4B,GAAG,4BAA4B,CAAC;AAC5D,QAAA,iCAAiC,GAAG,iCAAiC,CAAC;AACtE,QAAA,wBAAwB,GAAG,wBAAwB,CAAC;AACpD,QAAA,4BAA4B,GAAG,4BAA4B,CAAC;AAC5D,QAAA,oBAAoB,GAAG,oBAAoB,CAAC;AAC5C,QAAA,kBAAkB,GAAG,kBAAkB,CAAC"}

package/dist/decorators/entity.decorators.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @EntityType decorator
+ *
+ * Marks a command/query class with its entity type for automatic routing.
+ * When present, queueBus.enqueue(cmd) can auto-route without forEntity().
+ *
+ * @example
+ * ```typescript
+ * @EntityType('account')
+ * export class WithdrawCommand {
+ *   @QueueEntityId()
+ *   public readonly accountId: string;
+ *   public readonly amount: number;
+ * }
+ *
+ * // Can now use direct enqueue:
+ * await queueBus.enqueue(new WithdrawCommand(accountId, amount));
+ * ```
+ */
+export declare function EntityType(entityType: string): ClassDecorator;
+/**
+ * @QueueEntityId decorator
+ *
+ * Marks a property OR constructor parameter as the entity ID for queue routing.
+ * Only ONE @QueueEntityId() allowed per class (enforced at decoration time).
+ * Overrides module-level defaultEntityId configuration.
+ *
+ * @example Property decorator:
+ * ```typescript
+ * export class TransferCommand {
+ *   @QueueEntityId()
+ *   public readonly sourceAccountId: string;
+ *   public readonly amount: number;
+ * }
+ * ```
+ *
+ * @example Parameter decorator (recommended):
+ * ```typescript
+ * @QueueEntity('account')
+ * export class TransferCommand {
+ *   constructor(
+ *     @QueueEntityId() public readonly sourceAccountId: string,
+ *     public readonly amount: number,
+ *   ) {}
+ * }
+ * ```
+ */
+export declare function QueueEntityId(): PropertyDecorator & ParameterDecorator;
+/**
+ * @deprecated Use @QueueEntityId() instead. This alias is provided for backwards compatibility.
+ */
+export declare const EntityId: typeof QueueEntityId;
+/**
+ * @QueueEntity decorator
+ *
+ * Single decorator that combines @EntityType and @QueueEntityId into one.
+ * This is the recommended way to mark commands/queries for queue routing.
+ *
+ * @param entityType - The entity type for routing (e.g., 'table', 'account')
+ * @param entityIdProperty - Optional property name containing the entity ID.
+ *                           If omitted, uses module-level defaultEntityId from entities config.
+ *
+ * @example
+ * // With explicit property name:
+ * @QueueEntity('table', 'tableId')
+ * export class MakeBetCommand {
+ *   constructor(
+ *     public readonly tableId: string,  // <- unchanged!
+ *     public readonly amount: number,
+ *   ) {}
+ * }
+ *
+ * @example
+ * // Using module default (entities config has defaultEntityId: 'tableId'):
+ * @QueueEntity('table')
+ * export class DealCommand {
+ *   constructor(
+ *     public readonly tableId: string,
+ *     public readonly card: string,
+ *   ) {}
+ * }
+ *
+ * @example
+ * // Then just enqueue directly:
+ * await queueBus.enqueue(new MakeBetCommand(tableId, 100));
+ */
+export declare function QueueEntity(entityType: string, entityIdProperty?: string): ClassDecorator;
+//# sourceMappingURL=entity.decorators.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entity.decorators.d.ts","sourceRoot":"","sources":["../../src/decorators/entity.decorators.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,CAI7D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,IAAI,iBAAiB,GAAG,kBAAkB,CAqDtE;AAED;;GAEG;AACH,eAAO,MAAM,QAAQ,sBAAgB,CAAC;AAMtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,cAAc,CAUzF"}

package/dist/decorators/entity.decorators.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityId = void 0;
+exports.EntityType = EntityType;
+exports.QueueEntityId = QueueEntityId;
+exports.QueueEntity = QueueEntity;
+const constants_1 = require("./constants");
+const registry_1 = require("./registry");
+const utils_1 = require("./utils");
+/**
+ * @EntityType decorator
+ *
+ * Marks a command/query class with its entity type for automatic routing.
+ * When present, queueBus.enqueue(cmd) can auto-route without forEntity().
+ *
+ * @example
+ * ```typescript
+ * @EntityType('account')
+ * export class WithdrawCommand {
+ *   @QueueEntityId()
+ *   public readonly accountId: string;
+ *   public readonly amount: number;
+ * }
+ *
+ * // Can now use direct enqueue:
+ * await queueBus.enqueue(new WithdrawCommand(accountId, amount));
+ * ```
+ */
+function EntityType(entityType) {
+    return (target) => {
+        Reflect.defineMetadata(constants_1.ENTITY_TYPE_METADATA, entityType, target);
+    };
+}
+/**
+ * @QueueEntityId decorator
+ *
+ * Marks a property OR constructor parameter as the entity ID for queue routing.
+ * Only ONE @QueueEntityId() allowed per class (enforced at decoration time).
+ * Overrides module-level defaultEntityId configuration.
+ *
+ * @example Property decorator:
+ * ```typescript
+ * export class TransferCommand {
+ *   @QueueEntityId()
+ *   public readonly sourceAccountId: string;
+ *   public readonly amount: number;
+ * }
+ * ```
+ *
+ * @example Parameter decorator (recommended):
+ * ```typescript
+ * @QueueEntity('account')
+ * export class TransferCommand {
+ *   constructor(
+ *     @QueueEntityId() public readonly sourceAccountId: string,
+ *     public readonly amount: number,
+ *   ) {}
+ * }
+ * ```
+ */
+function QueueEntityId() {
+    return (target, propertyKey, parameterIndex) => {
+        // Parameter decorator case (on constructor param)
+        if (typeof parameterIndex === 'number') {
+            const constructor = target;
+            const className = constructor.name;
+            // Extract parameter name from constructor
+            const paramName = (0, utils_1.getConstructorParamName)(constructor, parameterIndex);
+            if (!paramName) {
+                throw new Error(`Cannot determine parameter name at index ${parameterIndex} in ${className}. ` +
+                    `Ensure you're using 'public readonly paramName' syntax.`);
+            }
+            // Check for duplicate
+            const existing = registry_1.queueEntityIdRegistry.get(constructor);
+            if (existing) {
+                throw new Error(`Multiple @QueueEntityId() decorators on ${className}. ` +
+                    `Found on '${existing}' and '${paramName}'. ` +
+                    `Only one parameter/property can be the entity ID.`);
+            }
+            registry_1.queueEntityIdRegistry.set(constructor, paramName);
+            Reflect.defineMetadata(constants_1.ENTITY_ID_METADATA, paramName, constructor);
+            return;
+        }
+        // Property decorator case (on class property)
+        const constructor = target.constructor;
+        const className = constructor.name;
+        const propName = String(propertyKey);
+        // Check for duplicate @QueueEntityId on same class
+        const existing = registry_1.queueEntityIdRegistry.get(constructor);
+        if (existing) {
+            throw new Error(`Multiple @QueueEntityId() decorators on ${className}. ` +
+                `Found on '${existing}' and '${propName}'. ` +
+                `Only one property can be the entity ID.`);
+        }
+        registry_1.queueEntityIdRegistry.set(constructor, propName);
+        Reflect.defineMetadata(constants_1.ENTITY_ID_METADATA, propName, constructor);
+    };
+}
+/**
+ * @deprecated Use @QueueEntityId() instead. This alias is provided for backwards compatibility.
+ */
+exports.EntityId = QueueEntityId;
+// =============================================================================
+// NEW COMBINED DECORATOR - Less Invasive
+// =============================================================================
+/**
+ * @QueueEntity decorator
+ *
+ * Single decorator that combines @EntityType and @QueueEntityId into one.
+ * This is the recommended way to mark commands/queries for queue routing.
+ *
+ * @param entityType - The entity type for routing (e.g., 'table', 'account')
+ * @param entityIdProperty - Optional property name containing the entity ID.
+ *                           If omitted, uses module-level defaultEntityId from entities config.
+ *
+ * @example
+ * // With explicit property name:
+ * @QueueEntity('table', 'tableId')
+ * export class MakeBetCommand {
+ *   constructor(
+ *     public readonly tableId: string,  // <- unchanged!
+ *     public readonly amount: number,
+ *   ) {}
+ * }
+ *
+ * @example
+ * // Using module default (entities config has defaultEntityId: 'tableId'):
+ * @QueueEntity('table')
+ * export class DealCommand {
+ *   constructor(
+ *     public readonly tableId: string,
+ *     public readonly card: string,
+ *   ) {}
+ * }
+ *
+ * @example
+ * // Then just enqueue directly:
+ * await queueBus.enqueue(new MakeBetCommand(tableId, 100));
+ */
+function QueueEntity(entityType, entityIdProperty) {
+    return (target) => {
+        // Always set entity type
+        Reflect.defineMetadata(constants_1.ENTITY_TYPE_METADATA, entityType, target);
+        // Set entity ID property if provided (otherwise falls back to module config)
+        if (entityIdProperty) {
+            Reflect.defineMetadata(constants_1.ENTITY_ID_METADATA, entityIdProperty, target);
+        }
+    };
+}
+//# sourceMappingURL=entity.decorators.js.map

package/dist/decorators/entity.decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.decorators.js","sourceRoot":"","sources":["../../src/decorators/entity.decorators.ts"],"names":[],"mappings":";;;AAuBA,gCAIC;AA6BD,sCAqDC;AA6CD,kCAUC;AApKD,2CAAuE;AACvE,yCAAmD;AACnD,mCAAkD;AAElD;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,UAAU,CAAC,UAAkB;IAC3C,OAAO,CAAC,MAAgB,EAAE,EAAE;QAC1B,OAAO,CAAC,cAAc,CAAC,gCAAoB,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IACnE,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,SAAgB,aAAa;IAC3B,OAAO,CACL,MAAc,EACd,WAAwC,EACxC,cAAuB,EACvB,EAAE;QACF,kDAAkD;QAClD,IAAI,OAAO,cAAc,KAAK,QAAQ,EAAE,CAAC;YACvC,MAAM,WAAW,GAAG,MAAkB,CAAC;YACvC,MAAM,SAAS,GAAG,WAAW,CAAC,IAAI,CAAC;YAEnC,0CAA0C;YAC1C,MAAM,SAAS,GAAG,IAAA,+BAAuB,EAAC,WAAW,EAAE,cAAc,CAAC,CAAC;YACvE,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,MAAM,IAAI,KAAK,CACb,4CAA4C,cAAc,OAAO,SAAS,IAAI;oBAC9E,yDAAyD,CAC1D,CAAC;YACJ,CAAC;YAED,sBAAsB;YACtB,MAAM,QAAQ,GAAG,gCAAqB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YACxD,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,IAAI,KAAK,CACb,2CAA2C,SAAS,IAAI;oBACxD,aAAa,QAAQ,UAAU,SAAS,KAAK;oBAC7C,mDAAmD,CACpD,CAAC;YACJ,CAAC;YAED,gCAAqB,CAAC,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;YAClD,OAAO,CAAC,cAAc,CAAC,8BAAkB,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;YACnE,OAAO;QACT,CAAC;QAED,8CAA8C;QAC9C,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;QACvC,MAAM,SAAS,GAAG,WAAW,CAAC,IAAI,CAAC;QACnC,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;QAErC,mDAAmD;QACnD,MAAM,QAAQ,GAAG,gCAAqB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACxD,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,2CAA2C,SAAS,IAAI;gBACxD,aAAa,QAAQ,UAAU,QAAQ,KAAK;gBAC5C,yCAAyC,CAC1C,CAAC;QACJ,CAAC;QAED,gCAAqB,CAAC,GAAG,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;QACjD,OAAO,CAAC,cAAc,CAAC,8BAAkB,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IACpE,CAAC,CAAC;AACJ,CAAC;AAED;;GAEG;AACU,QAAA,QAAQ,GAAG,aAAa,CAAC;AAEtC,gFAAgF;AAChF,yCAAyC;AACzC,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,SAAgB,WAAW,CAAC,UAAkB,EAAE,gBAAyB;IACvE,OAAO,CAAC,MAAgB,EAAE,EAAE;QAC1B,yBAAyB;QACzB,OAAO,CAAC,cAAc,CAAC,gCAAoB,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;QAEjE,6EAA6E;QAC7E,IAAI,gBAAgB,EAAE,CAAC;YACrB,OAAO,CAAC,cAAc,CAAC,8BAAkB,EAAE,gBAAgB,EAAE,MAAM,CAAC,CAAC;QACvE,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/decorators/index.d.ts

@@ -1,2 +1,10 @@
-export * from './decorators';
+export * from './constants';
+export * from './interfaces';
+export * from './entity.decorators';
+export * from './worker.decorators';
+export * from './scaler.decorators';
+export * from './job.decorators';
+export * from './legacy.decorators';
+export * from './metadata-readers';
+export * from './type-guards';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC"}

package/dist/decorators/index.js

@@ -14,5 +14,13 @@ 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("./decorators"), exports);
+__exportStar(require("./constants"), exports);
+__exportStar(require("./interfaces"), exports);
+__exportStar(require("./entity.decorators"), exports);
+__exportStar(require("./worker.decorators"), exports);
+__exportStar(require("./scaler.decorators"), exports);
+__exportStar(require("./job.decorators"), exports);
+__exportStar(require("./legacy.decorators"), exports);
+__exportStar(require("./metadata-readers"), exports);
+__exportStar(require("./type-guards"), exports);
 //# sourceMappingURL=index.js.map

package/dist/decorators/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA6B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA4B;AAC5B,+CAA6B;AAC7B,sDAAoC;AACpC,sDAAoC;AACpC,sDAAoC;AACpC,mDAAiC;AACjC,sDAAoC;AACpC,qDAAmC;AACnC,gDAA8B"}

package/dist/decorators/interfaces.d.ts

@@ -0,0 +1,130 @@
+import { Type } from '@nestjs/common';
+import { IWorkerConfig } from '../domain';
+/**
+ * Options for @WorkerProcessor decorator
+ */
+export interface WorkerProcessorOptions {
+    /** Entity type this processor handles (e.g., 'table', 'user') */
+    entityType: string;
+    /** Default property name for entity ID extraction (optional) */
+    defaultEntityId?: string;
+    /** Function to generate queue name from entityId */
+    queueName?: string | ((entityId: string) => string);
+    /** Function to generate worker name from entityId */
+    workerName?: string | ((entityId: string) => string);
+    /** Worker configuration */
+    workerConfig?: IWorkerConfig;
+    /**
+     * If true, workerConfig fully replaces module workerDefaults (no merge).
+     * If false (default), workerConfig is merged with workerDefaults.
+     */
+    overrideDefaults?: boolean;
+    /**
+     * Maximum workers per entity (default: 1).
+     * Used when operating without an EntityScaler.
+     */
+    maxWorkersPerEntity?: number;
+    /**
+     * Idle timeout in seconds before a worker is considered idle and can be terminated.
+     * Workers self-report idle time via heartbeat. Default: 15 seconds.
+     * Used when operating without an EntityScaler.
+     */
+    idleTimeoutSeconds?: number;
+    /**
+     * If true, workers are automatically spawned when jobs arrive (scalerless mode).
+     * When enabled, no @EntityScaler is required - workers spawn on job arrival
+     * and terminate when idle. Default: true if no EntityScaler is registered.
+     */
+    autoSpawn?: boolean;
+}
+/**
+ * Options for @EntityScaler decorator
+ */
+export interface EntityScalerOptions {
+    /** Entity type this scaler handles */
+    entityType: string;
+    /** Maximum workers per entity */
+    maxWorkersPerEntity?: number;
+    /**
+     * Idle timeout in seconds before a worker is considered idle and can be terminated.
+     * Workers self-report idle time via heartbeat. Default: 15 seconds.
+     */
+    idleTimeoutSeconds?: number;
+}
+/**
+ * Options for @JobCommand decorator
+ */
+export interface JobCommandOptions {
+    /** Job name (defaults to kebab-case of class name without 'Command' suffix) */
+    name?: string;
+    /** Entity type this command belongs to (optional, for scoped routing) */
+    entityType?: string;
+    /** Which constructor parameter is the entityId (default: 0 = first param) */
+    entityIdParam?: number | string;
+}
+/**
+ * Options for @JobQuery decorator
+ */
+export interface JobQueryOptions {
+    /** Job name (defaults to kebab-case of class name without 'Query' suffix) */
+    name?: string;
+    /** Entity type this query belongs to (optional, for scoped routing) */
+    entityType?: string;
+    /** Which constructor parameter is the entityId (default: 0 = first param) */
+    entityIdParam?: number | string;
+}
+/**
+ * Stored job command metadata
+ */
+export interface JobCommandMetadata {
+    jobName: string;
+    entityType?: string;
+    entityIdParam: number | string;
+    targetClass: Function;
+    paramNames: string[];
+}
+/**
+ * Stored job query metadata
+ */
+export interface JobQueryMetadata {
+    jobName: string;
+    entityType?: string;
+    entityIdParam: number | string;
+    targetClass: Function;
+    paramNames: string[];
+}
+/**
+ * Stored job handler metadata
+ */
+export interface JobHandlerMetadata {
+    jobName: string;
+    methodName: string;
+    isWildcard: boolean;
+}
+/**
+ * Stored worker processor metadata
+ */
+export interface WorkerProcessorMetadata {
+    entityType: string;
+    defaultEntityId?: string;
+    queueNameFn: (entityId: string) => string;
+    workerNameFn: (entityId: string) => string;
+    workerConfig: IWorkerConfig;
+    overrideDefaults: boolean;
+    targetClass: Type<any>;
+    jobHandlers: Map<string, JobHandlerMetadata>;
+    wildcardHandler?: JobHandlerMetadata;
+}
+/**
+ * Stored entity scaler metadata
+ */
+export interface EntityScalerMetadata {
+    entityType: string;
+    maxWorkersPerEntity: number;
+    targetClass: Type<any>;
+    getActiveEntitiesMethod?: string;
+    getDesiredWorkerCountMethod?: string;
+    onSpawnWorkerMethod?: string;
+    onTerminateWorkerMethod?: string;
+}
+//# sourceMappingURL=interfaces.d.ts.map

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

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

package/dist/decorators/interfaces.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=interfaces.js.map

package/dist/decorators/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/decorators/interfaces.ts"],"names":[],"mappings":""}