@nestjs-transactional/outbox 1.0.0-alpha.0

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

@@ -0,0 +1,69 @@
+import { type EventExternalizer } from '../externalization/event-externalizer';
+import { ExternalizationRegistry } from '../externalization/externalization-registry';
+import { EventPublicationRegistry } from '../registry/event-publication-registry';
+import { OutboxListenerRegistry } from '../registry/listener-registry';
+import type { EventPublicationProcessorOptions } from './processor-options';
+/**
+ * Async worker that drains the event publication queue:
+ *
+ * 1. Pulls up to `batchSize` publications in `PUBLISHED` / `RESUBMITTED`
+ *    state from the {@link EventPublicationRegistry};
+ * 2. atomically claims each one (`PUBLISHED/RESUBMITTED → PROCESSING`)
+ *    so concurrent workers cannot double-dispatch;
+ * 3. looks up the corresponding listener in the
+ *    {@link OutboxListenerRegistry} and invokes it with the
+ *    deserialized event;
+ * 4. finalizes the publication — `COMPLETED` with the configured
+ *    completion mode on success, `FAILED` with the error message
+ *    otherwise.
+ *
+ * Up to `maxConcurrent` invocations run in parallel inside one batch.
+ * Listener errors never bubble out: they are caught, logged, and
+ * recorded on the publication row.
+ */
+export declare class EventPublicationProcessor {
+    private readonly registry;
+    private readonly listenerRegistry;
+    private readonly options;
+    private readonly externalizer?;
+    private readonly externalizationRegistry?;
+    private readonly logger;
+    private running;
+    private processingLoop;
+    constructor(registry: EventPublicationRegistry, listenerRegistry: OutboxListenerRegistry, options: EventPublicationProcessorOptions, externalizer?: EventExternalizer | undefined, externalizationRegistry?: ExternalizationRegistry | undefined);
+    /** Start the periodic polling loop. Idempotent. */
+    start(): void;
+    /** Stop the polling loop and cancel any pending scheduled tick. */
+    stop(): void;
+    /**
+     * Process a single batch of pending publications. Safe to call
+     * directly from tests and one-shot tooling; `start()` triggers it
+     * periodically.
+     *
+     * Internal errors (e.g. DB unreachable) are caught and logged —
+     * this method never rejects.
+     */
+    processBatch(): Promise<void>;
+    private scheduleNext;
+    private processOne;
+    /**
+     * Externalize the event after the local listener has succeeded.
+     *
+     * Returns immediately (no-op) when:
+     * - no {@link EventExternalizer} is bound (DD-018 — externalization
+     *   is optional);
+     * - no {@link ExternalizationRegistry} is bound (defensive — the
+     *   `OutboxModule` always provides one, but direct `new`
+     *   instantiation in tests may omit it);
+     * - the event type carries no `@Externalized` mapping.
+     *
+     * Otherwise resolves the per-publication {@link ExternalizationMetadata}
+     * from the registry and invokes the externalizer. Any rejection is
+     * wrapped in {@link ExternalizationError} and re-thrown so the outer
+     * try / catch in `processOne` records the publication as `FAILED`,
+     * which preserves the single-unit atomicity contract from DD-019.
+     */
+    private tryExternalize;
+    private chunk;
+}
+//# sourceMappingURL=event-publication-processor.d.ts.map

