@nestjs-transactional/cqrs 1.0.0-alpha.0

package/dist/module/cqrs-transactional.module.js

@@ -0,0 +1,137 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var CqrsTransactionalModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CqrsTransactionalModule = exports.CQRS_TRANSACTIONAL_OPTIONS = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const cqrs_1 = require("@nestjs/cqrs");
+const core_2 = require("@nestjs-transactional/core");
+const event_dispatcher_1 = require("../event-dispatcher/event-dispatcher");
+const hybrid_event_publisher_1 = require("../event-publisher/hybrid-event-publisher");
+const transactional_event_publisher_1 = require("../event-publisher/transactional-event-publisher");
+const transactional_event_publisher_adapter_1 = require("../event-publisher/transactional-event-publisher-adapter");
+const bootstrap_1 = require("../handlers/bootstrap");
+const handler_wrapper_1 = require("../handlers/handler-wrapper");
+const integration_events_handler_scanner_1 = require("../handlers/integration-events-handler-scanner");
+const listener_scanner_1 = require("../handlers/listener-scanner");
+/**
+ * DI token for the resolved {@link CqrsTransactionalOptions} object.
+ * Consumers normally do not inject this directly — it is used by the
+ * module's internal factory to pass options to {@link CqrsHandlerWrapper}.
+ */
+exports.CQRS_TRANSACTIONAL_OPTIONS = 'CQRS_TRANSACTIONAL_OPTIONS';
+/**
+ * NestJS module that wires the `@nestjs-transactional/cqrs` runtime:
+ *
+ * - {@link TransactionalEventDispatcher} for phase-aware event
+ *   routing.
+ * - {@link TransactionalListenerScanner} for auto-registration of
+ *   `@TransactionalEventsHandler`-decorated classes at module init.
+ * - {@link IntegrationEventsHandlerScanner} for
+ *   `@IntegrationEventsHandler`-decorated classes, with smart routing
+ *   to the outbox (when bound) or the dispatcher (otherwise).
+ * - {@link CqrsHandlerWrapper} + {@link CqrsTransactionalBootstrap}
+ *   to wrap `@CommandHandler` / `@QueryHandler` / `@EventsHandler`
+ *   execute/handle methods at application bootstrap.
+ * - {@link TransactionalEventPublisher} +
+ *   {@link TransactionalEventPublisherAdapter} as the `EventPublisher`
+ *   DI override so `AggregateRoot.commit()` flows through the
+ *   dispatcher.
+ *
+ * Pair with `TransactionalModule.forRoot({ isGlobal: true })` at the
+ * application root. For TypeORM-backed applications, also register
+ * adapters with `TypeOrmTransactionalModule.forFeature(...)`.
+ *
+ * @example
+ * ```ts
+ * @Module({
+ *   imports: [
+ *     TransactionalModule.forRoot({ isGlobal: true }),
+ *     TypeOrmTransactionalModule.forFeature({ dataSource: myDs }),
+ *     CqrsModule,
+ *     CqrsTransactionalModule.forRoot(),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * **Multi-dataSource setups** (Phase 14.7): the cqrs runtime is
+ * dataSource-agnostic by design. There is exactly one
+ * `CqrsTransactionalModule.forRoot()` per application regardless of
+ * how many dataSources are configured — multi-DS routing emerges
+ * from the structural-port wiring, not from a per-DS module instance.
+ *
+ * Wire {@link OUTBOX_PUBLICATION_SCHEDULER} and
+ * {@link OUTBOX_LISTENER_REGISTRAR} to the outbox stack you want
+ * cqrs to delegate to (`useExisting: OutboxEventPublisher` /
+ * `useExisting: OutboxListenerRegistry`). Apps with multiple outbox
+ * stacks (one `OutboxModule.forRoot()` per dataSource — ADR-019)
+ * choose which one cqrs bridges to via the `useExisting` target.
+ *
+ * Known limitation in multi-DS deployments: the in-memory
+ * dispatcher's hook-attachment goes through
+ * `TransactionManager.registerBeforeCommit` / `registerAfterCommit`,
+ * which target the first-active transaction on the current async
+ * context (non-deterministic across simultaneously-active
+ * cross-dataSource transactions). For cross-DS event handling
+ * prefer the outbox path — see `docs/known-limitations.md`.
+ */
+let CqrsTransactionalModule = CqrsTransactionalModule_1 = class CqrsTransactionalModule {
+    static forRoot(options = {}) {
+        const resolved = {
+            wrapCommandHandlers: options.wrapCommandHandlers ?? true,
+            wrapQueryHandlers: options.wrapQueryHandlers ?? true,
+            wrapEventHandlers: options.wrapEventHandlers ?? true,
+            useTransactionalEventPublisher: options.useTransactionalEventPublisher ?? true,
+            defaultQueryOptions: options.defaultQueryOptions ?? { readOnly: true },
+            defaultCommandOptions: options.defaultCommandOptions,
+        };
+        const providers = [
+            {
+                provide: exports.CQRS_TRANSACTIONAL_OPTIONS,
+                useValue: resolved,
+            },
+            event_dispatcher_1.TransactionalEventDispatcher,
+            listener_scanner_1.TransactionalListenerScanner,
+            integration_events_handler_scanner_1.IntegrationEventsHandlerScanner,
+            {
+                provide: handler_wrapper_1.CqrsHandlerWrapper,
+                useFactory: (discovery, manager, opts) => new handler_wrapper_1.CqrsHandlerWrapper(discovery, manager, opts),
+                inject: [core_1.DiscoveryService, core_2.TransactionManager, exports.CQRS_TRANSACTIONAL_OPTIONS],
+            },
+            bootstrap_1.CqrsTransactionalBootstrap,
+        ];
+        const exportTokens = [event_dispatcher_1.TransactionalEventDispatcher];
+        if (resolved.useTransactionalEventPublisher) {
+            // Keep TransactionalEventPublisher as a standalone provider for
+            // consumers that want the in-memory-only strategy. The adapter
+            // itself now routes through HybridEventPublisher, which picks
+            // up the optional outbox scheduler via @Optional injection.
+            providers.push(transactional_event_publisher_1.TransactionalEventPublisher);
+            providers.push(hybrid_event_publisher_1.HybridEventPublisher);
+            providers.push({
+                provide: cqrs_1.EventPublisher,
+                useFactory: (strategy, eventBus) => new transactional_event_publisher_adapter_1.TransactionalEventPublisherAdapter(strategy, eventBus),
+                inject: [hybrid_event_publisher_1.HybridEventPublisher, cqrs_1.EventBus],
+            });
+            exportTokens.push(transactional_event_publisher_1.TransactionalEventPublisher, hybrid_event_publisher_1.HybridEventPublisher, cqrs_1.EventPublisher);
+        }
+        return {
+            module: CqrsTransactionalModule_1,
+            imports: [core_1.DiscoveryModule, cqrs_1.CqrsModule],
+            providers,
+            exports: exportTokens,
+        };
+    }
+};
+exports.CqrsTransactionalModule = CqrsTransactionalModule;
+exports.CqrsTransactionalModule = CqrsTransactionalModule = CqrsTransactionalModule_1 = __decorate([
+    (0, common_1.Module)({})
+], CqrsTransactionalModule);
+//# sourceMappingURL=cqrs-transactional.module.js.map

