@nestjs-transactional/cqrs 1.0.0-alpha.0

package/dist/decorators/transactional-events-handler.decorator.d.ts

@@ -0,0 +1,138 @@
+import 'reflect-metadata';
+import { type Type } from '@nestjs/common';
+import { TransactionPhase } from '../types/transactional-listener.types';
+/**
+ * Metadata key under which {@link TransactionalEventsHandlerMetadata} is
+ * stored on classes decorated with {@link TransactionalEventsHandler}.
+ *
+ * The key is a fresh `Symbol` (not `Symbol.for`) — this metadata is
+ * private to the cqrs package and does not need to be shared across
+ * package boundaries.
+ */
+export declare const TRANSACTIONAL_EVENTS_HANDLER_METADATA: unique symbol;
+/**
+ * Options accepted by the long form of {@link TransactionalEventsHandler}.
+ *
+ * Use this form when the handler needs any non-default behaviour (a
+ * different `phase`, `async` delivery, or `fallbackExecution` outside a
+ * transaction). When defaults are acceptable, prefer the rest-params
+ * short form: `@TransactionalEventsHandler(EventA, EventB)`.
+ */
+export interface TransactionalEventsHandlerOptions {
+    /** Domain event classes the handler subscribes to. Must be non-empty. */
+    readonly events: Type[];
+    /**
+     * Transaction phase to attach the handler to. Defaults to
+     * {@link TransactionPhase.AFTER_COMMIT} — the canonical "publish
+     * domain event" phase.
+     */
+    readonly phase?: TransactionPhase;
+    /**
+     * When `true`, the handler is invoked on a microtask and its failures
+     * never reach the surrounding transaction — including BEFORE_COMMIT,
+     * which therefore cannot cause a rollback. Defaults to `false`.
+     */
+    readonly async?: boolean;
+    /**
+     * When `true`, the handler fires even for events published outside
+     * any active transaction (direct `eventBus.publish(event)` calls).
+     * When `false` (default), such events are dropped with a warning.
+     */
+    readonly fallbackExecution?: boolean;
+    /**
+     * dataSource the handler's phase hooks attach to (Phase 14.3.1).
+     * Defaults to {@link DEFAULT_DATA_SOURCE_NAME} (`'default'`) —
+     * single-dataSource apps can omit it.
+     *
+     * Multi-dataSource apps with handlers belonging to a non-default
+     * dataSource MUST set this — the dispatcher uses it to find the
+     * matching active transaction via
+     * `TransactionContext.getActiveTransactionByDataSource(dataSource)`
+     * and pushes phase hooks directly onto that transaction's hook
+     * lists. Without it, the dispatcher falls back to `'default'` and
+     * the handler may attach to the wrong transaction (or none at all
+     * if the default-DS has no active tx in the current async context).
+     *
+     * Unlike `@OutboxEventsHandler` and `@IntegrationEventsHandler`'s
+     * outbox path — both of which auto-resolve the dataSource by
+     * walking per-DS event-type registries — the in-memory dispatcher
+     * has no event-type registry to consult. The cqrs package is
+     * decoupled from outbox by design (Phase 14.7), so the dataSource
+     * is declared explicitly on the decorator.
+     */
+    readonly dataSource?: string;
+}
+/**
+ * Resolved metadata attached to a handler class. All option fields are
+ * required (the decorator fills in defaults). `eventTypes` is the
+ * normalised list of event constructors the handler is registered for.
+ */
+export interface TransactionalEventsHandlerMetadata {
+    readonly eventTypes: Type[];
+    readonly phase: TransactionPhase;
+    readonly async: boolean;
+    readonly fallbackExecution: boolean;
+    readonly dataSource: string;
+}
+/**
+ * Mark a class as a transactional event handler. The class must
+ * expose a `handle(event): void | Promise<void>` method (enforce this
+ * at the type level by implementing {@link ITransactionalEventHandler}).
+ *
+ * Two forms:
+ *
+ * ```ts
+ * // Short form — defaults (AFTER_COMMIT, sync, no fallback):
+ * @TransactionalEventsHandler(OrderPlacedEvent, OrderCancelledEvent)
+ *
+ * // Long form — explicit options:
+ * @TransactionalEventsHandler({
+ *   events: [OrderPlacedEvent],
+ *   phase: TransactionPhase.BEFORE_COMMIT,
+ *   async: false,
+ * })
+ * ```
+ *
+ * Class-level only — this decorator does not accept methods. Multiple
+ * handlers may subscribe to the same event type; each is an independent
+ * class and runs in registration order.
+ *
+ * The metadata is written by `Reflect.defineMetadata`. The actual
+ * dispatcher registration happens at application bootstrap via
+ * `TransactionalListenerScanner`.
+ *
+ * **Multi-dataSource semantics (Phase 14.3.1).** The dispatcher pushes
+ * phase hooks directly onto the per-dataSource active transaction
+ * resolved via
+ * `TransactionContext.getActiveTransactionByDataSource(dataSource)`,
+ * bypassing `TransactionManager.registerBeforeCommit`'s first-active-tx
+ * semantics. The dataSource defaults to `'default'`; multi-DS apps
+ * pass `dataSource: 'billing'` (or similar) on the long form to attach
+ * the handler to a specific dataSource's transaction:
+ *
+ * ```ts
+ * @TransactionalEventsHandler({
+ *   events: [BillingEvent],
+ *   dataSource: 'billing',
+ * })
+ * class BillingHandler { handle(event: BillingEvent) {} }
+ * ```
+ *
+ * Unlike `@OutboxEventsHandler` (which auto-resolves the dataSource
+ * by walking per-DS event-type registries), the in-memory dispatcher
+ * has no event-type registry — the dataSource is declared explicitly
+ * on the decorator.
+ *
+ * @throws {Error} If no event types are supplied.
+ */
+export declare function TransactionalEventsHandler(...events: Type[]): ClassDecorator;
+export declare function TransactionalEventsHandler(options: TransactionalEventsHandlerOptions): ClassDecorator;
+/**
+ * Read the {@link TransactionalEventsHandlerMetadata} attached to
+ * `target` by {@link TransactionalEventsHandler}. Returns `undefined`
+ * when the class was not decorated.
+ *
+ * @param target - The class constructor.
+ */
+export declare function getTransactionalEventsHandlerMetadata(target: object): TransactionalEventsHandlerMetadata | undefined;
+//# sourceMappingURL=transactional-events-handler.decorator.d.ts.map