package/dist/dispatcher/event-publication-processor.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 EventPublicationProcessor_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventPublicationProcessor = void 0;
+const common_1 = require("@nestjs/common");
+const errors_1 = require("../externalization/errors");
+const event_externalizer_1 = require("../externalization/event-externalizer");
+const externalization_registry_1 = require("../externalization/externalization-registry");
+const event_publication_registry_1 = require("../registry/event-publication-registry");
+const listener_registry_1 = require("../registry/listener-registry");
+/**
+ * Async worker that drains the event publication queue:
+ *
+ * 1. Pulls up to `batchSize` publications in `PUBLISHED` / `RESUBMITTED`
+ *    state from the {@link EventPublicationRegistry};
+ * 2. atomically claims each one (`PUBLISHED/RESUBMITTED → PROCESSING`)
+ *    so concurrent workers cannot double-dispatch;
+ * 3. looks up the corresponding listener in the
+ *    {@link OutboxListenerRegistry} and invokes it with the
+ *    deserialized event;
+ * 4. finalizes the publication — `COMPLETED` with the configured
+ *    completion mode on success, `FAILED` with the error message
+ *    otherwise.
+ *
+ * Up to `maxConcurrent` invocations run in parallel inside one batch.
+ * Listener errors never bubble out: they are caught, logged, and
+ * recorded on the publication row.
+ */
+let EventPublicationProcessor = EventPublicationProcessor_1 = class EventPublicationProcessor {
+    registry;
+    listenerRegistry;
+    options;
+    externalizer;
+    externalizationRegistry;
+    logger = new common_1.Logger(EventPublicationProcessor_1.name);
+    running = false;
+    processingLoop = null;
+    constructor(registry, listenerRegistry, options, externalizer, externalizationRegistry) {
+        this.registry = registry;
+        this.listenerRegistry = listenerRegistry;
+        this.options = options;
+        this.externalizer = externalizer;
+        this.externalizationRegistry = externalizationRegistry;
+    }
+    /** Start the periodic polling loop. Idempotent. */
+    start() {
+        if (this.running) {
+            return;
+        }
+        this.running = true;
+        this.scheduleNext();
+        this.logger.log('EventPublicationProcessor started');
+    }
+    /** Stop the polling loop and cancel any pending scheduled tick. */
+    stop() {
+        this.running = false;
+        if (this.processingLoop !== null) {
+            clearTimeout(this.processingLoop);
+            this.processingLoop = null;
+        }
+        this.logger.log('EventPublicationProcessor stopped');
+    }
+    /**
+     * Process a single batch of pending publications. Safe to call
+     * directly from tests and one-shot tooling; `start()` triggers it
+     * periodically.
+     *
+     * Internal errors (e.g. DB unreachable) are caught and logged —
+     * this method never rejects.
+     */
+    async processBatch() {
+        try {
+            const publications = await this.registry.findReadyForProcessing(this.options.batchSize);
+            if (publications.length === 0) {
+                return;
+            }
+            this.logger.debug(`Processing batch of ${publications.length} publications`);
+            const chunks = this.chunk(publications, this.options.maxConcurrent);
+            for (const chunk of chunks) {
+                await Promise.all(chunk.map((pub) => this.processOne(pub)));
+            }
+        }
+        catch (err) {
+            this.logger.error('Batch processing failed', err instanceof Error ? err.stack : String(err));
+        }
+    }
+    scheduleNext() {
+        if (!this.running) {
+            return;
+        }
+        this.processingLoop = setTimeout(() => {
+            void this.processBatch().finally(() => this.scheduleNext());
+        }, this.options.pollingInterval);
+    }
+    async processOne(publication) {
+        try {
+            const claimed = await this.registry.tryClaim(publication.id);
+            if (!claimed) {
+                return;
+            }
+            const listener = this.listenerRegistry.getById(publication.listenerId);
+            if (listener === undefined) {
+                await this.registry.markFailed(publication.id, `Listener '${publication.listenerId}' is not registered`);
+                this.logger.warn(`Listener '${publication.listenerId}' not found for publication ${publication.id}`);
+                return;
+            }
+            try {
+                const event = this.registry.deserialize(publication);
+                // Local listener invocation runs first so cheap, in-process
+                // failures fail fast before we touch a broker (DD-019).
+                await listener.invoke(event);
+                // Externalization is optional and gated by the registry
+                // resolution wired in 11.2 — `tryExternalize` is a no-op until
+                // ExternalizationRegistry lookup lands.
+                await this.tryExternalize(event, publication);
+                await this.registry.markCompleted(publication.id, this.options.completionMode);
+            }
+            catch (err) {
+                const reason = err instanceof Error ? err.message : String(err);
+                await this.registry.markFailed(publication.id, reason);
+                this.logger.error(`Listener '${publication.listenerId}' failed for publication ${publication.id}: ${reason}`, err instanceof Error ? err.stack : undefined);
+            }
+        }
+        catch (err) {
+            this.logger.error(`Error processing publication ${publication.id}`, err instanceof Error ? err.stack : String(err));
+        }
+    }
+    /**
+     * Externalize the event after the local listener has succeeded.
+     *
+     * Returns immediately (no-op) when:
+     * - no {@link EventExternalizer} is bound (DD-018 — externalization
+     *   is optional);
+     * - no {@link ExternalizationRegistry} is bound (defensive — the
+     *   `OutboxModule` always provides one, but direct `new`
+     *   instantiation in tests may omit it);
+     * - the event type carries no `@Externalized` mapping.
+     *
+     * Otherwise resolves the per-publication {@link ExternalizationMetadata}
+     * from the registry and invokes the externalizer. Any rejection is
+     * wrapped in {@link ExternalizationError} and re-thrown so the outer
+     * try / catch in `processOne` records the publication as `FAILED`,
+     * which preserves the single-unit atomicity contract from DD-019.
+     */
+    async tryExternalize(event, publication) {
+        if (this.externalizer === undefined || this.externalizationRegistry === undefined) {
+            return;
+        }
+        const metadata = this.externalizationRegistry.buildMetadata(publication.eventType, event);
+        if (metadata === undefined) {
+            return;
+        }
+        try {
+            await this.externalizer.externalize(event, metadata);
+            this.logger.debug(`Externalized ${publication.eventType} → ${metadata.target}`);
+        }
+        catch (err) {
+            const cause = err instanceof Error ? err : undefined;
+            const message = err instanceof Error ? err.message : String(err);
+            throw new errors_1.ExternalizationError(`Externalization failed for ${publication.eventType}: ${message}`, publication.eventType, metadata.target, cause);
+        }
+    }
+    chunk(arr, size) {
+        const chunks = [];
+        for (let i = 0; i < arr.length; i += size) {
+            chunks.push(arr.slice(i, i + size));
+        }
+        return chunks;
+    }
+};
+exports.EventPublicationProcessor = EventPublicationProcessor;
+exports.EventPublicationProcessor = EventPublicationProcessor = EventPublicationProcessor_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(3, (0, common_1.Optional)()),
+    __param(3, (0, common_1.Inject)(event_externalizer_1.EVENT_EXTERNALIZER)),
+    __param(4, (0, common_1.Optional)()),
+    __metadata("design:paramtypes", [event_publication_registry_1.EventPublicationRegistry,
+        listener_registry_1.OutboxListenerRegistry, Object, Object, externalization_registry_1.ExternalizationRegistry])
+], EventPublicationProcessor);
+//# sourceMappingURL=event-publication-processor.js.map

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

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

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

