atomic-queues 1.2.3 → 1.2.5

package/README.md

@@ -5,30 +5,40 @@ A NestJS library for atomic, sequential job processing per entity with BullMQ an
 ## What It Does
 
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                     THE PROBLEM                                  │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                  │
-│  Multiple requests for the same entity arrive simultaneously:    │
-│                                                                  │
-│    Request A ───┐                                                │
-│    Request B ───┼──► Entity 123 ──► 💥 RACE CONDITION!          │
-│    Request C ───┘                                                │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
-
-┌─────────────────────────────────────────────────────────────────┐
-│                     THE SOLUTION                                 │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                  │
-│  atomic-queues ensures sequential processing per entity:         │
-│                                                                  │
-│    Request A ───┐     ┌─────────┐                                │
-│    Request B ───┼──►  │ Queue   │  ──► Worker ──► Entity 123    │
-│    Request C ───┘     │ A, B, C │      (1 at a time)            │
-│                       └─────────┘                                │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
+╔═══════════════════════════════════════════════════════════════════════════════╗
+║                              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           ║
+║                                                                                ║
+╚═══════════════════════════════════════════════════════════════════════════════╝
 ```
 
 ## Installation
@@ -132,40 +142,69 @@ That's it! The library automatically:
 ## How It Works
 
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                        FLOW DIAGRAM                              │
-└─────────────────────────────────────────────────────────────────┘
-
-  YOUR CODE                    ATOMIC-QUEUES                 WORKER
-  ─────────                    ─────────────                 ──────
-
-  queueBus
-    .forProcessor(OrderProcessor)
-    .enqueue(new ProcessOrderCommand(...))
-           │
-           │ 1. Extract queue config from @WorkerProcessor
-           │ 2. Extract orderId from command.orderId
-           │ 3. Build queue name: order-{orderId}-queue
-           ▼
-    ┌─────────────┐
-    │   Redis     │
-    │   Queue     │  ◄─── Job: { name: "ProcessOrderCommand", data: {...} }
-    └──────┬──────┘
-           │
-           │ 4. Worker pulls job from queue
-           ▼
-    ┌─────────────┐
-    │   Worker    │
-    │ (1 per ID)  │
-    └──────┬──────┘
-           │
-           │ 5. Lookup ProcessOrderCommand in registry
-           │ 6. Instantiate command from job.data
-           │ 7. Execute via CommandBus
-           ▼
-    ┌─────────────┐
-    │ CommandBus  │  ──►  ProcessOrderCommandHandler.execute()
-    └─────────────┘
+╔═══════════════════════════════════════════════════════════════════════════════╗
+║                              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);                       │
+│    }                                                                         │
+│  }                                                                           │
+└──────────────────────────────────────────────────────────────────────────────┘
 ```
 
 ---
@@ -281,109 +320,262 @@ export class OrderScaler {
 
 ## Complete Example
 
+A banking service handling critical financial transactions where race conditions could cause overdrafts or double-spending:
+
 ```typescript
 // ─────────────────────────────────────────────────────────────────
-// commands/place-bet.command.ts
+// commands/withdraw.command.ts
+// ─────────────────────────────────────────────────────────────────
+export class WithdrawCommand {
+  constructor(
+    public readonly accountId: string,
+    public readonly amount: number,
+    public readonly transactionId: string,
+    public readonly requestedBy: string,
+  ) {}
+}
+
+// ─────────────────────────────────────────────────────────────────
+// commands/deposit.command.ts
 // ─────────────────────────────────────────────────────────────────
-export class PlaceBetCommand {
+export class DepositCommand {
   constructor(
-    public readonly tableId: string,
-    public readonly playerId: string,
+    public readonly accountId: string,
     public readonly amount: number,
+    public readonly transactionId: string,
+    public readonly source: string,
   ) {}
 }
 
 // ─────────────────────────────────────────────────────────────────
-// commands/deal-cards.command.ts
+// commands/transfer.command.ts
 // ─────────────────────────────────────────────────────────────────
-export class DealCardsCommand {
+export class TransferCommand {
   constructor(
-    public readonly tableId: string,
+    public readonly accountId: string,  // Source account (for queue routing)
+    public readonly toAccountId: string,
+    public readonly amount: number,
+    public readonly transactionId: string,
   ) {}
 }
 
 // ─────────────────────────────────────────────────────────────────
-// handlers/place-bet.handler.ts (auto-registers PlaceBetCommand)
+// handlers/withdraw.handler.ts
 // ─────────────────────────────────────────────────────────────────
 import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
-import { PlaceBetCommand } from '../commands/place-bet.command';
+import { WithdrawCommand } from '../commands';
 
-@CommandHandler(PlaceBetCommand)
-export class PlaceBetHandler implements ICommandHandler<PlaceBetCommand> {
-  async execute(command: PlaceBetCommand) {
-    console.log(`Placing bet of ${command.amount} for player ${command.playerId}`);
+@CommandHandler(WithdrawCommand)
+export class WithdrawHandler implements ICommandHandler<WithdrawCommand> {
+  constructor(
+    private readonly accountRepo: AccountRepository,
+    private readonly ledger: LedgerService,
+  ) {}
+
+  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 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 
+    };
   }
 }
 
 // ─────────────────────────────────────────────────────────────────
-// handlers/deal-cards.handler.ts (auto-registers DealCardsCommand)
+// handlers/transfer.handler.ts
 // ─────────────────────────────────────────────────────────────────
 import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
-import { DealCardsCommand } from '../commands/deal-cards.command';
+import { TransferCommand, DepositCommand } from '../commands';
+import { QueueBus } from 'atomic-queues';
 
-@CommandHandler(DealCardsCommand)
-export class DealCardsHandler implements ICommandHandler<DealCardsCommand> {
-  async execute(command: DealCardsCommand) {
-    console.log(`Dealing cards for table ${command.tableId}`);
+@CommandHandler(TransferCommand)
+export class TransferHandler implements ICommandHandler<TransferCommand> {
+  constructor(
+    private readonly accountRepo: AccountRepository,
+    private readonly queueBus: QueueBus,
+  ) {}
+
+  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);
+    
+    if (sourceAccount.balance < amount) {
+      throw new InsufficientFundsError(accountId, sourceAccount.balance, amount);
+    }
+    
+    sourceAccount.balance -= amount;
+    await this.accountRepo.save(sourceAccount);
+    
+    // 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}`,
+      ));
+    
+    return { success: true, transactionId };
   }
 }
 
 // ─────────────────────────────────────────────────────────────────
