@nestjs-transactional/outbox 1.0.0-alpha.0

package/dist/registry/multi-ds-listener-registrar.d.ts

@@ -0,0 +1,78 @@
+import { ModuleRef } from '@nestjs/core';
+import { type OutboxDataSourceNames } from '../dispatcher/outbox-event-publisher';
+/**
+ * Cross-package shared DI token for the outbox listener registrar
+ * structural port (declared in the cqrs package as
+ * `OUTBOX_LISTENER_REGISTRAR`). Defined here via `Symbol.for(...)`
+ * with the same key the cqrs package uses, so both packages refer
+ * to the same Symbol identity without a direct import in either
+ * direction (Convention #8 — same pattern as `WRAPPED_MARKER`).
+ *
+ * Importing this constant from `@nestjs-transactional/outbox` and
+ * importing `OUTBOX_LISTENER_REGISTRAR` from `@nestjs-transactional/cqrs`
+ * yields the same Symbol — they are interchangeable in `@Inject(...)`
+ * arguments.
+ *
+ * @internal — used by `OutboxModule.forRoot` to auto-bind the smart
+ * registrar. Consumers should keep importing
+ * `OUTBOX_LISTENER_REGISTRAR` from `@nestjs-transactional/cqrs` for
+ * source-level clarity.
+ */
+export declare const OUTBOX_LISTENER_REGISTRAR_TOKEN: unique symbol;
+/** Shape of an entry registered through the structural registrar port. */
+interface RegistrarListenerEntry {
+    readonly id: string;
+    readonly eventType: string;
+    readonly invoke: (event: unknown) => Promise<void>;
+}
+/**
+ * Multi-dataSource implementation of the cqrs package's
+ * `OutboxListenerRegistrar` structural port (Phase 14.3.1).
+ *
+ * Walks every per-dataSource {@link EventTypeRegistry} to resolve
+ * which dataSource owns each incoming listener's event class, then
+ * registers the listener with that dataSource's
+ * {@link OutboxListenerRegistry}. The cqrs scanner
+ * (`IntegrationEventsHandlerScanner`) injects the structural port
+ * blindly — this class is what makes a single inject-point handle
+ * arbitrary multi-DS deployments.
+ *
+ * **Auto-binding.** `OutboxModule.forRoot` registers this class
+ * under {@link OUTBOX_LISTENER_REGISTRAR_TOKEN} on the first
+ * `forRoot` call. The cqrs `IntegrationEventsHandlerScanner` then
+ * picks it up via its `@Optional() @Inject(OUTBOX_LISTENER_REGISTRAR)`
+ * — no consumer-side wiring required.
+ *
+ * **Failure modes** (delegated to {@link resolveDataSourceByEventTypeName}):
+ *
+ *  - Event not registered in any dataSource → throws on registration.
+ *  - Event registered in more than one dataSource → throws on
+ *    registration.
+ *
+ * In both cases the `IntegrationEventsHandlerScanner` propagates the
+ * error from its `onModuleInit`, surfacing the misconfiguration at
+ * application bootstrap rather than at first dispatch.
+ */
+export declare class MultiDsOutboxListenerRegistrar {
+    private readonly moduleRef;
+    private readonly dataSourceNames;
+    private readonly logger;
+    constructor(moduleRef: ModuleRef, dataSourceNames: OutboxDataSourceNames);
+    /**
+     * Register a listener with the per-dataSource
+     * {@link OutboxListenerRegistry} whose dataSource owns
+     * `listener.eventType`. Throws when the event-type cannot be
+     * routed unambiguously — see {@link resolveDataSourceByEventTypeName}.
+     */
+    register(listener: RegistrarListenerEntry): void;
+    /**
+     * Collect a Map of dataSource name → {@link EventTypeRegistry}
+     * from the live registrations Set. Resolved fresh per `register`
+     * call so a registrar surviving across module rebuilds (test
+     * scenarios) sees the current state instead of a snapshot taken
+     * at construction time.
+     */
+    private collectEventTypeRegistries;
+}
+export {};
+//# sourceMappingURL=multi-ds-listener-registrar.d.ts.map

