@nestjs-transactional/outbox 1.0.0-alpha.0

package/dist/api/incomplete-event-publications.js

@@ -0,0 +1,72 @@
+"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); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IncompleteEventPublications = void 0;
+const common_1 = require("@nestjs/common");
+const event_publication_repository_1 = require("../repository/event-publication-repository");
+const publication_status_1 = require("../types/publication-status");
+const resubmission_options_1 = require("../types/resubmission-options");
+/**
+ * Operator-facing query + resubmit API for every publication that has
+ * not yet reached the terminal `COMPLETED` state. Equivalent to Spring
+ * Modulith's `IncompleteEventPublications`.
+ *
+ * Typical use case: startup / restart recovery — query the backlog,
+ * bulk-resubmit retriable rows, let the processor drain.
+ */
+let IncompleteEventPublications = class IncompleteEventPublications {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    /** Return every publication whose status is not `COMPLETED`. */
+    async findAll() {
+        return this.repository.findIncomplete();
+    }
+    /** How many publications are currently not `COMPLETED`. */
+    async count() {
+        const incomplete = await this.repository.findIncomplete();
+        return incomplete.length;
+    }
+    /**
+     * Scan every non-completed publication and transition retriable
+     * ones (`FAILED`, `PUBLISHED`) to `RESUBMITTED`. Publications
+     * currently `PROCESSING` or `RESUBMITTED` are left untouched —
+     * `PROCESSING` is owned by a worker and `RESUBMITTED` is already in
+     * the retry queue. Returns the number of rows transitioned.
+     */
+    async resubmitIncompletePublications(options = resubmission_options_1.ResubmissionOptions.defaults()) {
+        const incomplete = await this.repository.findIncomplete();
+        const filtered = options.filter !== null ? incomplete.filter(options.filter) : incomplete;
+        const toProcess = filtered.slice(0, options.batchSize);
+        let resubmitted = 0;
+        for (const pub of toProcess) {
+            if (pub.status === publication_status_1.PublicationStatus.FAILED ||
+                pub.status === publication_status_1.PublicationStatus.PUBLISHED) {
+                await this.repository.updateStatus(pub.id, publication_status_1.PublicationStatus.RESUBMITTED, {
+                    lastResubmissionDate: new Date(),
+                });
+                resubmitted++;
+            }
+        }
+        return resubmitted;
+    }
+};
+exports.IncompleteEventPublications = IncompleteEventPublications;
+exports.IncompleteEventPublications = IncompleteEventPublications = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(event_publication_repository_1.EVENT_PUBLICATION_REPOSITORY)),
+    __metadata("design:paramtypes", [Object])
+], IncompleteEventPublications);
+//# sourceMappingURL=incomplete-event-publications.js.map

package/dist/api/incomplete-event-publications.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"incomplete-event-publications.js","sourceRoot":"","sources":["../../src/api/incomplete-event-publications.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAAoD;AAEpD,6FAGoD;AAEpD,oEAAgE;AAChE,wEAAoE;AAGpE;;;;;;;GAOG;AAEI,IAAM,2BAA2B,GAAjC,MAAM,2BAA2B;IAGnB;IAFnB,YAEmB,UAAsC;QAAtC,eAAU,GAAV,UAAU,CAA4B;IACtD,CAAC;IAEJ,gEAAgE;IAChE,KAAK,CAAC,OAAO;QACX,OAAO,IAAI,CAAC,UAAU,CAAC,cAAc,EAAE,CAAC;IAC1C,CAAC;IAED,2DAA2D;IAC3D,KAAK,CAAC,KAAK;QACT,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,cAAc,EAAE,CAAC;QAC1D,OAAO,UAAU,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,8BAA8B,CAClC,UAA+B,0CAAmB,CAAC,QAAQ,EAAE;QAE7D,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,cAAc,EAAE,CAAC;QAE1D,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;QAC1F,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QAEvD,IAAI,WAAW,GAAG,CAAC,CAAC;QACpB,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;YAC5B,IACE,GAAG,CAAC,MAAM,KAAK,sCAAiB,CAAC,MAAM;gBACvC,GAAG,CAAC,MAAM,KAAK,sCAAiB,CAAC,SAAS,EAC1C,CAAC;gBACD,MAAM,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,EAAE,sCAAiB,CAAC,WAAW,EAAE;oBACxE,oBAAoB,EAAE,IAAI,IAAI,EAAE;iBACjC,CAAC,CAAC;gBACH,WAAW,EAAE,CAAC;YAChB,CAAC;QACH,CAAC;QAED,OAAO,WAAW,CAAC;IACrB,CAAC;CACF,CAAA;AA/CY,kEAA2B;sCAA3B,2BAA2B;IADvC,IAAA,mBAAU,GAAE;IAGR,WAAA,IAAA,eAAM,EAAC,2DAA4B,CAAC,CAAA;;GAF5B,2BAA2B,CA+CvC"}

