@nestjs-transactional/outbox 1.0.0-alpha.0

package/dist/serialization/event-type-registry.d.ts

@@ -0,0 +1,41 @@
+import { Type } from '@nestjs/common';
+/**
+ * Registry that maps event class names to their constructors so the
+ * serializer can reconstruct class instances from stored JSON payloads.
+ *
+ * Event classes are registered at application startup, typically via
+ * `OutboxModule.forFeature([...])` in the feature module that owns the
+ * event class. Each event type can only be registered once — duplicate
+ * registrations throw at bootstrap, so a misconfigured module fails
+ * fast rather than silently shadowing an earlier registration.
+ */
+export declare class EventTypeRegistry {
+    private readonly registry;
+    /**
+     * Register a single event class, keyed by its constructor name.
+     *
+     * @throws `Error` when an event class with the same constructor name
+     * has already been registered. Duplicate registration almost always
+     * indicates a configuration bug (the same event type appearing in
+     * two `forFeature` calls) — fail fast rather than silently shadow.
+     */
+    register(eventType: Type<object>): void;
+    /** Register many event classes at once. */
+    registerAll(eventTypes: Type<object>[]): void;
+    /** Return the registered class for the given name, or `undefined`. */
+    get(typeName: string): Type<object> | undefined;
+    /**
+     * Return the registered class for the given name.
+     *
+     * @throws `Error` with an actionable message when the type is
+     * unregistered — tells the caller how to register it.
+     */
+    getOrThrow(typeName: string): Type<object>;
+    /** Whether the given type name is known to the registry. */
+    has(typeName: string): boolean;
+    /** Return a snapshot of all registered entries. Mutations are not observed. */
+    getAll(): Map<string, Type<object>>;
+}
+/** DI token for the {@link EventTypeRegistry}. */
+export declare const EVENT_TYPE_REGISTRY: unique symbol;
+//# sourceMappingURL=event-type-registry.d.ts.map

package/dist/serialization/event-type-registry.js

@@ -0,0 +1,79 @@
+"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.EVENT_TYPE_REGISTRY = exports.EventTypeRegistry = void 0;
+const common_1 = require("@nestjs/common");
+/**
+ * Registry that maps event class names to their constructors so the
+ * serializer can reconstruct class instances from stored JSON payloads.
+ *
+ * Event classes are registered at application startup, typically via
+ * `OutboxModule.forFeature([...])` in the feature module that owns the
+ * event class. Each event type can only be registered once — duplicate
+ * registrations throw at bootstrap, so a misconfigured module fails
+ * fast rather than silently shadowing an earlier registration.
+ */
+let EventTypeRegistry = class EventTypeRegistry {
+    registry = new Map();
+    /**
+     * Register a single event class, keyed by its constructor name.
+     *
+     * @throws `Error` when an event class with the same constructor name
+     * has already been registered. Duplicate registration almost always
+     * indicates a configuration bug (the same event type appearing in
+     * two `forFeature` calls) — fail fast rather than silently shadow.
+     */
+    register(eventType) {
+        if (this.registry.has(eventType.name)) {
+            throw new Error(`Event type '${eventType.name}' already registered. ` +
+                `Each event type can only be registered once — check for ` +
+                `duplicate entries across OutboxModule.forFeature() calls.`);
+        }
+        this.registry.set(eventType.name, eventType);
+    }
+    /** Register many event classes at once. */
+    registerAll(eventTypes) {
+        for (const type of eventTypes) {
+            this.register(type);
+        }
+    }
+    /** Return the registered class for the given name, or `undefined`. */
+    get(typeName) {
+        return this.registry.get(typeName);
+    }
+    /**
+     * Return the registered class for the given name.
+     *
+     * @throws `Error` with an actionable message when the type is
+     * unregistered — tells the caller how to register it.
+     */
+    getOrThrow(typeName) {
+        const type = this.registry.get(typeName);
+        if (!type) {
+            throw new Error(`Event type '${typeName}' not registered. ` +
+                `Ensure it's registered via OutboxModule.forFeature([...]) in ` +
+                `the feature module that owns this event class.`);
+        }
+        return type;
+    }
+    /** Whether the given type name is known to the registry. */
+    has(typeName) {
+        return this.registry.has(typeName);
+    }
+    /** Return a snapshot of all registered entries. Mutations are not observed. */
+    getAll() {
+        return new Map(this.registry);
+    }
+};
+exports.EventTypeRegistry = EventTypeRegistry;
+exports.EventTypeRegistry = EventTypeRegistry = __decorate([
+    (0, common_1.Injectable)()
+], EventTypeRegistry);
+/** DI token for the {@link EventTypeRegistry}. */
+exports.EVENT_TYPE_REGISTRY = Symbol('EVENT_TYPE_REGISTRY');
+//# sourceMappingURL=event-type-registry.js.map

