@nestjs-transactional/cqrs 1.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Golovanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,431 @@
+# @nestjs-transactional/cqrs
+
+[![npm version](https://img.shields.io/npm/v/%40nestjs-transactional%2Fcqrs/alpha?style=flat-square&label=npm)](https://www.npmjs.com/package/@nestjs-transactional/cqrs)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/igorgolovanov/nestjs-transactional/blob/main/LICENSE)
+
+Integration between [@nestjs-transactional/core](../core) and
+[`@nestjs/cqrs`](https://docs.nestjs.com/recipes/cqrs). Gives
+`@CommandHandler` / `@QueryHandler` / `@EventsHandler` classes
+declarative transaction management and Spring-style event handler
+phases without forking `@nestjs/cqrs` (see ADR-003).
+
+## What it provides
+
+- **`@TransactionalEventsHandler(...events)`** — class-level event
+  handler decorator with Spring-compatible phases: `BEFORE_COMMIT`,
+  `AFTER_COMMIT` (default), `AFTER_ROLLBACK`, `AFTER_COMPLETION`. The
+  decorated class implements `ITransactionalEventHandler<T>` and
+  exposes a single `handle(event)` method. Matches the ergonomics of
+  `@nestjs/cqrs`'s own `@EventsHandler` (see ADR-014).
+- **`@IntegrationEventsHandler(...events)`** — class-level smart
+  default for cross-module handlers. Delivers via the outbox when the
+  `OUTBOX_LISTENER_REGISTRAR` structural port is bound (durable,
+  retried, resumable), falls back to in-memory `AFTER_COMMIT` + `async:
+  true` dispatch otherwise. Matches Spring Modulith's
+  `@ApplicationModuleListener` contract.
+- **`TransactionalEventPublisher` + `TransactionalEventPublisherAdapter`** —
+  drop-in replacement for `@nestjs/cqrs`'s `EventPublisher`.
+  `AggregateRoot.commit()` routes events through the transactional
+  dispatcher, so `AFTER_COMMIT` handlers only fire once the
+  transaction actually commits — no more "event published, then
+  transaction rolled back" race.
+- **`HybridEventPublisher`** — the strategy wired by
+  `CqrsTransactionalModule.forRoot()` into the `EventPublisher`
+  override. Routes aggregate events through the in-memory dispatcher
+  AND, when an outbox scheduler is bound to the
+  `OUTBOX_PUBLICATION_SCHEDULER` token, also through
+  `@nestjs-transactional/outbox` for durable delivery. Without
+  the outbox binding, behaves identically to
+  `TransactionalEventPublisher`.
+- **`CqrsHandlerWrapper` + `CqrsTransactionalBootstrap`** — bootstrap-time
+  wrapping of every `@CommandHandler` / `@QueryHandler` / `@EventsHandler`
+  instance that carries `@Transactional()` metadata (method-level or
+  class-level), or matches kind-specific defaults (e.g. read-only
+  wrapping for queries).
+- **`TransactionalListenerScanner` +
+  `IntegrationEventsHandlerScanner`** — `OnModuleInit` scanners that
+  auto-register every `@TransactionalEventsHandler` /
+  `@IntegrationEventsHandler` class with the appropriate delivery
+  path.
+- **`CqrsTransactionalModule.forRoot({...})`** — single entry point that
+  wires all of the above.
+
+Peer dependencies: `@nestjs-transactional/core`, `@nestjs/cqrs ^11`,
+`@nestjs/common ^10 || ^11`, `@nestjs/core ^10 || ^11`, `rxjs ^7`,
+`reflect-metadata`.
+
+## Module configuration
+
+```ts
+import { Module } from '@nestjs/common';
+import { TransactionalModule } from '@nestjs-transactional/core';
+import { TypeOrmTransactionalModule } from '@nestjs-transactional/typeorm';
+import { CqrsTransactionalModule } from '@nestjs-transactional/cqrs';
+
+@Module({
+  imports: [
+    TransactionalModule.forRoot({ isGlobal: true }),
+    TypeOrmTransactionalModule.forRoot(),
+    CqrsTransactionalModule.forRoot({
+      // every option has a sensible default — shown here for completeness
+      wrapCommandHandlers: true,
+      wrapQueryHandlers: true,
+      wrapEventHandlers: true,
+      defaultQueryOptions: { readOnly: true },
+      // defaultCommandOptions: { propagation: PropagationMode.REQUIRED },
+      useTransactionalEventPublisher: true,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+**Important**: do NOT import `CqrsModule` separately alongside
+`CqrsTransactionalModule.forRoot()`. The transactional module imports
+`CqrsModule` internally and overrides the `EventPublisher` DI token —
+importing `CqrsModule` a second time in the consumer shadows the
+override with the original.
+
+## Full example
+
+An order placement flow, end-to-end:
+
+```ts
+// aggregate.ts
+import { AggregateRoot } from '@nestjs/cqrs';
+
+export class OrderPlacedEvent {
+  constructor(public readonly orderId: string) {}
+}
+
+export class Order extends AggregateRoot {
+  constructor(public readonly id: string) {
+    super();
+  }
+  place(): void {
+    this.apply(new OrderPlacedEvent(this.id));
+  }
+}
+```
+
+```ts
+// order.repository.ts
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { OrderRow } from './order.entity';
+
+@Injectable()
+export class OrderRepository {
+  constructor(
+    @InjectRepository(OrderRow) private readonly rows: Repository<OrderRow>,
+  ) {}
+
+  async save(order: { id: string }): Promise<void> {
+    // The @InjectRepository instance auto-dispatches through the
+    // active @Transactional() scope's EntityManager — no
+    // getCurrentEntityManager() boilerplate needed.
+    await this.rows.save({ id: order.id });
+  }
+}
+```
+
+```ts
+// place-order.handler.ts
+import { CommandHandler, EventPublisher, type ICommandHandler } from '@nestjs/cqrs';
+import { Transactional } from '@nestjs-transactional/core';
+import { Order } from './aggregate';
+import { OrderRepository } from './order.repository';
+
+export class PlaceOrderCommand {
+  constructor(public readonly orderId: string) {}
+}
+
+@CommandHandler(PlaceOrderCommand)
+export class PlaceOrderHandler implements ICommandHandler<PlaceOrderCommand, void> {
+  constructor(
+    private readonly publisher: EventPublisher,
+    private readonly repo: OrderRepository,
+  ) {}
+
+  @Transactional()
+  async execute(command: PlaceOrderCommand): Promise<void> {
+    const order = this.publisher.mergeObjectContext(new Order(command.orderId));
+    order.place();
+    await this.repo.save(order);
+    order.commit(); // events attach as AFTER_COMMIT hooks on the current tx
+  }
+}
+```
+
+```ts
+// order.projection.ts
+import { Injectable } from '@nestjs/common';
+import {
+  type ITransactionalEventHandler,
+  TransactionPhase,
+  TransactionalEventsHandler,
+} from '@nestjs-transactional/cqrs';
+import { OrderPlacedEvent } from './aggregate';
+
+@Injectable()
+@TransactionalEventsHandler(OrderPlacedEvent)
+export class OrderCommittedProjection
+  implements ITransactionalEventHandler<OrderPlacedEvent>
+{
+  async handle(event: OrderPlacedEvent): Promise<void> {
+    // Runs AFTER the transaction commits, not before. Safe to do side
+    // effects here — the DB write is durable.
+  }
+}
+
+@Injectable()
+@TransactionalEventsHandler({
+  events: [OrderPlacedEvent],
+  phase: TransactionPhase.AFTER_ROLLBACK,
+})
+export class OrderRollbackProjection
+  implements ITransactionalEventHandler<OrderPlacedEvent>
+{
+  handle(event: OrderPlacedEvent, error?: unknown): void {
+    // Compensating action; receives the rollback cause as the second
+    // argument (added beyond the interface signature — TypeScript
+    // permits widening the parameter list on the implementation).
+  }
+}
+```
+
+Note the class-per-reaction shape: `OrderCommittedProjection` reacts
+to the AFTER_COMMIT phase, `OrderRollbackProjection` to
+AFTER_ROLLBACK. Each class has one `handle` method because each class
+has one responsibility — see ADR-014 for the rationale.
+
+What happens when `commandBus.execute(new PlaceOrderCommand('o-1'))` is
+dispatched:
+
+1. `CqrsHandlerWrapper` has replaced `PlaceOrderHandler.execute` with a
+   `TransactionManager.run(...)` wrapper at application bootstrap. The
+   dispatch enters a new transaction.
+2. Inside the wrapped execute, the aggregate's `publishAll` goes through
+   `TransactionalEventPublisher`, which calls
+   `TransactionalEventDispatcher.scheduleDispatch(event)`. The
+   dispatcher attaches `OrderCommittedProjection.handle` as an
+   `AFTER_COMMIT` hook on the current transaction, and
+   `OrderRollbackProjection.handle` as an `AFTER_ROLLBACK` hook.
+3. The repository's `@InjectRepository(OrderRow)` Repository
+   auto-dispatches through the active transaction (the transparent
+   transactional repository feature in
+   [`@nestjs-transactional/typeorm`](../typeorm)) — both writes go
+   through the same DB connection.
+4. `execute` resolves; `TransactionManager` commits the transaction;
+   the adapter flushes to the database.
+5. After the commit succeeds, the manager runs `AFTER_COMMIT` hooks —
+   `OrderCommittedProjection.handle` fires once, with a row already
+   visible in the database.
+6. On a thrown error, step 4 rolls back instead; step 5 runs
+   `AFTER_ROLLBACK` hooks — `OrderRollbackProjection.handle` fires,
+   receiving the original error.
+
+## Decorator shapes — rest params vs. options object
+
+Every handler decorator accepts two equivalent forms:
+
+```ts
+// Short form — rest params. Use when defaults are fine.
+@TransactionalEventsHandler(OrderPlacedEvent, OrderCancelledEvent)
+@OutboxEventsHandler(OrderPlacedEvent)
+@IntegrationEventsHandler(OrderPlacedEvent)
+
+// Long form — options object. Use when you need non-default phase,
+// async, fallbackExecution, or a stable listener id.
+@TransactionalEventsHandler({
+  events: [OrderPlacedEvent],
+  phase: TransactionPhase.BEFORE_COMMIT,
+  async: false,
+  fallbackExecution: true,
+})
+@IntegrationEventsHandler({
+  events: [OrderPlacedEvent],
+  id: 'Inventory.stable-id',
+})
+```
+
+## Handler phases at a glance
+
+| Phase | When it fires | If handler throws |
+|---|---|---|
+| `BEFORE_COMMIT` | Before the adapter issues COMMIT | Transaction rolls back |
+| `AFTER_COMMIT` *(default)* | After a successful COMMIT | Logged and swallowed |
+| `AFTER_ROLLBACK` | After ROLLBACK; receives the causing error as second arg | Logged and swallowed |
+| `AFTER_COMPLETION` | On any completion (commit OR rollback) | Logged and swallowed |
+
+`{ fallbackExecution: true }` makes a handler fire directly (via
+`queueMicrotask`) when the event is published outside any transaction.
+Otherwise out-of-transaction events are dropped with a warning.
+
+`{ async: true }` fires the handler via `queueMicrotask` even inside a
+transaction — its errors never reach the transaction's rollback path.
+Useful for genuinely fire-and-forget side effects.
+
+## Defaults baked into `CqrsTransactionalModule.forRoot()`
+
+- Command handlers are wrapped in `REQUIRED`-propagation transactions.
+  Without method- or class-level `@Transactional()`, they remain unwrapped
+  unless `defaultCommandOptions` is provided.
+- Query handlers are wrapped as read-only transactions by default
+  (`defaultQueryOptions: { readOnly: true }`). Pass
+  `defaultQueryOptions: undefined` to opt out.
+- Event handlers are wrapped only if they carry `@Transactional()` (no
+  kind-level default is applied to events — they are often used for
+  out-of-band side effects where wrapping is inappropriate).
+- `AggregateRoot.commit()` routes events through the dispatcher — set
+  `useTransactionalEventPublisher: false` to leave `@nestjs/cqrs`'s
+  standard `EventPublisher` in place (useful for gradual adoption).
+
+## Outbox integration
+
+`CqrsTransactionalModule.forRoot()` always wires `HybridEventPublisher`
+into the `EventPublisher` DI override. By default, `HybridEventPublisher`
+routes events only through the in-memory dispatcher — no outbox side
+effects. To turn on durable delivery, bind BOTH structural ports in
+your app module:
+
+```ts
+import { Module } from '@nestjs/common';
+import {
+  OutboxEventPublisher,
+  OutboxListenerRegistry,
+  OutboxModule,
+} from '@nestjs-transactional/outbox';
+import {
+  CqrsTransactionalModule,
+  OUTBOX_LISTENER_REGISTRAR,
+  OUTBOX_PUBLICATION_SCHEDULER,
+} from '@nestjs-transactional/cqrs';
+
+@Module({
+  imports: [
+    // ...the usual wiring — TransactionalModule, a typeorm adapter,
+    // OutboxTypeOrmModule, OutboxModule, CqrsTransactionalModule...
+    CqrsTransactionalModule.forRoot(),
+  ],
+  providers: [
+    // Routes AggregateRoot.commit() events to the outbox for durable
+    // publication.
+    { provide: OUTBOX_PUBLICATION_SCHEDULER, useExisting: OutboxEventPublisher },
+    // Routes @IntegrationEventsHandler classes to the outbox registry
+    // for durable delivery.
+    { provide: OUTBOX_LISTENER_REGISTRAR, useExisting: OutboxListenerRegistry },
+  ],
+})
+export class AppModule {}
+```
+
+With both bindings in place, a single `aggregate.commit()` call:
+
+1. Attaches one `AFTER_COMMIT` hook per `@TransactionalEventsHandler`
+   class registered for the event — fires after the transaction
+   commits, entirely in-memory, no DB rows.
+2. Buffers the event for outbox publication — a single
+   `beforeCommit` hook per transaction flushes the whole buffer into
+   `event_publication` rows, atomically with the business write.
+3. Once the transaction commits, the outbox processor (running in
+   a worker) polls those rows and invokes every
+   `@OutboxEventsHandler` / `@IntegrationEventsHandler` class
+   registered for the event.
+
+Rollback rolls back all three: no in-memory handlers fire, no
+publication rows are persisted, nothing downstream runs. This is the
+core guarantee of the outbox pattern — "event published only if the
+business change landed".
+
+## Choosing between handler flavours
+
+- **`@TransactionalEventsHandler`** — cheap, in-process, phase-aware,
+  non-durable. Use for side effects that are OK to lose on a crash
+  between commit and invocation (metrics, cache invalidation,
+  enrichment of in-memory state).
+- **`@OutboxEventsHandler`** *(from outbox)* — durable,
+  retry-on-failure, resumable-across-restart, delivered by a worker.
+  Use for integration with external systems, email sends, billing
+  events, or any side effect where at-least-once delivery matters.
+  Requires `OutboxModule` to be wired.
+- **`@IntegrationEventsHandler`** — smart default, class-level
+  composite. When the outbox registrar is bound, delivery goes
+  through the outbox (durable). Without it, delivery falls back to
+  the in-memory dispatcher with `AFTER_COMMIT` + `async: true` +
+  fresh-transaction semantics. Matches Spring Modulith's
+  `@ApplicationModuleListener` contract — "the thing you reach for by
+  default when wiring cross-module listeners, so you do not have to
+  revisit every call site when persistence comes online".
+
+### Delivery guarantees at a glance
+
+| Decorator | Persisted? | Retry on failure? | Survives process restart? | Transaction | Typical use case |
+| --- | --- | --- | --- | --- | --- |
+| `@TransactionalEventsHandler` | No — in-memory only | No | No | Joins the publishing transaction's lifecycle (fires at configured phase) | Cache invalidation, metrics, in-process enrichment |
+| `@OutboxEventsHandler` | Yes — `event_publication` row per listener | Yes — via operator-triggered resubmit | Yes — `republishOnStartup` replays | `REQUIRES_NEW` per invocation (default) | External API calls, emails, billing events, cross-module integration where loss is unacceptable |
+| `@IntegrationEventsHandler` | Yes if outbox registrar bound, No otherwise | Yes if outbox bound | Yes if outbox bound | `REQUIRES_NEW` (outbox) or `AFTER_COMMIT + async: true` inside a fresh tx (fallback) | Default choice for cross-module handlers — upgrades gracefully when the outbox comes online |
+
+How `@IntegrationEventsHandler` routes depends on module wiring, not
+on call-site configuration: write one decorator, and the same handler
+runs via the in-memory path during early development and via the
+durable outbox once the team is ready to stand up the worker process.
+`IntegrationEventsHandlerScanner` decides at bootstrap based on
+whether the `OUTBOX_LISTENER_REGISTRAR` provider is bound — so the
+handler fires exactly once.
+
+```ts
+@Injectable()
+@IntegrationEventsHandler(OrderPlacedEvent)
+export class InventoryReservationHandler
+  implements IIntegrationEventHandler<OrderPlacedEvent>
+{
+  async handle(event: OrderPlacedEvent): Promise<void> {
+    // with outbox wired: runs from the worker, retried on failure.
+    // without outbox:    runs in-memory after commit, fire-and-forget.
+  }
+}
+```
+
+Supply a stable `id` when the class name might change:
+
+```ts
+@IntegrationEventsHandler({
+  events: [OrderPlacedEvent],
+  id: 'Inventory.stable-id',
+})
+```
+
+The listener id format is `${baseId}#${EventName}` where baseId
+defaults to the class name — so class renames invalidate stored
+publications unless `options.id` is set.
+
+## Worked examples
+
+- [`basic-cqrs`](../../examples/basic-cqrs) — Command + Query (auto-readonly) + AFTER_COMMIT `@TransactionalEventsHandler`, no DB.
+- [`multi-datasource-cqrs`](../../examples/multi-datasource-cqrs) — `@Transactional({ dataSource })` per handler with per-DS hook attachment.
+- [`saga-pattern`](../../examples/saga-pattern), [`audit-logging`](../../examples/audit-logging) — `@TransactionalEventsHandler` + `@OutboxEventsHandler` against the same event class.
+- [`e-commerce-orders`](../../examples/e-commerce-orders) — full CQRS + REST controller + outbox-driven saga + multi-DS.
+
+Full catalogue: [examples/README.md](../../examples/README.md).
+
+## Limitations
+
+- Only works with **singleton** handlers. Request-scoped CQRS handlers
+  are resolved per-request by `@nestjs/cqrs` via `ModuleRef.resolve(...)`,
+  producing a fresh instance our bootstrap wrap has not mutated.
+- Direct `eventBus.publish(...)` calls (outside of an aggregate) do NOT
+  go through the transactional dispatcher — only `AggregateRoot.commit()`
+  -emitted events via `mergeObjectContext` / `mergeClassContext`. If you
+  need phase-aware handlers on bus-published events, publish them from
+  an aggregate instead.
+- `@nestjs/cqrs`'s handler-metadata constants are read via hardcoded
+  string literals (`__commandHandler__`, etc.) because `@nestjs/cqrs`
+  does not re-export them. See `handler-wrapper.ts` —
+  [DD-002](../../docs/dd/002-no-fork-nestjs-cqrs.md) documents this
+  coupling.
+
+## Status
+
+Alpha. Public API may change between 0.x releases.

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

@@ -0,0 +1,125 @@
+import 'reflect-metadata';
+import { type Type } from '@nestjs/common';
+/**
+ * Metadata key under which {@link IntegrationEventsHandlerMetadata} is
+ * stored on classes decorated with {@link IntegrationEventsHandler}.
+ *
+ * Private to the cqrs package — not shared with outbox (the
+ * smart scanner routes the handler based on whether a registrar is
+ * bound, not by inspecting shared metadata).
+ */
+export declare const INTEGRATION_EVENTS_HANDLER_METADATA: unique symbol;
+/**
+ * Options accepted by the long form of {@link IntegrationEventsHandler}.
+ */
+export interface IntegrationEventsHandlerOptions {
+    /** Domain event classes the handler subscribes to. Must be non-empty. */
+    readonly events: Type[];
+    /**
+     * Stable, globally-unique listener id used by the outbox registry to
+     * resolve which handler to invoke for a stored publication. When
+     * omitted, the scanner derives one from
+     * `${ClassName}#${EventName}` per event type — a rename of the class
+     * therefore breaks resume of already-stored publications. Supply an
+     * explicit id to protect against this. When multiple events are
+     * declared, the scanner appends `#${EventName}` to the supplied id.
+     */
+    readonly id?: string;
+    /**
+     * dataSource the in-memory dispatcher fallback path attaches phase
+     * hooks to (Phase 14.3.1). Only consulted when the outbox is NOT
+     * wired (no `OUTBOX_LISTENER_REGISTRAR` binding) — the outbox path
+     * auto-resolves the dataSource by walking per-DS event-type
+     * registries.
+     *
+     * Defaults to `'default'`. Multi-dataSource apps using the
+     * dispatcher fallback declare it explicitly on a non-default
+     * handler.
+     */
+    readonly dataSource?: string;
+}
+/**
+ * Resolved metadata attached to a handler class.
+ */
+export interface IntegrationEventsHandlerMetadata {
+    readonly eventTypes: Type[];
+    readonly id?: string;
+    readonly dataSource: string;
+}
+/**
+ * Smart-default decorator for cross-module / cross-service integration
+ * event handlers. The NestJS-idiomatic equivalent of Spring Modulith's
+ * `@ApplicationModuleListener` — see "Naming" below.
+ *
+ * Behaviour depends on module wiring, decided at bootstrap by
+ * `IntegrationEventsHandlerScanner`:
+ *
+ * 1. **Outbox wired** (the `OUTBOX_LISTENER_REGISTRAR` provider is
+ *    bound, typically via `OutboxModule`): the handler is registered
+ *    as a persistent outbox listener with `newTransaction: true`
+ *    semantics. Delivery is durable, at-least-once, retried on
+ *    failure, and survives process restarts.
+ *
+ * 2. **Outbox NOT wired**: the handler is registered in-memory via
+ *    `TransactionalEventDispatcher` with `phase: AFTER_COMMIT`,
+ *    `async: true`, and wrapped in a `REQUIRES_NEW` transaction —
+ *    mirroring the outbox-backed behaviour as closely as in-memory
+ *    dispatch allows (minus persistence).
+ *
+ * Either way, consumer code is identical:
+ *
+ * ```ts
+ * @IntegrationEventsHandler(OrderPlacedEvent)
+ * export class InventoryReservationHandler
+ *   implements IIntegrationEventHandler<OrderPlacedEvent>
+ * {
+ *   async handle(event: OrderPlacedEvent): Promise<void> { ... }
+ * }
+ * ```
+ *
+ * Two forms:
+ *
+ * ```ts
+ * // Short form:
+ * @IntegrationEventsHandler(OrderPlacedEvent, OrderCancelledEvent)
+ *
+ * // Long form with stable id:
+ * @IntegrationEventsHandler({
+ *   events: [OrderPlacedEvent],
+ *   id: 'inventory.reservation',
+ * })
+ * ```
+ *
+ * Behaviour is opinionated and fixed: AFTER_COMMIT phase, async
+ * execution, REQUIRES_NEW transaction. If you need any of those to
+ * differ, use {@link TransactionalEventsHandler} with explicit
+ * options instead — that decorator exposes the full configuration
+ * surface for in-memory event handling.
+ *
+ * **Naming.** The Spring Modulith decorator with this role is called
+ * `@ApplicationModuleListener`. We use `@IntegrationEventsHandler`
+ * because (a) "Application Module" overlaps with NestJS's `@Module()`
+ * (a DI concept), and (b) "Integration events" is the established
+ * DDD/microservices term for cross-module/cross-service event flow.
+ *
+ * **Multi-dataSource setups (Phase 14.3.1).** When the outbox path
+ * is wired, `OutboxModule.forRoot` auto-binds
+ * `OUTBOX_LISTENER_REGISTRAR` to a smart
+ * `MultiDsOutboxListenerRegistrar` that walks per-dataSource
+ * `EventTypeRegistry` instances to find which dataSource owns each
+ * handler's events and registers the listener with the matching
+ * per-DS registry — automatic, no decorator option required.
+ * Handlers subscribing to events across multiple dataSources are
+ * rejected at bootstrap (handlers must be dataSource-scoped).
+ *
+ * @throws {Error} If no event types are supplied.
+ */
+export declare function IntegrationEventsHandler(...events: Type[]): ClassDecorator;
+export declare function IntegrationEventsHandler(options: IntegrationEventsHandlerOptions): ClassDecorator;
+/**
+ * Read the {@link IntegrationEventsHandlerMetadata} attached to
+ * `target` by {@link IntegrationEventsHandler}. Returns `undefined`
+ * when the class was not decorated.
+ */
+export declare function getIntegrationEventsHandlerMetadata(target: object): IntegrationEventsHandlerMetadata | undefined;
+//# sourceMappingURL=integration-events-handler.decorator.d.ts.map

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

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INTEGRATION_EVENTS_HANDLER_METADATA = void 0;
+exports.IntegrationEventsHandler = IntegrationEventsHandler;
+exports.getIntegrationEventsHandlerMetadata = getIntegrationEventsHandlerMetadata;
+require("reflect-metadata");
+const core_1 = require("@nestjs-transactional/core");
+/**
+ * Metadata key under which {@link IntegrationEventsHandlerMetadata} is
+ * stored on classes decorated with {@link IntegrationEventsHandler}.
+ *
+ * Private to the cqrs package — not shared with outbox (the
+ * smart scanner routes the handler based on whether a registrar is
+ * bound, not by inspecting shared metadata).
+ */
+exports.INTEGRATION_EVENTS_HANDLER_METADATA = Symbol('INTEGRATION_EVENTS_HANDLER_METADATA');
+function IntegrationEventsHandler(...args) {
+    const metadata = resolveMetadata(args);
+    if (metadata.eventTypes.length === 0) {
+        throw new Error('@IntegrationEventsHandler requires at least one event type. ' +
+            'Pass class constructors as rest arguments or via the `events` option.');
+    }
+    return (target) => {
+        Reflect.defineMetadata(exports.INTEGRATION_EVENTS_HANDLER_METADATA, metadata, target);
+    };
+}
+function resolveMetadata(args) {
+    if (args.length === 1 && isOptionsObject(args[0])) {
+        const options = args[0];
+        return {
+            eventTypes: [...options.events],
+            id: options.id,
+            dataSource: options.dataSource ?? core_1.DEFAULT_DATA_SOURCE_NAME,
+        };
+    }
+    return {
+        eventTypes: args,
+        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 IntegrationEventsHandlerMetadata} attached to
+ * `target` by {@link IntegrationEventsHandler}. Returns `undefined`
+ * when the class was not decorated.
+ */
+function getIntegrationEventsHandlerMetadata(target) {
+    const value = Reflect.getMetadata(exports.INTEGRATION_EVENTS_HANDLER_METADATA, target);
+    return value;
+}
+//# sourceMappingURL=integration-events-handler.decorator.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"integration-events-handler.decorator.js","sourceRoot":"","sources":["../../src/decorators/integration-events-handler.decorator.ts"],"names":[],"mappings":";;;AAgIA,4DAeC;AAqCD,kFAKC;AAzLD,4BAA0B;AAG1B,qDAAsE;AAEtE;;;;;;;GAOG;AACU,QAAA,mCAAmC,GAAG,MAAM,CACvD,qCAAqC,CACtC,CAAC;AAiHF,SAAgB,wBAAwB,CACtC,GAAG,IAAgD;IAEnD,MAAM,QAAQ,GAAqC,eAAe,CAAC,IAAI,CAAC,CAAC;IAEzE,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,8DAA8D;YAC5D,uEAAuE,CAC1E,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,MAAc,EAAQ,EAAE;QAC9B,OAAO,CAAC,cAAc,CAAC,2CAAmC,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAChF,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CACtB,IAAgD;IAEhD,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,EAAE,EAAE,OAAO,CAAC,EAAE;YACd,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,+BAAwB;SAC3D,CAAC;IACJ,CAAC;IAED,OAAO;QACL,UAAU,EAAE,IAAc;QAC1B,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;;;;GAIG;AACH,SAAgB,mCAAmC,CACjD,MAAc;IAEd,MAAM,KAAK,GAAY,OAAO,CAAC,WAAW,CAAC,2CAAmC,EAAE,MAAM,CAAC,CAAC;IACxF,OAAO,KAAqD,CAAC;AAC/D,CAAC"}