-// table.processor.ts
+// account.processor.ts
 // ─────────────────────────────────────────────────────────────────
 import { Injectable } from '@nestjs/common';
 import { WorkerProcessor } from 'atomic-queues';
 
 @WorkerProcessor({
-  entityType: 'table',
-  queueName: (tableId) => `table-${tableId}-queue`,
-  workerName: (tableId) => `table-${tableId}-worker`,
+  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 TableProcessor {}
+export class AccountProcessor {}
 
 // ─────────────────────────────────────────────────────────────────
-// table.module.ts - No manual registration needed!
+// 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';
-import { TableProcessor } from './table.processor';
-import { TableGateway } from './table.gateway';
-import { PlaceBetHandler, DealCardsHandler } from './handlers';
 
 @Module({
   imports: [CqrsModule],
   providers: [
-    TableProcessor,
-    TableGateway,
-    PlaceBetHandler,   // Commands auto-discovered from handlers!
-    DealCardsHandler,
+    AccountProcessor,
+    AccountScaler,
+    WithdrawHandler,    // Commands auto-discovered!
+    DepositHandler,
+    TransferHandler,
   ],
+  controllers: [AccountController],
 })
-export class TableModule {}
+export class AccountModule {}
 
 // ─────────────────────────────────────────────────────────────────
-// table.gateway.ts (WebSocket example)
+// account.controller.ts
 // ─────────────────────────────────────────────────────────────────
-import { Injectable } from '@nestjs/common';
+import { Controller, Post, Body, Param } from '@nestjs/common';
 import { QueueBus } from 'atomic-queues';
-import { TableProcessor } from './table.processor';
-import { PlaceBetCommand, DealCardsCommand } from './commands';
+import { AccountProcessor } from './account.processor';
+import { WithdrawCommand, DepositCommand, TransferCommand } from './commands';
+import { v4 as uuid } from 'uuid';
 
-@Injectable()
-export class TableGateway {
+@Controller('accounts')
+export class AccountController {
   constructor(private readonly queueBus: QueueBus) {}
 
-  async onPlaceBet(tableId: string, playerId: string, amount: number) {
+  @Post(':accountId/withdraw')
+  async withdraw(
+    @Param('accountId') accountId: string,
+    @Body() body: { amount: number; requestedBy: string },
+  ) {
+    const transactionId = uuid();
+    
+    // Even if user spam-clicks "Withdraw", each request is queued
+    // and processed sequentially - no double-withdrawals possible
     await this.queueBus
-      .forProcessor(TableProcessor)
-      .enqueue(new PlaceBetCommand(tableId, playerId, amount));
+      .forProcessor(AccountProcessor)
+      .enqueue(new WithdrawCommand(
+        accountId,
+        body.amount,
+        transactionId,
+        body.requestedBy,
+      ));
+
+    return { 
+      queued: true, 
+      transactionId,
+      message: 'Withdrawal queued for processing',
+    };
   }
 
-  async onDealCards(tableId: string) {
+  @Post(':accountId/transfer')
+  async transfer(
+    @Param('accountId') accountId: string,
+    @Body() body: { toAccountId: string; amount: number },
+  ) {
+    const transactionId = uuid();
+    
     await this.queueBus
-      .forProcessor(TableProcessor)
-      .enqueue(new DealCardsCommand(tableId));
+      .forProcessor(AccountProcessor)
+      .enqueue(new TransferCommand(
+        accountId,
+        body.toAccountId,
+        body.amount,
+        transactionId,
+      ));
+
+    return { 
+      queued: true, 
+      transactionId,
+      message: 'Transfer queued for processing',
+    };
   }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atomic-queues",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "A plug-and-play NestJS library for atomic process handling per entity with BullMQ, Redis distributed locking, and dynamic worker management",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",