@nestjs-transactional/cqrs 1.0.0-alpha.0

package/dist/handlers/integration-events-handler-scanner.d.ts

@@ -0,0 +1,37 @@
+import { type OnModuleInit } from '@nestjs/common';
+import { DiscoveryService } from '@nestjs/core';
+import { TransactionManager } from '@nestjs-transactional/core';
+import { TransactionalEventDispatcher } from '../event-dispatcher/event-dispatcher';
+import { type OutboxListenerRegistrar } from './outbox-listener-registrar';
+/**
+ * Bootstrap-time scanner for `@IntegrationEventsHandler`-annotated
+ * classes. Decides at startup which delivery path to wire based on
+ * whether an {@link OutboxListenerRegistrar} is bound:
+ *
+ * - **Outbox bound** (typically via `OutboxModule` from
+ *   `@nestjs-transactional/outbox`): the handler's `handle`
+ *   method is registered with the outbox registry, wrapped in a
+ *   `REQUIRES_NEW` transaction. Delivery is durable, at-least-once,
+ *   retried on failure, survives restarts.
+ *
+ * - **Outbox not bound**: the handler is registered with
+ *   {@link TransactionalEventDispatcher} for `AFTER_COMMIT` phase,
+ *   `async: true` — and the scanner itself wraps the invocation in a
+ *   fresh transaction so downstream writes commit or roll back
+ *   independently, matching the outbox path as closely as in-memory
+ *   dispatch allows (minus persistence).
+ *
+ * Consumer code is identical either way; only module wiring decides.
+ */
+export declare class IntegrationEventsHandlerScanner implements OnModuleInit {
+    private readonly discovery;
+    private readonly dispatcher;
+    private readonly manager;
+    private readonly registrar?;
+    private readonly logger;
+    constructor(discovery: DiscoveryService, dispatcher: TransactionalEventDispatcher, manager: TransactionManager, registrar?: OutboxListenerRegistrar | undefined);
+    onModuleInit(): void;
+    private registerToOutbox;
+    private registerToDispatcher;
+}
+//# sourceMappingURL=integration-events-handler-scanner.d.ts.map

package/dist/handlers/integration-events-handler-scanner.js