package/dist/module/cqrs-transactional.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cqrs-transactional.module.js","sourceRoot":"","sources":["../../src/module/cqrs-transactional.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAA2E;AAC3E,uCAAiE;AACjE,uCAAoE;AACpE,qDAAgE;AAEhE,2EAAoF;AACpF,sFAAiF;AACjF,oGAA+F;AAC/F,oHAA8G;AAC9G,qDAAmE;AACnE,iEAA6F;AAC7F,uGAAiG;AACjG,mEAA4E;AAE5E;;;;GAIG;AACU,QAAA,0BAA0B,GAAG,4BAA4B,CAAC;AA2BvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEI,IAAM,uBAAuB,+BAA7B,MAAM,uBAAuB;IAClC,MAAM,CAAC,OAAO,CAAC,UAAoC,EAAE;QACnD,MAAM,QAAQ,GASsE;YAClF,mBAAmB,EAAE,OAAO,CAAC,mBAAmB,IAAI,IAAI;YACxD,iBAAiB,EAAE,OAAO,CAAC,iBAAiB,IAAI,IAAI;YACpD,iBAAiB,EAAE,OAAO,CAAC,iBAAiB,IAAI,IAAI;YACpD,8BAA8B,EAAE,OAAO,CAAC,8BAA8B,IAAI,IAAI;YAC9E,mBAAmB,EAAE,OAAO,CAAC,mBAAmB,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;YACtE,qBAAqB,EAAE,OAAO,CAAC,qBAAqB;SACrD,CAAC;QAEF,MAAM,SAAS,GAAe;YAC5B;gBACE,OAAO,EAAE,kCAA0B;gBACnC,QAAQ,EAAE,QAAQ;aACnB;YACD,+CAA4B;YAC5B,+CAA4B;YAC5B,oEAA+B;YAC/B;gBACE,OAAO,EAAE,oCAAkB;gBAC3B,UAAU,EAAE,CACV,SAA2B,EAC3B,OAA2B,EAC3B,IAA2B,EACP,EAAE,CAAC,IAAI,oCAAkB,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC;gBACzE,MAAM,EAAE,CAAC,uBAAgB,EAAE,yBAAkB,EAAE,kCAA0B,CAAC;aAC3E;YACD,sCAA0B;SAC3B,CAAC;QAEF,MAAM,YAAY,GAAc,CAAC,+CAA4B,CAAC,CAAC;QAE/D,IAAI,QAAQ,CAAC,8BAA8B,EAAE,CAAC;YAC5C,gEAAgE;YAChE,+DAA+D;YAC/D,8DAA8D;YAC9D,4DAA4D;YAC5D,SAAS,CAAC,IAAI,CAAC,2DAA2B,CAAC,CAAC;YAC5C,SAAS,CAAC,IAAI,CAAC,6CAAoB,CAAC,CAAC;YACrC,SAAS,CAAC,IAAI,CAAC;gBACb,OAAO,EAAE,qBAAc;gBACvB,UAAU,EAAE,CACV,QAA8B,EAC9B,QAAkB,EACkB,EAAE,CACtC,IAAI,0EAAkC,CAAC,QAAQ,EAAE,QAAQ,CAAC;gBAC5D,MAAM,EAAE,CAAC,6CAAoB,EAAE,eAAQ,CAAC;aACzC,CAAC,CAAC;YACH,YAAY,CAAC,IAAI,CAAC,2DAA2B,EAAE,6CAAoB,EAAE,qBAAc,CAAC,CAAC;QACvF,CAAC;QAED,OAAO;YACL,MAAM,EAAE,yBAAuB;YAC/B,OAAO,EAAE,CAAC,sBAAe,EAAE,iBAAU,CAAC;YACtC,SAAS;YACT,OAAO,EAAE,YAAuB;SACjC,CAAC;IACJ,CAAC;CACF,CAAA;AApEY,0DAAuB;kCAAvB,uBAAuB;IADnC,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,uBAAuB,CAoEnC"}

