atomic-queues 1.4.1 → 1.6.0

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":""}

package/dist/decorators/job.decorators.d.ts

@@ -0,0 +1,60 @@
+import { JobCommandOptions, JobQueryOptions } from './interfaces';
+/**
+ * @JobCommand class decorator
+ *
+ * Marks a command class for automatic job routing. When a job with the
+ * specified name arrives, the library will automatically instantiate
+ * the command with entityId + job.data and execute it via CommandBus.
+ *
+ * This eliminates the need for @JobHandler boilerplate in processors.
+ *
+ * @example
+ * ```typescript
+ * // Option 1: Explicit job name
+ * @JobCommand('make-bet')
+ * export class MakeBetCommand {
+ *   constructor(
+ *     public readonly tableId: string,    // entityId (first param)
+ *     public readonly playerId: string,
+ *     public readonly amount: number,
+ *   ) {}
+ * }
+ *
+ * // Option 2: Auto-derived job name (MakeBetCommand -> 'make-bet')
+ * @JobCommand()
+ * export class MakeBetCommand { ... }
+ *
+ * // Option 3: With options
+ * @JobCommand({
+ *   name: 'place-bet',
+ *   entityType: 'table',
+ *   entityIdParam: 'tableId',  // or 0 for first param
+ * })
+ * export class PlaceBetCommand { ... }
+ * ```
+ */
+export declare function JobCommand(options?: string | JobCommandOptions): ClassDecorator;
+/**
+ * @JobQuery class decorator
+ *
+ * Marks a query class for automatic job routing. When a job with the
+ * specified name arrives, the library will automatically instantiate
+ * the query with entityId + job.data and execute it via QueryBus.
+ *
+ * @example
+ * ```typescript
+ * @JobQuery('get-score')
+ * export class GetScoreQuery {
+ *   constructor(
+ *     public readonly tableId: string,
+ *     public readonly seatIndex: number,
+ *   ) {}
+ * }
+ *
+ * // Auto-derived: GetTableStateQuery -> 'get-table-state'
+ * @JobQuery()
+ * export class GetTableStateQuery { ... }
+ * ```
+ */
+export declare function JobQuery(options?: string | JobQueryOptions): ClassDecorator;
+//# sourceMappingURL=job.decorators.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"job.decorators.d.ts","sourceRoot":"","sources":["../../src/decorators/job.decorators.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAwC,MAAM,cAAc,CAAC;AAGxG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,iBAAiB,GAAG,cAAc,CAmB/E;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,cAAc,CAmB3E"}