package/dist/serialization/event-type-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-type-registry.js","sourceRoot":"","sources":["../../src/serialization/event-type-registry.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAAkD;AAElD;;;;;;;;;GASG;AAEI,IAAM,iBAAiB,GAAvB,MAAM,iBAAiB;IACX,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAC;IAE5D;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAuB;QAC9B,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CACb,eAAe,SAAS,CAAC,IAAI,wBAAwB;gBACnD,0DAA0D;gBAC1D,2DAA2D,CAC9D,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAC/C,CAAC;IAED,2CAA2C;IAC3C,WAAW,CAAC,UAA0B;QACpC,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;YAC9B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAED,sEAAsE;IACtE,GAAG,CAAC,QAAgB;QAClB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACrC,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,QAAgB;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CACb,eAAe,QAAQ,oBAAoB;gBACzC,+DAA+D;gBAC/D,gDAAgD,CACnD,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,4DAA4D;IAC5D,GAAG,CAAC,QAAgB;QAClB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACrC,CAAC;IAED,+EAA+E;IAC/E,MAAM;QACJ,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;CACF,CAAA;AA7DY,8CAAiB;4BAAjB,iBAAiB;IAD7B,IAAA,mBAAU,GAAE;GACA,iBAAiB,CA6D7B;AAED,kDAAkD;AACrC,QAAA,mBAAmB,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC"}

package/dist/serialization/event-type-resolver.d.ts

@@ -0,0 +1,43 @@
+import type { EventTypeRegistry } from './event-type-registry';
+/**
+ * Resolve the dataSource that owns a given event-type name by walking
+ * a Map of per-dataSource {@link EventTypeRegistry} instances. Returns
+ * the dataSource name as a string when exactly one registry contains
+ * the event-type — otherwise throws {@link OutboxError} with an
+ * actionable message.
+ *
+ * Single source of truth shared by three consumers (Phase 14.3.1):
+ *
+ *  - {@link OutboxEventPublisher.resolveDataSource} — smart-facade
+ *    publisher routes events to the dataSource that registered them.
+ *  - `OutboxListenerScanner` — decorator-driven `@OutboxEventsHandler`
+ *    handlers register with the per-dataSource
+ *    `OutboxListenerRegistry` whose dataSource owns the event class.
+ *  - `MultiDsOutboxListenerRegistrar` — bridges
+ *    `@IntegrationEventsHandler` from the cqrs package's structural
+ *    port to the per-dataSource registry.
+ *
+ * Failure modes:
+ *
+ *  - **Zero matches** (event not registered anywhere): the caller is
+ *    almost always missing an `OutboxModule.forFeature([X], { dataSource })`
+ *    call. The thrown message names the event and suggests the fix.
+ *  - **Multiple matches** (event registered in more than one dataSource):
+ *    ambiguous routing. The thrown message names the event, lists the
+ *    candidate dataSources, and suggests either restricting the
+ *    registration to one dataSource or using an explicit
+ *    `{ dataSource }` option (in publisher contexts) / programmatic
+ *    per-DS listener registration (in scanner contexts).
+ *
+ * The same throw policy is applied across all three consumers so the
+ * mental model is uniform: an event class belongs to exactly one
+ * dataSource by registration.
+ *
+ * @param eventTypeName The event class's `constructor.name`.
+ * @param registries Map of dataSource name → {@link EventTypeRegistry}.
+ * @returns The dataSource name.
+ * @throws {OutboxError} when zero or multiple registries contain the
+ *   event-type.
+ */
+export declare function resolveDataSourceByEventTypeName(eventTypeName: string, registries: ReadonlyMap<string, EventTypeRegistry>): string;
+//# sourceMappingURL=event-type-resolver.d.ts.map