package/dist/types/transactional-listener.types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Transaction lifecycle phase at which a `@TransactionalEventsHandler`
+ * runs. Mirrors Spring's `TransactionPhase` — see the package README
+ * for semantics.
+ *
+ * - {@link BEFORE_COMMIT}: handler runs before commit; a thrown error
+ *   causes the transaction to roll back (unless `async: true`).
+ * - {@link AFTER_COMMIT}: default. Handler runs only after the
+ *   transaction has successfully committed. The canonical "publish
+ *   domain event" phase.
+ * - {@link AFTER_ROLLBACK}: handler runs after a rollback.
+ * - {@link AFTER_COMPLETION}: handler runs on any completion (commit
+ *   or rollback).
+ */
+export declare enum TransactionPhase {
+    BEFORE_COMMIT = "BEFORE_COMMIT",
+    AFTER_COMMIT = "AFTER_COMMIT",
+    AFTER_ROLLBACK = "AFTER_ROLLBACK",
+    AFTER_COMPLETION = "AFTER_COMPLETION"
+}
+//# sourceMappingURL=transactional-listener.types.d.ts.map

package/dist/types/transactional-listener.types.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionPhase = void 0;
+/**
+ * Transaction lifecycle phase at which a `@TransactionalEventsHandler`
+ * runs. Mirrors Spring's `TransactionPhase` — see the package README
+ * for semantics.
+ *
+ * - {@link BEFORE_COMMIT}: handler runs before commit; a thrown error
+ *   causes the transaction to roll back (unless `async: true`).
+ * - {@link AFTER_COMMIT}: default. Handler runs only after the
+ *   transaction has successfully committed. The canonical "publish
+ *   domain event" phase.
+ * - {@link AFTER_ROLLBACK}: handler runs after a rollback.
+ * - {@link AFTER_COMPLETION}: handler runs on any completion (commit
+ *   or rollback).
+ */
+var TransactionPhase;
+(function (TransactionPhase) {
+    TransactionPhase["BEFORE_COMMIT"] = "BEFORE_COMMIT";
+    TransactionPhase["AFTER_COMMIT"] = "AFTER_COMMIT";
+    TransactionPhase["AFTER_ROLLBACK"] = "AFTER_ROLLBACK";
+    TransactionPhase["AFTER_COMPLETION"] = "AFTER_COMPLETION";
+})(TransactionPhase || (exports.TransactionPhase = TransactionPhase = {}));
+//# sourceMappingURL=transactional-listener.types.js.map