@@ -0,0 +1,129 @@
+import { type OnModuleInit } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+/**
+ * Optional override accepted by the facade `OutboxEventPublisher`'s
+ * publish methods to target a specific dataSource explicitly.
+ *
+ * When omitted, the facade routes by event-type registration: the
+ * event class is looked up in each per-dataSource
+ * {@link EventTypeRegistry}, and the dataSource that registered it
+ * owns the publication.
+ */
+export interface OutboxPublishOptions {
+    /**
+     * Public dataSource name to publish to. Always wins over event-type
+     * routing when set. Useful for events that are registered in
+     * multiple dataSources, or for explicit cross-dataSource routing.
+     */
+    readonly dataSource?: string;
+}
+/**
+ * High-level smart-facade publisher (DD-024). The single user-facing
+ * publisher class — application code injects `OutboxEventPublisher`
+ * and the facade routes publications to the per-dataSource
+ * {@link DataSourceOutboxPublisher} that owns the event class.
+ *
+ * **Routing algorithm** (in order):
+ *  1. If `options.dataSource` is provided, route to that dataSource.
+ *  2. Else, look up `event.constructor.name` in each registered
+ *     per-dataSource {@link EventTypeRegistry}; the registry that
+ *     contains the event determines the destination.
+ *  3. If no registry contains the event, throw {@link OutboxError}.
+ *
+ * **Cross-dataSource publishing** is allowed: the routing decision is
+ * about the event's *registered* dataSource, NOT about which
+ * transactions are currently active. With Phase 14.2's cross-DS
+ * simultaneous transactions, a billing event published from inside an
+ * outer-billing / inner-inventory async stack still routes to billing
+ * (because that's where the event class is registered) and validates
+ * its atomicity against the billing transaction.
+ *
+ * **Single-dataSource deployments** see no behavioural change: there
+ * is one per-DS publisher (named `'default'`), one event-type
+ * registry, and the facade transparently delegates to it.
+ *
+ * Replaces the pre-Phase-14.3 publisher whose internal
+ * `findCurrentTransaction()` returned an arbitrary first-active
+ * transaction — non-deterministic with multiple active transactions.
+ * No backwards-compatibility shim: callers always inject
+ * `OutboxEventPublisher` and receive routing semantics consistent
+ * with the registered event-type ownership.
+ */
+/** @internal — DI token carrying the live Map of registered dataSources. */
+export declare const OUTBOX_DATA_SOURCE_NAMES: unique symbol;
+/** @internal — Read-only view of the shared registration list. */
+export type OutboxDataSourceNames = ReadonlySet<string> | {
+    keys(): IterableIterator<string>;
+};
+export declare class OutboxEventPublisher implements OnModuleInit {
+    private readonly moduleRef;
+    /**
+     * Live reference to {@link OutboxModule.registrations} (passed via
+     * `useValue` so its `keys()` enumeration sees every dataSource
+     * registered across all `forRoot` calls — `useValue` captures the
+     * Map by reference, so later forRoot pushes are visible at
+     * `OnModuleInit` time).
+     */
+    private readonly dataSourceNames;
+    private readonly logger;
+    private readonly publishers;
+    private readonly eventTypeRegistries;
+    constructor(moduleRef: ModuleRef, 
+    /**
+     * Live reference to {@link OutboxModule.registrations} (passed via
+     * `useValue` so its `keys()` enumeration sees every dataSource
+     * registered across all `forRoot` calls — `useValue` captures the
+     * Map by reference, so later forRoot pushes are visible at
+     * `OnModuleInit` time).
+     */
+    dataSourceNames: OutboxDataSourceNames);
+    /**
+     * Late-bind per-DS publishers and event-type registries via
+     * `ModuleRef`. Lifecycle hook chosen because it fires AFTER every
+     * provider has been instantiated — by then every per-DS publisher
+     * exists and is resolvable, regardless of the order in which the
+     * facade's `forRoot` and per-DS `forRoot`s appear in the import
+     * tree.
+     */
+    onModuleInit(): void;
+    /**
+     * Publish a single event. Routing per the class JSDoc:
+     * `options.dataSource` (explicit) > event-type registration
+     * (implicit) > {@link OutboxError}.
+     *
+     * Must be called inside an active transaction *for the resolved
+     * dataSource* — `DataSourceOutboxPublisher.publish` enforces this
+     * with a clear error message naming the dataSource.
+     */
+    publish(event: unknown, options?: OutboxPublishOptions): Promise<void>;
+    /**
+     * Publish a batch of events. Each event is routed independently, so
+     * a mixed-dataSource batch (e.g. one billing event and one
+     * inventory event in the same call) routes each to its own
+     * dataSource publisher.
+     */
+    publishAll(events: readonly unknown[], options?: OutboxPublishOptions): Promise<void>;
+    /**
+     * Synchronous scheduling sibling of {@link publish}. Designed for
+     * sync callers such as `@nestjs/cqrs`'s `AggregateRoot.commit()`
+     * pathway. Same routing rules apply.
+     *
+     * Inside the resolved dataSource's active transaction: events are
+     * buffered and flushed in a `beforeCommit` hook
+     * (see {@link DataSourceOutboxPublisher.scheduleForPublication}).
+     * Outside any transaction: fire-and-forget {@link publish}, errors
+     * logged because there is no caller to propagate to.
+     *
+     * If the event cannot be routed (no matching registration), the
+     * call is logged-and-dropped — sync paths cannot raise.
+     */
+    scheduleForPublication(event: unknown, options?: OutboxPublishOptions): void;
+    /**
+     * Read-only snapshot of the dataSources this facade routes to.
+     * Useful for diagnostics and tests.
+     */
+    getRegisteredDataSources(): readonly string[];
+    private resolveDataSource;
+    private requirePublisher;
+}
+//# sourceMappingURL=outbox-event-publisher.d.ts.map

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

