@nestjs-transactional/outbox 1.0.0-alpha.0

package/dist/recovery/staleness-monitor.d.ts

@@ -0,0 +1,39 @@
+import { type EventPublicationRepository } from '../repository/event-publication-repository';
+import type { StalenessConfig } from '../types/staleness-config';
+/**
+ * Periodic watchdog that flips publications stuck in non-terminal
+ * states to `FAILED` once they have been in that state for longer
+ * than the configured threshold.
+ *
+ * Per-state thresholds live in {@link StalenessConfig} and a value of
+ * `0` disables the corresponding check. When every threshold is `0`,
+ * {@link start} is a no-op — we do not schedule the polling loop just
+ * to do nothing on every tick.
+ *
+ * Note: the `PROCESSING` / `RESUBMITTED` thresholds are evaluated
+ * against the publication's `publicationDate`, not against the moment
+ * it entered the current state. Real backends (outbox-typeorm) can
+ * refine this with per-state timestamps; the in-memory reference
+ * keeps it simple.
+ */
+export declare class StalenessMonitor {
+    private readonly repository;
+    private readonly config;
+    private readonly logger;
+    private running;
+    private monitorLoop;
+    constructor(repository: EventPublicationRepository, config: StalenessConfig);
+    /** Start the watchdog. Idempotent. */
+    start(): void;
+    /** Stop the watchdog and cancel any pending scheduled tick. */
+    stop(): void;
+    /**
+     * Run a single staleness sweep — invoked both by the scheduled loop
+     * and directly by tests / one-shot tooling. Never rejects; infra
+     * failures are caught and logged.
+     */
+    checkStaleness(): Promise<void>;
+    private scheduleNext;
+    private markStale;
+}
+//# sourceMappingURL=staleness-monitor.d.ts.map

package/dist/recovery/staleness-monitor.js

@@ -0,0 +1,118 @@
+"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 StalenessMonitor_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StalenessMonitor = 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");
+/**
+ * Periodic watchdog that flips publications stuck in non-terminal
+ * states to `FAILED` once they have been in that state for longer
+ * than the configured threshold.
+ *
+ * Per-state thresholds live in {@link StalenessConfig} and a value of
+ * `0` disables the corresponding check. When every threshold is `0`,
+ * {@link start} is a no-op — we do not schedule the polling loop just
+ * to do nothing on every tick.
+ *
+ * Note: the `PROCESSING` / `RESUBMITTED` thresholds are evaluated
+ * against the publication's `publicationDate`, not against the moment
+ * it entered the current state. Real backends (outbox-typeorm) can
+ * refine this with per-state timestamps; the in-memory reference
+ * keeps it simple.
+ */
+let StalenessMonitor = StalenessMonitor_1 = class StalenessMonitor {
+    repository;
+    config;
+    logger = new common_1.Logger(StalenessMonitor_1.name);
+    running = false;
+    monitorLoop = null;
+    constructor(repository, config) {
+        this.repository = repository;
+        this.config = config;
+    }
+    /** Start the watchdog. Idempotent. */
+    start() {
+        if (this.running) {
+            return;
+        }
+        if (this.config.published === 0 &&
+            this.config.processing === 0 &&
+            this.config.resubmitted === 0) {
+            this.logger.log('StalenessMonitor disabled (all thresholds = 0)');
+            return;
+        }
+        this.running = true;
+        this.scheduleNext();
+        this.logger.log(`StalenessMonitor started (interval: ${this.config.monitorInterval}ms)`);
+    }
+    /** Stop the watchdog and cancel any pending scheduled tick. */
+    stop() {
+        this.running = false;
+        if (this.monitorLoop !== null) {
+            clearTimeout(this.monitorLoop);
+            this.monitorLoop = null;
+        }
+    }
+    /**
+     * Run a single staleness sweep — invoked both by the scheduled loop
+     * and directly by tests / one-shot tooling. Never rejects; infra
+     * failures are caught and logged.
+     */
+    async checkStaleness() {
+        try {
+            const now = Date.now();
+            if (this.config.published > 0) {
+                await this.markStale(new Date(now - this.config.published), [publication_status_1.PublicationStatus.PUBLISHED], 'Publication stale in PUBLISHED state');
+            }
+            if (this.config.processing > 0) {
+                await this.markStale(new Date(now - this.config.processing), [publication_status_1.PublicationStatus.PROCESSING], 'Publication stale in PROCESSING state');
+            }
+            if (this.config.resubmitted > 0) {
+                await this.markStale(new Date(now - this.config.resubmitted), [publication_status_1.PublicationStatus.RESUBMITTED], 'Publication stale in RESUBMITTED state');
+            }
+        }
+        catch (err) {
+            this.logger.error('Staleness check failed', err instanceof Error ? err.stack : String(err));
+        }
+    }
+    scheduleNext() {
+        if (!this.running) {
+            return;
+        }
+        this.monitorLoop = setTimeout(() => {
+            void this.checkStaleness().finally(() => this.scheduleNext());
+        }, this.config.monitorInterval);
+    }
+    async markStale(beforeDate, statuses, reason) {
+        const stale = await this.repository.findStale(beforeDate, statuses);
+        if (stale.length === 0) {
+            return;
+        }
+        this.logger.warn(`Found ${stale.length} stale publication(s) in states [${statuses.join(',')}]`);
+        for (const pub of stale) {
+            await this.repository.updateStatus(pub.id, publication_status_1.PublicationStatus.FAILED, {
+                failureReason: reason,
+            });
+        }
+    }
+};
+exports.StalenessMonitor = StalenessMonitor;
+exports.StalenessMonitor = StalenessMonitor = StalenessMonitor_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(event_publication_repository_1.EVENT_PUBLICATION_REPOSITORY)),
+    __metadata("design:paramtypes", [Object, Object])
+], StalenessMonitor);
+//# sourceMappingURL=staleness-monitor.js.map