package/dist/decorators/inject-decorators.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Inject decorators for the outbox-side per-dataSource components
+ * (DD-022). Each decorator below is sugar over
+ * `@Inject(getXxxToken(dataSource))` with a default dataSource of
+ * `'default'` — matches the `@InjectRepository(Entity, dataSource?)`
+ * ergonomics from `@nestjs/typeorm`.
+ *
+ * Single-adapter consumers omit the argument; multi-adapter
+ * consumers pass the dataSource name they registered with
+ * `OutboxModule.forRoot({ dataSource })`.
+ */
+/**
+ * Inject the per-dataSource `OutboxEventPublisher`. The
+ * default-injected publisher is the smart facade (DD-024) that
+ * detects the active transaction context and routes accordingly;
+ * this decorator binds the underlying per-dataSource publisher
+ * directly when explicit selection is needed.
+ *
+ * @example
+ * ```ts
+ * class BillingService {
+ *   constructor(
+ *     @InjectOutboxPublisher('billing')
+ *     private readonly publisher: OutboxEventPublisher,
+ *   ) {}
+ * }
+ * ```
+ */
+export declare const InjectOutboxPublisher: (dataSource?: string) => ParameterDecorator;
+/**
+ * Inject the per-dataSource `EventTypeRegistry`. The registry is
+ * populated by the `OutboxModule.forFeature([...])` calls made
+ * against the same dataSource — registrations do not bleed across
+ * dataSources.
+ */
+export declare const InjectEventTypeRegistry: (dataSource?: string) => ParameterDecorator;
+/**
+ * Inject the per-dataSource `EventPublicationRegistry` — the
+ * lifecycle coordinator that owns publication state transitions
+ * (`PUBLISHED` → `PROCESSING` → `COMPLETED` / `FAILED`).
+ */
+export declare const InjectEventPublicationRegistry: (dataSource?: string) => ParameterDecorator;
+/**
+ * Inject the per-dataSource `EventPublicationProcessor` — the async
+ * worker that drains publications, dispatches them to listeners,
+ * and invokes the externalizer (when bound). Typically only needed
+ * by tests that drive the loop manually with `processBatch()`.
+ */
+export declare const InjectEventPublicationProcessor: (dataSource?: string) => ParameterDecorator;
+/**
+ * Inject the per-dataSource `OutboxListenerRegistry` — registry of
+ * listener entries scanned from `@OutboxEventsHandler` classes (and,
+ * when wired, `@IntegrationEventsHandler` classes routed via the
+ * outbox).
+ */
+export declare const InjectOutboxListenerRegistry: (dataSource?: string) => ParameterDecorator;
+/**
+ * Inject the per-dataSource `ExternalizationRegistry` — maps event
+ * type names to their `@Externalized` metadata. Consumed by the
+ * processor at dispatch time; rarely needed by application code.
+ */
+export declare const InjectExternalizationRegistry: (dataSource?: string) => ParameterDecorator;
+/**
+ * Inject the per-dataSource `EventPublicationRepository`. Adapter
+ * packages (`outbox-typeorm`, future `outbox-prisma`, ...) register
+ * their concrete repository under this token. Most application
+ * code injects the higher-level `OutboxEventPublisher` instead.
+ */
+export declare const InjectEventPublicationRepository: (dataSource?: string) => ParameterDecorator;
+/**
+ * Inject the per-dataSource `EventExternalizer`. Multi-adapter
+ * processes can wire externalization independently per outbox stack
+ * — e.g. the `'billing'` outbox emits to Kafka, the `'audit'` outbox
+ * is internal-only and binds no externalizer.
+ */
+export declare const InjectEventExternalizer: (dataSource?: string) => ParameterDecorator;
+/**
+ * Inject the per-dataSource `EventSerializer` used by the outbox to
+ * marshal events into the stored JSON payload and revive them at
+ * dispatch time. Distinct dataSources may use distinct
+ * serialization strategies (e.g. one JSON, another schema-validated)
+ * without forcing one strategy process-wide.
+ */
+export declare const InjectOutboxEventSerializer: (dataSource?: string) => ParameterDecorator;
+//# sourceMappingURL=inject-decorators.d.ts.map

