@nestjs-transactional/outbox 1.0.0-alpha.0

package/dist/externalization/errors.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExternalizationError = void 0;
+const errors_1 = require("../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.
+ */
+class ExternalizationError extends errors_1.OutboxError {
+    eventType;
+    target;
+    cause;
+    code = 'EXTERNALIZATION_ERROR';
+    constructor(message, eventType, target, cause) {
+        super(message);
+        this.eventType = eventType;
+        this.target = target;
+        this.cause = cause;
+    }
+}
+exports.ExternalizationError = ExternalizationError;
+//# sourceMappingURL=errors.js.map

package/dist/externalization/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/externalization/errors.ts"],"names":[],"mappings":";;;AAAA,4CAA8C;AAE9C;;;;;;;;;;;GAWG;AACH,MAAa,oBAAqB,SAAQ,oBAAW;IAKxC;IACA;IACA;IANF,IAAI,GAAG,uBAAuB,CAAC;IAExC,YACE,OAAe,EACN,SAAiB,EACjB,MAAc,EACd,KAAa;QAEtB,KAAK,CAAC,OAAO,CAAC,CAAC;QAJN,cAAS,GAAT,SAAS,CAAQ;QACjB,WAAM,GAAN,MAAM,CAAQ;QACd,UAAK,GAAL,KAAK,CAAQ;IAGxB,CAAC;CACF;AAXD,oDAWC"}

package/dist/externalization/event-externalizer.d.ts

@@ -0,0 +1,49 @@
+import type { ExternalizationMetadata } from './types';
+/**
+ * SPI for routing events that have an `@Externalized` mapping to an
+ * external message broker.
+ *
+ * Implementations are provided by extension packages — primarily
+ * `@nestjs-transactional/outbox-microservices` (Phase 11.3), which
+ * delegates to `@nestjs/microservices` `ClientProxy` and therefore
+ * covers every transport that NestJS already supports (Kafka,
+ * RabbitMQ, NATS, JMS, gRPC, custom). Future native (broker-specific)
+ * adapters can register under the same {@link EVENT_EXTERNALIZER}
+ * token without touching `outbox`.
+ *
+ * `EventPublicationProcessor` invokes `externalize()` AFTER the local
+ * outbox listener has succeeded for the publication and BEFORE the
+ * publication is finalized as `COMPLETED` (DD-019). If `externalize()`
+ * rejects, the publication is recorded as `FAILED` and can be
+ * resubmitted via {@link FailedEventPublications.resubmit} — the
+ * single-unit atomicity contract from DD-019 means a successful local
+ * listener may run again on retry, hence the documented idempotency
+ * requirement on listeners.
+ *
+ * Errors surface to the processor as ordinary rejections; wrap
+ * transport-specific failures in {@link ExternalizationError} for
+ * structured diagnostics if needed.
+ */
+export interface EventExternalizer {
+    /**
+     * Route the event to its broker-side target.
+     *
+     * @param event Deserialized event payload (the same instance that
+     *   was passed to the local listener).
+     * @param metadata Resolved routing metadata for this event. The
+     *   processor obtains it from the `ExternalizationRegistry`
+     *   (Phase 11.2).
+     */
+    externalize(event: unknown, metadata: ExternalizationMetadata): Promise<void>;
+}
+/**
+ * DI token for {@link EventExternalizer} bindings.
+ *
+ * Consumed by `EventPublicationProcessor` via `@Optional()` injection
+ * (DD-018) — the outbox runs in internal-only mode when no
+ * implementation is bound. Bind a concrete implementation via
+ * `useClass`, `useExisting`, or `useFactory` in the application's
+ * module configuration.
+ */
+export declare const EVENT_EXTERNALIZER: unique symbol;
+//# sourceMappingURL=event-externalizer.d.ts.map

package/dist/externalization/event-externalizer.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVENT_EXTERNALIZER = void 0;
+/**
+ * DI token for {@link EventExternalizer} bindings.
+ *
+ * Consumed by `EventPublicationProcessor` via `@Optional()` injection
+ * (DD-018) — the outbox runs in internal-only mode when no
+ * implementation is bound. Bind a concrete implementation via
+ * `useClass`, `useExisting`, or `useFactory` in the application's
+ * module configuration.
+ */
+exports.EVENT_EXTERNALIZER = Symbol('EVENT_EXTERNALIZER');
+//# sourceMappingURL=event-externalizer.js.map

package/dist/externalization/event-externalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-externalizer.js","sourceRoot":"","sources":["../../src/externalization/event-externalizer.ts"],"names":[],"mappings":";;;AAwCA;;;;;;;;GAQG;AACU,QAAA,kBAAkB,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC"}

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

@@ -0,0 +1,56 @@
+import { type OnModuleInit } from '@nestjs/common';
+import { EventTypeRegistry } from '../serialization/event-type-registry';
+import { type ExternalizedMetadata } from './externalized.decorator';
+import type { ExternalizationMetadata } from './types';
+/**
+ * Registry mapping event type names to their {@link ExternalizedMetadata}.
+ *
+ * Built by scanning {@link EventTypeRegistry} at module init: every
+ * registered class that carries `@Externalized` metadata is indexed
+ * by its constructor name (matching `EventPublication.eventType`).
+ * Event classes registered AFTER `onModuleInit` (e.g. via
+ * `EventTypeRegistry.register` from a custom provider's
+ * `OnApplicationBootstrap`) will not appear in the index — register
+ * event types via `OutboxModule.forFeature([...])` so the feature-
+ * module factory provider populates the registry during eager
+ * provider instantiation, before any `onModuleInit` hook runs.
+ *
+ * Consumed by `EventPublicationProcessor.tryExternalize` to resolve
+ * the per-publication {@link ExternalizationMetadata} that the bound
+ * `EventExternalizer` then translates into a transport-specific call.
+ *
+ * Always provided by `OutboxModule`. When no events are decorated
+ * with `@Externalized` the registry is simply empty — `get()` returns
+ * `undefined` for every type and the externalization step in the
+ * processor becomes a no-op.
+ */
+export declare class ExternalizationRegistry implements OnModuleInit {
+    private readonly eventTypeRegistry;
+    private readonly logger;
+    private readonly mapping;
+    constructor(eventTypeRegistry: EventTypeRegistry);
+    onModuleInit(): void;
+    /** Resolve {@link ExternalizedMetadata} for an event type, or `undefined`. */
+    get(eventType: string): ExternalizedMetadata | undefined;
+    /** Whether the given event type has an `@Externalized` mapping. */
+    has(eventType: string): boolean;
+    /**
+     * Build the per-publication {@link ExternalizationMetadata} that the
+     * processor passes to the bound `EventExternalizer`. Resolves
+     * dynamic `routingKey` and `headers` callbacks by invoking them with
+     * the actual event instance.
+     *
+     * @returns Resolved metadata, or `undefined` if `eventType` has no
+     * `@Externalized` mapping (the processor then skips the
+     * externalization call entirely).
+     */
+    buildMetadata(eventType: string, event: unknown): ExternalizationMetadata | undefined;
+}
+/**
+ * DI token for {@link ExternalizationRegistry}. Use the class token
+ * for direct injection — this Symbol is available for code that
+ * prefers token-based wiring or needs to override the registry in
+ * tests.
+ */
+export declare const EXTERNALIZATION_REGISTRY: unique symbol;
+//# sourceMappingURL=externalization-registry.d.ts.map

package/dist/externalization/externalization-registry.js

@@ -0,0 +1,103 @@
+"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 ExternalizationRegistry_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXTERNALIZATION_REGISTRY = exports.ExternalizationRegistry = void 0;
+const common_1 = require("@nestjs/common");
+const event_type_registry_1 = require("../serialization/event-type-registry");
+const externalized_decorator_1 = require("./externalized.decorator");
+/**
+ * Registry mapping event type names to their {@link ExternalizedMetadata}.
+ *
+ * Built by scanning {@link EventTypeRegistry} at module init: every
+ * registered class that carries `@Externalized` metadata is indexed
+ * by its constructor name (matching `EventPublication.eventType`).
+ * Event classes registered AFTER `onModuleInit` (e.g. via
+ * `EventTypeRegistry.register` from a custom provider's
+ * `OnApplicationBootstrap`) will not appear in the index — register
+ * event types via `OutboxModule.forFeature([...])` so the feature-
+ * module factory provider populates the registry during eager
+ * provider instantiation, before any `onModuleInit` hook runs.
+ *
+ * Consumed by `EventPublicationProcessor.tryExternalize` to resolve
+ * the per-publication {@link ExternalizationMetadata} that the bound
+ * `EventExternalizer` then translates into a transport-specific call.
+ *
+ * Always provided by `OutboxModule`. When no events are decorated
+ * with `@Externalized` the registry is simply empty — `get()` returns
+ * `undefined` for every type and the externalization step in the
+ * processor becomes a no-op.
+ */
+let ExternalizationRegistry = ExternalizationRegistry_1 = class ExternalizationRegistry {
+    eventTypeRegistry;
+    logger = new common_1.Logger(ExternalizationRegistry_1.name);
+    mapping = new Map();
+    constructor(eventTypeRegistry) {
+        this.eventTypeRegistry = eventTypeRegistry;
+    }
+    onModuleInit() {
+        for (const [name, type] of this.eventTypeRegistry.getAll()) {
+            const metadata = (0, externalized_decorator_1.getExternalizedMetadata)(type);
+            if (metadata !== undefined) {
+                this.mapping.set(name, metadata);
+                this.logger.debug(`Registered externalization for ${name} → ${metadata.target}`);
+            }
+        }
+        if (this.mapping.size > 0) {
+            this.logger.log(`Externalization configured for ${this.mapping.size} event type(s)`);
+        }
+    }
+    /** Resolve {@link ExternalizedMetadata} for an event type, or `undefined`. */
+    get(eventType) {
+        return this.mapping.get(eventType);
+    }
+    /** Whether the given event type has an `@Externalized` mapping. */
+    has(eventType) {
+        return this.mapping.has(eventType);
+    }
+    /**
+     * Build the per-publication {@link ExternalizationMetadata} that the
+     * processor passes to the bound `EventExternalizer`. Resolves
+     * dynamic `routingKey` and `headers` callbacks by invoking them with
+     * the actual event instance.
+     *
+     * @returns Resolved metadata, or `undefined` if `eventType` has no
+     * `@Externalized` mapping (the processor then skips the
+     * externalization call entirely).
+     */
+    buildMetadata(eventType, event) {
+        const config = this.mapping.get(eventType);
+        if (config === undefined) {
+            return undefined;
+        }
+        const headers = typeof config.headers === 'function' ? config.headers(event) : config.headers;
+        return {
+            eventType,
+            target: config.target,
+            client: config.client,
+            routingKey: config.routingKey?.(event),
+            headers,
+        };
+    }
+};
+exports.ExternalizationRegistry = ExternalizationRegistry;
+exports.ExternalizationRegistry = ExternalizationRegistry = ExternalizationRegistry_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [event_type_registry_1.EventTypeRegistry])
+], ExternalizationRegistry);
+/**
+ * DI token for {@link ExternalizationRegistry}. Use the class token
+ * for direct injection — this Symbol is available for code that
+ * prefers token-based wiring or needs to override the registry in
+ * tests.
+ */
+exports.EXTERNALIZATION_REGISTRY = Symbol('EXTERNALIZATION_REGISTRY');
+//# sourceMappingURL=externalization-registry.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"externalization-registry.js","sourceRoot":"","sources":["../../src/externalization/externalization-registry.ts"],"names":[],"mappings":";;;;;;;;;;;;;AAAA,2CAAuE;AAEvE,8EAAyE;AAEzE,qEAGkC;AAGlC;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEI,IAAM,uBAAuB,+BAA7B,MAAM,uBAAuB;IAIL;IAHZ,MAAM,GAAG,IAAI,eAAM,CAAC,yBAAuB,CAAC,IAAI,CAAC,CAAC;IAClD,OAAO,GAAG,IAAI,GAAG,EAAgC,CAAC;IAEnE,YAA6B,iBAAoC;QAApC,sBAAiB,GAAjB,iBAAiB,CAAmB;IAAG,CAAC;IAErE,YAAY;QACV,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,iBAAiB,CAAC,MAAM,EAAE,EAAE,CAAC;YAC3D,MAAM,QAAQ,GAAG,IAAA,gDAAuB,EAAC,IAAI,CAAC,CAAC;YAC/C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBACjC,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,kCAAkC,IAAI,MAAM,QAAQ,CAAC,MAAM,EAAE,CAC9D,CAAC;YACJ,CAAC;QACH,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC,MAAM,CAAC,GAAG,CACb,kCAAkC,IAAI,CAAC,OAAO,CAAC,IAAI,gBAAgB,CACpE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,GAAG,CAAC,SAAiB;QACnB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACrC,CAAC;IAED,mEAAmE;IACnE,GAAG,CAAC,SAAiB;QACnB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACrC,CAAC;IAED;;;;;;;;;OASG;IACH,aAAa,CAAC,SAAiB,EAAE,KAAc;QAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,OAAO,GACX,OAAO,MAAM,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;QAEhF,OAAO;YACL,SAAS;YACT,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC;YACtC,OAAO;SACR,CAAC;IACJ,CAAC;CACF,CAAA;AA7DY,0DAAuB;kCAAvB,uBAAuB;IADnC,IAAA,mBAAU,GAAE;qCAKqC,uCAAiB;GAJtD,uBAAuB,CA6DnC;AAED;;;;;GAKG;AACU,QAAA,wBAAwB,GAAG,MAAM,CAAC,0BAA0B,CAAC,CAAC"}