package/dist/recovery/staleness-monitor.js.map

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

package/dist/recovery/startup-recovery.d.ts

@@ -0,0 +1,37 @@
+import { type OnApplicationBootstrap } from '@nestjs/common';
+import { IncompleteEventPublications } from '../api/incomplete-event-publications';
+/** DI token for {@link OutboxRecoveryOptions}. */
+export declare const OUTBOX_RECOVERY_OPTIONS: unique symbol;
+/**
+ * Runtime configuration for {@link StartupRecoveryService}. Wired by
+ * `OutboxModule.forRoot` from the module-level options.
+ */
+export interface OutboxRecoveryOptions {
+    /**
+     * When `true`, every non-`COMPLETED` publication found at
+     * application bootstrap is transitioned to `RESUBMITTED` so the
+     * processor picks it up after the previous-run crash.
+     */
+    readonly republishOnStartup: boolean;
+    /**
+     * Maximum number of publications to resubmit in a single bootstrap
+     * pass. Defaults to 1000 when omitted.
+     */
+    readonly startupBatchSize?: number;
+}
+/**
+ * `OnApplicationBootstrap` hook that optionally resubmits every
+ * publication left in a non-terminal state when the previous process
+ * died — matches Spring Modulith's `Republishing on Startup`
+ * behaviour.
+ *
+ * Skips entirely when `republishOnStartup` is `false` (the default).
+ */
+export declare class StartupRecoveryService implements OnApplicationBootstrap {
+    private readonly incomplete;
+    private readonly options;
+    private readonly logger;
+    constructor(incomplete: IncompleteEventPublications, options: OutboxRecoveryOptions);
+    onApplicationBootstrap(): Promise<void>;
+}
+//# sourceMappingURL=startup-recovery.d.ts.map

package/dist/recovery/startup-recovery.js

