@nestjs-transactional/outbox 1.0.0-alpha.0

package/dist/interfaces/outbox-event-handler.interface.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Contract implemented by classes annotated with
+ * `@OutboxEventsHandler`. The worker invokes `handle(event)` for
+ * every event of a type the class is registered for, with an
+ * already-deserialised domain payload.
+ *
+ * `Promise<void>` — synchronous handlers are discouraged: the
+ * worker loop awaits the returned promise, so a void-returning
+ * implementation that synchronously performs I/O would block the
+ * worker until that work completes. Make the operation explicit.
+ *
+ * Mirrors the ergonomics of `IEventHandler` from `@nestjs/cqrs` —
+ * `any` as the default generic parameter is deliberate so that
+ * `implements IOutboxEventHandler` without a type argument still
+ * type-checks against any concrete event shape.
+ *
+ * @example
+ * ```ts
+ * @OutboxEventsHandler(OrderPlacedEvent)
+ * export class InventoryReservationHandler
+ *   implements IOutboxEventHandler<OrderPlacedEvent>
+ * {
+ *   async handle(event: OrderPlacedEvent): Promise<void> {
+ *     // durable, at-least-once, retried on failure
+ *   }
+ * }
+ * ```
+ */
+export interface IOutboxEventHandler<T = any> {
+    handle(event: T): Promise<void>;
+}
+//# sourceMappingURL=outbox-event-handler.interface.d.ts.map

package/dist/interfaces/outbox-event-handler.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=outbox-event-handler.interface.js.map

package/dist/interfaces/outbox-event-handler.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox-event-handler.interface.js","sourceRoot":"","sources":["../../src/interfaces/outbox-event-handler.interface.ts"],"names":[],"mappings":""}

package/dist/module/outbox-processing.module.d.ts

@@ -0,0 +1,29 @@
+import { type OnApplicationBootstrap, type OnApplicationShutdown } from '@nestjs/common';
+import { type OutboxProcessingBundle } from './outbox.module';
+/**
+ * Auto-starts every configured per-dataSource
+ * {@link EventPublicationProcessor} and {@link StalenessMonitor} on
+ * application bootstrap and stops them on shutdown.
+ *
+ * Phase 14.3 generalised this to multi-dataSource: the module reads
+ * {@link OUTBOX_PROCESSING_BUNDLE} provided by `OutboxModule.forRoot`
+ * — the bundle contains arrays of per-dataSource processors and
+ * monitors. Single-dataSource deployments see the bundle with
+ * exactly one processor and one monitor; nothing changes for them.
+ *
+ * Import this module in applications that SHOULD drain every
+ * configured outbox (typically a dedicated worker process), but NOT
+ * in API applications that only publish events — they should leave
+ * processing to the worker.
+ *
+ * Assumes {@link OutboxModule} is already registered earlier in the
+ * module tree (usually as `OutboxModule.forRoot({ isGlobal: true })`);
+ * the bundle is looked up from the global DI scope.
+ */
+export declare class OutboxProcessingModule implements OnApplicationBootstrap, OnApplicationShutdown {
+    private readonly bundle;
+    constructor(bundle: OutboxProcessingBundle);
+    onApplicationBootstrap(): void;
+    onApplicationShutdown(): void;
+}
+//# sourceMappingURL=outbox-processing.module.d.ts.map

package/dist/module/outbox-processing.module.js