package/dist/decorators/inject-decorators.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InjectOutboxEventSerializer = exports.InjectEventExternalizer = exports.InjectEventPublicationRepository = exports.InjectExternalizationRegistry = exports.InjectOutboxListenerRegistry = exports.InjectEventPublicationProcessor = exports.InjectEventPublicationRegistry = exports.InjectEventTypeRegistry = exports.InjectOutboxPublisher = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs-transactional/core");
+const token_utils_1 = require("../tokens/token-utils");
+/**
+ * Inject decorators for the outbox-side per-dataSource components
+ * (DD-022). Each decorator below is sugar over
+ * `@Inject(getXxxToken(dataSource))` with a default dataSource of
+ * `'default'` — matches the `@InjectRepository(Entity, dataSource?)`
+ * ergonomics from `@nestjs/typeorm`.
+ *
+ * Single-adapter consumers omit the argument; multi-adapter
+ * consumers pass the dataSource name they registered with
+ * `OutboxModule.forRoot({ dataSource })`.
+ */
+/**
+ * Inject the per-dataSource `OutboxEventPublisher`. The
+ * default-injected publisher is the smart facade (DD-024) that
+ * detects the active transaction context and routes accordingly;
+ * this decorator binds the underlying per-dataSource publisher
+ * directly when explicit selection is needed.
+ *
+ * @example
+ * ```ts
+ * class BillingService {
+ *   constructor(
+ *     @InjectOutboxPublisher('billing')
+ *     private readonly publisher: OutboxEventPublisher,
+ *   ) {}
+ * }
+ * ```
+ */
+const InjectOutboxPublisher = (dataSource = core_1.DEFAULT_DATA_SOURCE_NAME) => (0, common_1.Inject)((0, token_utils_1.getOutboxPublisherToken)(dataSource));
+exports.InjectOutboxPublisher = InjectOutboxPublisher;
+/**
+ * Inject the per-dataSource `EventTypeRegistry`. The registry is
+ * populated by the `OutboxModule.forFeature([...])` calls made
+ * against the same dataSource — registrations do not bleed across
+ * dataSources.
+ */
+const InjectEventTypeRegistry = (dataSource = core_1.DEFAULT_DATA_SOURCE_NAME) => (0, common_1.Inject)((0, token_utils_1.getEventTypeRegistryToken)(dataSource));
+exports.InjectEventTypeRegistry = InjectEventTypeRegistry;
+/**
+ * Inject the per-dataSource `EventPublicationRegistry` — the
+ * lifecycle coordinator that owns publication state transitions
+ * (`PUBLISHED` → `PROCESSING` → `COMPLETED` / `FAILED`).
+ */
+const InjectEventPublicationRegistry = (dataSource = core_1.DEFAULT_DATA_SOURCE_NAME) => (0, common_1.Inject)((0, token_utils_1.getEventPublicationRegistryToken)(dataSource));
+exports.InjectEventPublicationRegistry = InjectEventPublicationRegistry;
+/**
+ * Inject the per-dataSource `EventPublicationProcessor` — the async
+ * worker that drains publications, dispatches them to listeners,
+ * and invokes the externalizer (when bound). Typically only needed
+ * by tests that drive the loop manually with `processBatch()`.
+ */
+const InjectEventPublicationProcessor = (dataSource = core_1.DEFAULT_DATA_SOURCE_NAME) => (0, common_1.Inject)((0, token_utils_1.getEventPublicationProcessorToken)(dataSource));
+exports.InjectEventPublicationProcessor = InjectEventPublicationProcessor;
+/**
+ * Inject the per-dataSource `OutboxListenerRegistry` — registry of
+ * listener entries scanned from `@OutboxEventsHandler` classes (and,
+ * when wired, `@IntegrationEventsHandler` classes routed via the
+ * outbox).
+ */
+const InjectOutboxListenerRegistry = (dataSource = core_1.DEFAULT_DATA_SOURCE_NAME) => (0, common_1.Inject)((0, token_utils_1.getOutboxListenerRegistryToken)(dataSource));
+exports.InjectOutboxListenerRegistry = InjectOutboxListenerRegistry;
+/**
+ * Inject the per-dataSource `ExternalizationRegistry` — maps event
+ * type names to their `@Externalized` metadata. Consumed by the
+ * processor at dispatch time; rarely needed by application code.
+ */
+const InjectExternalizationRegistry = (dataSource = core_1.DEFAULT_DATA_SOURCE_NAME) => (0, common_1.Inject)((0, token_utils_1.getExternalizationRegistryToken)(dataSource));
+exports.InjectExternalizationRegistry = InjectExternalizationRegistry;
+/**
+ * Inject the per-dataSource `EventPublicationRepository`. Adapter
+ * packages (`outbox-typeorm`, future `outbox-prisma`, ...) register
+ * their concrete repository under this token. Most application
+ * code injects the higher-level `OutboxEventPublisher` instead.
+ */
+const InjectEventPublicationRepository = (dataSource = core_1.DEFAULT_DATA_SOURCE_NAME) => (0, common_1.Inject)((0, token_utils_1.getEventPublicationRepositoryToken)(dataSource));
+exports.InjectEventPublicationRepository = InjectEventPublicationRepository;
+/**
+ * Inject the per-dataSource `EventExternalizer`. Multi-adapter
+ * processes can wire externalization independently per outbox stack
+ * — e.g. the `'billing'` outbox emits to Kafka, the `'audit'` outbox
+ * is internal-only and binds no externalizer.
+ */
+const InjectEventExternalizer = (dataSource = core_1.DEFAULT_DATA_SOURCE_NAME) => (0, common_1.Inject)((0, token_utils_1.getEventExternalizerToken)(dataSource));
+exports.InjectEventExternalizer = InjectEventExternalizer;
+/**
+ * Inject the per-dataSource `EventSerializer` used by the outbox to
+ * marshal events into the stored JSON payload and revive them at
+ * dispatch time. Distinct dataSources may use distinct
+ * serialization strategies (e.g. one JSON, another schema-validated)
+ * without forcing one strategy process-wide.
+ */
+const InjectOutboxEventSerializer = (dataSource = core_1.DEFAULT_DATA_SOURCE_NAME) => (0, common_1.Inject)((0, token_utils_1.getOutboxEventSerializerToken)(dataSource));
+exports.InjectOutboxEventSerializer = InjectOutboxEventSerializer;
+//# sourceMappingURL=inject-decorators.js.map