package/dist/registry/multi-ds-listener-registrar.js

@@ -0,0 +1,112 @@
+"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 MultiDsOutboxListenerRegistrar_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MultiDsOutboxListenerRegistrar = exports.OUTBOX_LISTENER_REGISTRAR_TOKEN = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const outbox_event_publisher_1 = require("../dispatcher/outbox-event-publisher");
+const event_type_resolver_1 = require("../serialization/event-type-resolver");
+const token_utils_1 = require("../tokens/token-utils");
+/**
+ * Cross-package shared DI token for the outbox listener registrar
+ * structural port (declared in the cqrs package as
+ * `OUTBOX_LISTENER_REGISTRAR`). Defined here via `Symbol.for(...)`
+ * with the same key the cqrs package uses, so both packages refer
+ * to the same Symbol identity without a direct import in either
+ * direction (Convention #8 — same pattern as `WRAPPED_MARKER`).
+ *
+ * Importing this constant from `@nestjs-transactional/outbox` and
+ * importing `OUTBOX_LISTENER_REGISTRAR` from `@nestjs-transactional/cqrs`
+ * yields the same Symbol — they are interchangeable in `@Inject(...)`
+ * arguments.
+ *
+ * @internal — used by `OutboxModule.forRoot` to auto-bind the smart
+ * registrar. Consumers should keep importing
+ * `OUTBOX_LISTENER_REGISTRAR` from `@nestjs-transactional/cqrs` for
+ * source-level clarity.
+ */
+exports.OUTBOX_LISTENER_REGISTRAR_TOKEN = Symbol.for('@nestjs-transactional/cqrs/outbox-listener-registrar');
+/**
+ * Multi-dataSource implementation of the cqrs package's
+ * `OutboxListenerRegistrar` structural port (Phase 14.3.1).
+ *
+ * Walks every per-dataSource {@link EventTypeRegistry} to resolve
+ * which dataSource owns each incoming listener's event class, then
+ * registers the listener with that dataSource's
+ * {@link OutboxListenerRegistry}. The cqrs scanner
+ * (`IntegrationEventsHandlerScanner`) injects the structural port
+ * blindly — this class is what makes a single inject-point handle
+ * arbitrary multi-DS deployments.
+ *
+ * **Auto-binding.** `OutboxModule.forRoot` registers this class
+ * under {@link OUTBOX_LISTENER_REGISTRAR_TOKEN} on the first
+ * `forRoot` call. The cqrs `IntegrationEventsHandlerScanner` then
+ * picks it up via its `@Optional() @Inject(OUTBOX_LISTENER_REGISTRAR)`
+ * — no consumer-side wiring required.
+ *
+ * **Failure modes** (delegated to {@link resolveDataSourceByEventTypeName}):
+ *
+ *  - Event not registered in any dataSource → throws on registration.
+ *  - Event registered in more than one dataSource → throws on
+ *    registration.
+ *
+ * In both cases the `IntegrationEventsHandlerScanner` propagates the
+ * error from its `onModuleInit`, surfacing the misconfiguration at
+ * application bootstrap rather than at first dispatch.
+ */
+let MultiDsOutboxListenerRegistrar = MultiDsOutboxListenerRegistrar_1 = class MultiDsOutboxListenerRegistrar {
+    moduleRef;
+    dataSourceNames;
+    logger = new common_1.Logger(MultiDsOutboxListenerRegistrar_1.name);
+    constructor(moduleRef, dataSourceNames) {
+        this.moduleRef = moduleRef;
+        this.dataSourceNames = dataSourceNames;
+    }
+    /**
+     * Register a listener with the per-dataSource
+     * {@link OutboxListenerRegistry} whose dataSource owns
+     * `listener.eventType`. Throws when the event-type cannot be
+     * routed unambiguously — see {@link resolveDataSourceByEventTypeName}.
+     */
+    register(listener) {
+        const eventTypeRegistries = this.collectEventTypeRegistries();
+        const dataSource = (0, event_type_resolver_1.resolveDataSourceByEventTypeName)(listener.eventType, eventTypeRegistries);
+        const registry = this.moduleRef.get((0, token_utils_1.getOutboxListenerRegistryToken)(dataSource), { strict: false });
+        registry.register(listener);
+        this.logger.debug(`Routed listener id='${listener.id}' for event '${listener.eventType}' → dataSource '${dataSource}'`);
+    }
+    /**
+     * Collect a Map of dataSource name → {@link EventTypeRegistry}
+     * from the live registrations Set. Resolved fresh per `register`
+     * call so a registrar surviving across module rebuilds (test
+     * scenarios) sees the current state instead of a snapshot taken
+     * at construction time.
+     */
+    collectEventTypeRegistries() {
+        const registries = new Map();
+        for (const dataSource of this.dataSourceNames.keys()) {
+            const registry = this.moduleRef.get((0, token_utils_1.getEventTypeRegistryToken)(dataSource), { strict: false });
+            registries.set(dataSource, registry);
+        }
+        return registries;
+    }
+};
+exports.MultiDsOutboxListenerRegistrar = MultiDsOutboxListenerRegistrar;
+exports.MultiDsOutboxListenerRegistrar = MultiDsOutboxListenerRegistrar = MultiDsOutboxListenerRegistrar_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)(outbox_event_publisher_1.OUTBOX_DATA_SOURCE_NAMES)),
+    __metadata("design:paramtypes", [core_1.ModuleRef, Object])
+], MultiDsOutboxListenerRegistrar);
+//# sourceMappingURL=multi-ds-listener-registrar.js.map