package/dist/serialization/event-type-resolver.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDataSourceByEventTypeName = resolveDataSourceByEventTypeName;
+const errors_1 = require("../types/errors");
+/**
+ * Resolve the dataSource that owns a given event-type name by walking
+ * a Map of per-dataSource {@link EventTypeRegistry} instances. Returns
+ * the dataSource name as a string when exactly one registry contains
+ * the event-type — otherwise throws {@link OutboxError} with an
+ * actionable message.
+ *
+ * Single source of truth shared by three consumers (Phase 14.3.1):
+ *
+ *  - {@link OutboxEventPublisher.resolveDataSource} — smart-facade
+ *    publisher routes events to the dataSource that registered them.
+ *  - `OutboxListenerScanner` — decorator-driven `@OutboxEventsHandler`
+ *    handlers register with the per-dataSource
+ *    `OutboxListenerRegistry` whose dataSource owns the event class.
+ *  - `MultiDsOutboxListenerRegistrar` — bridges
+ *    `@IntegrationEventsHandler` from the cqrs package's structural
+ *    port to the per-dataSource registry.
+ *
+ * Failure modes:
+ *
+ *  - **Zero matches** (event not registered anywhere): the caller is
+ *    almost always missing an `OutboxModule.forFeature([X], { dataSource })`
+ *    call. The thrown message names the event and suggests the fix.
+ *  - **Multiple matches** (event registered in more than one dataSource):
+ *    ambiguous routing. The thrown message names the event, lists the
+ *    candidate dataSources, and suggests either restricting the
+ *    registration to one dataSource or using an explicit
+ *    `{ dataSource }` option (in publisher contexts) / programmatic
+ *    per-DS listener registration (in scanner contexts).
+ *
+ * The same throw policy is applied across all three consumers so the
+ * mental model is uniform: an event class belongs to exactly one
+ * dataSource by registration.
+ *
+ * @param eventTypeName The event class's `constructor.name`.
+ * @param registries Map of dataSource name → {@link EventTypeRegistry}.
+ * @returns The dataSource name.
+ * @throws {OutboxError} when zero or multiple registries contain the
+ *   event-type.
+ */
+function resolveDataSourceByEventTypeName(eventTypeName, registries) {
+    const matches = [];
+    for (const [dataSource, registry] of registries) {
+        if (registry.has(eventTypeName)) {
+            matches.push(dataSource);
+        }
+    }
+    if (matches.length === 0) {
+        throw new errors_1.OutboxError(`Event type '${eventTypeName}' is not registered in any dataSource. ` +
+            `Add it to OutboxModule.forFeature([...], { dataSource: '...' }) ` +
+            `in the feature module that owns the event class.`);
+    }
+    if (matches.length > 1) {
+        throw new errors_1.OutboxError(`Event type '${eventTypeName}' is registered in multiple dataSources ` +
+            `(${matches.join(', ')}). Pass an explicit { dataSource } option to ` +
+            `disambiguate, or register the event in only one dataSource.`);
+    }
+    // Exactly one match — narrow safe.
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    return matches[0];
+}
+//# sourceMappingURL=event-type-resolver.js.map

package/dist/serialization/event-type-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-type-resolver.js","sourceRoot":"","sources":["../../src/serialization/event-type-resolver.ts"],"names":[],"mappings":";;AA4CA,4EA4BC;AAxED,4CAA8C;AAI9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,SAAgB,gCAAgC,CAC9C,aAAqB,EACrB,UAAkD;IAElD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,IAAI,UAAU,EAAE,CAAC;QAChD,IAAI,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,CAAC;YAChC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,oBAAW,CACnB,eAAe,aAAa,yCAAyC;YACnE,kEAAkE;YAClE,kDAAkD,CACrD,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,oBAAW,CACnB,eAAe,aAAa,0CAA0C;YACpE,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,+CAA+C;YACrE,6DAA6D,CAChE,CAAC;IACJ,CAAC;IACD,mCAAmC;IACnC,oEAAoE;IACpE,OAAO,OAAO,CAAC,CAAC,CAAE,CAAC;AACrB,CAAC"}

package/dist/serialization/json-event-serializer.d.ts