@@ -0,0 +1,144 @@
+"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 __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var IntegrationEventsHandlerScanner_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IntegrationEventsHandlerScanner = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const core_2 = require("@nestjs-transactional/core");
+const integration_events_handler_decorator_1 = require("../decorators/integration-events-handler.decorator");
+const event_dispatcher_1 = require("../event-dispatcher/event-dispatcher");
+const transactional_listener_types_1 = require("../types/transactional-listener.types");
+const outbox_listener_registrar_1 = require("./outbox-listener-registrar");
+/**
+ * Bootstrap-time scanner for `@IntegrationEventsHandler`-annotated
+ * classes. Decides at startup which delivery path to wire based on
+ * whether an {@link OutboxListenerRegistrar} is bound:
+ *
+ * - **Outbox bound** (typically via `OutboxModule` from
+ *   `@nestjs-transactional/outbox`): the handler's `handle`
+ *   method is registered with the outbox registry, wrapped in a
+ *   `REQUIRES_NEW` transaction. Delivery is durable, at-least-once,
+ *   retried on failure, survives restarts.
+ *
+ * - **Outbox not bound**: the handler is registered with
+ *   {@link TransactionalEventDispatcher} for `AFTER_COMMIT` phase,
+ *   `async: true` — and the scanner itself wraps the invocation in a
+ *   fresh transaction so downstream writes commit or roll back
+ *   independently, matching the outbox path as closely as in-memory
+ *   dispatch allows (minus persistence).
+ *
+ * Consumer code is identical either way; only module wiring decides.
+ */
+let IntegrationEventsHandlerScanner = IntegrationEventsHandlerScanner_1 = class IntegrationEventsHandlerScanner {
+    discovery;
+    dispatcher;
+    manager;
+    registrar;
+    logger = new common_1.Logger(IntegrationEventsHandlerScanner_1.name);
+    constructor(discovery, dispatcher, manager, registrar) {
+        this.discovery = discovery;
+        this.dispatcher = dispatcher;
+        this.manager = manager;
+        this.registrar = registrar;
+    }
+    onModuleInit() {
+        const providers = this.discovery.getProviders();
+        for (const wrapper of providers) {
+            if (wrapper.metatype === null ||
+                typeof wrapper.metatype !== 'function' ||
+                wrapper.instance === null ||
+                wrapper.instance === undefined) {
+                continue;
+            }
+            const metadata = (0, integration_events_handler_decorator_1.getIntegrationEventsHandlerMetadata)(wrapper.metatype);
+            if (metadata === undefined) {
+                continue;
+            }
+            const instance = wrapper.instance;
+            const rawHandle = instance.handle;
+            if (typeof rawHandle !== 'function') {
+                const className = wrapper.metatype.name ?? 'anonymous';
+                this.logger.warn(`@IntegrationEventsHandler on ${className}: missing \`handle(event)\` method — skipping`);
+                continue;
+            }
+            const boundHandle = rawHandle.bind(instance);
+            if (this.registrar !== undefined) {
+                this.registerToOutbox(instance, metadata, boundHandle, this.registrar);
+            }
+            else {
+                this.registerToDispatcher(instance, metadata, boundHandle);
+            }
+        }
+    }
+    registerToOutbox(instance, metadata, boundHandle, registrar) {
+        const manager = this.manager;
+        const invoke = async (event) => {
+            await manager.run({ propagation: core_2.PropagationMode.REQUIRES_NEW }, async () => {
+                await boundHandle(event);
+            });
+        };
+        const baseId = metadata.id ?? instance.constructor.name;
+        for (const eventType of metadata.eventTypes) {
+            const listenerId = composeListenerId(baseId, eventType);
+            registrar.register({
+                id: listenerId,
+                eventType: eventType.name,
+                invoke,
+            });
+            this.logger.debug(`Registered ${instance.constructor.name}.handle for ${eventType.name} via outbox (id=${listenerId})`);
+        }
+    }
+    registerToDispatcher(instance, metadata, boundHandle) {
+        const manager = this.manager;
+        // Proxy preserves the original class name for dispatcher logs
+        // while exposing a `handle` that opens a fresh transaction per
+        // invocation — AFTER_COMMIT + async + a new tx, matching the
+        // outbox semantics as closely as in-memory dispatch permits.
+        const ctor = instance.constructor;
+        const proxy = Object.create(ctor.prototype);
+        proxy.handle = async (event) => {
+            await manager.run({}, async () => {
+                await boundHandle(event);
+            });
+        };
+        for (const eventType of metadata.eventTypes) {
+            this.dispatcher.registerListener(proxy, 'handle', {
+                eventType,
+                phase: transactional_listener_types_1.TransactionPhase.AFTER_COMMIT,
+                async: true,
+                fallbackExecution: false,
+                dataSource: metadata.dataSource,
+            });
+        }
+    }
+};
+exports.IntegrationEventsHandlerScanner = IntegrationEventsHandlerScanner;
+exports.IntegrationEventsHandlerScanner = IntegrationEventsHandlerScanner = IntegrationEventsHandlerScanner_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(3, (0, common_1.Optional)()),
+    __param(3, (0, common_1.Inject)(outbox_listener_registrar_1.OUTBOX_LISTENER_REGISTRAR)),
+    __metadata("design:paramtypes", [core_1.DiscoveryService,
+        event_dispatcher_1.TransactionalEventDispatcher,
+        core_2.TransactionManager, Object])
+], IntegrationEventsHandlerScanner);
+/**
+ * Compose the stable listener id. Always ends with `#${EventName}`
+ * so a single class handling multiple event types gets distinct ids
+ * — the registry requires globally-unique ids.
+ */
+function composeListenerId(baseId, eventType) {
+    return `${baseId}#${eventType.name}`;
+}
+//# sourceMappingURL=integration-events-handler-scanner.js.map

package/dist/handlers/integration-events-handler-scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration-events-handler-scanner.js","sourceRoot":"","sources":["../../src/handlers/integration-events-handler-scanner.ts"],"names":[],"mappings":"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"}

package/dist/handlers/listener-scanner.d.ts