@@ -0,0 +1,172 @@
+"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 OutboxEventPublisher_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutboxEventPublisher = exports.OUTBOX_DATA_SOURCE_NAMES = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const event_type_resolver_1 = require("../serialization/event-type-resolver");
+const token_utils_1 = require("../tokens/token-utils");
+const errors_1 = require("../types/errors");
+/**
+ * High-level smart-facade publisher (DD-024). The single user-facing
+ * publisher class — application code injects `OutboxEventPublisher`
+ * and the facade routes publications to the per-dataSource
+ * {@link DataSourceOutboxPublisher} that owns the event class.
+ *
+ * **Routing algorithm** (in order):
+ *  1. If `options.dataSource` is provided, route to that dataSource.
+ *  2. Else, look up `event.constructor.name` in each registered
+ *     per-dataSource {@link EventTypeRegistry}; the registry that
+ *     contains the event determines the destination.
+ *  3. If no registry contains the event, throw {@link OutboxError}.
+ *
+ * **Cross-dataSource publishing** is allowed: the routing decision is
+ * about the event's *registered* dataSource, NOT about which
+ * transactions are currently active. With Phase 14.2's cross-DS
+ * simultaneous transactions, a billing event published from inside an
+ * outer-billing / inner-inventory async stack still routes to billing
+ * (because that's where the event class is registered) and validates
+ * its atomicity against the billing transaction.
+ *
+ * **Single-dataSource deployments** see no behavioural change: there
+ * is one per-DS publisher (named `'default'`), one event-type
+ * registry, and the facade transparently delegates to it.
+ *
+ * Replaces the pre-Phase-14.3 publisher whose internal
+ * `findCurrentTransaction()` returned an arbitrary first-active
+ * transaction — non-deterministic with multiple active transactions.
+ * No backwards-compatibility shim: callers always inject
+ * `OutboxEventPublisher` and receive routing semantics consistent
+ * with the registered event-type ownership.
+ */
+/** @internal — DI token carrying the live Map of registered dataSources. */
+exports.OUTBOX_DATA_SOURCE_NAMES = Symbol('OUTBOX_DATA_SOURCE_NAMES');
+let OutboxEventPublisher = OutboxEventPublisher_1 = class OutboxEventPublisher {
+    moduleRef;
+    dataSourceNames;
+    logger = new common_1.Logger(OutboxEventPublisher_1.name);
+    publishers = new Map();
+    eventTypeRegistries = new Map();
+    constructor(moduleRef, dataSourceNames) {
+        this.moduleRef = moduleRef;
+        this.dataSourceNames = dataSourceNames;
+    }
+    /**
+     * Late-bind per-DS publishers and event-type registries via
+     * `ModuleRef`. Lifecycle hook chosen because it fires AFTER every
+     * provider has been instantiated — by then every per-DS publisher
+     * exists and is resolvable, regardless of the order in which the
+     * facade's `forRoot` and per-DS `forRoot`s appear in the import
+     * tree.
+     */
+    onModuleInit() {
+        for (const ds of this.dataSourceNames.keys()) {
+            this.publishers.set(ds, this.moduleRef.get((0, token_utils_1.getOutboxPublisherToken)(ds), {
+                strict: false,
+            }));
+            this.eventTypeRegistries.set(ds, this.moduleRef.get((0, token_utils_1.getEventTypeRegistryToken)(ds), {
+                strict: false,
+            }));
+        }
+    }
+    /**
+     * Publish a single event. Routing per the class JSDoc:
+     * `options.dataSource` (explicit) > event-type registration
+     * (implicit) > {@link OutboxError}.
+     *
+     * Must be called inside an active transaction *for the resolved
+     * dataSource* — `DataSourceOutboxPublisher.publish` enforces this
+     * with a clear error message naming the dataSource.
+     */
+    async publish(event, options = {}) {
+        const dataSource = this.resolveDataSource(event, options);
+        const publisher = this.requirePublisher(dataSource);
+        await publisher.publish(event);
+    }
+    /**
+     * Publish a batch of events. Each event is routed independently, so
+     * a mixed-dataSource batch (e.g. one billing event and one
+     * inventory event in the same call) routes each to its own
+     * dataSource publisher.
+     */
+    async publishAll(events, options = {}) {
+        for (const event of events) {
+            await this.publish(event, options);
+        }
+    }
+    /**
+     * Synchronous scheduling sibling of {@link publish}. Designed for
+     * sync callers such as `@nestjs/cqrs`'s `AggregateRoot.commit()`
+     * pathway. Same routing rules apply.
+     *
+     * Inside the resolved dataSource's active transaction: events are
+     * buffered and flushed in a `beforeCommit` hook
+     * (see {@link DataSourceOutboxPublisher.scheduleForPublication}).
+     * Outside any transaction: fire-and-forget {@link publish}, errors
+     * logged because there is no caller to propagate to.
+     *
+     * If the event cannot be routed (no matching registration), the
+     * call is logged-and-dropped — sync paths cannot raise.
+     */
+    scheduleForPublication(event, options = {}) {
+        let dataSource;
+        try {
+            dataSource = this.resolveDataSource(event, options);
+        }
+        catch (err) {
+            this.logger.error(`scheduleForPublication: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        const publisher = this.publishers.get(dataSource);
+        if (publisher === undefined) {
+            this.logger.error(`scheduleForPublication: no outbox publisher registered for dataSource '${dataSource}'`);
+            return;
+        }
+        publisher.scheduleForPublication(event);
+    }
+    /**
+     * Read-only snapshot of the dataSources this facade routes to.
+     * Useful for diagnostics and tests.
+     */
+    getRegisteredDataSources() {
+        return Array.from(this.publishers.keys());
+    }
+    resolveDataSource(event, options) {
+        if (options.dataSource !== undefined) {
+            return options.dataSource;
+        }
+        // Phase 14.3.1 — same helper used by `OutboxListenerScanner` and
+        // `MultiDsOutboxListenerRegistrar` so the routing policy (one
+        // owning DS per event class, throw on 0 or many matches) stays
+        // consistent across publish and listener-registration paths.
+        const eventType = event.constructor.name;
+        return (0, event_type_resolver_1.resolveDataSourceByEventTypeName)(eventType, this.eventTypeRegistries);
+    }
+    requirePublisher(dataSource) {
+        const publisher = this.publishers.get(dataSource);
+        if (publisher === undefined) {
+            throw new errors_1.OutboxError(`No outbox configured for dataSource '${dataSource}'. ` +
+                `Add 'OutboxModule.forRoot({ dataSource: '${dataSource}' })' to the module imports.`);
+        }
+        return publisher;
+    }
+};
+exports.OutboxEventPublisher = OutboxEventPublisher;
+exports.OutboxEventPublisher = OutboxEventPublisher = OutboxEventPublisher_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)(exports.OUTBOX_DATA_SOURCE_NAMES)),
+    __metadata("design:paramtypes", [core_1.ModuleRef, Object])
+], OutboxEventPublisher);
+//# sourceMappingURL=outbox-event-publisher.js.map

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

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

package/dist/dispatcher/processor-options.d.ts

@@ -0,0 +1,24 @@
+import { CompletionMode } from '../types/completion-mode';
+/**
+ * Tunables for the {@link EventPublicationProcessor} polling loop.
+ *
+ * Values are enforced at injection time — provide a fully-populated
+ * object (merge with {@link DEFAULT_PROCESSOR_OPTIONS} if you only
+ * want to override a subset).
+ */
+export interface EventPublicationProcessorOptions {
+    /** Milliseconds to wait between polling cycles. */
+    readonly pollingInterval: number;
+    /** Maximum publications fetched per poll. */
+    readonly batchSize: number;
+    /** Maximum listener invocations that may run in parallel inside one batch. */
+    readonly maxConcurrent: number;
+    /** How a successfully-delivered publication is finalized. */
+    readonly completionMode: CompletionMode;
+}
+/**
+ * Reasonable defaults for local development — a 1-second poll, 100 rows
+ * per batch, 10 parallel listener invocations, and `UPDATE` completion.
+ */
+export declare const DEFAULT_PROCESSOR_OPTIONS: EventPublicationProcessorOptions;
+//# sourceMappingURL=processor-options.d.ts.map

package/dist/dispatcher/processor-options.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PROCESSOR_OPTIONS = void 0;
+const completion_mode_1 = require("../types/completion-mode");
+/**
+ * Reasonable defaults for local development — a 1-second poll, 100 rows
+ * per batch, 10 parallel listener invocations, and `UPDATE` completion.
+ */
+exports.DEFAULT_PROCESSOR_OPTIONS = {
+    pollingInterval: 1000,
+    batchSize: 100,
+    maxConcurrent: 10,
+    completionMode: completion_mode_1.CompletionMode.UPDATE,
+};
+//# sourceMappingURL=processor-options.js.map

package/dist/dispatcher/processor-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processor-options.js","sourceRoot":"","sources":["../../src/dispatcher/processor-options.ts"],"names":[],"mappings":";;;AAAA,8DAA0D;AAoB1D;;;GAGG;AACU,QAAA,yBAAyB,GAAqC;IACzE,eAAe,EAAE,IAAI;IACrB,SAAS,EAAE,GAAG;IACd,aAAa,EAAE,EAAE;IACjB,cAAc,EAAE,gCAAc,CAAC,MAAM;CACtC,CAAC"}

package/dist/externalization/errors.d.ts

@@ -0,0 +1,21 @@
+import { OutboxError } from '../types/errors';
+/**
+ * Raised when an {@link EventExternalizer} fails to deliver a
+ * publication to its external broker target. Carries diagnostic
+ * context (event type, broker target, optional underlying cause) so
+ * operators can correlate a `FAILED` publication row with the broker
+ * issue without parsing free-form messages.
+ *
+ * Implementations are encouraged to wrap transport-specific failures
+ * in this error, but the `EventPublicationProcessor` does not
+ * require it — any rejection from `externalize()` is recorded on the
+ * publication.
+ */
+export declare class ExternalizationError extends OutboxError {
+    readonly eventType: string;
+    readonly target: string;
+    readonly cause?: Error | undefined;
+    readonly code = "EXTERNALIZATION_ERROR";
+    constructor(message: string, eventType: string, target: string, cause?: Error | undefined);
+}
+//# sourceMappingURL=errors.d.ts.map