package/dist/decorators/job.decorators.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobCommand = JobCommand;
+exports.JobQuery = JobQuery;
+const constants_1 = require("./constants");
+const utils_1 = require("./utils");
+/**
+ * @JobCommand class decorator
+ *
+ * Marks a command class for automatic job routing. When a job with the
+ * specified name arrives, the library will automatically instantiate
+ * the command with entityId + job.data and execute it via CommandBus.
+ *
+ * This eliminates the need for @JobHandler boilerplate in processors.
+ *
+ * @example
+ * ```typescript
+ * // Option 1: Explicit job name
+ * @JobCommand('make-bet')
+ * export class MakeBetCommand {
+ *   constructor(
+ *     public readonly tableId: string,    // entityId (first param)
+ *     public readonly playerId: string,
+ *     public readonly amount: number,
+ *   ) {}
+ * }
+ *
+ * // Option 2: Auto-derived job name (MakeBetCommand -> 'make-bet')
+ * @JobCommand()
+ * export class MakeBetCommand { ... }
+ *
+ * // Option 3: With options
+ * @JobCommand({
+ *   name: 'place-bet',
+ *   entityType: 'table',
+ *   entityIdParam: 'tableId',  // or 0 for first param
+ * })
+ * export class PlaceBetCommand { ... }
+ * ```
+ */
+function JobCommand(options) {
+    return (target) => {
+        const opts = typeof options === 'string'
+            ? { name: options }
+            : (options || {});
+        const jobName = opts.name || (0, utils_1.deriveJobName)(target.name, 'Command');
+        const paramNames = (0, utils_1.getConstructorParamNames)(target);
+        const metadata = {
+            jobName,
+            entityType: opts.entityType,
+            entityIdParam: opts.entityIdParam ?? 0,
+            targetClass: target,
+            paramNames,
+        };
+        Reflect.defineMetadata(constants_1.JOB_COMMAND_METADATA, metadata, target);
+    };
+}
+/**
+ * @JobQuery class decorator
+ *
+ * Marks a query class for automatic job routing. When a job with the
+ * specified name arrives, the library will automatically instantiate
+ * the query with entityId + job.data and execute it via QueryBus.
+ *
+ * @example
+ * ```typescript
+ * @JobQuery('get-score')
+ * export class GetScoreQuery {
+ *   constructor(
+ *     public readonly tableId: string,
+ *     public readonly seatIndex: number,
+ *   ) {}
+ * }
+ *
+ * // Auto-derived: GetTableStateQuery -> 'get-table-state'
+ * @JobQuery()
+ * export class GetTableStateQuery { ... }
+ * ```
+ */
+function JobQuery(options) {
+    return (target) => {
+        const opts = typeof options === 'string'
+            ? { name: options }
+            : (options || {});
+        const jobName = opts.name || (0, utils_1.deriveJobName)(target.name, 'Query');
+        const paramNames = (0, utils_1.getConstructorParamNames)(target);
+        const metadata = {
+            jobName,
+            entityType: opts.entityType,
+            entityIdParam: opts.entityIdParam ?? 0,
+            targetClass: target,
+            paramNames,
+        };
+        Reflect.defineMetadata(constants_1.JOB_QUERY_METADATA, metadata, target);
+    };
+}
+//# sourceMappingURL=job.decorators.js.map

package/dist/decorators/job.decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.decorators.js","sourceRoot":"","sources":["../../src/decorators/job.decorators.ts"],"names":[],"mappings":";;AAsCA,gCAmBC;AAwBD,4BAmBC;AApGD,2CAAuE;AAEvE,mCAAkE;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,SAAgB,UAAU,CAAC,OAAoC;IAC7D,OAAO,CAAC,MAAgB,EAAE,EAAE;QAC1B,MAAM,IAAI,GAAsB,OAAO,OAAO,KAAK,QAAQ;YACzD,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE;YACnB,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;QAEpB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,IAAI,IAAA,qBAAa,EAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACnE,MAAM,UAAU,GAAG,IAAA,gCAAwB,EAAC,MAAM,CAAC,CAAC;QAEpD,MAAM,QAAQ,GAAuB;YACnC,OAAO;YACP,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,aAAa,EAAE,IAAI,CAAC,aAAa,IAAI,CAAC;YACtC,WAAW,EAAE,MAAM;YACnB,UAAU;SACX,CAAC;QAEF,OAAO,CAAC,cAAc,CAAC,gCAAoB,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IACjE,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,QAAQ,CAAC,OAAkC;IACzD,OAAO,CAAC,MAAgB,EAAE,EAAE;QAC1B,MAAM,IAAI,GAAoB,OAAO,OAAO,KAAK,QAAQ;YACvD,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE;YACnB,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;QAEpB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,IAAI,IAAA,qBAAa,EAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACjE,MAAM,UAAU,GAAG,IAAA,gCAAwB,EAAC,MAAM,CAAC,CAAC;QAEpD,MAAM,QAAQ,GAAqB;YACjC,OAAO;YACP,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,aAAa,EAAE,IAAI,CAAC,aAAa,IAAI,CAAC;YACtC,WAAW,EAAE,MAAM;YACnB,UAAU;SACX,CAAC;QAEF,OAAO,CAAC,cAAc,CAAC,8BAAkB,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC/D,CAAC,CAAC;AACJ,CAAC"}