package/dist/decorators/inject-decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject-decorators.js","sourceRoot":"","sources":["../../src/decorators/inject-decorators.ts"],"names":[],"mappings":";;;AAAA,2CAAwC;AACxC,qDAAsE;AAEtE,uDAU+B;AAE/B;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACI,MAAM,qBAAqB,GAAG,CACnC,aAAqB,+BAAwB,EACzB,EAAE,CAAC,IAAA,eAAM,EAAC,IAAA,qCAAuB,EAAC,UAAU,CAAC,CAAC,CAAC;AAFxD,QAAA,qBAAqB,yBAEmC;AAErE;;;;;GAKG;AACI,MAAM,uBAAuB,GAAG,CACrC,aAAqB,+BAAwB,EACzB,EAAE,CAAC,IAAA,eAAM,EAAC,IAAA,uCAAyB,EAAC,UAAU,CAAC,CAAC,CAAC;AAF1D,QAAA,uBAAuB,2BAEmC;AAEvE;;;;GAIG;AACI,MAAM,8BAA8B,GAAG,CAC5C,aAAqB,+BAAwB,EACzB,EAAE,CAAC,IAAA,eAAM,EAAC,IAAA,8CAAgC,EAAC,UAAU,CAAC,CAAC,CAAC;AAFjE,QAAA,8BAA8B,kCAEmC;AAE9E;;;;;GAKG;AACI,MAAM,+BAA+B,GAAG,CAC7C,aAAqB,+BAAwB,EACzB,EAAE,CAAC,IAAA,eAAM,EAAC,IAAA,+CAAiC,EAAC,UAAU,CAAC,CAAC,CAAC;AAFlE,QAAA,+BAA+B,mCAEmC;AAE/E;;;;;GAKG;AACI,MAAM,4BAA4B,GAAG,CAC1C,aAAqB,+BAAwB,EACzB,EAAE,CAAC,IAAA,eAAM,EAAC,IAAA,4CAA8B,EAAC,UAAU,CAAC,CAAC,CAAC;AAF/D,QAAA,4BAA4B,gCAEmC;AAE5E;;;;GAIG;AACI,MAAM,6BAA6B,GAAG,CAC3C,aAAqB,+BAAwB,EACzB,EAAE,CAAC,IAAA,eAAM,EAAC,IAAA,6CAA+B,EAAC,UAAU,CAAC,CAAC,CAAC;AAFhE,QAAA,6BAA6B,iCAEmC;AAE7E;;;;;GAKG;AACI,MAAM,gCAAgC,GAAG,CAC9C,aAAqB,+BAAwB,EACzB,EAAE,CAAC,IAAA,eAAM,EAAC,IAAA,gDAAkC,EAAC,UAAU,CAAC,CAAC,CAAC;AAFnE,QAAA,gCAAgC,oCAEmC;AAEhF;;;;;GAKG;AACI,MAAM,uBAAuB,GAAG,CACrC,aAAqB,+BAAwB,EACzB,EAAE,CAAC,IAAA,eAAM,EAAC,IAAA,uCAAyB,EAAC,UAAU,CAAC,CAAC,CAAC;AAF1D,QAAA,uBAAuB,2BAEmC;AAEvE;;;;;;GAMG;AACI,MAAM,2BAA2B,GAAG,CACzC,aAAqB,+BAAwB,EACzB,EAAE,CAAC,IAAA,eAAM,EAAC,IAAA,2CAA6B,EAAC,UAAU,CAAC,CAAC,CAAC;AAF9D,QAAA,2BAA2B,+BAEmC"}

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

