@ferrox-node/cqrs 1.1.1

package/dist/cqrs/cqrs-engine.d.ts

@@ -0,0 +1,12 @@
+export declare class CqrsEngine {
+    private handlers;
+    registerCommandHandler(type: string, handler: (cmd: any) => Promise<any>): void;
+    executeCommand(cmd: any): Promise<any>;
+}
+export declare class SagaOrchestrator {
+    private steps;
+    addStep(step: any): void;
+    execute(): Promise<{
+        success: boolean;
+    }>;
+}

package/dist/cqrs/cqrs-engine.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SagaOrchestrator = exports.CqrsEngine = void 0;
+class CqrsEngine {
+    handlers = new Map();
+    registerCommandHandler(type, handler) {
+        this.handlers.set(type, handler);
+    }
+    async executeCommand(cmd) {
+        const handler = this.handlers.get(cmd.type);
+        if (!handler)
+            throw new Error('No handler');
+        return handler(cmd);
+    }
+}
+exports.CqrsEngine = CqrsEngine;
+class SagaOrchestrator {
+    steps = [];
+    addStep(step) { this.steps.push(step); }
+    async execute() { return { success: true }; }
+}
+exports.SagaOrchestrator = SagaOrchestrator;

package/dist/cqrs/cqrs-saga.d.ts

@@ -0,0 +1,20 @@
+export interface SagaTransaction {
+    id: string;
+    payload: any;
+}
+export interface SagaStep {
+    name: string;
+    execute: (tx: SagaTransaction) => Promise<any>;
+    compensate: (tx: SagaTransaction, executeResult?: any) => Promise<void>;
+}
+export declare class AcidSagaCoordinator {
+    private steps;
+    /**
+     * Adds a step to the Distributed Transaction (SAGA)
+     */
+    addStep(name: string, execute: (tx: SagaTransaction) => Promise<any>, compensate: (tx: SagaTransaction, res?: any) => Promise<void>): this;
+    /**
+     * Executes the transaction. If any step fails, triggers the compensation (rollback) flow in reverse order.
+     */
+    execute(tx: SagaTransaction): Promise<void>;
+}

package/dist/cqrs/cqrs-saga.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AcidSagaCoordinator = void 0;
+const logger_1 = require("@node-yalc/logger");
+const logger = (0, logger_1.AppLoggerFactory)('SagaCoordinator');
+class AcidSagaCoordinator {
+    steps = [];
+    /**
+     * Adds a step to the Distributed Transaction (SAGA)
+     */
+    addStep(name, execute, compensate) {
+        this.steps.push({ name, execute, compensate });
+        return this;
+    }
+    /**
+     * Executes the transaction. If any step fails, triggers the compensation (rollback) flow in reverse order.
+     */
+    async execute(tx) {
+        const executedSteps = [];
+        logger.log(`[SAGA] Starting ACID Transaction ${tx.id} with ${this.steps.length} steps`);
+        for (const step of this.steps) {
+            try {
+                logger?.debug?.(`[SAGA] Executing step: ${step.name}`);
+                const result = await step.execute(tx);
+                executedSteps.push({ step, result });
+            }
+            catch (error) {
+                logger.error(`[SAGA] Transaction ${tx.id} failed at step '${step.name}'. Initiating compensation...`);
+                // Rollback sequentially in reverse
+                for (let i = executedSteps.length - 1; i >= 0; i--) {
+                    const { step: rollbackStep, result } = executedSteps[i];
+                    try {
+                        logger.warn(`[SAGA] Compensating step: ${rollbackStep.name}`);
+                        await rollbackStep.compensate(tx, result);
+                    }
+                    catch (compError) {
+                        logger.error(`[SAGA] CRITICAL: Compensation failed for step '${rollbackStep.name}': ${compError.message}`);
+                        // In a real CQRS, you would send this to a Dead Letter Queue or trigger manual intervention alerts
+                    }
+                }
+                throw new Error(`SAGA Transaction ${tx.id} aborted due to failure in step '${step.name}': ${error.message}`);
+            }
+        }
+        logger.log(`[SAGA] Transaction ${tx.id} completed successfully`);
+    }
+}
+exports.AcidSagaCoordinator = AcidSagaCoordinator;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './cqrs/cqrs-saga';
+export * from './cqrs/cqrs-engine';

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./cqrs/cqrs-saga"), exports);
+__exportStar(require("./cqrs/cqrs-engine"), exports);

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@ferrox-node/cqrs",
+  "version": "1.1.1",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@ferrox-node/core": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/src/cqrs/cqrs-saga.ts