@@ -0,0 +1,33 @@
+import { type OnModuleInit } from '@nestjs/common';
+import { DiscoveryService } from '@nestjs/core';
+import { TransactionalEventDispatcher } from '../event-dispatcher/event-dispatcher';
+/**
+ * Bootstrap-time scanner that walks every provider in the running
+ * Nest application, finds every class decorated with
+ * `@TransactionalEventsHandler`, and registers its `handle` method
+ * with the {@link TransactionalEventDispatcher} — one registration
+ * per event type listed in the decorator metadata.
+ *
+ * Scanning is class-level only. The handler class must expose a
+ * `handle(event): void | Promise<void>` method (enforce this at the
+ * type level by implementing `ITransactionalEventHandler`).
+ *
+ * `@IntegrationEventsHandler` is NOT processed here —
+ * `IntegrationEventsHandlerScanner` owns it, with smart routing to
+ * the outbox or this dispatcher depending on which provider is bound.
+ *
+ * Registration happens in `onModuleInit` so all providers have been
+ * instantiated by the time the scan runs. Providers with no instance
+ * or no metatype are skipped silently.
+ *
+ * Wired into the application by `CqrsTransactionalModule`. Not
+ * exported for direct consumer instantiation.
+ */
+export declare class TransactionalListenerScanner implements OnModuleInit {
+    private readonly discovery;
+    private readonly dispatcher;
+    private readonly logger;
+    constructor(discovery: DiscoveryService, dispatcher: TransactionalEventDispatcher);
+    onModuleInit(): void;
+}
+//# sourceMappingURL=listener-scanner.d.ts.map

package/dist/handlers/listener-scanner.js

@@ -0,0 +1,86 @@
+"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 __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var TransactionalListenerScanner_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionalListenerScanner = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const transactional_events_handler_decorator_1 = require("../decorators/transactional-events-handler.decorator");
+const event_dispatcher_1 = require("../event-dispatcher/event-dispatcher");
+/**
+ * Bootstrap-time scanner that walks every provider in the running
+ * Nest application, finds every class decorated with
+ * `@TransactionalEventsHandler`, and registers its `handle` method
+ * with the {@link TransactionalEventDispatcher} — one registration
+ * per event type listed in the decorator metadata.
+ *
+ * Scanning is class-level only. The handler class must expose a
+ * `handle(event): void | Promise<void>` method (enforce this at the
+ * type level by implementing `ITransactionalEventHandler`).
+ *
+ * `@IntegrationEventsHandler` is NOT processed here —
+ * `IntegrationEventsHandlerScanner` owns it, with smart routing to
+ * the outbox or this dispatcher depending on which provider is bound.
+ *
+ * Registration happens in `onModuleInit` so all providers have been
+ * instantiated by the time the scan runs. Providers with no instance
+ * or no metatype are skipped silently.
+ *
+ * Wired into the application by `CqrsTransactionalModule`. Not
+ * exported for direct consumer instantiation.
+ */
+let TransactionalListenerScanner = TransactionalListenerScanner_1 = class TransactionalListenerScanner {
+    discovery;
+    dispatcher;
+    logger = new common_1.Logger(TransactionalListenerScanner_1.name);
+    constructor(discovery, dispatcher) {
+        this.discovery = discovery;
+        this.dispatcher = dispatcher;
+    }
+    onModuleInit() {
+        const providers = this.discovery.getProviders();
+        for (const wrapper of providers) {
+            if (wrapper.metatype === null ||
+                typeof wrapper.metatype !== 'function' ||
+                wrapper.instance === null ||
+                wrapper.instance === undefined) {
+                continue;
+            }
+            const metadata = (0, transactional_events_handler_decorator_1.getTransactionalEventsHandlerMetadata)(wrapper.metatype);
+            if (metadata === undefined) {
+                continue;
+            }
+            const instance = wrapper.instance;
+            const handleMethod = instance.handle;
+            if (typeof handleMethod !== 'function') {
+                const className = wrapper.metatype.name ?? 'anonymous';
+                this.logger.warn(`@TransactionalEventsHandler on ${className}: missing \`handle(event)\` method — skipping`);
+                continue;
+            }
+            for (const eventType of metadata.eventTypes) {
+                this.dispatcher.registerListener(instance, 'handle', {
+                    eventType,
+                    phase: metadata.phase,
+                    async: metadata.async,
+                    fallbackExecution: metadata.fallbackExecution,
+                    dataSource: metadata.dataSource,
+                });
+            }
+        }
+    }
+};
+exports.TransactionalListenerScanner = TransactionalListenerScanner;
+exports.TransactionalListenerScanner = TransactionalListenerScanner = TransactionalListenerScanner_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [core_1.DiscoveryService,
+        event_dispatcher_1.TransactionalEventDispatcher])
+], TransactionalListenerScanner);
+//# sourceMappingURL=listener-scanner.js.map