package/dist/types/transactional-listener.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactional-listener.types.js","sourceRoot":"","sources":["../../src/types/transactional-listener.types.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;GAaG;AACH,IAAY,gBAKX;AALD,WAAY,gBAAgB;IAC1B,mDAA+B,CAAA;IAC/B,iDAA6B,CAAA;IAC7B,qDAAiC,CAAA;IACjC,yDAAqC,CAAA;AACvC,CAAC,EALW,gBAAgB,gCAAhB,gBAAgB,QAK3B"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@nestjs-transactional/cqrs",
+  "version": "1.0.0-alpha.0",
+  "description": "@nestjs/cqrs integration for @nestjs-transactional/core — transactional event listeners with phases, handler wrapping, AggregateRoot integration",
+  "license": "MIT",
+  "author": "Igor Golovanov",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/igorgolovanov/nestjs-transactional.git",
+    "directory": "packages/cqrs"
+  },
+  "bugs": {
+    "url": "https://github.com/igorgolovanov/nestjs-transactional/issues"
+  },
+  "homepage": "https://github.com/igorgolovanov/nestjs-transactional/tree/main/packages/cqrs#readme",
+  "keywords": [
+    "nestjs",
+    "cqrs",
+    "transaction",
+    "transactional",
+    "spring",
+    "event-listener",
+    "aggregate-root",
+    "after-commit"
+  ],
+  "engines": {
+    "node": ">=22.11.0"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.js.map",
+    "!dist/**/*.spec.*"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "@nestjs/core": "^10.0.0 || ^11.0.0",
+    "@nestjs/cqrs": "^11.0.0",
+    "reflect-metadata": "^0.1.13 || ^0.2.0",
+    "rxjs": "^7.0.0",
+    "@nestjs-transactional/core": "^1.0.0-alpha.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/cqrs": "^11.0.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "@nestjs-transactional/core": "1.0.0-alpha.0",
+    "@nestjs-transactional/outbox": "1.0.0-alpha.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rimraf dist *.tsbuildinfo coverage",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:cov": "jest --coverage",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint \"src/**/*.ts\""
+  }
+}