@@ -0,0 +1,20 @@
+import type { EventSerializer } from './event-serializer';
+import { EventTypeRegistry } from './event-type-registry';
+/**
+ * Default JSON-based {@link EventSerializer}. Uses `JSON.stringify` for
+ * encoding and `JSON.parse` + `Object.create` for decoding, consulting
+ * an {@link EventTypeRegistry} to restore the class prototype when
+ * possible.
+ *
+ * This implementation is intentionally simple: it restores the
+ * prototype but does not call the constructor, so classes with private
+ * fields, Value-Object invariants, or custom deserialization must
+ * provide their own `EventSerializer`.
+ */
+export declare class JsonEventSerializer implements EventSerializer {
+    private readonly registry;
+    constructor(registry: EventTypeRegistry);
+    serialize(event: unknown): string;
+    deserialize(serialized: string, eventType: string): unknown;
+}
+//# sourceMappingURL=json-event-serializer.d.ts.map

package/dist/serialization/json-event-serializer.js

@@ -0,0 +1,64 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonEventSerializer = void 0;
+const common_1 = require("@nestjs/common");
+const errors_1 = require("../types/errors");
+const event_type_registry_1 = require("./event-type-registry");
+/**
+ * Default JSON-based {@link EventSerializer}. Uses `JSON.stringify` for
+ * encoding and `JSON.parse` + `Object.create` for decoding, consulting
+ * an {@link EventTypeRegistry} to restore the class prototype when
+ * possible.
+ *
+ * This implementation is intentionally simple: it restores the
+ * prototype but does not call the constructor, so classes with private
+ * fields, Value-Object invariants, or custom deserialization must
+ * provide their own `EventSerializer`.
+ */
+let JsonEventSerializer = class JsonEventSerializer {
+    registry;
+    constructor(registry) {
+        this.registry = registry;
+    }
+    serialize(event) {
+        if (!event || typeof event !== 'object') {
+            throw new errors_1.SerializationError(`Cannot serialize non-object: ${typeof event}`);
+        }
+        try {
+            return JSON.stringify(event);
+        }
+        catch (err) {
+            throw new errors_1.SerializationError(`Failed to serialize event: ${err.message}`);
+        }
+    }
+    deserialize(serialized, eventType) {
+        const EventClass = this.registry.get(eventType);
+        let data;
+        try {
+            data = JSON.parse(serialized);
+        }
+        catch (err) {
+            throw new errors_1.DeserializationError(`Failed to deserialize event '${eventType}': ${err.message}`);
+        }
+        if (!EventClass) {
+            return data;
+        }
+        const prototype = EventClass.prototype;
+        return Object.assign(Object.create(prototype), data);
+    }
+};
+exports.JsonEventSerializer = JsonEventSerializer;
+exports.JsonEventSerializer = JsonEventSerializer = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [event_type_registry_1.EventTypeRegistry])
+], JsonEventSerializer);
+//# sourceMappingURL=json-event-serializer.js.map

package/dist/serialization/json-event-serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-event-serializer.js","sourceRoot":"","sources":["../../src/serialization/json-event-serializer.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAA4C;AAE5C,4CAA2E;AAG3E,+DAA0D;AAE1D;;;;;;;;;;GAUG;AAEI,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;IACD;IAA7B,YAA6B,QAA2B;QAA3B,aAAQ,GAAR,QAAQ,CAAmB;IAAG,CAAC;IAE5D,SAAS,CAAC,KAAc;QACtB,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACxC,MAAM,IAAI,2BAAkB,CAAC,gCAAgC,OAAO,KAAK,EAAE,CAAC,CAAC;QAC/E,CAAC;QACD,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,2BAAkB,CAC1B,8BAA+B,GAAa,CAAC,OAAO,EAAE,CACvD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,WAAW,CAAC,UAAkB,EAAE,SAAiB;QAC/C,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAEhD,IAAI,IAAa,CAAC;QAClB,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,6BAAoB,CAC5B,gCAAgC,SAAS,MAAO,GAAa,CAAC,OAAO,EAAE,CACxE,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,SAAS,GAAW,UAAU,CAAC,SAAmB,CAAC;QACzD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAW,EAAE,IAAI,CAAC,CAAC;IACjE,CAAC;CACF,CAAA;AAnCY,kDAAmB;8BAAnB,mBAAmB;IAD/B,IAAA,mBAAU,GAAE;qCAE4B,uCAAiB;GAD7C,mBAAmB,CAmC/B"}