package/dist/handlers/listener-scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener-scanner.js","sourceRoot":"","sources":["../../src/handlers/listener-scanner.ts"],"names":[],"mappings":";;;;;;;;;;;;;AAAA,2CAAuE;AACvE,uCAAgD;AAEhD,iHAA6G;AAC7G,2EAAoF;AAEpF;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEI,IAAM,4BAA4B,oCAAlC,MAAM,4BAA4B;IAIpB;IACA;IAJF,MAAM,GAAG,IAAI,eAAM,CAAC,8BAA4B,CAAC,IAAI,CAAC,CAAC;IAExE,YACmB,SAA2B,EAC3B,UAAwC;QADxC,cAAS,GAAT,SAAS,CAAkB;QAC3B,eAAU,GAAV,UAAU,CAA8B;IACxD,CAAC;IAEJ,YAAY;QACV,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,CAAC;QAEhD,KAAK,MAAM,OAAO,IAAI,SAAS,EAAE,CAAC;YAChC,IACE,OAAO,CAAC,QAAQ,KAAK,IAAI;gBACzB,OAAO,OAAO,CAAC,QAAQ,KAAK,UAAU;gBACtC,OAAO,CAAC,QAAQ,KAAK,IAAI;gBACzB,OAAO,CAAC,QAAQ,KAAK,SAAS,EAC9B,CAAC;gBACD,SAAS;YACX,CAAC;YAED,MAAM,QAAQ,GAAG,IAAA,8EAAqC,EAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YACzE,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,SAAS;YACX,CAAC;YAED,MAAM,QAAQ,GAAW,OAAO,CAAC,QAAkB,CAAC;YACpD,MAAM,YAAY,GAAI,QAAoC,CAAC,MAAM,CAAC;YAClE,IAAI,OAAO,YAAY,KAAK,UAAU,EAAE,CAAC;gBACvC,MAAM,SAAS,GAAI,OAAO,CAAC,QAA8B,CAAC,IAAI,IAAI,WAAW,CAAC;gBAC9E,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,kCAAkC,SAAS,+CAA+C,CAC3F,CAAC;gBACF,SAAS;YACX,CAAC;YAED,KAAK,MAAM,SAAS,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC;gBAC5C,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE;oBACnD,SAAS;oBACT,KAAK,EAAE,QAAQ,CAAC,KAAK;oBACrB,KAAK,EAAE,QAAQ,CAAC,KAAK;oBACrB,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB;oBAC7C,UAAU,EAAE,QAAQ,CAAC,UAAU;iBAChC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;CACF,CAAA;AA/CY,oEAA4B;uCAA5B,4BAA4B;IADxC,IAAA,mBAAU,GAAE;qCAKmB,uBAAgB;QACf,+CAA4B;GALhD,4BAA4B,CA+CxC"}

package/dist/handlers/outbox-listener-registrar.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Minimal structural contract for an outbox listener registrar,
+ * declared here (and injected via {@link OUTBOX_LISTENER_REGISTRAR})
+ * rather than imported from `@nestjs-transactional/outbox`
+ * directly — keeps the cqrs package usable without the outbox stack.
+ *
+ * `@nestjs-transactional/outbox`'s `OutboxListenerRegistry`
+ * satisfies this interface structurally (its `register` method
+ * accepts exactly this shape). The outbox package's
+ * `MultiDsOutboxListenerRegistrar` (Phase 14.3.1) is a smarter
+ * implementation that walks every per-dataSource event-type registry
+ * to resolve which dataSource owns each listener's event class and
+ * routes the registration to the matching per-DS registry — so a
+ * single binding handles arbitrary multi-dataSource deployments.
+ *
+ * **Auto-binding (Phase 14.3.1).** `OutboxModule.forRoot` binds this
+ * token to `MultiDsOutboxListenerRegistrar` automatically on the
+ * first `forRoot` call. Consumers do NOT need to declare the binding
+ * themselves; the registrar is in place by the time the cqrs
+ * `IntegrationEventsHandlerScanner` runs its `onModuleInit`. Manual
+ * binding remains supported for advanced cases (custom routing
+ * policy, structural decoupling tests).
+ *
+ * Cross-package token identity is via `Symbol.for(...)` so the cqrs
+ * declaration and the outbox auto-binding refer to the same Symbol
+ * without either package importing from the other (Convention #8 —
+ * mirrors `WRAPPED_MARKER`).
+ */
+export interface OutboxListenerRegistrar {
+    register(listener: {
+        readonly id: string;
+        readonly eventType: string;
+        readonly invoke: (event: unknown) => Promise<void>;
+    }): void;
+}
+/**
+ * DI token for the optional {@link OutboxListenerRegistrar} injected
+ * into `IntegrationEventsHandlerScanner`. When unbound, the scanner
+ * falls back to in-memory registration via
+ * {@link TransactionalEventDispatcher}.
+ *
+ * `Symbol.for(...)` (not `Symbol(...)`) — Phase 14.3.1: the outbox
+ * package auto-binds this token to its `MultiDsOutboxListenerRegistrar`
+ * via `Symbol.for` lookup on the same key. Both packages thereby
+ * refer to the same Symbol identity without a direct import in
+ * either direction.
+ */
+export declare const OUTBOX_LISTENER_REGISTRAR: unique symbol;
+//# sourceMappingURL=outbox-listener-registrar.d.ts.map