@@ -0,0 +1,66 @@
+"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.OutboxProcessingModule = void 0;
+const common_1 = require("@nestjs/common");
+const outbox_module_1 = require("./outbox.module");
+/**
+ * Auto-starts every configured per-dataSource
+ * {@link EventPublicationProcessor} and {@link StalenessMonitor} on
+ * application bootstrap and stops them on shutdown.
+ *
+ * Phase 14.3 generalised this to multi-dataSource: the module reads
+ * {@link OUTBOX_PROCESSING_BUNDLE} provided by `OutboxModule.forRoot`
+ * — the bundle contains arrays of per-dataSource processors and
+ * monitors. Single-dataSource deployments see the bundle with
+ * exactly one processor and one monitor; nothing changes for them.
+ *
+ * Import this module in applications that SHOULD drain every
+ * configured outbox (typically a dedicated worker process), but NOT
+ * in API applications that only publish events — they should leave
+ * processing to the worker.
+ *
+ * Assumes {@link OutboxModule} is already registered earlier in the
+ * module tree (usually as `OutboxModule.forRoot({ isGlobal: true })`);
+ * the bundle is looked up from the global DI scope.
+ */
+let OutboxProcessingModule = class OutboxProcessingModule {
+    bundle;
+    constructor(bundle) {
+        this.bundle = bundle;
+    }
+    onApplicationBootstrap() {
+        for (const processor of this.bundle.processors) {
+            processor.start();
+        }
+        for (const monitor of this.bundle.monitors) {
+            monitor.start();
+        }
+    }
+    onApplicationShutdown() {
+        for (const processor of this.bundle.processors) {
+            processor.stop();
+        }
+        for (const monitor of this.bundle.monitors) {
+            monitor.stop();
+        }
+    }
+};
+exports.OutboxProcessingModule = OutboxProcessingModule;
+exports.OutboxProcessingModule = OutboxProcessingModule = __decorate([
+    (0, common_1.Module)({}),
+    __param(0, (0, common_1.Inject)(outbox_module_1.OUTBOX_PROCESSING_BUNDLE)),
+    __metadata("design:paramtypes", [Object])
+], OutboxProcessingModule);
+//# sourceMappingURL=outbox-processing.module.js.map

package/dist/module/outbox-processing.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox-processing.module.js","sourceRoot":"","sources":["../../src/module/outbox-processing.module.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAKwB;AAExB,mDAGyB;AAEzB;;;;;;;;;;;;;;;;;;;GAmBG;AAEI,IAAM,sBAAsB,GAA5B,MAAM,sBAAsB;IAGd;IAFnB,YAEmB,MAA8B;QAA9B,WAAM,GAAN,MAAM,CAAwB;IAC9C,CAAC;IAEJ,sBAAsB;QACpB,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;YAC/C,SAAS,CAAC,KAAK,EAAE,CAAC;QACpB,CAAC;QACD,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YAC3C,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;IACH,CAAC;IAED,qBAAqB;QACnB,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;YAC/C,SAAS,CAAC,IAAI,EAAE,CAAC;QACnB,CAAC;QACD,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YAC3C,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;CACF,CAAA;AAvBY,wDAAsB;iCAAtB,sBAAsB;IADlC,IAAA,eAAM,EAAC,EAAE,CAAC;IAGN,WAAA,IAAA,eAAM,EAAC,wCAAwB,CAAC,CAAA;;GAFxB,sBAAsB,CAuBlC"}

package/dist/module/outbox.module.d.ts