package/dist/externalization/externalized.decorator.d.ts

@@ -0,0 +1,121 @@
+import 'reflect-metadata';
+/**
+ * Metadata key under which {@link ExternalizedMetadata} is stored on
+ * classes decorated with {@link Externalized}.
+ *
+ * Fresh `Symbol` (not `Symbol.for`) — externalization metadata is read
+ * only by `ExternalizationRegistry` inside outbox; cross-package
+ * sharing is not required.
+ */
+export declare const EXTERNALIZED_METADATA: unique symbol;
+/**
+ * Options accepted by {@link Externalized}. The optional `TEvent`
+ * generic types the `routingKey` and `headers` callbacks so users get
+ * IDE assistance when extracting fields from the event:
+ *
+ * ```ts
+ * @Externalized<OrderPlacedEvent>({
+ *   target: 'orders',
+ *   routingKey: (e) => e.tenantId, // `e` is OrderPlacedEvent
+ * })
+ * class OrderPlacedEvent { ... }
+ * ```
+ *
+ * The generic is erased at storage time — the
+ * {@link ExternalizationRegistry} sees the callbacks as `(event:
+ * unknown) => ...` (see {@link ExternalizedMetadata}).
+ */
+export interface ExternalizedOptions<TEvent = unknown> {
+    /**
+     * Broker-side destination — Kafka topic, RabbitMQ exchange, NATS
+     * subject, gRPC service, etc. Required, must be a non-empty string.
+     * Interpretation is delegated to the
+     * `EventExternalizer` implementation.
+     */
+    readonly target: string;
+    /**
+     * Optional override for which `ClientProxy` registration the
+     * externalizer should use when more than one is bound. Resolution
+     * semantics are owned by the externalizer; `outbox-microservices`
+     * (Phase 11.3) interprets it as a token in the user's
+     * `ClientsModule` registration (DD-017).
+     */
+    readonly client?: string | symbol;
+    /**
+     * Optional callback that derives a routing key from the event
+     * instance. Used by brokers that support secondary routing
+     * (RabbitMQ routing key, Kafka message key, ...). Implementations
+     * that do not understand routing keys ignore the field.
+     */
+    readonly routingKey?: (event: TEvent) => string;
+    /**
+     * Optional message headers. Either a static record, or a callback
+     * that derives headers from the event instance.
+     */
+    readonly headers?: Record<string, string> | ((event: TEvent) => Record<string, string>);
+}
+/**
+ * Stored shape of {@link ExternalizedOptions} after decoration. The
+ * `TEvent` generic from the input is erased — callbacks accept
+ * `unknown` and are invoked with the original event instance by
+ * {@link ExternalizationRegistry.buildMetadata}.
+ */
+export interface ExternalizedMetadata {
+    readonly target: string;
+    readonly client?: string | symbol;
+    readonly routingKey?: (event: unknown) => string;
+    readonly headers?: Record<string, string> | ((event: unknown) => Record<string, string>);
+}
+/**
+ * Mark an event class for externalization to a message broker.
+ *
+ * After a local outbox listener completes successfully for a
+ * publication of this event type, the
+ * `EventPublicationProcessor` invokes the bound
+ * `EventExternalizer` (see DD-018) with the resolved
+ * {@link ExternalizationMetadata}. Reliability — retry on broker
+ * failure, recovery on restart — is provided by the existing outbox
+ * machinery (single-unit atomicity per DD-019). For Phase 11.1 / 11.2
+ * the actual broker delivery requires a concrete externalizer
+ * implementation (e.g.
+ * `@nestjs-transactional/outbox-microservices`, Phase 11.3); without
+ * one, decorated events are processed locally and the externalization
+ * step is skipped without error.
+ *
+ * @throws {Error} If `target` is missing, not a string, or empty.
+ *
+ * @example
+ * Static target:
+ * ```ts
+ * @Externalized({ target: 'orders.placed' })
+ * export class OrderPlacedEvent {
+ *   constructor(public readonly orderId: string) {}
+ * }
+ * ```
+ *
+ * @example
+ * Per-event routing key and headers:
+ * ```ts
+ * @Externalized<OrderPlacedEvent>({
+ *   target: 'orders',
+ *   routingKey: (e) => e.tenantId,
+ *   headers: (e) => ({ 'x-correlation-id': e.correlationId }),
+ *   client: 'KAFKA_CLIENT', // forwarded to the externalizer
+ * })
+ * export class OrderPlacedEvent {
+ *   constructor(
+ *     readonly orderId: string,
+ *     readonly tenantId: string,
+ *     readonly correlationId: string,
+ *   ) {}
+ * }
+ * ```
+ */
+export declare function Externalized<TEvent = unknown>(options: ExternalizedOptions<TEvent>): ClassDecorator;
+/**
+ * Read the {@link ExternalizedMetadata} attached to `target` by
+ * {@link Externalized}. Returns `undefined` when the class was not
+ * decorated.
+ */
+export declare function getExternalizedMetadata(target: object): ExternalizedMetadata | undefined;
+//# sourceMappingURL=externalized.decorator.d.ts.map