@@ -0,0 +1,55 @@
+"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 StartupRecoveryService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StartupRecoveryService = exports.OUTBOX_RECOVERY_OPTIONS = void 0;
+const common_1 = require("@nestjs/common");
+const incomplete_event_publications_1 = require("../api/incomplete-event-publications");
+const resubmission_options_1 = require("../types/resubmission-options");
+/** DI token for {@link OutboxRecoveryOptions}. */
+exports.OUTBOX_RECOVERY_OPTIONS = Symbol('OUTBOX_RECOVERY_OPTIONS');
+/**
+ * `OnApplicationBootstrap` hook that optionally resubmits every
+ * publication left in a non-terminal state when the previous process
+ * died — matches Spring Modulith's `Republishing on Startup`
+ * behaviour.
+ *
+ * Skips entirely when `republishOnStartup` is `false` (the default).
+ */
+let StartupRecoveryService = StartupRecoveryService_1 = class StartupRecoveryService {
+    incomplete;
+    options;
+    logger = new common_1.Logger(StartupRecoveryService_1.name);
+    constructor(incomplete, options) {
+        this.incomplete = incomplete;
+        this.options = options;
+    }
+    async onApplicationBootstrap() {
+        if (!this.options.republishOnStartup) {
+            return;
+        }
+        this.logger.log('Checking for incomplete publications to republish...');
+        const count = await this.incomplete.resubmitIncompletePublications(resubmission_options_1.ResubmissionOptions.defaults().withBatchSize(this.options.startupBatchSize ?? 1000));
+        if (count > 0) {
+            this.logger.log(`Resubmitted ${count} incomplete publication(s) from previous run`);
+        }
+    }
+};
+exports.StartupRecoveryService = StartupRecoveryService;
+exports.StartupRecoveryService = StartupRecoveryService = StartupRecoveryService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)(exports.OUTBOX_RECOVERY_OPTIONS)),
+    __metadata("design:paramtypes", [incomplete_event_publications_1.IncompleteEventPublications, Object])
+], StartupRecoveryService);
+//# sourceMappingURL=startup-recovery.js.map

package/dist/recovery/startup-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup-recovery.js","sourceRoot":"","sources":["../../src/recovery/startup-recovery.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyF;AAEzF,wFAAmF;AACnF,wEAAoE;AAEpE,kDAAkD;AACrC,QAAA,uBAAuB,GAAG,MAAM,CAAC,yBAAyB,CAAC,CAAC;AAoBzE;;;;;;;GAOG;AAEI,IAAM,sBAAsB,8BAA5B,MAAM,sBAAsB;IAId;IAEA;IALF,MAAM,GAAG,IAAI,eAAM,CAAC,wBAAsB,CAAC,IAAI,CAAC,CAAC;IAElE,YACmB,UAAuC,EAEvC,OAA8B;QAF9B,eAAU,GAAV,UAAU,CAA6B;QAEvC,YAAO,GAAP,OAAO,CAAuB;IAC9C,CAAC;IAEJ,KAAK,CAAC,sBAAsB;QAC1B,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC;YACrC,OAAO;QACT,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,sDAAsD,CAAC,CAAC;QAExE,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,8BAA8B,CAChE,0CAAmB,CAAC,QAAQ,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,gBAAgB,IAAI,IAAI,CAAC,CACpF,CAAC;QAEF,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACd,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,eAAe,KAAK,8CAA8C,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;CACF,CAAA;AAxBY,wDAAsB;iCAAtB,sBAAsB;IADlC,IAAA,mBAAU,GAAE;IAMR,WAAA,IAAA,eAAM,EAAC,+BAAuB,CAAC,CAAA;qCADH,2DAA2B;GAJ/C,sBAAsB,CAwBlC"}

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