package/dist/decorators/transactional-events-handler.decorator.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRANSACTIONAL_EVENTS_HANDLER_METADATA = void 0;
+exports.TransactionalEventsHandler = TransactionalEventsHandler;
+exports.getTransactionalEventsHandlerMetadata = getTransactionalEventsHandlerMetadata;
+require("reflect-metadata");
+const core_1 = require("@nestjs-transactional/core");
+const transactional_listener_types_1 = require("../types/transactional-listener.types");
+/**
+ * Metadata key under which {@link TransactionalEventsHandlerMetadata} is
+ * stored on classes decorated with {@link TransactionalEventsHandler}.
+ *
+ * The key is a fresh `Symbol` (not `Symbol.for`) — this metadata is
+ * private to the cqrs package and does not need to be shared across
+ * package boundaries.
+ */
+exports.TRANSACTIONAL_EVENTS_HANDLER_METADATA = Symbol('TRANSACTIONAL_EVENTS_HANDLER_METADATA');
+function TransactionalEventsHandler(...args) {
+    const metadata = resolveMetadata(args);
+    if (metadata.eventTypes.length === 0) {
+        throw new Error('@TransactionalEventsHandler requires at least one event type. ' +
+            'Pass class constructors as rest arguments or via the `events` option.');
+    }
+    return (target) => {
+        Reflect.defineMetadata(exports.TRANSACTIONAL_EVENTS_HANDLER_METADATA, metadata, target);
+    };
+}
+function resolveMetadata(args) {
+    if (args.length === 1 && isOptionsObject(args[0])) {
+        const options = args[0];
+        return {
+            eventTypes: [...options.events],
+            phase: options.phase ?? transactional_listener_types_1.TransactionPhase.AFTER_COMMIT,
+            async: options.async ?? false,
+            fallbackExecution: options.fallbackExecution ?? false,
+            dataSource: options.dataSource ?? core_1.DEFAULT_DATA_SOURCE_NAME,
+        };
+    }
+    return {
+        eventTypes: args,
+        phase: transactional_listener_types_1.TransactionPhase.AFTER_COMMIT,
+        async: false,
+        fallbackExecution: false,
+        dataSource: core_1.DEFAULT_DATA_SOURCE_NAME,
+    };
+}
+function isOptionsObject(candidate) {
+    return (candidate !== null &&
+        typeof candidate === 'object' &&
+        !Array.isArray(candidate) &&
+        typeof candidate !== 'function' &&
+        'events' in candidate);
+}
+/**
+ * Read the {@link TransactionalEventsHandlerMetadata} attached to
+ * `target` by {@link TransactionalEventsHandler}. Returns `undefined`
+ * when the class was not decorated.
+ *
+ * @param target - The class constructor.
+ */
+function getTransactionalEventsHandlerMetadata(target) {
+    const value = Reflect.getMetadata(exports.TRANSACTIONAL_EVENTS_HANDLER_METADATA, target);
+    return value;
+}
+//# sourceMappingURL=transactional-events-handler.decorator.js.map