package/dist/externalization/externalized.decorator.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXTERNALIZED_METADATA = void 0;
+exports.Externalized = Externalized;
+exports.getExternalizedMetadata = getExternalizedMetadata;
+require("reflect-metadata");
+/**
+ * Metadata key under which {@link ExternalizedMetadata} is stored on
+ * classes decorated with {@link Externalized}.
+ *
+ * Fresh `Symbol` (not `Symbol.for`) — externalization metadata is read
+ * only by `ExternalizationRegistry` inside outbox; cross-package
+ * sharing is not required.
+ */
+exports.EXTERNALIZED_METADATA = Symbol('EXTERNALIZED_METADATA');
+/**
+ * Mark an event class for externalization to a message broker.
+ *
+ * After a local outbox listener completes successfully for a
+ * publication of this event type, the
+ * `EventPublicationProcessor` invokes the bound
+ * `EventExternalizer` (see DD-018) with the resolved
+ * {@link ExternalizationMetadata}. Reliability — retry on broker
+ * failure, recovery on restart — is provided by the existing outbox
+ * machinery (single-unit atomicity per DD-019). For Phase 11.1 / 11.2
+ * the actual broker delivery requires a concrete externalizer
+ * implementation (e.g.
+ * `@nestjs-transactional/outbox-microservices`, Phase 11.3); without
+ * one, decorated events are processed locally and the externalization
+ * step is skipped without error.
+ *
+ * @throws {Error} If `target` is missing, not a string, or empty.
+ *
+ * @example
+ * Static target:
+ * ```ts
+ * @Externalized({ target: 'orders.placed' })
+ * export class OrderPlacedEvent {
+ *   constructor(public readonly orderId: string) {}
+ * }
+ * ```
+ *
+ * @example
+ * Per-event routing key and headers:
+ * ```ts
+ * @Externalized<OrderPlacedEvent>({
+ *   target: 'orders',
+ *   routingKey: (e) => e.tenantId,
+ *   headers: (e) => ({ 'x-correlation-id': e.correlationId }),
+ *   client: 'KAFKA_CLIENT', // forwarded to the externalizer
+ * })
+ * export class OrderPlacedEvent {
+ *   constructor(
+ *     readonly orderId: string,
+ *     readonly tenantId: string,
+ *     readonly correlationId: string,
+ *   ) {}
+ * }
+ * ```
+ */
+function Externalized(options) {
+    if (typeof options.target !== 'string' || options.target.length === 0) {
+        throw new Error('@Externalized requires "target" option as a non-empty string');
+    }
+    // The `TEvent` generic is erased on storage — the registry invokes
+    // callbacks with `unknown` and passes the original event instance
+    // captured at publish time.
+    const metadata = {
+        target: options.target,
+        client: options.client,
+        routingKey: options.routingKey,
+        headers: options.headers,
+    };
+    return (target) => {
+        Reflect.defineMetadata(exports.EXTERNALIZED_METADATA, metadata, target);
+    };
+}
+/**
+ * Read the {@link ExternalizedMetadata} attached to `target` by
+ * {@link Externalized}. Returns `undefined` when the class was not
+ * decorated.
+ */
+function getExternalizedMetadata(target) {
+    const value = Reflect.getMetadata(exports.EXTERNALIZED_METADATA, target);
+    return value;
+}
+//# sourceMappingURL=externalized.decorator.js.map