@@ -0,0 +1,70 @@
+import type { EventPublicationRepository } from '../repository/event-publication-repository';
+import type { EventSerializer } from '../serialization/event-serializer';
+import { CompletionMode } from '../types/completion-mode';
+import type { EventPublication } from '../types/event-publication';
+/**
+ * Central service that coordinates the event publication lifecycle.
+ *
+ * Responsibilities:
+ * - persist publication entries (one per listener) atomically with the
+ *   business transaction via the injected {@link EventPublicationRepository};
+ * - transition lifecycle states (`PUBLISHED` → `PROCESSING` →
+ *   `COMPLETED` / `FAILED` → `RESUBMITTED`);
+ * - hand out deserialized event payloads ready for listener invocation.
+ *
+ * Does NOT invoke listeners — that is the dispatcher's job (Phase 5.6).
+ * Inspired by the internals of Spring Modulith's Event Publication
+ * Registry.
+ */
+export declare class EventPublicationRegistry {
+    private readonly repository;
+    private readonly serializer;
+    constructor(repository: EventPublicationRepository, serializer: EventSerializer);
+    /**
+     * Persist one publication entry per listener for a single event.
+     *
+     * Must be called inside an active transaction so the entries are
+     * committed atomically with the business write. Returns an empty
+     * array when there are no listeners — no repository call is made.
+     *
+     * The event's `constructor.name` is stored as `eventType` and used
+     * by the deserializer to look up the class at delivery time.
+     */
+    publish(event: unknown, listenerIds: readonly string[]): Promise<EventPublication[]>;
+    /**
+     * Atomically transition the publication from `PUBLISHED` or
+     * `RESUBMITTED` to `PROCESSING`. Returns `true` when the claim
+     * succeeded, `false` when another worker already holds it or the
+     * publication is in a terminal state.
+     */
+    tryClaim(publicationId: string): Promise<boolean>;
+    /**
+     * Mark the publication as completed using the requested
+     * {@link CompletionMode}:
+     * - `UPDATE` (default): set `completion_date` and keep the row for audit;
+     * - `DELETE`: delete the row outright;
+     * - `ARCHIVE`: move the row to the archive table (impl-specific).
+     */
+    markCompleted(publicationId: string, mode?: CompletionMode): Promise<void>;
+    /**
+     * Mark the publication as failed, storing the given reason so
+     * operators can triage.
+     */
+    markFailed(publicationId: string, reason: string): Promise<void>;
+    /**
+     * Mark a previously-failed publication as resubmitted for retry.
+     * Stamps `lastResubmissionDate` with the current time.
+     */
+    markResubmitted(publicationId: string): Promise<void>;
+    /**
+     * Decode the stored payload back into an application object via the
+     * configured {@link EventSerializer}. Delivered to the listener as-is.
+     */
+    deserialize(publication: EventPublication): unknown;
+    /**
+     * Pass-through to {@link EventPublicationRepository.findReadyForProcessing}
+     * — used by the (upcoming) async dispatcher to pull work.
+     */
+    findReadyForProcessing(limit: number): Promise<EventPublication[]>;
+}
+//# sourceMappingURL=event-publication-registry.d.ts.map

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