package/dist/decorators/transactional-events-handler.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactional-events-handler.decorator.js","sourceRoot":"","sources":["../../src/decorators/transactional-events-handler.decorator.ts"],"names":[],"mappings":";;;AA4IA,gEAeC;AA4CD,sFAKC;AA5MD,4BAA0B;AAG1B,qDAAsE;AAEtE,wFAAyE;AAEzE;;;;;;;GAOG;AACU,QAAA,qCAAqC,GAAG,MAAM,CACzD,uCAAuC,CACxC,CAAC;AA2HF,SAAgB,0BAA0B,CACxC,GAAG,IAAkD;IAErD,MAAM,QAAQ,GAAuC,eAAe,CAAC,IAAI,CAAC,CAAC;IAE3E,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,gEAAgE;YAC9D,uEAAuE,CAC1E,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,MAAc,EAAQ,EAAE;QAC9B,OAAO,CAAC,cAAc,CAAC,6CAAqC,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAClF,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CACtB,IAAkD;IAElD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACxB,OAAO;YACL,UAAU,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;YAC/B,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,+CAAgB,CAAC,YAAY;YACrD,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,KAAK;YAC7B,iBAAiB,EAAE,OAAO,CAAC,iBAAiB,IAAI,KAAK;YACrD,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,+BAAwB;SAC3D,CAAC;IACJ,CAAC;IAED,OAAO;QACL,UAAU,EAAE,IAAc;QAC1B,KAAK,EAAE,+CAAgB,CAAC,YAAY;QACpC,KAAK,EAAE,KAAK;QACZ,iBAAiB,EAAE,KAAK;QACxB,UAAU,EAAE,+BAAwB;KACrC,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CACtB,SAAkB;IAElB,OAAO,CACL,SAAS,KAAK,IAAI;QAClB,OAAO,SAAS,KAAK,QAAQ;QAC7B,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;QACzB,OAAO,SAAS,KAAK,UAAU;QAC/B,QAAQ,IAAI,SAAS,CACtB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,qCAAqC,CACnD,MAAc;IAEd,MAAM,KAAK,GAAY,OAAO,CAAC,WAAW,CAAC,6CAAqC,EAAE,MAAM,CAAC,CAAC;IAC1F,OAAO,KAAuD,CAAC;AACjE,CAAC"}

package/dist/event-dispatcher/event-dispatcher.d.ts