@@ -0,0 +1,196 @@
+import { type DynamicModule, type InjectionToken, type ModuleMetadata, type Provider, type Type } from '@nestjs/common';
+import { EventPublicationProcessor } from '../dispatcher/event-publication-processor';
+import { type EventPublicationProcessorOptions } from '../dispatcher/processor-options';
+import { StalenessMonitor } from '../recovery/staleness-monitor';
+import { StartupRecoveryService } from '../recovery/startup-recovery';
+import { CompletionMode } from '../types/completion-mode';
+import { type StalenessConfig } from '../types/staleness-config';
+/**
+ * Synchronous options for {@link OutboxModule.forRoot}.
+ *
+ * Multi-dataSource deployments call `forRoot` once per dataSource:
+ *
+ * ```ts
+ * OutboxModule.forRoot({})                              // default
+ * OutboxModule.forRoot({ dataSource: 'billing' })       // billing
+ * OutboxModule.forRoot({ dataSource: 'inventory' })     // inventory
+ * ```
+ *
+ * Matches the convention used by `TypeOrmModule`, `MongooseModule`,
+ * `ClientsModule`, and others — each `forRoot` call registers a
+ * complete provider matrix for one dataSource. Cross-call
+ * coordination of the singleton facade / scanner / processing bundle
+ * happens through {@link OutboxModule.registrations} (static class
+ * storage, mirroring `@nestjs/typeorm`'s `EntitiesMetadataStorage`).
+ *
+ * Calling `forRoot` twice with the same `dataSource` (or twice with
+ * `dataSource` omitted, which both default to `'default'`) throws at
+ * module-definition time — dataSource names must be unique across a
+ * process.
+ *
+ * Tests that build multiple modules in sequence must reset the
+ * static storage between cases — call {@link OutboxModule.resetForTesting}
+ * in `beforeEach` (or `afterEach`).
+ */
+export interface OutboxModuleOptions {
+    /** dataSource name. Defaults to `'default'`. */
+    readonly dataSource?: string;
+    /** Register the module as `@Global()`. Default: `true`. */
+    readonly isGlobal?: boolean;
+    readonly processor?: Partial<EventPublicationProcessorOptions>;
+    readonly staleness?: Partial<StalenessConfig>;
+    readonly republishOnStartup?: boolean;
+    readonly startupBatchSize?: number;
+    readonly completionMode?: CompletionMode;
+    /**
+     * Provider for the event serializer. The Provider's `provide` field
+     * is IGNORED — the module re-binds the provider to
+     * `getOutboxEventSerializerToken(dataSource)`. Defaults to a JSON
+     * serializer wired to this dataSource's `EventTypeRegistry`.
+     */
+    readonly serializer?: Provider;
+    /**
+     * Provider for the event publication repository. Same `provide`
+     * re-binding as `serializer`. Defaults to
+     * {@link InMemoryEventPublicationRepository} — TESTS ONLY. Production
+     * deployments wire a durable backend (`outbox-typeorm`, ...).
+     */
+    readonly repository?: Provider;
+}
+/**
+ * Result shape resolved by {@link OutboxModuleAsyncOptions.useFactory}.
+ * Provider-valued fields (`serializer`, `repository`) stay static
+ * because providers must be known at module-definition time.
+ */
+export interface OutboxModuleAsyncFactoryResult {
+    readonly processor?: Partial<EventPublicationProcessorOptions>;
+    readonly staleness?: Partial<StalenessConfig>;
+    readonly republishOnStartup?: boolean;
+    readonly startupBatchSize?: number;
+    readonly completionMode?: CompletionMode;
+}
+/**
+ * Asynchronous options for {@link OutboxModule.forRootAsync}. Each
+ * call registers a single dataSource's outbox stack with config
+ * resolved asynchronously. Multi-dataSource deployments call
+ * `forRootAsync` once per dataSource (symmetric with `forRoot`).
+ */
+export interface OutboxModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+    readonly dataSource?: string;
+    readonly isGlobal?: boolean;
+    readonly serializer?: Provider;
+    readonly repository?: Provider;
+    readonly useFactory: (...args: never[]) => Promise<OutboxModuleAsyncFactoryResult> | OutboxModuleAsyncFactoryResult;
+    readonly inject?: readonly InjectionToken[];
+}
+/** DI token carrying the resolved {@link EventPublicationProcessorOptions}. */
+export declare const OUTBOX_PROCESSOR_OPTIONS: unique symbol;
+/** DI token carrying the resolved {@link StalenessConfig}. */
+export declare const OUTBOX_STALENESS_CONFIG: unique symbol;
+/**
+ * Bundle of per-dataSource processors and monitors that
+ * {@link OutboxProcessingModule} reads on bootstrap to start every
+ * configured outbox loop. Provided by `forRoot` so the processing
+ * module needs no per-dataSource configuration of its own.
+ */
+export declare const OUTBOX_PROCESSING_BUNDLE: unique symbol;
+/**
+ * Shape of the processing bundle. The three arrays are aligned by
+ * index — `processors[i]` / `monitors[i]` / `recoveryServices[i]`
+ * all belong to the same dataSource.
+ */
+export interface OutboxProcessingBundle {
+    readonly processors: readonly EventPublicationProcessor[];
+    readonly monitors: readonly StalenessMonitor[];
+    readonly recoveryServices: readonly StartupRecoveryService[];
+}
+/**
+ * NestJS module that wires the Event Publication Registry. ADR-019
+ * shape — multi-dataSource deployments call {@link forRoot} once per
+ * dataSource. The first call registers process-wide singletons (smart
+ * facade, listener scanner, processing bundle); subsequent calls only
+ * register per-dataSource providers. Default-DS class-token aliases
+ * are registered by whichever call has `dataSource: 'default'` (or
+ * `dataSource` omitted).
+ *
+ * Cross-call state lives in {@link registrations} — a static class
+ * storage keyed by dataSource name. Mirrors `@nestjs/typeorm`'s
+ * `EntitiesMetadataStorage` pattern.
+ *
+ * Does NOT start the processor or staleness monitor automatically —
+ * import {@link OutboxProcessingModule} in the worker process to
+ * auto-start every registered per-dataSource loop on
+ * `OnApplicationBootstrap`.
+ *
+ * Requires `TransactionalModule.forRoot({ isGlobal: true })` registered
+ * earlier in the module tree so the per-DS publisher can find the
+ * `TransactionManager` via the global DI scope.
+ */
+export declare class OutboxModule {
+    /**
+     * @internal
+     * Process-wide registry of every dataSource that has called
+     * {@link forRoot} or {@link forRootAsync}. Singleton factories
+     * (smart facade, processing bundle) close over this Map and
+     * enumerate it at injection time, after every `forRoot` has been
+     * evaluated synchronously.
+     *
+     * Tests that build multiple modules sequentially MUST call
+     * {@link resetForTesting} between cases — otherwise residual
+     * registrations from earlier tests collide with later ones.
+     */
+    private static readonly registrations;
+    /**
+     * Test-only — drop every registration so a subsequent `forRoot`
+     * starts from a clean slate. Mirrors the cleanup pattern used with
+     * `EntitiesMetadataStorage` in `@nestjs/typeorm` test suites.
+     *
+     * Production code should never call this. Calling at runtime
+     * after the module has been initialised would NOT clear the
+     * provider tree NestJS already built — it only clears the
+     * registration record that drives subsequent `forRoot` calls.
+     *
+     * @internal
+     */
+    static resetForTesting(): void;
+    static forRoot(options?: OutboxModuleOptions): DynamicModule;
+    /**
+     * Asynchronous registration of one dataSource's outbox stack.
+     * Symmetric with {@link forRoot} — call once per dataSource;
+     * provider-valued fields (`serializer`, `repository`) stay static
+     * because providers must be known at module-definition time, while
+     * `processor` / `staleness` / etc. resolve via the async factory.
+     */
+    static forRootAsync(options: OutboxModuleAsyncOptions): DynamicModule;
+    /**
+     * Register event classes that the outbox should know about — typed
+     * inputs to the per-dataSource `EventTypeRegistry` so the JSON
+     * serializer can revive stored payloads back into class instances,
+     * and so externalization mappings (`@Externalized`) can be picked
+     * up by the registry scan.
+     *
+     * @param eventTypes Event classes to register. Empty array is a
+     *   no-op (matches `TypeOrmModule.forFeature([])`).
+     * @param options Optional per-call options. `dataSource` defaults
+     *   to `'default'` — single-dataSource consumers omit it.
+     *
+     * @example Single-dataSource
+     * ```ts
+     * OutboxModule.forFeature([OrderPlacedEvent, OrderShippedEvent])
+     * ```
+     *
+     * @example Multi-dataSource
+     * ```ts
+     * OutboxModule.forFeature([BillingEvent], { dataSource: 'billing' })
+     * OutboxModule.forFeature([InventoryEvent], { dataSource: 'inventory' })
+     * ```
+     *
+     * Multiple `forFeature` calls accumulate into the per-dataSource
+     * registry. Duplicate registrations (same event class, same
+     * dataSource) throw at bootstrap with a clear message.
+     */
+    static forFeature(eventTypes: Type<object>[], options?: {
+        readonly dataSource?: string;
+    }): DynamicModule;
+}
+//# sourceMappingURL=outbox.module.d.ts.map