package/dist/testing/assertable-published-events.d.ts

@@ -0,0 +1,71 @@
+import { type Type } from '@nestjs/common';
+import { PublishedEvents, type PublishedEventsView } from './published-events';
+/**
+ * Thrown when an assertion made against the published-events view does
+ * not hold. A separate class (instead of a plain `Error`) so tests can
+ * pattern-match with `rejects.toBeInstanceOf(PublishedEventsAssertionError)`
+ * when they want to assert on failure modes.
+ */
+export declare class PublishedEventsAssertionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Jest-friendly fluent assertions over {@link PublishedEvents}. Inspired
+ * by Spring Modulith's `AssertablePublishedEvents`. Designed to read
+ * naturally at the call site:
+ *
+ * ```ts
+ * const view = await assertablePublishedEvents.contains(OrderPlacedEvent);
+ * view.matching((e) => e.orderId, 'order-123').hasSize(1);
+ * ```
+ *
+ * Both assertions throw {@link PublishedEventsAssertionError} on
+ * failure, which Jest renders as a normal test failure.
+ */
+export declare class AssertablePublishedEvents {
+    private readonly events;
+    constructor(events: PublishedEvents);
+    /**
+     * Assert that at least one event of the given class was published,
+     * then return a view over those events for further assertions.
+     *
+     * @throws {PublishedEventsAssertionError} when no matching event
+     *   was published.
+     */
+    contains<T extends object>(eventType: Type<T>): Promise<AssertionView<T>>;
+    /**
+     * Assert that NO event of the given class was published.
+     *
+     * @throws {PublishedEventsAssertionError} when one or more matching
+     *   events were published.
+     */
+    doesNotContain<T extends object>(eventType: Type<T>): Promise<void>;
+}
+/**
+ * Materialised, filtered view returned by
+ * {@link AssertablePublishedEvents.contains}. Further filtering /
+ * sizing runs in memory — no additional repository reads.
+ */
+export declare class AssertionView<T extends object> {
+    private readonly view;
+    private readonly events;
+    private readonly eventType;
+    constructor(view: PublishedEventsView<T>, events: readonly T[], eventType: Type<T>);
+    /**
+     * Narrow the view to events whose derived value equals `expected`.
+     * Returns a new {@link AssertionView} so assertions can chain.
+     *
+     * @throws {PublishedEventsAssertionError} when no event in the
+     *   current view matches.
+     */
+    matching<K>(getter: (event: T) => K, expected: K): AssertionView<T>;
+    /**
+     * Assert the view contains exactly `expected` events.
+     *
+     * @throws {PublishedEventsAssertionError} when the count differs.
+     */
+    hasSize(expected: number): this;
+    /** Read the current events. Useful for ad-hoc assertions with Jest's matchers. */
+    toArray(): T[];
+}
+//# sourceMappingURL=assertable-published-events.d.ts.map

package/dist/testing/assertable-published-events.js