@@ -0,0 +1,97 @@
+import 'reflect-metadata';
+import { type Type } from '@nestjs/common';
+/**
+ * Metadata key under which {@link OutboxEventsHandlerMetadata} is
+ * stored on classes decorated with {@link OutboxEventsHandler}.
+ *
+ * Fresh `Symbol` (not `Symbol.for`) — this metadata is read only by
+ * outbox's own `OutboxListenerScanner`. Cross-package sharing is
+ * not required because `@IntegrationEventsHandler` in the cqrs
+ * package uses the `OUTBOX_LISTENER_REGISTRAR` structural port, not
+ * metadata introspection, to route handlers to the outbox.
+ */
+export declare const OUTBOX_EVENTS_HANDLER_METADATA: unique symbol;
+/**
+ * Options accepted by the long form of {@link OutboxEventsHandler}.
+ */
+export interface OutboxEventsHandlerOptions {
+    /** Domain event classes the handler subscribes to. Must be non-empty. */
+    readonly events: Type[];
+    /**
+     * Stable, globally-unique listener id base. When set, the scanner
+     * derives the per-event-type id as `${id}#${EventName}`. When
+     * omitted, the base id is `${ClassName}` — a rename of the class
+     * therefore breaks resume of already-stored publications.
+     *
+     * The id (after the suffix is appended) is persisted on every
+     * `event_publication` row — supply an explicit id to protect
+     * against renames in production.
+     */
+    readonly id?: string;
+    /**
+     * Run the handler in its own new transaction (`REQUIRES_NEW`
+     * semantics). Default: `true` — matches Spring Modulith's
+     * `@ApplicationModuleListener` behaviour. Set to `false` to run
+     * the handler without opening a transaction (e.g. the handler
+     * only calls an idempotent external API).
+     */
+    readonly newTransaction?: boolean;
+}
+/**
+ * Resolved metadata attached to a handler class.
+ */
+export interface OutboxEventsHandlerMetadata {
+    readonly eventTypes: Type[];
+    readonly id?: string;
+    readonly newTransaction: boolean;
+}
+/**
+ * Mark a class as a persistent outbox handler. The class must
+ * implement {@link IOutboxEventHandler} — expose a
+ * `handle(event): Promise<void>` method.
+ *
+ * Distinct from `@TransactionalEventsHandler` (cqrs package), which
+ * is in-memory and phase-based: `@OutboxEventsHandler` is
+ * persistent, always after-commit, and supports retry / recovery on
+ * restart. Also distinct from `@IntegrationEventsHandler`, which
+ * switches between durable and in-memory delivery based on module
+ * wiring — this decorator ALWAYS routes to the outbox (and will
+ * fail bootstrap without an outbox registry).
+ *
+ * Two forms:
+ *
+ * ```ts
+ * // Short form — defaults (newTransaction: true):
+ * @OutboxEventsHandler(OrderPlacedEvent, OrderCancelledEvent)
+ *
+ * // Long form — explicit options:
+ * @OutboxEventsHandler({
+ *   events: [OrderPlacedEvent],
+ *   id: 'inventory.reservation',
+ *   newTransaction: false,
+ * })
+ * ```
+ *
+ * Class-level only; the metadata is written by
+ * `Reflect.defineMetadata`. The actual registration happens at
+ * application bootstrap via `OutboxListenerScanner`.
+ *
+ * **Multi-dataSource (Phase 14.3.1).** The scanner walks every
+ * per-dataSource `EventTypeRegistry` and routes the handler to the
+ * `OutboxListenerRegistry` whose dataSource owns the decorated
+ * events — automatic, no decorator option required. A handler
+ * subscribing to events spanning multiple dataSources is rejected
+ * at bootstrap with an actionable message; handlers must be
+ * dataSource-scoped.
+ *
+ * @throws {Error} If no event types are supplied.
+ */
+export declare function OutboxEventsHandler(...events: Type[]): ClassDecorator;
+export declare function OutboxEventsHandler(options: OutboxEventsHandlerOptions): ClassDecorator;
+/**
+ * Read the {@link OutboxEventsHandlerMetadata} attached to `target`
+ * by {@link OutboxEventsHandler}. Returns `undefined` when the
+ * class was not decorated.
+ */
+export declare function getOutboxEventsHandlerMetadata(target: object): OutboxEventsHandlerMetadata | undefined;
+//# sourceMappingURL=outbox-events-handler.decorator.d.ts.map

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

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OUTBOX_EVENTS_HANDLER_METADATA = void 0;
+exports.OutboxEventsHandler = OutboxEventsHandler;
+exports.getOutboxEventsHandlerMetadata = getOutboxEventsHandlerMetadata;
+require("reflect-metadata");
+/**
+ * Metadata key under which {@link OutboxEventsHandlerMetadata} is
+ * stored on classes decorated with {@link OutboxEventsHandler}.
+ *
+ * Fresh `Symbol` (not `Symbol.for`) — this metadata is read only by
+ * outbox's own `OutboxListenerScanner`. Cross-package sharing is
+ * not required because `@IntegrationEventsHandler` in the cqrs
+ * package uses the `OUTBOX_LISTENER_REGISTRAR` structural port, not
+ * metadata introspection, to route handlers to the outbox.
+ */
+exports.OUTBOX_EVENTS_HANDLER_METADATA = Symbol('OUTBOX_EVENTS_HANDLER_METADATA');
+function OutboxEventsHandler(...args) {
+    const metadata = resolveMetadata(args);
+    if (metadata.eventTypes.length === 0) {
+        throw new Error('@OutboxEventsHandler requires at least one event type. ' +
+            'Pass class constructors as rest arguments or via the `events` option.');
+    }
+    return (target) => {
+        Reflect.defineMetadata(exports.OUTBOX_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,
+            newTransaction: options.newTransaction ?? true,
+        };
+    }
+    return {
+        eventTypes: args,
+        newTransaction: true,
+    };
+}
+function isOptionsObject(candidate) {
+    return (candidate !== null &&
+        typeof candidate === 'object' &&
+        !Array.isArray(candidate) &&
+        typeof candidate !== 'function' &&
+        'events' in candidate);
+}
+/**
+ * Read the {@link OutboxEventsHandlerMetadata} attached to `target`
+ * by {@link OutboxEventsHandler}. Returns `undefined` when the
+ * class was not decorated.
+ */
+function getOutboxEventsHandlerMetadata(target) {
+    const value = Reflect.getMetadata(exports.OUTBOX_EVENTS_HANDLER_METADATA, target);
+    return value;
+}
+//# sourceMappingURL=outbox-events-handler.decorator.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"outbox-events-handler.decorator.js","sourceRoot":"","sources":["../../src/decorators/outbox-events-handler.decorator.ts"],"names":[],"mappings":";;;AA+FA,kDAeC;AAmCD,wEAKC;AAtJD,4BAA0B;AAI1B;;;;;;;;;GASG;AACU,QAAA,8BAA8B,GAAG,MAAM,CAAC,gCAAgC,CAAC,CAAC;AAiFvF,SAAgB,mBAAmB,CACjC,GAAG,IAA2C;IAE9C,MAAM,QAAQ,GAAgC,eAAe,CAAC,IAAI,CAAC,CAAC;IAEpE,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,yDAAyD;YACvD,uEAAuE,CAC1E,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,MAAc,EAAQ,EAAE;QAC9B,OAAO,CAAC,cAAc,CAAC,sCAA8B,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC3E,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CACtB,IAA2C;IAE3C,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,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,IAAI;SAC/C,CAAC;IACJ,CAAC;IAED,OAAO;QACL,UAAU,EAAE,IAAc;QAC1B,cAAc,EAAE,IAAI;KACrB,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,SAAkB;IACzC,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,8BAA8B,CAC5C,MAAc;IAEd,MAAM,KAAK,GAAY,OAAO,CAAC,WAAW,CAAC,sCAA8B,EAAE,MAAM,CAAC,CAAC;IACnF,OAAO,KAAgD,CAAC;AAC1D,CAAC"}