package/dist/externalization/externalized.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"externalized.decorator.js","sourceRoot":"","sources":["../../src/externalization/externalized.decorator.ts"],"names":[],"mappings":";;;AAqHA,oCAuBC;AAOD,0DAGC;AAtJD,4BAA0B;AAE1B;;;;;;;GAOG;AACU,QAAA,qBAAqB,GAAG,MAAM,CAAC,uBAAuB,CAAC,CAAC;AA8DrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,SAAgB,YAAY,CAC1B,OAAoC;IAEpC,IAAI,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;IAClF,CAAC;IAED,mEAAmE;IACnE,kEAAkE;IAClE,4BAA4B;IAC5B,MAAM,QAAQ,GAAyB;QACrC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,UAAU,EAAE,OAAO,CAAC,UAAsD;QAC1E,OAAO,EAAE,OAAO,CAAC,OAGJ;KACd,CAAC;IAEF,OAAO,CAAC,MAAc,EAAQ,EAAE;QAC9B,OAAO,CAAC,cAAc,CAAC,6BAAqB,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAClE,CAAC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAgB,uBAAuB,CAAC,MAAc;IACpD,MAAM,KAAK,GAAY,OAAO,CAAC,WAAW,CAAC,6BAAqB,EAAE,MAAM,CAAC,CAAC;IAC1E,OAAO,KAAyC,CAAC;AACnD,CAAC"}