package/dist/registry/multi-ds-listener-registrar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-ds-listener-registrar.js","sourceRoot":"","sources":["../../src/registry/multi-ds-listener-registrar.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAA4D;AAC5D,uCAAyC;AAEzC,iFAG8C;AAE9C,8EAAwF;AACxF,uDAG+B;AAI/B;;;;;;;;;;;;;;;;;GAiBG;AACU,QAAA,+BAA+B,GAAG,MAAM,CAAC,GAAG,CACvD,sDAAsD,CACvD,CAAC;AASF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEI,IAAM,8BAA8B,sCAApC,MAAM,8BAA8B;IAItB;IAEA;IALF,MAAM,GAAG,IAAI,eAAM,CAAC,gCAA8B,CAAC,IAAI,CAAC,CAAC;IAE1E,YACmB,SAAoB,EAEpB,eAAsC;QAFtC,cAAS,GAAT,SAAS,CAAW;QAEpB,oBAAe,GAAf,eAAe,CAAuB;IACtD,CAAC;IAEJ;;;;;OAKG;IACH,QAAQ,CAAC,QAAgC;QACvC,MAAM,mBAAmB,GAAG,IAAI,CAAC,0BAA0B,EAAE,CAAC;QAC9D,MAAM,UAAU,GAAG,IAAA,sDAAgC,EACjD,QAAQ,CAAC,SAAS,EAClB,mBAAmB,CACpB,CAAC;QAEF,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CACjC,IAAA,4CAA8B,EAAC,UAAU,CAAC,EAC1C,EAAE,MAAM,EAAE,KAAK,EAAE,CAClB,CAAC;QACF,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAE5B,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,uBAAuB,QAAQ,CAAC,EAAE,gBAAgB,QAAQ,CAAC,SAAS,mBAAmB,UAAU,GAAG,CACrG,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACK,0BAA0B;QAChC,MAAM,UAAU,GAAG,IAAI,GAAG,EAA6B,CAAC;QACxD,KAAK,MAAM,UAAU,IAAI,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,EAAE,CAAC;YACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CACjC,IAAA,uCAAyB,EAAC,UAAU,CAAC,EACrC,EAAE,MAAM,EAAE,KAAK,EAAE,CAClB,CAAC;YACF,UAAU,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,UAAU,CAAC;IACpB,CAAC;CACF,CAAA;AAnDY,wEAA8B;yCAA9B,8BAA8B;IAD1C,IAAA,mBAAU,GAAE;IAMR,WAAA,IAAA,eAAM,EAAC,iDAAwB,CAAC,CAAA;qCADL,gBAAS;GAJ5B,8BAA8B,CAmD1C"}