package/dist/dispatcher/data-source-outbox-publisher.d.ts

@@ -0,0 +1,69 @@
+import type { EventPublicationRegistry } from '../registry/event-publication-registry';
+import type { OutboxListenerRegistry } from '../registry/listener-registry';
+/**
+ * Per-dataSource publisher (Phase 14.3). Owns the per-transaction
+ * buffer, lifecycle hook registration, and delegate calls into the
+ * `EventPublicationRegistry` bound to a single dataSource.
+ *
+ * Not user-facing — application code injects the smart facade
+ * {@link OutboxEventPublisher}, which routes events to the
+ * `DataSourceOutboxPublisher` whose dataSource owns the event class.
+ * Exported nonetheless because:
+ *   - tests may want to drive a per-DS publisher directly
+ *   - advanced consumers (e.g. cross-DS bridges) may need the
+ *     dataSource-bound surface
+ *
+ * Single-DS deployments still resolve `OutboxEventPublisher` from DI
+ * — the facade transparently delegates to the only registered
+ * `DataSourceOutboxPublisher`.
+ */
+export declare class DataSourceOutboxPublisher {
+    readonly dataSource: string;
+    private readonly registry;
+    private readonly listenerRegistry;
+    private readonly logger;
+    private readonly pending;
+    /**
+     * @param dataSource Public dataSource name this publisher binds to.
+     *   Used as the lookup key for the active transaction (DD-023) and
+     *   surfaced in error messages.
+     * @param registry Per-DS {@link EventPublicationRegistry}.
+     * @param listenerRegistry Per-DS {@link OutboxListenerRegistry}.
+     */
+    constructor(dataSource: string, registry: EventPublicationRegistry, listenerRegistry: OutboxListenerRegistry);
+    /**
+     * Publish a single event into this dataSource's outbox. Must be
+     * called inside an active transaction *for this dataSource*. Throws
+     * {@link IllegalTransactionStateError} otherwise — the publication
+     * row must commit atomically with the business write, and the
+     * specific dataSource's transaction is the only context that can
+     * provide that atomicity.
+     *
+     * Creates one publication entry per listener registered for the
+     * event type. Zero listeners is a silent no-op (but the
+     * active-transaction check still applies).
+     */
+    publish(event: unknown): Promise<void>;
+    /**
+     * Publish a batch of events through this dataSource — same semantics
+     * and same active-transaction check applied per event.
+     */
+    publishAll(events: readonly unknown[]): Promise<void>;
+    /**
+     * Synchronous scheduling for sync callers (e.g. `@nestjs/cqrs`'s
+     * `AggregateRoot.commit()`). Inside a transaction *for this
+     * dataSource*: events are buffered and flushed in a `beforeCommit`
+     * hook. Outside any transaction (or no transaction for this DS):
+     * fire-and-forget {@link publish}, errors logged.
+     *
+     * The hook is attached directly to this dataSource's `ActiveTransaction.beforeCommitHooks`
+     * — `transactionManager.registerBeforeCommit` is NOT used because it
+     * always targets "the first active transaction on the context",
+     * which is the wrong target when multiple dataSources have live
+     * transactions in the same async stack (Phase 14.2 cross-DS
+     * simultaneous scenario).
+     */
+    scheduleForPublication(event: unknown): void;
+    private ensureActiveTransaction;
+}
+//# sourceMappingURL=data-source-outbox-publisher.d.ts.map