@@ -0,0 +1,138 @@
+"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.EventPublicationRegistry = void 0;
+const common_1 = require("@nestjs/common");
+const event_publication_repository_1 = require("../repository/event-publication-repository");
+const event_serializer_1 = require("../serialization/event-serializer");
+const completion_mode_1 = require("../types/completion-mode");
+const publication_status_1 = require("../types/publication-status");
+/**
+ * Central service that coordinates the event publication lifecycle.
+ *
+ * Responsibilities:
+ * - persist publication entries (one per listener) atomically with the
+ *   business transaction via the injected {@link EventPublicationRepository};
+ * - transition lifecycle states (`PUBLISHED` → `PROCESSING` →
+ *   `COMPLETED` / `FAILED` → `RESUBMITTED`);
+ * - hand out deserialized event payloads ready for listener invocation.
+ *
+ * Does NOT invoke listeners — that is the dispatcher's job (Phase 5.6).
+ * Inspired by the internals of Spring Modulith's Event Publication
+ * Registry.
+ */
+let EventPublicationRegistry = class EventPublicationRegistry {
+    repository;
+    serializer;
+    constructor(repository, serializer) {
+        this.repository = repository;
+        this.serializer = serializer;
+    }
+    /**
+     * Persist one publication entry per listener for a single event.
+     *
+     * Must be called inside an active transaction so the entries are
+     * committed atomically with the business write. Returns an empty
+     * array when there are no listeners — no repository call is made.
+     *
+     * The event's `constructor.name` is stored as `eventType` and used
+     * by the deserializer to look up the class at delivery time.
+     */
+    async publish(event, listenerIds) {
+        if (listenerIds.length === 0) {
+            return [];
+        }
+        // Delegate validation of the event shape (must be an object) to the
+        // serializer — it throws SerializationError with a clear message.
+        const serialized = this.serializer.serialize(event);
+        const eventType = event.constructor.name;
+        const inputs = listenerIds.map((listenerId) => ({
+            listenerId,
+            eventType,
+            serializedEvent: serialized,
+        }));
+        return this.repository.createAll(inputs);
+    }
+    /**
+     * Atomically transition the publication from `PUBLISHED` or
+     * `RESUBMITTED` to `PROCESSING`. Returns `true` when the claim
+     * succeeded, `false` when another worker already holds it or the
+     * publication is in a terminal state.
+     */
+    async tryClaim(publicationId) {
+        return this.repository.tryClaim(publicationId);
+    }
+    /**
+     * Mark the publication as completed using the requested
+     * {@link CompletionMode}:
+     * - `UPDATE` (default): set `completion_date` and keep the row for audit;
+     * - `DELETE`: delete the row outright;
+     * - `ARCHIVE`: move the row to the archive table (impl-specific).
+     */
+    async markCompleted(publicationId, mode = completion_mode_1.CompletionMode.UPDATE) {
+        switch (mode) {
+            case completion_mode_1.CompletionMode.UPDATE:
+                await this.repository.updateStatus(publicationId, publication_status_1.PublicationStatus.COMPLETED, {
+                    completionDate: new Date(),
+                });
+                return;
+            case completion_mode_1.CompletionMode.DELETE:
+                await this.repository.delete(publicationId);
+                return;
+            case completion_mode_1.CompletionMode.ARCHIVE:
+                await this.repository.archiveCompleted(publicationId);
+                return;
+        }
+    }
+    /**
+     * Mark the publication as failed, storing the given reason so
+     * operators can triage.
+     */
+    async markFailed(publicationId, reason) {
+        await this.repository.updateStatus(publicationId, publication_status_1.PublicationStatus.FAILED, {
+            failureReason: reason,
+        });
+    }
+    /**
+     * Mark a previously-failed publication as resubmitted for retry.
+     * Stamps `lastResubmissionDate` with the current time.
+     */
+    async markResubmitted(publicationId) {
+        await this.repository.updateStatus(publicationId, publication_status_1.PublicationStatus.RESUBMITTED, {
+            lastResubmissionDate: new Date(),
+        });
+    }
+    /**
+     * Decode the stored payload back into an application object via the
+     * configured {@link EventSerializer}. Delivered to the listener as-is.
+     */
+    deserialize(publication) {
+        return this.serializer.deserialize(publication.serializedEvent, publication.eventType);
+    }
+    /**
+     * Pass-through to {@link EventPublicationRepository.findReadyForProcessing}
+     * — used by the (upcoming) async dispatcher to pull work.
+     */
+    async findReadyForProcessing(limit) {
+        return this.repository.findReadyForProcessing(limit);
+    }
+};
+exports.EventPublicationRegistry = EventPublicationRegistry;
+exports.EventPublicationRegistry = EventPublicationRegistry = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(event_publication_repository_1.EVENT_PUBLICATION_REPOSITORY)),
+    __param(1, (0, common_1.Inject)(event_serializer_1.EVENT_SERIALIZER)),
+    __metadata("design:paramtypes", [Object, Object])
+], EventPublicationRegistry);
+//# sourceMappingURL=event-publication-registry.js.map

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

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

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

@@ -0,0 +1,52 @@
+/**
+ * A listener registered with the {@link OutboxListenerRegistry}.
+ *
+ * `id` is stable across restarts — it is persisted on every
+ * {@link EventPublication} row, so renaming the method breaks resume /
+ * retry of stored publications. Consumers are expected to either use
+ * the default `"ClassName.methodName"` shape or supply an explicit id
+ * in the decorator's options (see ADR-009 — planned).
+ */
+export interface RegisteredOutboxListener {
+    /** Globally-unique listener id (e.g. `"InventoryModule.onOrderPlaced"`). */
+    readonly id: string;
+    /** Event class name this listener subscribes to. */
+    readonly eventType: string;
+    /** Invoke the listener with a decoded event payload. */
+    readonly invoke: (event: unknown) => Promise<void>;
+}
+/**
+ * Registry of `@OutboxEventsHandler`-annotated classes (and other
+ * programmatically-registered listeners such as those routed from
+ * `@IntegrationEventsHandler` via the structural registrar port),
+ * keyed by both the listener id (for targeted dispatch / resume) and
+ * the event class name (for fan-out when a new event is published).
+ *
+ * Populated at application bootstrap by the scanner (upcoming Phase 5
+ * iteration). Stateless beyond the two index maps.
+ */
+export declare class OutboxListenerRegistry {
+    private readonly listenersByEventType;
+    private readonly listenersById;
+    /**
+     * Index a listener under both its id and its event type.
+     *
+     * @throws {DuplicateListenerIdError} when a listener with the same
+     * id is already registered — ids must be unique to avoid
+     * non-deterministic dispatch.
+     */
+    register(listener: RegisteredOutboxListener): void;
+    /**
+     * Return every listener subscribed to the given event class name, in
+     * registration order. Returns `[]` (never `undefined`) for unknown
+     * event types.
+     */
+    getByEventType(eventType: string): RegisteredOutboxListener[];
+    /** Return the listener with the given id, or `undefined` when not registered. */
+    getById(id: string): RegisteredOutboxListener | undefined;
+    /** Return every registered listener, in registration order. */
+    getAll(): RegisteredOutboxListener[];
+    /** Drop every registered listener. Primarily a testing convenience. */
+    clear(): void;
+}
+//# sourceMappingURL=listener-registry.d.ts.map