package/dist/registry/outbox-listener-scanner.d.ts

@@ -0,0 +1,66 @@
+import { type OnModuleInit, type Type } from '@nestjs/common';
+import { DiscoveryService, ModuleRef } from '@nestjs/core';
+import { TransactionManager } from '@nestjs-transactional/core';
+import { type OutboxDataSourceNames } from '../dispatcher/outbox-event-publisher';
+/**
+ * Bootstrap-time scanner that walks every provider in the running
+ * Nest application, finds classes decorated with
+ * `@OutboxEventsHandler`, and registers their `handle` method with
+ * the per-dataSource {@link OutboxListenerRegistry} that owns each
+ * decorated event class.
+ *
+ * **Per-dataSource routing (Phase 14.3.1).** Multi-`OutboxModule.forRoot`
+ * deployments register events to per-DS `EventTypeRegistry`
+ * instances via `OutboxModule.forFeature(events, { dataSource })`.
+ * The scanner walks every per-DS `EventTypeRegistry`, resolves which
+ * dataSource owns each handler's event classes (via
+ * {@link resolveDataSourceByEventTypeName}), and registers the
+ * handler with the matching per-DS `OutboxListenerRegistry`.
+ *
+ * Single-dataSource deployments see the same behaviour they always
+ * have: events go to the only registry, handlers register against it.
+ *
+ * **Constraint: handler events must come from a single dataSource.**
+ * A handler subscribing to events spanning multiple dataSources is a
+ * configuration error — handlers conceptually belong to one
+ * bounded context. The scanner throws at bootstrap with an
+ * actionable message naming the offending events and dataSources.
+ *
+ * Scanning is class-level only. The handler class must expose a
+ * `handle(event): Promise<void>` method (enforce this at the type
+ * level by implementing `IOutboxEventHandler`).
+ *
+ * Each registered entry carries a pre-bound `invoke` closure that
+ * applies `REQUIRES_NEW` transaction semantics when
+ * `newTransaction: true` (the default) and invokes the method
+ * directly otherwise.
+ *
+ * Registration runs in `onModuleInit` so all providers have been
+ * instantiated by the time the scan happens.
+ */
+export declare class OutboxListenerScanner implements OnModuleInit {
+    private readonly discovery;
+    private readonly moduleRef;
+    private readonly dataSourceNames;
+    private readonly transactionManager;
+    private readonly logger;
+    constructor(discovery: DiscoveryService, moduleRef: ModuleRef, dataSourceNames: OutboxDataSourceNames, transactionManager: TransactionManager);
+    onModuleInit(): void;
+    /**
+     * Resolve which dataSource a handler belongs to by looking up each
+     * of its decorated events in the per-DS event-type registries. The
+     * handler's events must all resolve to the same dataSource —
+     * cross-DS handlers are rejected at bootstrap.
+     */
+    private resolveHandlerDataSource;
+    private collectEventTypeRegistries;
+    private collectListenerRegistries;
+}
+/**
+ * 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. Exported so consumers
+ * can pre-compute the id for explicit registration / tests.
+ */
+export declare function composeListenerId(baseId: string, eventType: Type): string;
+//# sourceMappingURL=outbox-listener-scanner.d.ts.map