package/dist/dispatcher/data-source-outbox-publisher.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataSourceOutboxPublisher = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs-transactional/core");
+/**
+ * Per-dataSource publisher (Phase 14.3). Owns the per-transaction
+ * buffer, lifecycle hook registration, and delegate calls into the
+ * `EventPublicationRegistry` bound to a single dataSource.
+ *
+ * Not user-facing — application code injects the smart facade
+ * {@link OutboxEventPublisher}, which routes events to the
+ * `DataSourceOutboxPublisher` whose dataSource owns the event class.
+ * Exported nonetheless because:
+ *   - tests may want to drive a per-DS publisher directly
+ *   - advanced consumers (e.g. cross-DS bridges) may need the
+ *     dataSource-bound surface
+ *
+ * Single-DS deployments still resolve `OutboxEventPublisher` from DI
+ * — the facade transparently delegates to the only registered
+ * `DataSourceOutboxPublisher`.
+ */
+class DataSourceOutboxPublisher {
+    dataSource;
+    registry;
+    listenerRegistry;
+    logger;
+    // Per-transaction buffer of events awaiting flush. Keyed by the
+    // ActiveTransaction object itself so the entry is GC'd with the
+    // transaction — no cleanup code to maintain, and no risk of
+    // cross-transaction leakage.
+    pending = new WeakMap();
+    /**
+     * @param dataSource Public dataSource name this publisher binds to.
+     *   Used as the lookup key for the active transaction (DD-023) and
+     *   surfaced in error messages.
+     * @param registry Per-DS {@link EventPublicationRegistry}.
+     * @param listenerRegistry Per-DS {@link OutboxListenerRegistry}.
+     */
+    constructor(dataSource, registry, listenerRegistry) {
+        this.dataSource = dataSource;
+        this.registry = registry;
+        this.listenerRegistry = listenerRegistry;
+        this.logger = new common_1.Logger(`DataSourceOutboxPublisher[${dataSource}]`);
+    }
+    /**
+     * Publish a single event into this dataSource's outbox. Must be
+     * called inside an active transaction *for this dataSource*. Throws
+     * {@link IllegalTransactionStateError} otherwise — the publication
+     * row must commit atomically with the business write, and the
+     * specific dataSource's transaction is the only context that can
+     * provide that atomicity.
+     *
+     * Creates one publication entry per listener registered for the
+     * event type. Zero listeners is a silent no-op (but the
+     * active-transaction check still applies).
+     */
+    async publish(event) {
+        this.ensureActiveTransaction();
+        const eventType = event.constructor.name;
+        const listeners = this.listenerRegistry.getByEventType(eventType);
+        if (listeners.length === 0) {
+            return;
+        }
+        const listenerIds = listeners.map((l) => l.id);
+        await this.registry.publish(event, listenerIds);
+    }
+    /**
+     * Publish a batch of events through this dataSource — same semantics
+     * and same active-transaction check applied per event.
+     */
+    async publishAll(events) {
+        for (const event of events) {
+            await this.publish(event);
+        }
+    }
+    /**
+     * Synchronous scheduling for sync callers (e.g. `@nestjs/cqrs`'s
+     * `AggregateRoot.commit()`). Inside a transaction *for this
+     * dataSource*: events are buffered and flushed in a `beforeCommit`
+     * hook. Outside any transaction (or no transaction for this DS):
+     * fire-and-forget {@link publish}, errors logged.
+     *
+     * The hook is attached directly to this dataSource's `ActiveTransaction.beforeCommitHooks`
+     * — `transactionManager.registerBeforeCommit` is NOT used because it
+     * always targets "the first active transaction on the context",
+     * which is the wrong target when multiple dataSources have live
+     * transactions in the same async stack (Phase 14.2 cross-DS
+     * simultaneous scenario).
+     */
+    scheduleForPublication(event) {
+        const tx = core_1.TransactionContext.getActiveTransactionByDataSource(this.dataSource);
+        if (tx === undefined) {
+            void this.publish(event).catch((err) => {
+                this.logger.error(`scheduleForPublication outside an active '${this.dataSource}' transaction failed: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err.stack : undefined);
+            });
+            return;
+        }
+        let buffer = this.pending.get(tx);
+        if (buffer === undefined) {
+            buffer = [];
+            this.pending.set(tx, buffer);
+            // Push the hook onto THIS specific transaction's hook list —
+            // not via transactionManager.registerBeforeCommit which targets
+            // the first-active transaction (wrong with multi-DS).
+            tx.beforeCommitHooks.push(async () => {
+                const toFlush = this.pending.get(tx);
+                this.pending.delete(tx);
+                if (toFlush !== undefined && toFlush.length > 0) {
+                    await this.publishAll(toFlush);
+                }
+            });
+        }
+        buffer.push(event);
+    }
+    ensureActiveTransaction() {
+        const tx = core_1.TransactionContext.getActiveTransactionByDataSource(this.dataSource);
+        if (tx === undefined) {
+            throw new core_1.IllegalTransactionStateError(`OutboxEventPublisher.publish for dataSource '${this.dataSource}' must be ` +
+                `called inside an active transaction for that dataSource. Wrap the call ` +
+                `in @Transactional({ dataSource: '${this.dataSource}' }) so the publication ` +
+                `row commits atomically with the business write.`);
+        }
+    }
+}
+exports.DataSourceOutboxPublisher = DataSourceOutboxPublisher;
+//# sourceMappingURL=data-source-outbox-publisher.js.map

package/dist/dispatcher/data-source-outbox-publisher.js.map

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