@@ -0,0 +1,124 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssertionView = exports.AssertablePublishedEvents = exports.PublishedEventsAssertionError = void 0;
+const common_1 = require("@nestjs/common");
+const published_events_1 = require("./published-events");
+/**
+ * Thrown when an assertion made against the published-events view does
+ * not hold. A separate class (instead of a plain `Error`) so tests can
+ * pattern-match with `rejects.toBeInstanceOf(PublishedEventsAssertionError)`
+ * when they want to assert on failure modes.
+ */
+class PublishedEventsAssertionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PublishedEventsAssertionError';
+    }
+}
+exports.PublishedEventsAssertionError = PublishedEventsAssertionError;
+/**
+ * Jest-friendly fluent assertions over {@link PublishedEvents}. Inspired
+ * by Spring Modulith's `AssertablePublishedEvents`. Designed to read
+ * naturally at the call site:
+ *
+ * ```ts
+ * const view = await assertablePublishedEvents.contains(OrderPlacedEvent);
+ * view.matching((e) => e.orderId, 'order-123').hasSize(1);
+ * ```
+ *
+ * Both assertions throw {@link PublishedEventsAssertionError} on
+ * failure, which Jest renders as a normal test failure.
+ */
+let AssertablePublishedEvents = class AssertablePublishedEvents {
+    events;
+    constructor(events) {
+        this.events = events;
+    }
+    /**
+     * Assert that at least one event of the given class was published,
+     * then return a view over those events for further assertions.
+     *
+     * @throws {PublishedEventsAssertionError} when no matching event
+     *   was published.
+     */
+    async contains(eventType) {
+        const view = this.events.ofType(eventType);
+        const events = await view.get();
+        if (events.length === 0) {
+            throw new PublishedEventsAssertionError(`Expected at least one event of type ${eventType.name}, but found none`);
+        }
+        return new AssertionView(view, events, eventType);
+    }
+    /**
+     * Assert that NO event of the given class was published.
+     *
+     * @throws {PublishedEventsAssertionError} when one or more matching
+     *   events were published.
+     */
+    async doesNotContain(eventType) {
+        const events = await this.events.ofType(eventType).get();
+        if (events.length > 0) {
+            throw new PublishedEventsAssertionError(`Expected no events of type ${eventType.name}, but found ${events.length}`);
+        }
+    }
+};
+exports.AssertablePublishedEvents = AssertablePublishedEvents;
+exports.AssertablePublishedEvents = AssertablePublishedEvents = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [published_events_1.PublishedEvents])
+], AssertablePublishedEvents);
+/**
+ * Materialised, filtered view returned by
+ * {@link AssertablePublishedEvents.contains}. Further filtering /
+ * sizing runs in memory — no additional repository reads.
+ */
+class AssertionView {
+    view;
+    events;
+    eventType;
+    constructor(view, events, eventType) {
+        this.view = view;
+        this.events = events;
+        this.eventType = eventType;
+    }
+    /**
+     * Narrow the view to events whose derived value equals `expected`.
+     * Returns a new {@link AssertionView} so assertions can chain.
+     *
+     * @throws {PublishedEventsAssertionError} when no event in the
+     *   current view matches.
+     */
+    matching(getter, expected) {
+        const filtered = this.events.filter((event) => getter(event) === expected);
+        if (filtered.length === 0) {
+            throw new PublishedEventsAssertionError(`Expected at least one event of type ${this.eventType.name} matching the predicate, but none found`);
+        }
+        return new AssertionView(this.view, filtered, this.eventType);
+    }
+    /**
+     * Assert the view contains exactly `expected` events.
+     *
+     * @throws {PublishedEventsAssertionError} when the count differs.
+     */
+    hasSize(expected) {
+        if (this.events.length !== expected) {
+            throw new PublishedEventsAssertionError(`Expected ${expected} events of type ${this.eventType.name}, but found ${this.events.length}`);
+        }
+        return this;
+    }
+    /** Read the current events. Useful for ad-hoc assertions with Jest's matchers. */
+    toArray() {
+        return [...this.events];
+    }
+}
+exports.AssertionView = AssertionView;
+//# sourceMappingURL=assertable-published-events.js.map