@@ -0,0 +1,100 @@
+import { type Type } from '@nestjs/common';
+import { TransactionManager } from '@nestjs-transactional/core';
+import { TransactionPhase } from '../types/transactional-listener.types';
+/**
+ * Resolved per-event-type listener configuration used by
+ * {@link TransactionalEventDispatcher.registerListener}. Scanners flatten
+ * class-level `@TransactionalEventsHandler` metadata (which lists many
+ * event types per class) into one of these entries per event type.
+ */
+export interface DispatcherListenerMetadata {
+    readonly eventType: Type;
+    readonly phase: TransactionPhase;
+    readonly fallbackExecution: boolean;
+    readonly async: boolean;
+    /**
+     * dataSource the listener's phase hooks attach to (Phase 14.3.1).
+     * Optional for backward compatibility — when omitted, defaults to
+     * `'default'`. Scanners normalise from decorator metadata before
+     * calling {@link TransactionalEventDispatcher.registerListener}.
+     */
+    readonly dataSource?: string;
+}
+/**
+ * Routes domain events to methods registered by scanners for
+ * `@TransactionalEventsHandler`-annotated classes, honouring the
+ * requested {@link TransactionPhase}:
+ *
+ * - Inside an active transaction, the listener is attached to the
+ *   transaction as a before-commit / after-commit / after-rollback
+ *   hook via {@link TransactionManager}. Phase AFTER_COMPLETION
+ *   attaches to both after-commit and after-rollback.
+ * - Outside any transaction, listeners with `fallbackExecution: true`
+ *   are invoked via `queueMicrotask`; others are dropped with a
+ *   warning.
+ *
+ * Error propagation:
+ * - Errors thrown from a BEFORE_COMMIT listener propagate through the
+ *   manager's commit path and trigger rollback (matches Spring).
+ * - Errors thrown from an AFTER_COMMIT / AFTER_ROLLBACK /
+ *   AFTER_COMPLETION listener are logged and swallowed by
+ *   {@link TransactionManager}'s hook runner — the transaction
+ *   outcome is already decided.
+ * - `async: true` listeners are fire-and-forget via `queueMicrotask`:
+ *   their failures are logged but never reach the enclosing
+ *   transaction, even in BEFORE_COMMIT phase.
+ *
+ * **Multi-dataSource (Phase 14.3.1).** Hook attachment is per-dataSource:
+ * the dispatcher resolves the listener's bound dataSource via
+ * `TransactionContext.getActiveTransactionByDataSource(dataSource)`
+ * and pushes hooks directly onto that transaction's hook list,
+ * bypassing `TransactionManager.registerBeforeCommit`'s first-active-tx
+ * semantics. The dataSource comes from the listener metadata (defaults
+ * to `'default'`); scanners populate it from the
+ * `@TransactionalEventsHandler({ dataSource })` /
+ * `@IntegrationEventsHandler({ dataSource })` option. Cross-DS
+ * simultaneous transactions therefore route deterministically — a
+ * billing-bound handler attaches to the billing transaction's hooks
+ * even when an inventory transaction is also active on the same
+ * async stack.
+ */
+export declare class TransactionalEventDispatcher {
+    private readonly manager;
+    private readonly logger;
+    private readonly listenersByType;
+    /**
+     * `manager` is no longer consulted after Phase 14.3.1 — the
+     * dispatcher pushes hooks directly onto the per-dataSource
+     * `ActiveTransaction` resolved via `TransactionContext`. The
+     * parameter is preserved as a constructor argument so existing
+     * `new TransactionalEventDispatcher(manager)` callsites in tests
+     * keep compiling. NestJS DI continues to inject the manager
+     * automatically. A future cleanup phase may drop it.
+     */
+    constructor(manager: TransactionManager);
+    /**
+     * Register a handler method discovered on `instance`. The lookup key
+     * is `metadata.eventType.name` — see {@link scheduleDispatch} for
+     * matching semantics. Multiple handlers for the same event are
+     * invoked in registration order within the hook runner.
+     *
+     * @throws {TypeError} If `instance[methodName]` is not a function.
+     *   This is a caller contract violation — the scanner must only pass
+     *   method names that actually resolve to methods on the instance.
+     */
+    registerListener(instance: object, methodName: string, metadata: DispatcherListenerMetadata): void;
+    /**
+     * Route `event` to every listener registered for its exact
+     * constructor name. Listener matching is nominal and non-inheriting:
+     * a listener registered for `Parent` is NOT invoked for a `Child
+     * extends Parent` event, because the lookup uses
+     * `event.constructor.name`.
+     */
+    scheduleDispatch(event: object): void;
+    private attachHookToTransaction;
+    private invokeListener;
+    private scheduleFallback;
+    private callListener;
+    private logListenerFailure;
+}
+//# sourceMappingURL=event-dispatcher.d.ts.map

package/dist/event-dispatcher/event-dispatcher.js