package/dist/registry/outbox-listener-scanner.js

@@ -0,0 +1,192 @@
+"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 OutboxListenerScanner_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutboxListenerScanner = void 0;
+exports.composeListenerId = composeListenerId;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const core_2 = require("@nestjs-transactional/core");
+const outbox_events_handler_decorator_1 = require("../decorators/outbox-events-handler.decorator");
+const outbox_event_publisher_1 = require("../dispatcher/outbox-event-publisher");
+const event_type_resolver_1 = require("../serialization/event-type-resolver");
+const token_utils_1 = require("../tokens/token-utils");
+const errors_1 = require("../types/errors");
+/**
+ * Bootstrap-time scanner that walks every provider in the running
+ * Nest application, finds classes decorated with
+ * `@OutboxEventsHandler`, and registers their `handle` method with
+ * the per-dataSource {@link OutboxListenerRegistry} that owns each
+ * decorated event class.
+ *
+ * **Per-dataSource routing (Phase 14.3.1).** Multi-`OutboxModule.forRoot`
+ * deployments register events to per-DS `EventTypeRegistry`
+ * instances via `OutboxModule.forFeature(events, { dataSource })`.
+ * The scanner walks every per-DS `EventTypeRegistry`, resolves which
+ * dataSource owns each handler's event classes (via
+ * {@link resolveDataSourceByEventTypeName}), and registers the
+ * handler with the matching per-DS `OutboxListenerRegistry`.
+ *
+ * Single-dataSource deployments see the same behaviour they always
+ * have: events go to the only registry, handlers register against it.
+ *
+ * **Constraint: handler events must come from a single dataSource.**
+ * A handler subscribing to events spanning multiple dataSources is a
+ * configuration error — handlers conceptually belong to one
+ * bounded context. The scanner throws at bootstrap with an
+ * actionable message naming the offending events and dataSources.
+ *
+ * Scanning is class-level only. The handler class must expose a
+ * `handle(event): Promise<void>` method (enforce this at the type
+ * level by implementing `IOutboxEventHandler`).
+ *
+ * Each registered entry carries a pre-bound `invoke` closure that
+ * applies `REQUIRES_NEW` transaction semantics when
+ * `newTransaction: true` (the default) and invokes the method
+ * directly otherwise.
+ *
+ * Registration runs in `onModuleInit` so all providers have been
+ * instantiated by the time the scan happens.
+ */
+let OutboxListenerScanner = OutboxListenerScanner_1 = class OutboxListenerScanner {
+    discovery;
+    moduleRef;
+    dataSourceNames;
+    transactionManager;
+    logger = new common_1.Logger(OutboxListenerScanner_1.name);
+    constructor(discovery, moduleRef, dataSourceNames, transactionManager) {
+        this.discovery = discovery;
+        this.moduleRef = moduleRef;
+        this.dataSourceNames = dataSourceNames;
+        this.transactionManager = transactionManager;
+    }
+    onModuleInit() {
+        const eventTypeRegistries = this.collectEventTypeRegistries();
+        const listenerRegistries = this.collectListenerRegistries();
+        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, outbox_events_handler_decorator_1.getOutboxEventsHandlerMetadata)(wrapper.metatype);
+            if (metadata === undefined) {
+                continue;
+            }
+            const className = wrapper.metatype.name ?? 'anonymous';
+            const instance = wrapper.instance;
+            const rawHandle = instance.handle;
+            if (typeof rawHandle !== 'function') {
+                this.logger.warn(`@OutboxEventsHandler on ${className}: missing \`handle(event)\` method — skipping`);
+                continue;
+            }
+            const dataSource = this.resolveHandlerDataSource(className, metadata.eventTypes, eventTypeRegistries);
+            const registry = listenerRegistries.get(dataSource);
+            if (registry === undefined) {
+                // Defensive — every dataSource in `dataSourceNames` is also
+                // in `listenerRegistries` because both maps are built from
+                // the same Set. Throw rather than silently skip.
+                throw new errors_1.OutboxError(`@OutboxEventsHandler on ${className}: no OutboxListenerRegistry registered for ` +
+                    `dataSource '${dataSource}'. This is a framework bug — please open an issue.`);
+            }
+            const boundHandle = rawHandle.bind(instance);
+            const manager = this.transactionManager;
+            const { newTransaction } = metadata;
+            const invoke = async (event) => {
+                if (newTransaction) {
+                    await manager.run({ propagation: core_2.PropagationMode.REQUIRES_NEW }, async () => {
+                        await boundHandle(event);
+                    });
+                }
+                else {
+                    await boundHandle(event);
+                }
+            };
+            const baseId = metadata.id ?? instance.constructor.name;
+            for (const eventType of metadata.eventTypes) {
+                const listenerId = composeListenerId(baseId, eventType);
+                registry.register({
+                    id: listenerId,
+                    eventType: eventType.name,
+                    invoke,
+                });
+            }
+        }
+    }
+    /**
+     * Resolve which dataSource a handler belongs to by looking up each
+     * of its decorated events in the per-DS event-type registries. The
+     * handler's events must all resolve to the same dataSource —
+     * cross-DS handlers are rejected at bootstrap.
+     */
+    resolveHandlerDataSource(className, eventTypes, eventTypeRegistries) {
+        const dataSourcePerEvent = new Map();
+        for (const eventType of eventTypes) {
+            const dataSource = (0, event_type_resolver_1.resolveDataSourceByEventTypeName)(eventType.name, eventTypeRegistries);
+            dataSourcePerEvent.set(eventType.name, dataSource);
+        }
+        const uniqueDataSources = new Set(dataSourcePerEvent.values());
+        if (uniqueDataSources.size > 1) {
+            const breakdown = [...dataSourcePerEvent]
+                .map(([eventName, dataSource]) => `  ${eventName} → '${dataSource}'`)
+                .join('\n');
+            throw new errors_1.OutboxError(`@OutboxEventsHandler on ${className}: events span multiple dataSources:\n${breakdown}\n` +
+                `Handlers must be scoped to a single dataSource. Either:\n` +
+                `  • register the events under the same dataSource (OutboxModule.forFeature(...))\n` +
+                `  • split the handler into separate classes per dataSource\n` +
+                `  • register manually via getOutboxListenerRegistryToken(ds).register(...)`);
+        }
+        // Exactly one entry — uniqueDataSources is non-empty because
+        // metadata.eventTypes is enforced non-empty by the decorator.
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        return [...uniqueDataSources][0];
+    }
+    collectEventTypeRegistries() {
+        const registries = new Map();
+        for (const dataSource of this.dataSourceNames.keys()) {
+            registries.set(dataSource, this.moduleRef.get((0, token_utils_1.getEventTypeRegistryToken)(dataSource), {
+                strict: false,
+            }));
+        }
+        return registries;
+    }
+    collectListenerRegistries() {
+        const registries = new Map();
+        for (const dataSource of this.dataSourceNames.keys()) {
+            registries.set(dataSource, this.moduleRef.get((0, token_utils_1.getOutboxListenerRegistryToken)(dataSource), {
+                strict: false,
+            }));
+        }
+        return registries;
+    }
+};
+exports.OutboxListenerScanner = OutboxListenerScanner;
+exports.OutboxListenerScanner = OutboxListenerScanner = OutboxListenerScanner_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(2, (0, common_1.Inject)(outbox_event_publisher_1.OUTBOX_DATA_SOURCE_NAMES)),
+    __metadata("design:paramtypes", [core_1.DiscoveryService,
+        core_1.ModuleRef, Object, core_2.TransactionManager])
+], OutboxListenerScanner);
+/**
+ * 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. Exported so consumers
+ * can pre-compute the id for explicit registration / tests.
+ */
+function composeListenerId(baseId, eventType) {
+    return `${baseId}#${eventType.name}`;
+}
+//# sourceMappingURL=outbox-listener-scanner.js.map