@@ -0,0 +1,62 @@
+import { AppLoggerFactory } from '@node-yalc/logger';
+
+const logger = AppLoggerFactory('SagaCoordinator');
+
+export interface SagaTransaction {
+  id: string;
+  payload: any;
+}
+
+export interface SagaStep {
+  name: string;
+  execute: (tx: SagaTransaction) => Promise<any>;
+  compensate: (tx: SagaTransaction, executeResult?: any) => Promise<void>;
+}
+
+export class AcidSagaCoordinator {
+  private steps: SagaStep[] = [];
+
+  /**
+   * Adds a step to the Distributed Transaction (SAGA)
+   */
+  addStep(name: string, execute: (tx: SagaTransaction) => Promise<any>, compensate: (tx: SagaTransaction, res?: any) => Promise<void>): this {
+    this.steps.push({ name, execute, compensate });
+    return this;
+  }
+
+  /**
+   * Executes the transaction. If any step fails, triggers the compensation (rollback) flow in reverse order.
+   */
+  async execute(tx: SagaTransaction): Promise<void> {
+    const executedSteps: { step: SagaStep; result: any }[] = [];
+
+    logger.log(`[SAGA] Starting ACID Transaction ${tx.id} with ${this.steps.length} steps`);
+
+    for (const step of this.steps) {
+      try {
+        logger?.debug?.(`[SAGA] Executing step: ${step.name}`);
+        const result = await step.execute(tx);
+        executedSteps.push({ step, result });
+      } catch (error: any) {
+        logger.error(`[SAGA] Transaction ${tx.id} failed at step '${step.name}'. Initiating compensation...`);
+        
+        // Rollback sequentially in reverse
+        for (let i = executedSteps.length - 1; i >= 0; i--) {
+          const { step: rollbackStep, result } = executedSteps[i];
+          try {
+            logger.warn(`[SAGA] Compensating step: ${rollbackStep.name}`);
+            await rollbackStep.compensate(tx, result);
+          } catch (compError: any) {
+            logger.error(`[SAGA] CRITICAL: Compensation failed for step '${rollbackStep.name}': ${compError.message}`);
+            // In a real CQRS, you would send this to a Dead Letter Queue or trigger manual intervention alerts
+          }
+        }
+        
+        throw new Error(`SAGA Transaction ${tx.id} aborted due to failure in step '${step.name}': ${error.message}`);
+      }
+    }
+
+    logger.log(`[SAGA] Transaction ${tx.id} completed successfully`);
+  }
+}
+

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './cqrs/cqrs-saga';
+export * from './cqrs/cqrs-engine';

package/tests/cqrs-saga.spec.ts

@@ -0,0 +1,76 @@
+import { AcidSagaCoordinator } from '../src/cqrs/cqrs-saga';
+
+describe('AcidSagaCoordinator', () => {
+  it('should execute all steps successfully in order', async () => {
+    const saga = new AcidSagaCoordinator();
+    const trace: string[] = [];
+
+    saga.addStep(
+      'step1',
+      async () => { trace.push('step1-exec'); },
+      async () => { trace.push('step1-comp'); }
+    );
+    saga.addStep(
+      'step2',
+      async () => { trace.push('step2-exec'); },
+      async () => { trace.push('step2-comp'); }
+    );
+
+    await saga.execute({ id: 'tx-1', payload: {} });
+
+    expect(trace).toEqual(['step1-exec', 'step2-exec']);
+  });
+
+  it('should compensate backward in case of step failure', async () => {
+    const saga = new AcidSagaCoordinator();
+    const trace: string[] = [];
+
+    saga.addStep(
+      'ChargeCard',
+      async () => { trace.push('charged'); return { amount: 100 }; },
+      async () => { trace.push('refunded'); }
+    );
+    saga.addStep(
+      'BookInventory',
+      async () => { trace.push('booked'); },
+      async () => { trace.push('unbooked'); }
+    );
+    saga.addStep(
+      'ShipItem',
+      async () => { throw new Error('Warehouse offline'); },
+      async () => { trace.push('unshipped'); }
+    );
+
+    await expect(saga.execute({ id: 'tx-2', payload: {} })).rejects.toThrow('Warehouse offline');
+
+    // Expected: It charged, booked, then failed to ship.
+    // So it must UNbook first, then REFUND.
+    expect(trace).toEqual(['charged', 'booked', 'unbooked', 'refunded']);
+  });
+
+  it('should continue compensation even if a compensation step fails', async () => {
+    const saga = new AcidSagaCoordinator();
+    const trace: string[] = [];
+
+    saga.addStep(
+      'Step1',
+      async () => { trace.push('s1'); },
+      async () => { trace.push('c1'); }
+    );
+    saga.addStep(
+      'Step2',
+      async () => { trace.push('s2'); },
+      async () => { throw new Error('Compensation error'); }
+    );
+    saga.addStep(
+      'Step3',
+      async () => { throw new Error('Execution error'); },
+      async () => { trace.push('c3'); }
+    );
+
+    await expect(saga.execute({ id: 'tx-3', payload: {} })).rejects.toThrow('Execution error');
+    // Step1 and Step2 executed. Step3 failed.
+    // Compensation: Step2 throws error, Step1 continues compensation!
+    expect(trace).toEqual(['s1', 's2', 'c1']);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../core/tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "baseUrl": ".",
+  },
+  "include": [
+    "src/**/*"
+  ]
+}
+
+
+
+
+
+
+