@@ -0,0 +1,229 @@
+"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 TransactionalEventDispatcher_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionalEventDispatcher = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs-transactional/core");
+const transactional_listener_types_1 = require("../types/transactional-listener.types");
+/**
+ * Routes domain events to methods registered by scanners for
+ * `@TransactionalEventsHandler`-annotated classes, honouring the
+ * requested {@link TransactionPhase}:
+ *
+ * - Inside an active transaction, the listener is attached to the
+ *   transaction as a before-commit / after-commit / after-rollback
+ *   hook via {@link TransactionManager}. Phase AFTER_COMPLETION
+ *   attaches to both after-commit and after-rollback.
+ * - Outside any transaction, listeners with `fallbackExecution: true`
+ *   are invoked via `queueMicrotask`; others are dropped with a
+ *   warning.
+ *
+ * Error propagation:
+ * - Errors thrown from a BEFORE_COMMIT listener propagate through the
+ *   manager's commit path and trigger rollback (matches Spring).
+ * - Errors thrown from an AFTER_COMMIT / AFTER_ROLLBACK /
+ *   AFTER_COMPLETION listener are logged and swallowed by
+ *   {@link TransactionManager}'s hook runner — the transaction
+ *   outcome is already decided.
+ * - `async: true` listeners are fire-and-forget via `queueMicrotask`:
+ *   their failures are logged but never reach the enclosing
+ *   transaction, even in BEFORE_COMMIT phase.
+ *
+ * **Multi-dataSource (Phase 14.3.1).** Hook attachment is per-dataSource:
+ * the dispatcher resolves the listener's bound dataSource via
+ * `TransactionContext.getActiveTransactionByDataSource(dataSource)`
+ * and pushes hooks directly onto that transaction's hook list,
+ * bypassing `TransactionManager.registerBeforeCommit`'s first-active-tx
+ * semantics. The dataSource comes from the listener metadata (defaults
+ * to `'default'`); scanners populate it from the
+ * `@TransactionalEventsHandler({ dataSource })` /
+ * `@IntegrationEventsHandler({ dataSource })` option. Cross-DS
+ * simultaneous transactions therefore route deterministically — a
+ * billing-bound handler attaches to the billing transaction's hooks
+ * even when an inventory transaction is also active on the same
+ * async stack.
+ */
+let TransactionalEventDispatcher = TransactionalEventDispatcher_1 = class TransactionalEventDispatcher {
+    manager;
+    logger = new common_1.Logger(TransactionalEventDispatcher_1.name);
+    listenersByType = new Map();
+    /**
+     * `manager` is no longer consulted after Phase 14.3.1 — the
+     * dispatcher pushes hooks directly onto the per-dataSource
+     * `ActiveTransaction` resolved via `TransactionContext`. The
+     * parameter is preserved as a constructor argument so existing
+     * `new TransactionalEventDispatcher(manager)` callsites in tests
+     * keep compiling. NestJS DI continues to inject the manager
+     * automatically. A future cleanup phase may drop it.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    constructor(manager) {
+        this.manager = manager;
+    }
+    /**
+     * Register a handler method discovered on `instance`. The lookup key
+     * is `metadata.eventType.name` — see {@link scheduleDispatch} for
+     * matching semantics. Multiple handlers for the same event are
+     * invoked in registration order within the hook runner.
+     *
+     * @throws {TypeError} If `instance[methodName]` is not a function.
+     *   This is a caller contract violation — the scanner must only pass
+     *   method names that actually resolve to methods on the instance.
+     */
+    registerListener(instance, methodName, metadata) {
+        const rawMethod = instance[methodName];
+        if (typeof rawMethod !== 'function') {
+            throw new TypeError(`Transactional event handler target ${instance.constructor.name}.${methodName} ` +
+                `is not a function — cannot register as a listener`);
+        }
+        const typeName = metadata.eventType.name;
+        const instanceLabel = instance.constructor.name;
+        const entry = {
+            handler: rawMethod.bind(instance),
+            instanceLabel,
+            methodName,
+            metadata,
+        };
+        const listeners = this.listenersByType.get(typeName);
+        if (listeners === undefined) {
+            this.listenersByType.set(typeName, [entry]);
+        }
+        else {
+            listeners.push(entry);
+        }
+        this.logger.debug(`Registered handler ${instanceLabel}.${methodName} for ${typeName} phase=${metadata.phase}`);
+    }
+    /**
+     * Route `event` to every listener registered for its exact
+     * constructor name. Listener matching is nominal and non-inheriting:
+     * a listener registered for `Parent` is NOT invoked for a `Child
+     * extends Parent` event, because the lookup uses
+     * `event.constructor.name`.
+     */
+    scheduleDispatch(event) {
+        const typeName = event.constructor.name;
+        const listeners = this.listenersByType.get(typeName);
+        if (listeners === undefined || listeners.length === 0) {
+            return;
+        }
+        const store = core_1.TransactionContext.getStore();
+        const anyTxActive = store !== undefined && store.activeTransactions.size > 0;
+        for (const listener of listeners) {
+            const dataSource = listener.metadata.dataSource ?? core_1.DEFAULT_DATA_SOURCE_NAME;
+            const tx = core_1.TransactionContext.getActiveTransactionByDataSource(dataSource);
+            if (tx === undefined) {
+                // No active transaction for this listener's dataSource. Two
+                // sub-cases:
+                //  - There IS at least one active tx (just not for this DS):
+                //    the event is "in a transaction" only for some other DS.
+                //    A listener bound to a different DS has no business
+                //    firing — skip silently. This preserves DD-023's
+                //    independent-context semantics (cross-dataSource calls
+                //    do not silently enrol).
+                //  - No active tx anywhere: classic out-of-transaction case —
+                //    fallbackExecution: true fires immediately, others warn
+                //    and drop.
+                if (!anyTxActive && listener.metadata.fallbackExecution) {
+                    this.scheduleFallback(listener, event);
+                }
+                else if (!anyTxActive) {
+                    this.logger.warn(`Event ${typeName} published outside a transaction; handler ` +
+                        `${listener.instanceLabel}.${listener.methodName} has no ` +
+                        `fallbackExecution=true — skipping.`);
+                }
+                else {
+                    this.logger.debug(`Event ${typeName}: handler ${listener.instanceLabel}.${listener.methodName} ` +
+                        `bound to dataSource '${dataSource}' has no matching active transaction — skipping.`);
+                }
+                continue;
+            }
+            this.attachHookToTransaction(listener, event, tx);
+        }
+    }
+    attachHookToTransaction(listener, event, tx) {
+        const invoke = () => this.invokeListener(listener, event);
+        const invokeWithError = (error) => this.invokeListener(listener, event, error);
+        // Push hooks directly onto THIS specific transaction's hook lists,
+        // bypassing TransactionManager.registerBeforeCommit's
+        // first-active-tx resolution. Same pattern as
+        // DataSourceOutboxPublisher.scheduleForPublication (Phase 14.3).
+        switch (listener.metadata.phase) {
+            case transactional_listener_types_1.TransactionPhase.BEFORE_COMMIT:
+                tx.beforeCommitHooks.push(invoke);
+                return;
+            case transactional_listener_types_1.TransactionPhase.AFTER_COMMIT:
+                tx.afterCommitHooks.push(invoke);
+                return;
+            case transactional_listener_types_1.TransactionPhase.AFTER_ROLLBACK:
+                tx.afterRollbackHooks.push(invokeWithError);
+                return;
+            case transactional_listener_types_1.TransactionPhase.AFTER_COMPLETION:
+                tx.afterCommitHooks.push(invoke);
+                tx.afterRollbackHooks.push(invokeWithError);
+                return;
+        }
+    }
+    async invokeListener(listener, event, error) {
+        if (listener.metadata.async) {
+            queueMicrotask(() => {
+                try {
+                    const result = this.callListener(listener, event, error);
+                    if (result instanceof Promise) {
+                        result.catch((err) => this.logListenerFailure(listener, err));
+                    }
+                }
+                catch (err) {
+                    this.logListenerFailure(listener, err);
+                }
+            });
+            return;
+        }
+        try {
+            const result = this.callListener(listener, event, error);
+            if (result instanceof Promise) {
+                await result;
+            }
+        }
+        catch (err) {
+            this.logListenerFailure(listener, err);
+            // Rethrow so BEFORE_COMMIT failures reach the manager's rollback path.
+            // For AFTER_COMMIT/AFTER_ROLLBACK/AFTER_COMPLETION the manager's
+            // hook runner swallows the error after a warn-level log.
+            throw err;
+        }
+    }
+    scheduleFallback(listener, event) {
+        queueMicrotask(() => {
+            try {
+                const result = this.callListener(listener, event);
+                if (result instanceof Promise) {
+                    result.catch((err) => this.logListenerFailure(listener, err));
+                }
+            }
+            catch (err) {
+                this.logListenerFailure(listener, err);
+            }
+        });
+    }
+    callListener(listener, event, error) {
+        return listener.handler(event, error);
+    }
+    logListenerFailure(listener, err) {
+        this.logger.error(`Transactional event handler ${listener.instanceLabel}.${listener.methodName} failed`, err instanceof Error ? err.stack : String(err));
+    }
+};
+exports.TransactionalEventDispatcher = TransactionalEventDispatcher;
+exports.TransactionalEventDispatcher = TransactionalEventDispatcher = TransactionalEventDispatcher_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [core_1.TransactionManager])
+], TransactionalEventDispatcher);
+//# sourceMappingURL=event-dispatcher.js.map