package/dist/registry/outbox-listener-scanner.js.map

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

package/dist/repository/event-publication-repository.d.ts

@@ -0,0 +1,112 @@
+import type { EventPublication, NewEventPublication } from '../types/event-publication';
+import type { PublicationStatus } from '../types/publication-status';
+/**
+ * Options accepted by {@link EventPublicationRepository.updateStatus}.
+ */
+export interface UpdateStatusOptions {
+    /** Set when transitioning to `COMPLETED` so downstream tools can audit. */
+    readonly completionDate?: Date;
+    /** Populated when transitioning to `FAILED`. */
+    readonly failureReason?: string;
+    /**
+     * Increment `completionAttempts` by one as part of the update.
+     * Used when a listener picks up a publication via `tryClaim`.
+     */
+    readonly incrementAttempts?: boolean;
+    /** Set when transitioning to `RESUBMITTED`. */
+    readonly lastResubmissionDate?: Date;
+}
+/**
+ * Options accepted by {@link EventPublicationRepository.findCompleted}.
+ */
+export interface FindCompletedOptions {
+    /** Only include publications whose `completionDate` is strictly before this. */
+    readonly olderThan?: Date;
+    /** Cap the number of returned rows. */
+    readonly limit?: number;
+}
+/**
+ * Options accepted by {@link EventPublicationRepository.findFailed}.
+ */
+export interface FindFailedOptions {
+    /** Minimum age (ms since `publicationDate`) for the row to be included. */
+    readonly minAge?: number;
+    /** Only include rows with `completionAttempts <= maxAttempts`. */
+    readonly maxAttempts?: number;
+}
+/**
+ * Persistence SPI for event publications.
+ *
+ * Implementations provide storage (TypeORM, Prisma, MongoDB, ...).
+ *
+ * All mutating operations are expected to participate in the ambient
+ * transaction (through the `AsyncLocalStorage` context provided by
+ * `@nestjs-transactional/core`) when one is active, so publication
+ * rows are committed atomically with the business data.
+ */
+export interface EventPublicationRepository {
+    /**
+     * Create multiple publications atomically. Called during event
+     * publishing — one entry per listener registered for the event.
+     */
+    createAll(publications: NewEventPublication[]): Promise<EventPublication[]>;
+    /** Lookup a publication by its id, or `null` when not found. */
+    findById(id: string): Promise<EventPublication | null>;
+    /**
+     * Update a publication's status. Used for lifecycle transitions:
+     * - `PUBLISHED` → `PROCESSING` (a listener has picked it up)
+     * - `PROCESSING` → `COMPLETED` (success)
+     * - `PROCESSING` → `FAILED` (exception)
+     * - `FAILED` → `RESUBMITTED` (operator resubmit)
+     */
+    updateStatus(id: string, status: PublicationStatus, options?: UpdateStatusOptions): Promise<void>;
+    /**
+     * Atomically claim a publication: transition `PUBLISHED` or
+     * `RESUBMITTED` → `PROCESSING` (and increment `completionAttempts`)
+     * iff the current status is one of those. Returns `true` when the
+     * claim succeeded, `false` otherwise — used by the dispatcher to
+     * prevent double-processing across workers.
+     */
+    tryClaim(id: string): Promise<boolean>;
+    /**
+     * Find publications ready for processing (status `PUBLISHED` or
+     * `RESUBMITTED`). Production implementations should use
+     * `SELECT ... FOR UPDATE SKIP LOCKED` (or equivalent) to be safe
+     * against concurrent workers.
+     */
+    findReadyForProcessing(limit: number): Promise<EventPublication[]>;
+    /**
+     * Find publications in the given statuses whose `publicationDate` is
+     * strictly before `beforeDate`. Used by the staleness monitor.
+     */
+    findStale(beforeDate: Date, statuses: PublicationStatus[]): Promise<EventPublication[]>;
+    /** Find all completed publications, with optional pagination / cutoff. */
+    findCompleted(options?: FindCompletedOptions): Promise<EventPublication[]>;
+    /**
+     * Find all incomplete publications (status other than `COMPLETED`).
+     * Backs the `IncompleteEventPublications` operator API.
+     */
+    findIncomplete(): Promise<EventPublication[]>;
+    /**
+     * Find failed publications. Backs the `FailedEventPublications`
+     * operator API.
+     */
+    findFailed(options?: FindFailedOptions): Promise<EventPublication[]>;
+    /**
+     * Delete completed publications whose `completionDate` is strictly
+     * before `olderThan` (or all completed publications when the argument
+     * is omitted). Returns the number of rows removed.
+     */
+    deleteCompleted(olderThan?: Date): Promise<number>;
+    /**
+     * Archive a completed publication. Implementation-specific — typical
+     * TypeORM backend copies the row to an archive table before removing
+     * it from the hot queue.
+     */
+    archiveCompleted(id: string): Promise<void>;
+    /** Delete a single publication by id. Used for `DELETE` completion mode. */
+    delete(id: string): Promise<void>;
+}
+/** DI token for the active {@link EventPublicationRepository}. */
+export declare const EVENT_PUBLICATION_REPOSITORY: unique symbol;
+//# sourceMappingURL=event-publication-repository.d.ts.map

