atomic-queues 1.2.7 → 1.4.1

package/README.md

@@ -1,56 +1,98 @@
 # atomic-queues
 
-A NestJS library for atomic, sequential job processing per entity with BullMQ and Redis.
+A NestJS library for atomic, sequential job processing per entity using BullMQ and Redis.
 
-## What It Does
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [The Concurrency Problem](#the-concurrency-problem)
+- [The Per-Entity Queue Architecture](#the-per-entity-queue-architecture)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Commands and Decorators](#commands-and-decorators)
+- [Configuration](#configuration)
+- [Complete Example](#complete-example)
+- [Advanced: Custom Worker Processors](#advanced-custom-worker-processors)
+- [License](#license)
+
+---
+
+## Overview
+
+**atomic-queues** solves the fundamental concurrency problem in distributed systems: ensuring that operations on the same logical entity execute sequentially, even when requests arrive simultaneously across multiple service instances.
+
+Rather than relying on distributed locks—which introduce contention, latency degradation, and complex failure modes—this library implements a **per-entity queue architecture** where each entity (user account, order, document) has its own dedicated processing queue and worker.
+
+---
+
+## The Concurrency Problem
+
+Consider a banking system where a user with a $100 balance submits two concurrent $80 withdrawal requests:
+
+```
+Time    Request A                    Request B                    Database State
+─────────────────────────────────────────────────────────────────────────────────
+T₀      SELECT balance → $100        SELECT balance → $100        balance = $100
+T₁      CHECK: $100 >= $80 ✓         CHECK: $100 >= $80 ✓              
+T₂      UPDATE: balance = $20        UPDATE: balance = $20        balance = $20
+T₃                                   UPDATE: balance = -$60       balance = -$60
+─────────────────────────────────────────────────────────────────────────────────
+Result: Both withdrawals succeed. Balance becomes -$60. Integrity violated.
+```
+
+With atomic-queues, operations are queued and processed sequentially:
 
 ```
-╔═══════════════════════════════════════════════════════════════════════════════╗
-║                              THE PROBLEM                                       ║
-╠═══════════════════════════════════════════════════════════════════════════════╣
-║                                                                                ║
-║   User has $100 balance. Two $80 withdrawals arrive at the same time:          ║
-║                                                                                ║
-║       Withdraw $80 ──┐                                                         ║
-║          (API 1)     │    ┌────────────────────┐                               ║
-║                      ├───▶│  Balance: $100     │                               ║
-║       Withdraw $80 ──┘    │  Both read $100    │                               ║
-║          (API 2)          │  Both approve      │                               ║
-║                           │  Final: -$60 💥    │                               ║
-║                           └────────────────────┘                               ║
-║                                                                                ║
-║   Race condition: Both transactions see $100, both succeed, balance goes -$60  ║
-║                                                                                ║
-╚═══════════════════════════════════════════════════════════════════════════════╝
-
-╔═══════════════════════════════════════════════════════════════════════════════╗
-║                              THE SOLUTION                                      ║
-╠═══════════════════════════════════════════════════════════════════════════════╣
-║                                                                                ║
-║   atomic-queues processes one transaction at a time per account:               ║
-║                                                                                ║
-║       Withdraw $80 ──┐     ┌─────────────┐     ┌─────────────────────────────┐ ║
-║          (API 1)     │     │             │     │ Worker processes queue:     │ ║
-║                      ├────▶│ Redis Queue │────▶│                             │ ║
-║       Withdraw $80 ──┘     │  [W1] [W2]  │     │  W1: $100 - $80 = $20 ✓     │ ║
-║          (API 2)           │             │     │  W2: $20 < $80 = REJECTED ✓ │ ║
-║                            └─────────────┘     └─────────────────────────────┘ ║
-║                                                                                ║
-║   Sequential processing: W1 completes first, W2 sees updated balance           ║
-║                                                                                ║
-╚═══════════════════════════════════════════════════════════════════════════════╝
+Time    Queue State                 Worker Execution              Database State
+───────────────────────────────────────────────────────────────────────────────────
+T₀      [Withdraw $80, Withdraw $80]                              balance = $100
+T₁      [Withdraw $80]              Process Op₁: $100 - $80       balance = $20
+T₂      []                          Process Op₂: $20 < $80 → REJECT   balance = $20
+───────────────────────────────────────────────────────────────────────────────────
+Result: First withdrawal succeeds. Second is rejected. Integrity preserved.
 ```
 
+---
+
+## The Per-Entity Queue Architecture
+
+```
+                                    ┌─────────────────────────────────────────┐
+   Request A ─┐                     │         Per-Entity Queue                │
+              │                     │  ┌─────┐ ┌─────┐ ┌─────┐               │
+   Request B ─┼──▶ [Entity Router] ─┼─▶│ Op₁ │→│ Op₂ │→│ Op₃ │→ [Worker] ─┐ │
+              │                     │  └─────┘ └─────┘ └─────┘             │ │
+   Request C ─┘                     │                                      │ │
+                                    │      Sequential Processing ◄─────────┘ │
+                                    └─────────────────────────────────────────┘
+```
+
+**Key features:**
+- Each entity has exactly one active worker (enforced via Redis heartbeat)
+- Workers spawn automatically when jobs arrive
+- Workers terminate after configurable idle period
+- Node failure → heartbeat expires → worker respawns on healthy node
+
+---
+
 ## Installation
 
 ```bash
 npm install atomic-queues bullmq ioredis
 ```
 
+---
+
 ## Quick Start
 
 ### 1. Configure the Module
 
+The `entities` configuration is **optional**. Choose the approach that fits your needs:
+
+#### Option A: Minimal Setup (uses default naming)
+
 ```typescript
 import { Module } from '@nestjs/common';
 import { AtomicQueuesModule } from 'atomic-queues';
@@ -60,289 +102,309 @@ import { AtomicQueuesModule } from 'atomic-queues';
     AtomicQueuesModule.forRoot({
       redis: { host: 'localhost', port: 6379 },
       keyPrefix: 'myapp',
+      enableCronManager: true,
+      // No entities config needed! Uses default naming:
+      // Queue: {keyPrefix}:{entityType}:{entityId}:queue
+      // Worker: {keyPrefix}:{entityType}:{entityId}:worker
     }),
   ],
 })
 export class AppModule {}
 ```
 
-### 2. Create Your Commands
+#### Option B: Custom Queue/Worker Naming (via entities config)
 
-Plain classes - no decorators needed:
+```typescript
+@Module({
+  imports: [
+    AtomicQueuesModule.forRoot({
+      redis: { host: 'localhost', port: 6379 },
+      keyPrefix: 'myapp',
+      enableCronManager: true,
+      
+      // Optional: Define custom naming and settings per entity type
+      entities: {
+        account: {
+          queueName: (id) => `${id}-queue`,        // Custom queue naming
+          workerName: (id) => `${id}-worker`,      // Custom worker naming
+          maxWorkersPerEntity: 1,
+          idleTimeoutSeconds: 15,
+        },
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+#### Option C: Custom Naming via @WorkerProcessor
+
+For advanced use cases, define a processor class instead of entities config:
 
 ```typescript
-// commands/process-order.command.ts
-export class ProcessOrderCommand {
+@WorkerProcessor({
+  entityType: 'account',
+  queueName: (id) => `${id}-queue`,
+  workerName: (id) => `${id}-worker`,
+  maxWorkersPerEntity: 1,
+  idleTimeoutSeconds: 15,
+})
+@Injectable()
+export class AccountProcessor {}
+```
+
+> **When to use each:**
+> - **Option A**: Default naming works for you
+> - **Option B**: Need custom naming but no custom job handling logic
+> - **Option C**: Need custom naming AND custom `@JobHandler` methods
+
+### 2. Create Commands with Decorators
+
+```typescript
+import { QueueEntity, QueueEntityId } from 'atomic-queues';
+
+@QueueEntity('account')
+export class WithdrawCommand {
   constructor(
-    public readonly orderId: string,
-    public readonly items: string[],
+    @QueueEntityId() public readonly accountId: string,
     public readonly amount: number,
+    public readonly transactionId: string,
   ) {}
 }
 
-// commands/ship-order.command.ts
-export class ShipOrderCommand {
+@QueueEntity('account')
+export class DepositCommand {
   constructor(
-    public readonly orderId: string,
-    public readonly address: string,
+    @QueueEntityId() public readonly accountId: string,
+    public readonly amount: number,
+    public readonly source: string,
   ) {}
 }
 ```
 
-### 3. Create a Worker Processor
+### 3. Create Command Handlers (standard @nestjs/cqrs)
 
 ```typescript
-import { Injectable } from '@nestjs/common';
-import { WorkerProcessor } from 'atomic-queues';
+import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
+import { WithdrawCommand } from './commands';
 
-@WorkerProcessor({
-  entityType: 'order',
-  queueName: (orderId) => `order-${orderId}-queue`,
-  workerName: (orderId) => `order-${orderId}-worker`,
-})
-@Injectable()
-export class OrderProcessor {}
-```
+@CommandHandler(WithdrawCommand)
+export class WithdrawHandler implements ICommandHandler<WithdrawCommand> {
+  constructor(private readonly accountRepo: AccountRepository) {}
 
-### 4. Queue Jobs with the Fluent API
+  async execute(command: WithdrawCommand) {
+    const { accountId, amount, transactionId } = command;
+    
+    // SAFE: No race conditions! Processed sequentially per account.
+    const account = await this.accountRepo.findById(accountId);
+    
+    if (account.balance < amount) {
+      throw new InsufficientFundsError(accountId, account.balance, amount);
+    }
+    
+    account.balance -= amount;
+    await this.accountRepo.save(account);
+    
+    return { success: true, newBalance: account.balance };
+  }
+}
+```
 
-Commands are **automatically registered** from your `@CommandHandler` classes - no manual registration needed!
+### 4. Enqueue Jobs
 
 ```typescript
 import { Injectable } from '@nestjs/common';
 import { QueueBus } from 'atomic-queues';
-import { OrderProcessor } from './order.processor';
-import { ProcessOrderCommand, ShipOrderCommand } from './commands';
+import { WithdrawCommand, DepositCommand } from './commands';
 
 @Injectable()
-export class OrderService {
+export class AccountService {
   constructor(private readonly queueBus: QueueBus) {}
 
-  async createOrder(orderId: string, items: string[], amount: number) {
-    // Jobs are queued and processed sequentially per orderId
-    await this.queueBus
-      .forProcessor(OrderProcessor)
-      .enqueue(new ProcessOrderCommand(orderId, items, amount));
+  async withdraw(accountId: string, amount: number, transactionId: string) {
+    // Command is automatically routed to the account's queue
+    await this.queueBus.enqueue(new WithdrawCommand(accountId, amount, transactionId));
+  }
 
-    await this.queueBus
-      .forProcessor(OrderProcessor)
-      .enqueue(new ShipOrderCommand(orderId, '123 Main St'));
+  async deposit(accountId: string, amount: number, source: string) {
+    await this.queueBus.enqueue(new DepositCommand(accountId, amount, source));
   }
 }
 ```
 
-That's it! The library automatically:
-- Discovers commands from `@CommandHandler` decorators
-- Creates a queue for each `orderId`
+**That's it!** The library automatically:
+- Creates a queue for each `accountId` when jobs arrive
 - Spawns a worker to process jobs sequentially
-- Routes jobs to the correct command handlers
-
----
-
-## How It Works
-
-```
-╔═══════════════════════════════════════════════════════════════════════════════╗
-║                              ARCHITECTURE                                      ║
-╚═══════════════════════════════════════════════════════════════════════════════╝
-
-┌──────────────────┐
-│   API Request    │   POST /accounts/ACC-123/withdraw { amount: 80 }
-└────────┬─────────┘
-         │
-         ▼
-┌──────────────────────────────────────────────────────────────────────────────┐
-│  QueueBus.forProcessor(AccountProcessor).enqueue(new WithdrawCommand(...))   │
-└────────┬─────────────────────────────────────────────────────────────────────┘
-         │
-         │  ① Reads @WorkerProcessor metadata from AccountProcessor
-         │  ② Extracts accountId from command.accountId property
-         │  ③ Generates queue name: "account-ACC-123-queue"
-         │
-         ▼
-┌──────────────────────────────────────────────────────────────────────────────┐
-│                              REDIS                                            │
-│  ┌────────────────────────────────────────────────────────────────────────┐  │
-│  │  Queue: account-ACC-123-queue                                          │  │
-│  │  ┌─────────────────┬─────────────────┬─────────────────┐               │  │
-│  │  │ Job 1           │ Job 2           │ Job 3           │  ...          │  │
-│  │  │ WithdrawCommand │ DepositCommand  │ TransferCommand │               │  │
-│  │  │ amount: 80      │ amount: 50      │ amount: 25      │               │  │
-│  │  └─────────────────┴─────────────────┴─────────────────┘               │  │
-│  └────────────────────────────────────────────────────────────────────────┘  │
-│                                                                               │
-│  ┌────────────────────────────────────────────────────────────────────────┐  │
-│  │  Queue: account-ACC-456-queue  (different account = different queue)   │  │
-│  │  ┌─────────────────┐                                                   │  │
-│  │  │ Job 1           │  ← Processes in parallel with ACC-123             │  │
-│  │  │ WithdrawCommand │                                                   │  │
-│  │  └─────────────────┘                                                   │  │
-│  └────────────────────────────────────────────────────────────────────────┘  │
-└──────────────────────────────────────────────────────────────────────────────┘
-         │
-         │  ④ BullMQ Worker pulls Job 1 (only one job at a time per queue)
-         │
-         ▼
-┌──────────────────────────────────────────────────────────────────────────────┐
-│  Worker: account-ACC-123-worker                                              │
-│                                                                               │
-│  ┌─────────────────────────────────────────────────────────────────────────┐ │
-│  │  ⑤ Lookup "WithdrawCommand" in QueueBus.globalRegistry                  │ │
-│  │  ⑥ Instantiate: Object.assign(new WithdrawCommand(), job.data)          │ │
-│  │  ⑦ Execute: CommandBus.execute(withdrawCommand)                         │ │
-│  └─────────────────────────────────────────────────────────────────────────┘ │
-└────────┬─────────────────────────────────────────────────────────────────────┘
-         │
-         ▼
-┌──────────────────────────────────────────────────────────────────────────────┐
-│  @CommandHandler(WithdrawCommand)                                            │
-│  class WithdrawHandler {                                                     │
-│    async execute(cmd: WithdrawCommand) {                                     │
-│      // Safe! No race conditions - guaranteed sequential execution           │
-│      const balance = await this.repo.getBalance(cmd.accountId);              │
-│      if (balance < cmd.amount) throw new InsufficientFundsError();           │
-│      await this.repo.debit(cmd.accountId, cmd.amount);                       │
-│    }                                                                         │
-│  }                                                                           │
-└──────────────────────────────────────────────────────────────────────────────┘
-```
+- Routes jobs to the correct `@CommandHandler`
+- Terminates idle workers after the configured timeout
 
 ---
 
-## API Reference
+## Commands and Decorators
 
-### QueueBus
+### @QueueEntity(entityType)
 
-The main way to add jobs to queues:
+Marks a command class for queue routing. The `entityType` must match a key in your `entities` config.
 
 ```typescript
-// Enqueue a single command
-await queueBus
-  .forProcessor(MyProcessor)
-  .enqueue(new MyCommand(entityId, data));
-
-// Enqueue and wait for result
-const result = await queueBus
-  .forProcessor(MyProcessor)
-  .enqueueAndWait(new MyQuery(entityId));
-
-// Enqueue multiple commands
-await queueBus
-  .forProcessor(MyProcessor)
-  .enqueueBulk([
-    new CommandA(entityId),
-    new CommandB(entityId),
-  ]);
-
-// With job options (delay, priority, etc.)
-await queueBus
-  .forProcessor(MyProcessor)
-  .enqueue(new MyCommand(entityId), {
-    jobOptions: { delay: 5000, priority: 1 }
-  });
+@QueueEntity('account')
+export class TransferCommand { ... }
 ```
 
-### @WorkerProcessor
+### @QueueEntityId()
 
-Defines how workers are created for an entity type:
+Marks which property contains the entity ID for queue routing. Only one per class.
 
 ```typescript
-@WorkerProcessor({
-  entityType: 'order',                              // Required
-  queueName: (id) => `order-${id}-queue`,           // Optional
-  workerName: (id) => `order-${id}-worker`,         // Optional
-  workerConfig: {
-    concurrency: 1,                                 // Jobs per worker (default: 1)
-    stalledInterval: 1000,                          // Check stalled jobs (ms)
-    lockDuration: 30000,                            // Job lock duration (ms)
-  },
-})
+@QueueEntity('account')
+export class TransferCommand {
+  constructor(
+    @QueueEntityId() public readonly sourceAccountId: string,  // Routes to source account's queue
+    public readonly targetAccountId: string,
+    public readonly amount: number,
+  ) {}
+}
 ```
 
----
-
-## Entity ID Extraction
+### Alternative: Use defaultEntityId
 
-The `entityId` is automatically extracted from your command's properties:
+If all commands for an entity use the same property name, configure it once:
 
 ```typescript
-// These property names are checked in order:
-// entityId, tableId, userId, id, gameId, playerId
-
-export class ProcessOrderCommand {
-  constructor(
-    public readonly orderId: string,  // ✓ 'orderId' contains 'Id' → entityId
-    public readonly items: string[],
-  ) {}
+// In module config
+entities: {
+  account: {
+    defaultEntityId: 'accountId',  // Commands without @QueueEntityId use this
+    // ...
+  },
 }
 
-// Or use standard names
-export class UpdateUserCommand {
+// Then commands don't need @QueueEntityId
+@QueueEntity('account')
+export class WithdrawCommand {
   constructor(
-    public readonly userId: string,   // ✓ Matches 'userId' → entityId
-    public readonly name: string,
+    public readonly accountId: string,  // Automatically used
+    public readonly amount: number,
   ) {}
 }
 ```
 
 ---
 
-## Scaling with Entity Scalers
-
-For dynamic worker management based on demand:
+## Configuration
 
 ```typescript
-import { Injectable } from '@nestjs/common';
-import { EntityScaler, GetActiveEntities, GetDesiredWorkerCount } from 'atomic-queues';
-
-@EntityScaler({
-  entityType: 'order',
-  maxWorkersPerEntity: 1,
-})
-@Injectable()
-export class OrderScaler {
-  constructor(private readonly orderRepo: OrderRepository) {}
-
-  @GetActiveEntities()
-  async getActiveOrders(): Promise<string[]> {
-    // Return IDs that need workers
-    return this.orderRepo.findPendingOrderIds();
-  }
-
-  @GetDesiredWorkerCount()
-  async getWorkerCount(orderId: string): Promise<number> {
-    return 1; // One worker per order
-  }
-}
+AtomicQueuesModule.forRoot({
+  redis: {
+    host: 'localhost',
+    port: 6379,
+    password: 'secret',
+  },
+  
+  keyPrefix: 'myapp',            // Redis key prefix (default: 'aq')
+  enableCronManager: true,       // Enable worker lifecycle management
+  cronInterval: 5000,            // Scaling check interval (ms)
+  
+  workerDefaults: {
+    concurrency: 1,              // Jobs processed simultaneously
+    stalledInterval: 1000,       // Stalled job check interval (ms)
+    lockDuration: 30000,         // Job lock duration (ms)
+    heartbeatTTL: 3,             // Worker heartbeat TTL (seconds)
+  },
+  
+  // OPTIONAL: Per-entity configuration
+  // If omitted, uses default naming: {keyPrefix}:{entityType}:{entityId}:queue/worker
+  entities: {
+    account: {
+      defaultEntityId: 'accountId',
+      queueName: (id) => `${id}-queue`,
+      workerName: (id) => `${id}-worker`,
+      maxWorkersPerEntity: 1,
+      idleTimeoutSeconds: 15,
+      autoSpawn: true,           // Default: true
+      workerConfig: {            // Override defaults per entity
+        concurrency: 1,
+        lockDuration: 60000,
+      },
+    },
+    order: {
+      defaultEntityId: 'orderId',
+      queueName: (id) => `order-${id}-queue`,
+      idleTimeoutSeconds: 30,
+    },
+  },
+});
 ```
 
 ---
 
 ## Complete Example
 
-A banking service handling critical financial transactions where race conditions could cause overdrafts or double-spending:
+A banking service handling financial transactions:
 
 ```typescript
+// ─────────────────────────────────────────────────────────────────
+// app.module.ts
+// ─────────────────────────────────────────────────────────────────
+import { Module } from '@nestjs/common';
+import { CqrsModule } from '@nestjs/cqrs';
+import { AtomicQueuesModule } from 'atomic-queues';
+
+@Module({
+  imports: [
+    CqrsModule,
+    AtomicQueuesModule.forRoot({
+      redis: { host: 'localhost', port: 6379 },
+      keyPrefix: 'banking',
+      enableCronManager: true,
+      entities: {
+        account: {
+          queueName: (id) => `${id}-queue`,
+          workerName: (id) => `${id}-worker`,
+          maxWorkersPerEntity: 1,
+          idleTimeoutSeconds: 15,
+          workerConfig: {
+            concurrency: 1,
+            lockDuration: 60000,
+          },
+        },
+      },
+    }),
+  ],
+  providers: [
+    AccountService,
+    WithdrawHandler,
+    DepositHandler,
+    TransferHandler,
+  ],
+  controllers: [AccountController],
+})
+export class AppModule {}
+
 // ─────────────────────────────────────────────────────────────────
 // commands/withdraw.command.ts
 // ─────────────────────────────────────────────────────────────────
+import { QueueEntity, QueueEntityId } from 'atomic-queues';
+
+@QueueEntity('account')
 export class WithdrawCommand {
   constructor(
-    public readonly accountId: string,
+    @QueueEntityId() public readonly accountId: string,
     public readonly amount: number,
     public readonly transactionId: string,
-    public readonly requestedBy: string,
   ) {}
 }
 
 // ─────────────────────────────────────────────────────────────────
 // commands/deposit.command.ts
 // ─────────────────────────────────────────────────────────────────
+import { QueueEntity, QueueEntityId } from 'atomic-queues';
+
+@QueueEntity('account')
 export class DepositCommand {
   constructor(
-    public readonly accountId: string,
+    @QueueEntityId() public readonly accountId: string,
     public readonly amount: number,
-    public readonly transactionId: string,
     public readonly source: string,
   ) {}
 }
@@ -350,9 +412,12 @@ export class DepositCommand {
 // ─────────────────────────────────────────────────────────────────
 // commands/transfer.command.ts
 // ─────────────────────────────────────────────────────────────────
+import { QueueEntity, QueueEntityId } from 'atomic-queues';
+
+@QueueEntity('account')
 export class TransferCommand {
   constructor(
-    public readonly accountId: string,  // Source account (for queue routing)
+    @QueueEntityId() public readonly accountId: string,  // Source account
     public readonly toAccountId: string,
     public readonly amount: number,
     public readonly transactionId: string,
@@ -367,46 +432,22 @@ import { WithdrawCommand } from '../commands';
 
 @CommandHandler(WithdrawCommand)
 export class WithdrawHandler implements ICommandHandler<WithdrawCommand> {
-  constructor(
-    private readonly accountRepo: AccountRepository,
-    private readonly ledger: LedgerService,
-  ) {}
+  constructor(private readonly accountRepo: AccountRepository) {}
 
   async execute(command: WithdrawCommand) {
-    const { accountId, amount, transactionId } = command;
-    
-    // SAFE: No race conditions! This handler runs sequentially per account
-    // Even if 10 withdrawals arrive simultaneously, they execute one-by-one
+    const { accountId, amount } = command;
     
+    // SAFE: Sequential execution per account
     const account = await this.accountRepo.findById(accountId);
     
     if (account.balance < amount) {
       throw new InsufficientFundsError(accountId, account.balance, amount);
     }
     
-    if (account.status !== 'active') {
-      throw new AccountFrozenError(accountId);
-    }
-    
-    // Debit the account
     account.balance -= amount;
     await this.accountRepo.save(account);
     
-    // Record in ledger
-    await this.ledger.record({
-      transactionId,
-      accountId,
-      type: 'DEBIT',
-      amount,
-      balanceAfter: account.balance,
-      timestamp: new Date(),
-    });
-    
-    return { 
-      success: true, 
-      transactionId, 
-      newBalance: account.balance 
-    };
+    return { success: true, newBalance: account.balance };
   }
 }
 
@@ -425,105 +466,34 @@ export class TransferHandler implements ICommandHandler<TransferCommand> {
   ) {}
 
   async execute(command: TransferCommand) {
-    const { accountId, toAccountId, amount, transactionId } = command;
-    
-    // Step 1: Debit source account (already in source account's queue)
-    const sourceAccount = await this.accountRepo.findById(accountId);
+    const { accountId, toAccountId, amount } = command;
     
-    if (sourceAccount.balance < amount) {
-      throw new InsufficientFundsError(accountId, sourceAccount.balance, amount);
+    // Debit source (we're in source account's queue)
+    const source = await this.accountRepo.findById(accountId);
+    if (source.balance < amount) {
+      throw new InsufficientFundsError(accountId, source.balance, amount);
     }
     
-    sourceAccount.balance -= amount;
-    await this.accountRepo.save(sourceAccount);
+    source.balance -= amount;
+    await this.accountRepo.save(source);
     
-    // Step 2: Queue credit to destination account (different queue!)
-    // This ensures the destination account also processes atomically
-    await this.queueBus
-      .forProcessor(AccountProcessor)
-      .enqueue(new DepositCommand(
-        toAccountId,
-        amount,
-        transactionId,
-        `transfer:${accountId}`,
-      ));
+    // Credit destination (enqueued to destination's queue)
+    await this.queueBus.enqueue(new DepositCommand(
+      toAccountId,
+      amount,
+      `transfer:${accountId}`,
+    ));
     
-    return { success: true, transactionId };
+    return { success: true };
   }
 }
 
-// ─────────────────────────────────────────────────────────────────
-// account.processor.ts
-// ─────────────────────────────────────────────────────────────────
-import { Injectable } from '@nestjs/common';
-import { WorkerProcessor } from 'atomic-queues';
-
-@WorkerProcessor({
-  entityType: 'account',
-  queueName: (accountId) => `bank-account-${accountId}-queue`,
-  workerName: (accountId) => `bank-account-${accountId}-worker`,
-  workerConfig: {
-    concurrency: 1,        // CRITICAL: Must be 1 for financial transactions
-    lockDuration: 60000,   // 60s lock for long transactions
-    stalledInterval: 5000,
-  },
-})
-@Injectable()
-export class AccountProcessor {}
-
-// ─────────────────────────────────────────────────────────────────
-// account.scaler.ts - Scale workers based on active accounts
-// ─────────────────────────────────────────────────────────────────
-import { Injectable } from '@nestjs/common';
-import { EntityScaler, GetActiveEntities, GetDesiredWorkerCount } from 'atomic-queues';
-
-@EntityScaler({
-  entityType: 'account',
-  maxWorkersPerEntity: 1,  // Never more than 1 worker per account
-})
-@Injectable()
-export class AccountScaler {
-  constructor(private readonly accountRepo: AccountRepository) {}
-
-  @GetActiveEntities()
-  async getActiveAccounts(): Promise<string[]> {
-    // Return accounts with pending transactions
-    return this.accountRepo.findAccountsWithPendingTransactions();
-  }
-
-  @GetDesiredWorkerCount()
-  async getWorkerCount(accountId: string): Promise<number> {
-    // Always 1 worker per account for atomicity
-    return 1;
-  }
-}
-
-// ─────────────────────────────────────────────────────────────────
-// account.module.ts
-// ─────────────────────────────────────────────────────────────────
-import { Module } from '@nestjs/common';
-import { CqrsModule } from '@nestjs/cqrs';
-
-@Module({
-  imports: [CqrsModule],
-  providers: [
-    AccountProcessor,
-    AccountScaler,
-    WithdrawHandler,    // Commands auto-discovered!
-    DepositHandler,
-    TransferHandler,
-  ],
-  controllers: [AccountController],
-})
-export class AccountModule {}
-
 // ─────────────────────────────────────────────────────────────────
 // account.controller.ts
 // ─────────────────────────────────────────────────────────────────
 import { Controller, Post, Body, Param } from '@nestjs/common';
 import { QueueBus } from 'atomic-queues';
-import { AccountProcessor } from './account.processor';
-import { WithdrawCommand, DepositCommand, TransferCommand } from './commands';
+import { WithdrawCommand, TransferCommand } from './commands';
 import { v4 as uuid } from 'uuid';
 
 @Controller('accounts')
@@ -533,26 +503,15 @@ export class AccountController {
   @Post(':accountId/withdraw')
   async withdraw(
     @Param('accountId') accountId: string,
-    @Body() body: { amount: number; requestedBy: string },
+    @Body() body: { amount: number },
   ) {
     const transactionId = uuid();
     
-    // Even if user spam-clicks "Withdraw", each request is queued
-    // and processed sequentially - no double-withdrawals possible
-    await this.queueBus
-      .forProcessor(AccountProcessor)
-      .enqueue(new WithdrawCommand(
-        accountId,
-        body.amount,
-        transactionId,
-        body.requestedBy,
-      ));
-
-    return { 
-      queued: true, 
-      transactionId,
-      message: 'Withdrawal queued for processing',
-    };
+    await this.queueBus.enqueue(
+      new WithdrawCommand(accountId, body.amount, transactionId)
+    );
+
+    return { queued: true, transactionId };
   }
 
   @Post(':accountId/transfer')
@@ -562,99 +521,50 @@ export class AccountController {
   ) {
     const transactionId = uuid();
     
-    await this.queueBus
-      .forProcessor(AccountProcessor)
-      .enqueue(new TransferCommand(
-        accountId,
-        body.toAccountId,
-        body.amount,
-        transactionId,
-      ));
-
-    return { 
-      queued: true, 
-      transactionId,
-      message: 'Transfer queued for processing',
-    };
+    await this.queueBus.enqueue(
+      new TransferCommand(accountId, body.toAccountId, body.amount, transactionId)
+    );
+
+    return { queued: true, transactionId };
   }
 }
 ```
 
 ---
 
-## Configuration
-
-```typescript
-AtomicQueuesModule.forRoot({
-  redis: {
-    host: 'localhost',
-    port: 6379,
-    password: 'secret',
-  },
-  
-  keyPrefix: 'myapp',           // Redis key prefix (default: 'aq')
-  
-  enableCronManager: true,       // Enable auto-scaling (default: false)
-  cronInterval: 5000,            // Scaling check interval (default: 5000ms)
-  
-  verbose: false,                // Enable verbose logging (default: false)
-                                 // When true, logs service job processing details
-  
-  workerDefaults: {
-    concurrency: 1,              // Jobs processed simultaneously
-    stalledInterval: 1000,       // Stalled job check interval
-    lockDuration: 30000,         // Job lock duration
-    heartbeatTTL: 3,             // Worker heartbeat TTL (seconds)
-  },
-});
-```
-
----
-
-## Command Registration
+## Advanced: Custom Worker Processors
 
-By default, atomic-queues **auto-discovers** all commands from your `@CommandHandler` and `@QueryHandler` decorators. No manual registration needed!
+For special cases where you need custom job handling logic, you can still define a `@WorkerProcessor`:
 
-### Auto-Discovery (Default)
+```typescript
+import { Injectable } from '@nestjs/common';
+import { WorkerProcessor, JobHandler } from 'atomic-queues';
+import { Job } from 'bullmq';
 
-Commands are automatically discovered when you have CQRS handlers:
+@WorkerProcessor({
+  entityType: 'account',
+  queueName: (id) => `${id}-queue`,
+  workerName: (id) => `${id}-worker`,
+  maxWorkersPerEntity: 1,
+  idleTimeoutSeconds: 15,
+})
+@Injectable()
+export class AccountProcessor {
+  // Custom handler for specific job types
+  @JobHandler('special-operation')
+  async handleSpecialOperation(job: Job, entityId: string) {
+    // Custom logic here
+  }
 
-```typescript
-// Your handler - that's all you need!
-@CommandHandler(ProcessOrderCommand)
-export class ProcessOrderHandler implements ICommandHandler<ProcessOrderCommand> {
-  async execute(command: ProcessOrderCommand) {
-    // ProcessOrderCommand is auto-registered with QueueBus
+  // Wildcard handler for everything else
+  @JobHandler('*')
+  async handleAll(job: Job, entityId: string) {
+    // Falls back to CQRS routing automatically
   }
 }
 ```
 
-### Manual Registration (Optional)
-
-If you need to register commands without handlers, or disable auto-discovery:
-
-```typescript
-// Disable auto-discovery in config
-AtomicQueuesModule.forRoot({
-  redis: { host: 'localhost', port: 6379 },
-  autoRegisterCommands: false, // Disable auto-discovery
-});
-
-// Then manually register
-QueueBus.registerCommands(ProcessOrderCommand, ShipOrderCommand);
-```
-
----
-
-## Why Use atomic-queues?
-
-| Feature | Without | With atomic-queues |
-|---------|---------|-------------------|
-| Sequential per-entity | Manual locking | Automatic via queues |
-| Race conditions | Possible | Prevented |
-| Worker management | Manual | Automatic |
-| Horizontal scaling | Complex | Built-in |
-| Code organization | Scattered | Clean decorators |
+**Note:** When you define a `@WorkerProcessor` for an entity type, it takes precedence over config-based default registration.
 
 ---