package/dist/testing/assertable-published-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertable-published-events.js","sourceRoot":"","sources":["../../src/testing/assertable-published-events.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAAuD;AAEvD,yDAA+E;AAE/E;;;;;GAKG;AACH,MAAa,6BAA8B,SAAQ,KAAK;IACtD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAC9C,CAAC;CACF;AALD,sEAKC;AAED;;;;;;;;;;;;GAYG;AAEI,IAAM,yBAAyB,GAA/B,MAAM,yBAAyB;IACP;IAA7B,YAA6B,MAAuB;QAAvB,WAAM,GAAN,MAAM,CAAiB;IAAG,CAAC;IAExD;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,CAAmB,SAAkB;QACjD,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC3C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC;QAChC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,6BAA6B,CACrC,uCAAuC,SAAS,CAAC,IAAI,kBAAkB,CACxE,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,aAAa,CAAI,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;IACvD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,cAAc,CAAmB,SAAkB;QACvD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,CAAC;QACzD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,6BAA6B,CACrC,8BAA8B,SAAS,CAAC,IAAI,eAAe,MAAM,CAAC,MAAM,EAAE,CAC3E,CAAC;QACJ,CAAC;IACH,CAAC;CACF,CAAA;AAnCY,8DAAyB;oCAAzB,yBAAyB;IADrC,IAAA,mBAAU,GAAE;qCAE0B,kCAAe;GADzC,yBAAyB,CAmCrC;AAED;;;;GAIG;AACH,MAAa,aAAa;IAEL;IACA;IACA;IAHnB,YACmB,IAA4B,EAC5B,MAAoB,EACpB,SAAkB;QAFlB,SAAI,GAAJ,IAAI,CAAwB;QAC5B,WAAM,GAAN,MAAM,CAAc;QACpB,cAAS,GAAT,SAAS,CAAS;IAClC,CAAC;IAEJ;;;;;;OAMG;IACH,QAAQ,CAAI,MAAuB,EAAE,QAAW;QAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC,CAAC;QAC3E,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,6BAA6B,CACrC,uCAAuC,IAAI,CAAC,SAAS,CAAC,IAAI,yCAAyC,CACpG,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,aAAa,CAAI,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IACnE,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,QAAgB;QACtB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YACpC,MAAM,IAAI,6BAA6B,CACrC,YAAY,QAAQ,mBAAmB,IAAI,CAAC,SAAS,CAAC,IAAI,eAAe,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAC9F,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kFAAkF;IAClF,OAAO;QACL,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;CACF;AA1CD,sCA0CC"}

package/dist/testing/in-memory-repository.d.ts

@@ -0,0 +1,52 @@
+import { TransactionManager } from '@nestjs-transactional/core';
+import type { EventPublicationRepository, FindCompletedOptions, FindFailedOptions, UpdateStatusOptions } from '../repository/event-publication-repository';
+import type { EventPublication, NewEventPublication } from '../types/event-publication';
+import { PublicationStatus } from '../types/publication-status';
+/**
+ * In-memory reference implementation of {@link EventPublicationRepository}.
+ *
+ * Intended for unit and integration tests of outbox consumers that
+ * do not want to spin up a real database. Not thread-safe — do not use
+ * in production.
+ *
+ * Optional `TransactionManager` enables transaction-aware behaviour:
+ * when a mutating method is called inside an active transaction, the
+ * repository registers an `afterRollback` hook that undoes the change
+ * — so the visible state after rollback matches what a real
+ * transactional backend would show. When no `TransactionManager` is
+ * provided (or no transaction is active), mutations apply immediately
+ * and are not undone.
+ *
+ * Exposes a few extra methods beyond the SPI (`reset`, `getAll`,
+ * `count`) to help tests set up and assert on state.
+ */
+export declare class InMemoryEventPublicationRepository implements EventPublicationRepository {
+    private readonly transactionManager?;
+    private readonly publications;
+    constructor(transactionManager?: TransactionManager | undefined);
+    createAll(inputs: NewEventPublication[]): Promise<EventPublication[]>;
+    findById(id: string): Promise<EventPublication | null>;
+    updateStatus(id: string, status: PublicationStatus, options?: UpdateStatusOptions): Promise<void>;
+    tryClaim(id: string): Promise<boolean>;
+    findReadyForProcessing(limit: number): Promise<EventPublication[]>;
+    findStale(beforeDate: Date, statuses: PublicationStatus[]): Promise<EventPublication[]>;
+    findCompleted(options?: FindCompletedOptions): Promise<EventPublication[]>;
+    findIncomplete(): Promise<EventPublication[]>;
+    findFailed(options?: FindFailedOptions): Promise<EventPublication[]>;
+    deleteCompleted(olderThan?: Date): Promise<number>;
+    archiveCompleted(id: string): Promise<void>;
+    delete(id: string): Promise<void>;
+    /** Drop every stored publication. Does not interact with transactions. */
+    reset(): void;
+    /** Snapshot of every stored publication, in insertion order. */
+    getAll(): EventPublication[];
+    /** Number of stored publications. */
+    count(): number;
+    /**
+     * If a `TransactionManager` was provided and a transaction is active,
+     * register the given `undo` closure to fire on rollback. Otherwise
+     * this is a no-op.
+     */
+    private trackRollback;
+}
+//# sourceMappingURL=in-memory-repository.d.ts.map