package/dist/repository/event-publication-repository.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVENT_PUBLICATION_REPOSITORY = void 0;
+/** DI token for the active {@link EventPublicationRepository}. */
+exports.EVENT_PUBLICATION_REPOSITORY = Symbol('EVENT_PUBLICATION_REPOSITORY');
+//# sourceMappingURL=event-publication-repository.js.map

package/dist/repository/event-publication-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-publication-repository.js","sourceRoot":"","sources":["../../src/repository/event-publication-repository.ts"],"names":[],"mappings":";;;AAiIA,kEAAkE;AACrD,QAAA,4BAA4B,GAAG,MAAM,CAAC,8BAA8B,CAAC,CAAC"}

package/dist/serialization/event-serializer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Serializes events for storage in the publication log and deserializes
+ * them back into application objects when a publication is picked up by
+ * a worker.
+ *
+ * Inspired by Spring Modulith's `EventSerializer`.
+ *
+ * Implementations are expected to:
+ * - throw `SerializationError` when encoding fails (circular refs,
+ *   unsupported values);
+ * - throw `DeserializationError` when decoding fails (malformed payload,
+ *   schema drift, missing type);
+ * - be deterministic so the same input yields the same output.
+ */
+export interface EventSerializer {
+    /** Encode an event payload into a string suitable for row storage. */
+    serialize(event: unknown): string;
+    /**
+     * Decode a previously-serialized payload back into an application
+     * object. `eventType` is the class name recorded alongside the
+     * payload — the implementation may use it to look up a class
+     * prototype via an {@link EventTypeRegistry} or similar.
+     */
+    deserialize(serialized: string, eventType: string): unknown;
+}
+/** DI token for the active {@link EventSerializer} implementation. */
+export declare const EVENT_SERIALIZER: unique symbol;
+//# sourceMappingURL=event-serializer.d.ts.map

package/dist/serialization/event-serializer.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVENT_SERIALIZER = void 0;
+/** DI token for the active {@link EventSerializer} implementation. */
+exports.EVENT_SERIALIZER = Symbol('EVENT_SERIALIZER');
+//# sourceMappingURL=event-serializer.js.map

package/dist/serialization/event-serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-serializer.js","sourceRoot":"","sources":["../../src/serialization/event-serializer.ts"],"names":[],"mappings":";;;AA0BA,sEAAsE;AACzD,QAAA,gBAAgB,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAC"}