package/dist/handlers/outbox-listener-registrar.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OUTBOX_LISTENER_REGISTRAR = void 0;
+/**
+ * DI token for the optional {@link OutboxListenerRegistrar} injected
+ * into `IntegrationEventsHandlerScanner`. When unbound, the scanner
+ * falls back to in-memory registration via
+ * {@link TransactionalEventDispatcher}.
+ *
+ * `Symbol.for(...)` (not `Symbol(...)`) — Phase 14.3.1: the outbox
+ * package auto-binds this token to its `MultiDsOutboxListenerRegistrar`
+ * via `Symbol.for` lookup on the same key. Both packages thereby
+ * refer to the same Symbol identity without a direct import in
+ * either direction.
+ */
+exports.OUTBOX_LISTENER_REGISTRAR = Symbol.for('@nestjs-transactional/cqrs/outbox-listener-registrar');
+//# sourceMappingURL=outbox-listener-registrar.js.map

package/dist/handlers/outbox-listener-registrar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox-listener-registrar.js","sourceRoot":"","sources":["../../src/handlers/outbox-listener-registrar.ts"],"names":[],"mappings":";;;AAoCA;;;;;;;;;;;GAWG;AACU,QAAA,yBAAyB,GAAG,MAAM,CAAC,GAAG,CACjD,sDAAsD,CACvD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { TransactionPhase } from './types/transactional-listener.types';
+export { TRANSACTIONAL_EVENTS_HANDLER_METADATA, TransactionalEventsHandler, getTransactionalEventsHandlerMetadata, type TransactionalEventsHandlerMetadata, type TransactionalEventsHandlerOptions, } from './decorators/transactional-events-handler.decorator';
+export { INTEGRATION_EVENTS_HANDLER_METADATA, IntegrationEventsHandler, getIntegrationEventsHandlerMetadata, type IntegrationEventsHandlerMetadata, type IntegrationEventsHandlerOptions, } from './decorators/integration-events-handler.decorator';
+export type { ITransactionalEventHandler } from './interfaces/transactional-event-handler.interface';
+export type { IIntegrationEventHandler } from './interfaces/integration-event-handler.interface';
+export { TransactionalEventDispatcher, type DispatcherListenerMetadata, } from './event-dispatcher/event-dispatcher';
+export { TransactionalListenerScanner } from './handlers/listener-scanner';
+export { IntegrationEventsHandlerScanner } from './handlers/integration-events-handler-scanner';
+export { OUTBOX_LISTENER_REGISTRAR, type OutboxListenerRegistrar, } from './handlers/outbox-listener-registrar';
+export { CQRS_HANDLER_WRAPPER_OPTIONS, CqrsHandlerWrapper, type HandlerWrapperOptions, } from './handlers/handler-wrapper';
+export { CqrsTransactionalBootstrap } from './handlers/bootstrap';
+export { TransactionalEventPublisher } from './event-publisher/transactional-event-publisher';
+export { TransactionalEventPublisherAdapter } from './event-publisher/transactional-event-publisher-adapter';
+export { HybridEventPublisher, OUTBOX_PUBLICATION_SCHEDULER, type OutboxPublicationScheduler, } from './event-publisher/hybrid-event-publisher';
+export { CQRS_TRANSACTIONAL_OPTIONS, CqrsTransactionalModule, type CqrsTransactionalOptions, } from './module/cqrs-transactional.module';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CqrsTransactionalModule = exports.CQRS_TRANSACTIONAL_OPTIONS = exports.OUTBOX_PUBLICATION_SCHEDULER = exports.HybridEventPublisher = exports.TransactionalEventPublisherAdapter = exports.TransactionalEventPublisher = exports.CqrsTransactionalBootstrap = exports.CqrsHandlerWrapper = exports.CQRS_HANDLER_WRAPPER_OPTIONS = exports.OUTBOX_LISTENER_REGISTRAR = exports.IntegrationEventsHandlerScanner = exports.TransactionalListenerScanner = exports.TransactionalEventDispatcher = exports.getIntegrationEventsHandlerMetadata = exports.IntegrationEventsHandler = exports.INTEGRATION_EVENTS_HANDLER_METADATA = exports.getTransactionalEventsHandlerMetadata = exports.TransactionalEventsHandler = exports.TRANSACTIONAL_EVENTS_HANDLER_METADATA = exports.TransactionPhase = void 0;
+var transactional_listener_types_1 = require("./types/transactional-listener.types");
+Object.defineProperty(exports, "TransactionPhase", { enumerable: true, get: function () { return transactional_listener_types_1.TransactionPhase; } });
+var transactional_events_handler_decorator_1 = require("./decorators/transactional-events-handler.decorator");
+Object.defineProperty(exports, "TRANSACTIONAL_EVENTS_HANDLER_METADATA", { enumerable: true, get: function () { return transactional_events_handler_decorator_1.TRANSACTIONAL_EVENTS_HANDLER_METADATA; } });
+Object.defineProperty(exports, "TransactionalEventsHandler", { enumerable: true, get: function () { return transactional_events_handler_decorator_1.TransactionalEventsHandler; } });
+Object.defineProperty(exports, "getTransactionalEventsHandlerMetadata", { enumerable: true, get: function () { return transactional_events_handler_decorator_1.getTransactionalEventsHandlerMetadata; } });
+var integration_events_handler_decorator_1 = require("./decorators/integration-events-handler.decorator");
+Object.defineProperty(exports, "INTEGRATION_EVENTS_HANDLER_METADATA", { enumerable: true, get: function () { return integration_events_handler_decorator_1.INTEGRATION_EVENTS_HANDLER_METADATA; } });
+Object.defineProperty(exports, "IntegrationEventsHandler", { enumerable: true, get: function () { return integration_events_handler_decorator_1.IntegrationEventsHandler; } });
+Object.defineProperty(exports, "getIntegrationEventsHandlerMetadata", { enumerable: true, get: function () { return integration_events_handler_decorator_1.getIntegrationEventsHandlerMetadata; } });
+var event_dispatcher_1 = require("./event-dispatcher/event-dispatcher");
+Object.defineProperty(exports, "TransactionalEventDispatcher", { enumerable: true, get: function () { return event_dispatcher_1.TransactionalEventDispatcher; } });
+var listener_scanner_1 = require("./handlers/listener-scanner");
+Object.defineProperty(exports, "TransactionalListenerScanner", { enumerable: true, get: function () { return listener_scanner_1.TransactionalListenerScanner; } });
+var integration_events_handler_scanner_1 = require("./handlers/integration-events-handler-scanner");
+Object.defineProperty(exports, "IntegrationEventsHandlerScanner", { enumerable: true, get: function () { return integration_events_handler_scanner_1.IntegrationEventsHandlerScanner; } });
+var outbox_listener_registrar_1 = require("./handlers/outbox-listener-registrar");
+Object.defineProperty(exports, "OUTBOX_LISTENER_REGISTRAR", { enumerable: true, get: function () { return outbox_listener_registrar_1.OUTBOX_LISTENER_REGISTRAR; } });
+var handler_wrapper_1 = require("./handlers/handler-wrapper");
+Object.defineProperty(exports, "CQRS_HANDLER_WRAPPER_OPTIONS", { enumerable: true, get: function () { return handler_wrapper_1.CQRS_HANDLER_WRAPPER_OPTIONS; } });
+Object.defineProperty(exports, "CqrsHandlerWrapper", { enumerable: true, get: function () { return handler_wrapper_1.CqrsHandlerWrapper; } });
+var bootstrap_1 = require("./handlers/bootstrap");
+Object.defineProperty(exports, "CqrsTransactionalBootstrap", { enumerable: true, get: function () { return bootstrap_1.CqrsTransactionalBootstrap; } });
+var transactional_event_publisher_1 = require("./event-publisher/transactional-event-publisher");
+Object.defineProperty(exports, "TransactionalEventPublisher", { enumerable: true, get: function () { return transactional_event_publisher_1.TransactionalEventPublisher; } });
+var transactional_event_publisher_adapter_1 = require("./event-publisher/transactional-event-publisher-adapter");
+Object.defineProperty(exports, "TransactionalEventPublisherAdapter", { enumerable: true, get: function () { return transactional_event_publisher_adapter_1.TransactionalEventPublisherAdapter; } });
+var hybrid_event_publisher_1 = require("./event-publisher/hybrid-event-publisher");
+Object.defineProperty(exports, "HybridEventPublisher", { enumerable: true, get: function () { return hybrid_event_publisher_1.HybridEventPublisher; } });
+Object.defineProperty(exports, "OUTBOX_PUBLICATION_SCHEDULER", { enumerable: true, get: function () { return hybrid_event_publisher_1.OUTBOX_PUBLICATION_SCHEDULER; } });
+var cqrs_transactional_module_1 = require("./module/cqrs-transactional.module");
+Object.defineProperty(exports, "CQRS_TRANSACTIONAL_OPTIONS", { enumerable: true, get: function () { return cqrs_transactional_module_1.CQRS_TRANSACTIONAL_OPTIONS; } });
+Object.defineProperty(exports, "CqrsTransactionalModule", { enumerable: true, get: function () { return cqrs_transactional_module_1.CqrsTransactionalModule; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,qFAAwE;AAA/D,gIAAA,gBAAgB,OAAA;AAEzB,8GAM6D;AAL3D,+JAAA,qCAAqC,OAAA;AACrC,oJAAA,0BAA0B,OAAA;AAC1B,+JAAA,qCAAqC,OAAA;AAKvC,0GAM2D;AALzD,2JAAA,mCAAmC,OAAA;AACnC,gJAAA,wBAAwB,OAAA;AACxB,2JAAA,mCAAmC,OAAA;AAQrC,wEAG6C;AAF3C,gIAAA,4BAA4B,OAAA;AAI9B,gEAA2E;AAAlE,gIAAA,4BAA4B,OAAA;AACrC,oGAAgG;AAAvF,qJAAA,+BAA+B,OAAA;AACxC,kFAG8C;AAF5C,sIAAA,yBAAyB,OAAA;AAI3B,8DAIoC;AAHlC,+HAAA,4BAA4B,OAAA;AAC5B,qHAAA,kBAAkB,OAAA;AAIpB,kDAAkE;AAAzD,uHAAA,0BAA0B,OAAA;AAEnC,iGAA8F;AAArF,4IAAA,2BAA2B,OAAA;AACpC,iHAA6G;AAApG,2JAAA,kCAAkC,OAAA;AAC3C,mFAIkD;AAHhD,8HAAA,oBAAoB,OAAA;AACpB,sIAAA,4BAA4B,OAAA;AAI9B,gFAI4C;AAH1C,uIAAA,0BAA0B,OAAA;AAC1B,oIAAA,uBAAuB,OAAA"}

package/dist/interfaces/integration-event-handler.interface.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Contract implemented by classes annotated with
+ * `@IntegrationEventsHandler` — the smart-default decorator for
+ * cross-module / cross-service event handlers.
+ *
+ * The Spring Modulith equivalent is `@ApplicationModuleListener`.
+ * The name `@IntegrationEventsHandler` is preferred in the NestJS
+ * ecosystem because "Application Module" overlaps with NestJS's own
+ * `@Module()` (a DI concept), and "Integration events" is the
+ * established DDD/microservices term for the role this decorator
+ * plays.
+ *
+ * Shape is identical to {@link ITransactionalEventHandler}; the two
+ * interfaces exist separately as marker types so code can
+ * discriminate by intent (cross-module integration handler vs.
+ * intra-module transactional listener) even though both share the
+ * `handle(event)` contract.
+ *
+ * @example
+ * ```ts
+ * @IntegrationEventsHandler(OrderPlacedEvent)
+ * export class InventoryReservationHandler
+ *   implements IIntegrationEventHandler<OrderPlacedEvent>
+ * {
+ *   async handle(event: OrderPlacedEvent): Promise<void> {
+ *     // durable when the outbox is wired, in-memory AFTER_COMMIT
+ *     // fallback otherwise.
+ *   }
+ * }
+ * ```
+ */
+export interface IIntegrationEventHandler<T = any> {
+    handle(event: T): Promise<void> | void;
+}
+//# sourceMappingURL=integration-event-handler.interface.d.ts.map

package/dist/interfaces/integration-event-handler.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=integration-event-handler.interface.js.map

package/dist/interfaces/integration-event-handler.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration-event-handler.interface.js","sourceRoot":"","sources":["../../src/interfaces/integration-event-handler.interface.ts"],"names":[],"mappings":""}

package/dist/interfaces/transactional-event-handler.interface.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Contract implemented by classes annotated with
+ * `@TransactionalEventsHandler`.
+ *
+ * The single `handle` method is invoked for each event of a type the
+ * class is registered for. When a handler listens to several event
+ * types, narrow the generic parameter to their union (e.g.
+ * `ITransactionalEventHandler<OrderPlaced | OrderCancelled>`) or
+ * leave it unbound for the most permissive shape.
+ *
+ * Mirrors the ergonomics of `IEventHandler` from `@nestjs/cqrs` —
+ * `any` as the default generic parameter is deliberate so that
+ * `implements ITransactionalEventHandler` without a type argument
+ * type-checks against any concrete event shape.
+ *
+ * @example
+ * ```ts
+ * @TransactionalEventsHandler(OrderPlacedEvent)
+ * export class OrderPlacedNotifier
+ *   implements ITransactionalEventHandler<OrderPlacedEvent>
+ * {
+ *   async handle(event: OrderPlacedEvent): Promise<void> {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export interface ITransactionalEventHandler<T = any> {
+    handle(event: T): Promise<void> | void;
+}
+//# sourceMappingURL=transactional-event-handler.interface.d.ts.map

package/dist/interfaces/transactional-event-handler.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=transactional-event-handler.interface.js.map

package/dist/interfaces/transactional-event-handler.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactional-event-handler.interface.js","sourceRoot":"","sources":["../../src/interfaces/transactional-event-handler.interface.ts"],"names":[],"mappings":""}

package/dist/module/cqrs-transactional.module.d.ts

@@ -0,0 +1,92 @@
+import { type DynamicModule } from '@nestjs/common';
+import { type HandlerWrapperOptions } from '../handlers/handler-wrapper';
+/**
+ * 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}.
+ */
+export declare const CQRS_TRANSACTIONAL_OPTIONS = "CQRS_TRANSACTIONAL_OPTIONS";
+/**
+ * Options accepted by {@link CqrsTransactionalModule.forRoot}. Extends
+ * {@link HandlerWrapperOptions} with the flag controlling whether
+ * `@nestjs/cqrs`'s `EventPublisher` is overridden with
+ * {@link TransactionalEventPublisherAdapter}.
+ *
+ * Defaults:
+ * - `wrapCommandHandlers`: `true`
+ * - `wrapQueryHandlers`: `true`
+ * - `wrapEventHandlers`: `true`
+ * - `defaultQueryOptions`: `{ readOnly: true }`
+ * - `useTransactionalEventPublisher`: `true`
+ */
+export interface CqrsTransactionalOptions extends HandlerWrapperOptions {
+    /**
+     * If `true` (default), overrides `@nestjs/cqrs`'s `EventPublisher`
+     * DI token with {@link TransactionalEventPublisherAdapter} so
+     * `AggregateRoot.commit()` routes events through the transactional
+     * dispatcher (phase-aware handlers). Set to `false` to leave the
+     * standard `EventPublisher` in place — useful when integrating
+     * progressively into an existing codebase.
+     */
+    readonly useTransactionalEventPublisher?: boolean;
+}
+/**
+ * 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`.
+ */
+export declare class CqrsTransactionalModule {
+    static forRoot(options?: CqrsTransactionalOptions): DynamicModule;
+}
+//# sourceMappingURL=cqrs-transactional.module.d.ts.map