package/dist/event-dispatcher/event-dispatcher.js.map

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

package/dist/event-publisher/hybrid-event-publisher.d.ts

@@ -0,0 +1,76 @@
+import type { IEvent, IEventPublisher } from '@nestjs/cqrs';
+import { TransactionalEventDispatcher } from '../event-dispatcher/event-dispatcher';
+/**
+ * Minimal structural contract for the outbox-side publisher. Declared
+ * here (and injected via the {@link OUTBOX_PUBLICATION_SCHEDULER}
+ * token) rather than importing from
+ * `@nestjs-transactional/outbox` directly — keeps `cqrs` usable
+ * without pulling in the outbox stack.
+ *
+ * `@nestjs-transactional/outbox`'s `OutboxEventPublisher`
+ * satisfies this interface structurally (it exposes
+ * `scheduleForPublication`). Wire the token in the host application
+ * when the outbox is enabled:
+ *
+ * ```ts
+ * providers: [
+ *   {
+ *     provide: OUTBOX_PUBLICATION_SCHEDULER,
+ *     useExisting: OutboxEventPublisher,
+ *   },
+ * ]
+ * ```
+ */
+export interface OutboxPublicationScheduler {
+    scheduleForPublication(event: unknown): void;
+}
+/**
+ * DI token for the optional outbox scheduler injected into
+ * {@link HybridEventPublisher}. When unbound, the hybrid publisher
+ * delegates only to the in-memory dispatcher.
+ */
+export declare const OUTBOX_PUBLICATION_SCHEDULER: unique symbol;
+/**
+ * `IEventPublisher` implementation that routes aggregate-emitted
+ * events through BOTH the in-memory transactional dispatcher
+ * (`@TransactionalEventsHandler`) AND — when wired — the outbox
+ * (`@OutboxEventsHandler`, introduced in a later phase). Both paths
+ * run inside the surrounding transaction:
+ *
+ * - In-memory: the dispatcher attaches hooks to the current
+ *   transaction so listeners fire at the configured phase
+ *   (`AFTER_COMMIT` by default). No database rows are written.
+ * - Outbox: {@link OutboxPublicationScheduler.scheduleForPublication}
+ *   buffers the event and flushes the buffer via one `beforeCommit`
+ *   hook per transaction. Publication rows commit atomically with
+ *   the business write; rollback skips the flush.
+ *
+ * When no outbox scheduler is bound, behaves identically to
+ * {@link TransactionalEventPublisher}. Callers get outbox semantics
+ * automatically as soon as the scheduler is wired — no code change
+ * at the call site.
+ *
+ * Important: the outbox path is best-effort from the perspective of
+ * `AggregateRoot.commit()`. `commit()` is synchronous, so we cannot
+ * await the DB write here. Errors raised while the `beforeCommit`
+ * hook flushes the buffer DO bubble up — they cause the transaction
+ * to roll back, which is the intended behavior.
+ *
+ * **Multi-dataSource (Phase 14.7).** The outbox scheduler is the
+ * smart-facade `OutboxEventPublisher` (DD-024). When wired,
+ * AggregateRoot events are routed to the per-dataSource publisher
+ * that owns the event class — the same routing semantics as
+ * `OutboxEventPublisher.publish()`. Multi-DS apps with multiple
+ * outbox stacks (one `OutboxModule.forRoot()` per dataSource per
+ * ADR-019) bind `OUTBOX_PUBLICATION_SCHEDULER` to the smart facade
+ * via `useExisting: OutboxEventPublisher`; the facade's internal
+ * Map fans out to the correct per-DS publisher.
+ */
+export declare class HybridEventPublisher implements IEventPublisher {
+    private readonly dispatcher;
+    private readonly outbox?;
+    constructor(dispatcher: TransactionalEventDispatcher, outbox?: OutboxPublicationScheduler | undefined);
+    publish<T extends IEvent>(event: T): void;
+    publishAll<T extends IEvent>(events: T[]): void;
+}
+//# sourceMappingURL=hybrid-event-publisher.d.ts.map