package/dist/registry/listener-registry.js

@@ -0,0 +1,67 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutboxListenerRegistry = void 0;
+const common_1 = require("@nestjs/common");
+const errors_1 = require("../types/errors");
+/**
+ * Registry of `@OutboxEventsHandler`-annotated classes (and other
+ * programmatically-registered listeners such as those routed from
+ * `@IntegrationEventsHandler` via the structural registrar port),
+ * keyed by both the listener id (for targeted dispatch / resume) and
+ * the event class name (for fan-out when a new event is published).
+ *
+ * Populated at application bootstrap by the scanner (upcoming Phase 5
+ * iteration). Stateless beyond the two index maps.
+ */
+let OutboxListenerRegistry = class OutboxListenerRegistry {
+    listenersByEventType = new Map();
+    listenersById = new Map();
+    /**
+     * Index a listener under both its id and its event type.
+     *
+     * @throws {DuplicateListenerIdError} when a listener with the same
+     * id is already registered — ids must be unique to avoid
+     * non-deterministic dispatch.
+     */
+    register(listener) {
+        if (this.listenersById.has(listener.id)) {
+            throw new errors_1.DuplicateListenerIdError(listener.id);
+        }
+        const listeners = this.listenersByEventType.get(listener.eventType) ?? [];
+        listeners.push(listener);
+        this.listenersByEventType.set(listener.eventType, listeners);
+        this.listenersById.set(listener.id, listener);
+    }
+    /**
+     * Return every listener subscribed to the given event class name, in
+     * registration order. Returns `[]` (never `undefined`) for unknown
+     * event types.
+     */
+    getByEventType(eventType) {
+        return this.listenersByEventType.get(eventType) ?? [];
+    }
+    /** Return the listener with the given id, or `undefined` when not registered. */
+    getById(id) {
+        return this.listenersById.get(id);
+    }
+    /** Return every registered listener, in registration order. */
+    getAll() {
+        return Array.from(this.listenersById.values());
+    }
+    /** Drop every registered listener. Primarily a testing convenience. */
+    clear() {
+        this.listenersByEventType.clear();
+        this.listenersById.clear();
+    }
+};
+exports.OutboxListenerRegistry = OutboxListenerRegistry;
+exports.OutboxListenerRegistry = OutboxListenerRegistry = __decorate([
+    (0, common_1.Injectable)()
+], OutboxListenerRegistry);
+//# sourceMappingURL=listener-registry.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"listener-registry.js","sourceRoot":"","sources":["../../src/registry/listener-registry.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAA4C;AAE5C,4CAA2D;AAoB3D;;;;;;;;;GASG;AAEI,IAAM,sBAAsB,GAA5B,MAAM,sBAAsB;IAChB,oBAAoB,GAAG,IAAI,GAAG,EAAsC,CAAC;IACrE,aAAa,GAAG,IAAI,GAAG,EAAoC,CAAC;IAE7E;;;;;;OAMG;IACH,QAAQ,CAAC,QAAkC;QACzC,IAAI,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,iCAAwB,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAClD,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QAC1E,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzB,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QAC7D,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IAChD,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,SAAiB;QAC9B,OAAO,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;IACxD,CAAC;IAED,iFAAiF;IACjF,OAAO,CAAC,EAAU;QAChB,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,+DAA+D;IAC/D,MAAM;QACJ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,uEAAuE;IACvE,KAAK;QACH,IAAI,CAAC,oBAAoB,CAAC,KAAK,EAAE,CAAC;QAClC,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;IAC7B,CAAC;CACF,CAAA;AA9CY,wDAAsB;iCAAtB,sBAAsB;IADlC,IAAA,mBAAU,GAAE;GACA,sBAAsB,CA8ClC"}