package/dist/externalization/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Metadata describing how a single event should be routed to an
+ * external message broker.
+ *
+ * Produced by the `ExternalizationRegistry` (Phase 11.2) by resolving
+ * the event's class against the metadata stored by the `@Externalized`
+ * decorator. Consumed by an {@link EventExternalizer} implementation
+ * (e.g. `MicroservicesEventExternalizer` from
+ * `@nestjs-transactional/outbox-microservices`, Phase 11.3) which
+ * translates the abstract `target` / `routingKey` / `headers` shape
+ * into transport-specific calls.
+ *
+ * Field semantics:
+ * - `eventType` matches `EventPublication.eventType` and is filled in
+ *   for diagnostics — externalizer implementations should not need to
+ *   re-derive it from the payload.
+ * - `target` is the broker-side destination (Kafka topic, RabbitMQ
+ *   exchange, NATS subject, gRPC method, ...). Interpretation is
+ *   delegated to the externalizer.
+ * - `routingKey` is the optional sub-routing token for brokers that
+ *   support it (RabbitMQ routing key, Kafka partition key when used
+ *   that way). Implementations that do not understand routing keys
+ *   should ignore the field.
+ * - `headers` is an optional flat string map propagated to the
+ *   transport's headers / metadata if the transport supports them.
+ * - `client` is an optional override for which `ClientProxy`
+ *   registration the externalizer should use when more than one is
+ *   bound. Resolution semantics are owned by the externalizer
+ *   implementation — `outbox-microservices` interprets it as a token
+ *   in the user's `ClientsModule` registration (DD-017).
+ */
+export interface ExternalizationMetadata {
+    readonly eventType: string;
+    readonly target: string;
+    readonly routingKey?: string;
+    readonly headers?: Record<string, string>;
+    readonly client?: string | symbol;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/externalization/types.js

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

package/dist/externalization/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/externalization/types.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+export * from './types/publication-status';
+export * from './types/event-publication';
+export * from './types/completion-mode';
+export * from './types/resubmission-options';
+export * from './types/staleness-config';
+export * from './types/errors';
+export * from './serialization/event-serializer';
+export * from './serialization/event-type-registry';
+export * from './serialization/event-type-resolver';
+export * from './serialization/json-event-serializer';
+export * from './repository/event-publication-repository';
+export * from './registry/event-publication-registry';
+export * from './registry/listener-registry';
+export * from './registry/multi-ds-listener-registrar';
+export * from './registry/outbox-listener-scanner';
+export * from './decorators/outbox-events-handler.decorator';
+export * from './decorators/inject-decorators';
+export * from './tokens';
+export type { IOutboxEventHandler } from './interfaces/outbox-event-handler.interface';
+export * from './dispatcher/outbox-event-publisher';
+export * from './dispatcher/data-source-outbox-publisher';
+export * from './dispatcher/event-publication-processor';
+export * from './dispatcher/processor-options';
+export type { ExternalizationMetadata } from './externalization/types';
+export type { EventExternalizer } from './externalization/event-externalizer';
+export { EVENT_EXTERNALIZER } from './externalization/event-externalizer';
+export { ExternalizationError } from './externalization/errors';
+export { Externalized, getExternalizedMetadata, EXTERNALIZED_METADATA, } from './externalization/externalized.decorator';
+export type { ExternalizedOptions, ExternalizedMetadata, } from './externalization/externalized.decorator';
+export { ExternalizationRegistry, EXTERNALIZATION_REGISTRY, } from './externalization/externalization-registry';
+export * from './recovery/staleness-monitor';
+export * from './api/failed-event-publications';
+export * from './api/incomplete-event-publications';
+export * from './api/completed-event-publications';
+export * from './recovery/startup-recovery';
+export * from './module/outbox.module';
+export * from './module/outbox-processing.module';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,58 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXTERNALIZATION_REGISTRY = exports.ExternalizationRegistry = exports.EXTERNALIZED_METADATA = exports.getExternalizedMetadata = exports.Externalized = exports.ExternalizationError = exports.EVENT_EXTERNALIZER = void 0;
+__exportStar(require("./types/publication-status"), exports);
+__exportStar(require("./types/event-publication"), exports);
+__exportStar(require("./types/completion-mode"), exports);
+__exportStar(require("./types/resubmission-options"), exports);
+__exportStar(require("./types/staleness-config"), exports);
+__exportStar(require("./types/errors"), exports);
+__exportStar(require("./serialization/event-serializer"), exports);
+__exportStar(require("./serialization/event-type-registry"), exports);
+__exportStar(require("./serialization/event-type-resolver"), exports);
+__exportStar(require("./serialization/json-event-serializer"), exports);
+__exportStar(require("./repository/event-publication-repository"), exports);
+__exportStar(require("./registry/event-publication-registry"), exports);
+__exportStar(require("./registry/listener-registry"), exports);
+__exportStar(require("./registry/multi-ds-listener-registrar"), exports);
+__exportStar(require("./registry/outbox-listener-scanner"), exports);
+__exportStar(require("./decorators/outbox-events-handler.decorator"), exports);
+__exportStar(require("./decorators/inject-decorators"), exports);
+__exportStar(require("./tokens"), exports);
+__exportStar(require("./dispatcher/outbox-event-publisher"), exports);
+__exportStar(require("./dispatcher/data-source-outbox-publisher"), exports);
+__exportStar(require("./dispatcher/event-publication-processor"), exports);
+__exportStar(require("./dispatcher/processor-options"), exports);
+var event_externalizer_1 = require("./externalization/event-externalizer");
+Object.defineProperty(exports, "EVENT_EXTERNALIZER", { enumerable: true, get: function () { return event_externalizer_1.EVENT_EXTERNALIZER; } });
+var errors_1 = require("./externalization/errors");
+Object.defineProperty(exports, "ExternalizationError", { enumerable: true, get: function () { return errors_1.ExternalizationError; } });
+var externalized_decorator_1 = require("./externalization/externalized.decorator");
+Object.defineProperty(exports, "Externalized", { enumerable: true, get: function () { return externalized_decorator_1.Externalized; } });
+Object.defineProperty(exports, "getExternalizedMetadata", { enumerable: true, get: function () { return externalized_decorator_1.getExternalizedMetadata; } });
+Object.defineProperty(exports, "EXTERNALIZED_METADATA", { enumerable: true, get: function () { return externalized_decorator_1.EXTERNALIZED_METADATA; } });
+var externalization_registry_1 = require("./externalization/externalization-registry");
+Object.defineProperty(exports, "ExternalizationRegistry", { enumerable: true, get: function () { return externalization_registry_1.ExternalizationRegistry; } });
+Object.defineProperty(exports, "EXTERNALIZATION_REGISTRY", { enumerable: true, get: function () { return externalization_registry_1.EXTERNALIZATION_REGISTRY; } });
+__exportStar(require("./recovery/staleness-monitor"), exports);
+__exportStar(require("./api/failed-event-publications"), exports);
+__exportStar(require("./api/incomplete-event-publications"), exports);
+__exportStar(require("./api/completed-event-publications"), exports);
+__exportStar(require("./recovery/startup-recovery"), exports);
+__exportStar(require("./module/outbox.module"), exports);
+__exportStar(require("./module/outbox-processing.module"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,6DAA2C;AAC3C,4DAA0C;AAC1C,0DAAwC;AACxC,+DAA6C;AAC7C,2DAAyC;AACzC,iDAA+B;AAE/B,mEAAiD;AACjD,sEAAoD;AACpD,sEAAoD;AACpD,wEAAsD;AAEtD,4EAA0D;AAE1D,wEAAsD;AACtD,+DAA6C;AAC7C,yEAAuD;AACvD,qEAAmD;AAEnD,+EAA6D;AAC7D,iEAA+C;AAE/C,2CAAyB;AAIzB,sEAAoD;AACpD,4EAA0D;AAC1D,2EAAyD;AACzD,iEAA+C;AAI/C,2EAA0E;AAAjE,wHAAA,kBAAkB,OAAA;AAC3B,mDAAgE;AAAvD,8GAAA,oBAAoB,OAAA;AAC7B,mFAIkD;AAHhD,sHAAA,YAAY,OAAA;AACZ,iIAAA,uBAAuB,OAAA;AACvB,+HAAA,qBAAqB,OAAA;AAMvB,uFAGoD;AAFlD,mIAAA,uBAAuB,OAAA;AACvB,oIAAA,wBAAwB,OAAA;AAG1B,+DAA6C;AAE7C,kEAAgD;AAChD,sEAAoD;AACpD,qEAAmD;AAEnD,8DAA4C;AAE5C,yDAAuC;AACvC,oEAAkD"}