@starci/jest-preset 2.3.7 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2.4.0 - 2026-10-28
+
+- Changed: the source is TypeScript in `src/`, built to CommonJS JavaScript in `dist/` (`npm run build`; `prepack` builds), and the declarations are emitted from it instead of hand-written; `main`, `types` and every export (`.`, `./mock`, `./clock`, `./entity-manager`, `./ids`, `./matchers`, `./cache`, `./lock`, `./event-bus`, `./queue`, `./inbox`, `./builders`, `./merge`) point into `dist/`. No rule or behaviour changed; the specifiers are unchanged. The files jest loads by path are now `dist/world-runner.js`, `dist/unit-metadata.js`, `dist/unit-metadata.generated.js` (the coverage anchor, copied byte for byte from `assets/`) and `dist/lcov.js`; `@starci/jest-preset/merge` now has types.
+- Changed: `starciJestConfig` returns `StarciJestConfig` (jest's `Config` with `projects` all objects, a custom reporter path allowed in `coverageReporters` and a `coverageThreshold` keyed by glob only), the type its value always had; `createMock` takes a factory called with the property name; the package specs are `test/*.spec.ts` and load the built `dist/`.
+
 ## 2.3.7 - 2026-10-27
 
 - Changed: licensed MIT (was UNLICENSED); the package metadata names the repository, homepage and bugs so npm can attach provenance. No rule or behaviour changed.

package/README.md

@@ -19,7 +19,7 @@ and the exclusions. A repository has no other jest setting to tune.
   `src/tests/{world,integration,e2e,contract}/`), `integration` (`src/tests/integration/**/*.integration-spec.ts`), `e2e`
   (`src/tests/e2e/**/*.e2e-spec.ts`) and `contract` (`src/tests/contract/**/*.contract-spec.ts`). The last three compile against
   `src/tests/tsconfig.json`, start the one test world through `globalSetup`/`globalTeardown`
-  (`src/tests/world/global-setup.ts`, `global-teardown.ts`) and run on the world runner (`world-runner.cjs`, `WORLD_RUNNER`): every
+  (`src/tests/world/global-setup.ts`, `global-teardown.ts`) and run on the world runner (`world-runner.js`, `WORLD_RUNNER`): every
   spec file in a worker process of its own and never in band, so nothing the globalSetup or another file left on a process global
   (a framework registry such as `@nestjs/graphql`'s type metadata) reaches the file; and up to `min(--maxWorkers, slots)` files at
   once, each bound to its own data slot of `@starci/test-world` 1.1.0 (`STARCI_TEST_WORLD_SLOT`), never two files on one slot,
@@ -37,8 +37,8 @@ and the exclusions. A repository has no other jest setting to tune.
   `ruleParams.be.logicRoles` role inside a measured slot must reach 100 on every metric (an average never passes). The
   managed `test` script runs the unit project with `--coverage` and fails below it. Coverage is measured by v8, which counts the
   real source. The unit project overlays `isolatedModules: true`, `importHelpers: true` and `sourceMap: true` on the repository tsconfig, so ts-jest
-  transpiles each file without building a type program. `unit-metadata.cjs`, a ts-jest wrapper and after-transformer, maps
-  only synthetic `typeof value === "function" ? value : Object` guards inside TypeScript's generated `__metadata("design:paramtypes", ...)` calls to the dedicated `unit-metadata.generated.cjs` coverage anchor. Their runtime guards remain unchanged, including
+  transpiles each file without building a type program. `unit-metadata.js`, a ts-jest wrapper and after-transformer, maps
+  only synthetic `typeof value === "function" ? value : Object` guards inside TypeScript's generated `__metadata("design:paramtypes", ...)` calls to the dedicated `unit-metadata.generated.js` coverage anchor. Their runtime guards remain unchanged, including
   the fallback to `Object` for an undefined or non-class dependency; generated branches are not attributed to source parameters.
   The wrapper restores that second source after ts-jest emits its map. The anchor ignores generated guards only and is omitted from LCOV. Application source calls and guards remain measured. Source maps are enabled even when the build config disables them.
   Source conditionals, including branches on the same constructor line, still count toward per-file 100 coverage. Decorator helpers

package/{builders.cjs → dist/builders.d.ts}

@@ -1,5 +1,3 @@
-"use strict"
-
 /**
  * `builder(defaults)` -- the one way a spec makes a plain value with a few fields changed: a module options object
  * (`<CAP>_OPTIONS`), a principal, a request context. Options tokens are provided as REAL values, never as doubles; a
@@ -8,8 +6,5 @@
  *   const options = builder<OrderOptions>({ maxLines: 50, allowGuestCheckout: false })
  *   options({ allowGuestCheckout: true })   // a whole OrderOptions with one flag flipped
  */
-function builder(defaults) {
-  return (overrides) => ({ ...defaults, ...overrides })
-}
-
-module.exports = { builder }
+/** Makes a builder of `T`: a function returning the defaults with `overrides` applied. */
+export declare function builder<T extends object>(defaults: T): (overrides?: Partial<T>) => T;

package/dist/builders.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.builder = builder;
+/**
+ * `builder(defaults)` -- the one way a spec makes a plain value with a few fields changed: a module options object
+ * (`<CAP>_OPTIONS`), a principal, a request context. Options tokens are provided as REAL values, never as doubles; a
+ * builder holds the valid defaults once so each spec states only the field it varies.
+ *
+ *   const options = builder<OrderOptions>({ maxLines: 50, allowGuestCheckout: false })
+ *   options({ allowGuestCheckout: true })   // a whole OrderOptions with one flag flipped
+ */
+/** Makes a builder of `T`: a function returning the defaults with `overrides` applied. */
+function builder(defaults) {
+    return (overrides) => ({ ...defaults, ...overrides });
+}

package/dist/cache.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `fakeCache(clock)` -- a behavioural in-memory double of a cache port.
+ *
+ * It keeps entries as JSON text (like a Redis-backed cache, so a Date comes back as a string and a `key.parse` narrows
+ * what was stored), expires them from the `FakeClock` (`clock.advance(ms)` is a TTL expiry, no sleep), and offers the
+ * inspection a spec needs: `has(key)`, `ttlOf(key)`, `keys()`.
+ *
+ * Two call shapes are served by the same object, so it stands in for either kind of cache dependency:
+ *   - the typed-key port: `get({ key, args })`, `set({ key, args, value })`, `del({ key, args })`, where `key` is
+ *     `{ name, ttl: { seconds }, parse? }` and the entry text is `<name>:<arg>:...`;
+ *   - the cache-manager shape: `get(text)`, `set(text, value, ttlMs?)`, `del(text)`.
+ * `has`, `ttlOf` and `del` accept a request or the entry text.
+ */
+/** The declared key of a typed cache entry: `{ name, ttl, parse? }`. */
+export interface FakeCacheKey<TValue = unknown> {
+    readonly name: string;
+    readonly ttl: {
+        readonly seconds: number;
+    };
+    readonly parse?: (stored: unknown) => TValue | null;
+}
+/** The typed-key request: the key plus the arguments that make the entry unique. */
+export interface FakeCacheRequest<TValue = unknown> {
+    readonly key: FakeCacheKey<TValue>;
+    readonly args?: ReadonlyArray<string>;
+}
+export type FakeCacheEntry<TValue = unknown> = FakeCacheRequest<TValue> & {
+    readonly value: TValue;
+};
+/** A behavioural in-memory cache: JSON round trip, expiry driven by the clock, inspection helpers. */
+export interface FakeCache {
+    get<TValue>(request: FakeCacheRequest<TValue>): Promise<TValue | null>;
+    get(text: string): Promise<unknown>;
+    set<TValue>(entry: FakeCacheEntry<TValue>): Promise<void>;
+    set(text: string, value: unknown, ttlMs?: number): Promise<void>;
+    del(request: FakeCacheRequest | string): Promise<void>;
+    /** Whether a live (not expired) entry exists. */
+    has(request: FakeCacheRequest | string): boolean;
+    /** Seconds left before the entry expires (rounded up); null when absent, expired or without a ttl. */
+    ttlOf(request: FakeCacheRequest | string): number | null;
+    /** The texts of the live entries. */
+    keys(): string[];
+    clear(): void;
+}
+/** The cache double; `clock` is the `FakeClock` of the spec, so `clock.advance(ms)` expires entries. */
+export declare function fakeCache(clock: {
+    now(): Date;
+}): FakeCache;

package/dist/cache.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * `fakeCache(clock)` -- a behavioural in-memory double of a cache port.
+ *
+ * It keeps entries as JSON text (like a Redis-backed cache, so a Date comes back as a string and a `key.parse` narrows
+ * what was stored), expires them from the `FakeClock` (`clock.advance(ms)` is a TTL expiry, no sleep), and offers the
+ * inspection a spec needs: `has(key)`, `ttlOf(key)`, `keys()`.
+ *
+ * Two call shapes are served by the same object, so it stands in for either kind of cache dependency:
+ *   - the typed-key port: `get({ key, args })`, `set({ key, args, value })`, `del({ key, args })`, where `key` is
+ *     `{ name, ttl: { seconds }, parse? }` and the entry text is `<name>:<arg>:...`;
+ *   - the cache-manager shape: `get(text)`, `set(text, value, ttlMs?)`, `del(text)`.
+ * `has`, `ttlOf` and `del` accept a request or the entry text.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fakeCache = fakeCache;
+const textOf = (request) => typeof request === "string" ? request : [request.key.name, ...(request.args ?? [])].join(":");
+/** The cache double; `clock` is the `FakeClock` of the spec, so `clock.advance(ms)` expires entries. */
+function fakeCache(clock) {
+    if (!clock || typeof clock.now !== "function")
+        throw new Error("fakeCache: pass the FakeClock the spec drives, fakeCache(clock)");
+    const entries = new Map();
+    const live = (text) => {
+        const entry = entries.get(text);
+        if (entry === undefined)
+            return undefined;
+        if (entry.expiresAt !== null && clock.now().getTime() >= entry.expiresAt) {
+            entries.delete(text);
+            return undefined;
+        }
+        return entry;
+    };
+    async function get(request) {
+        const entry = live(textOf(request));
+        if (entry === undefined)
+            return null;
+        const stored = JSON.parse(entry.json);
+        return typeof request === "string" || typeof request.key.parse !== "function" ? stored : request.key.parse(stored);
+    }
+    async function set(request, value, ttlMs) {
+        const text = textOf(request);
+        const stored = typeof request === "string" ? value : request.value;
+        const lifetimeMs = typeof request === "string" ? ttlMs : request.key.ttl.seconds * 1000;
+        if (lifetimeMs !== undefined && !(lifetimeMs > 0))
+            throw new Error(`fakeCache: the ttl of ${text} must be positive`);
+        entries.set(text, { json: JSON.stringify(stored), expiresAt: lifetimeMs === undefined ? null : clock.now().getTime() + lifetimeMs });
+    }
+    return {
+        get,
+        set,
+        async del(request) {
+            entries.delete(textOf(request));
+        },
+        /** Whether a live (not expired) entry exists. */
+        has: (request) => live(textOf(request)) !== undefined,
+        /** Seconds left before the entry expires (rounded up), null when there is no live entry or it never expires. */
+        ttlOf(request) {
+            const entry = live(textOf(request));
+            if (entry === undefined || entry.expiresAt === null)
+                return null;
+            return Math.ceil((entry.expiresAt - clock.now().getTime()) / 1000);
+        },
+        /** The texts of the live entries. */
+        keys: () => [...entries.keys()].filter((text) => live(text) !== undefined),
+        /** Drops every entry. */
+        clear: () => entries.clear(),
+    };
+}

package/dist/clock.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `FakeClock` -- the test double for the injected `Clock` port (`platform/clock`).
+ *
+ * Business code asks its `Clock` port for the time (`clock.now()`) instead of reading `Date.now()` or
+ * `new Date()` ambiently (`no-ambient-clock`, R79). A spec then drives time explicitly: it starts the
+ * clock at a chosen instant, advances it by a duration, or sets it to a new instant, all without a real
+ * sleep and without a race against the wall clock.
+ */
+/** The test double for the injected `Clock` port: `{ now(): Date }`, plus spec-only time control. */
+export declare class FakeClock {
+    private _now;
+    /** @param at - The instant the clock starts at; defaults to now, once, at construction. */
+    constructor(at?: Date | number | string);
+    /** The current instant, matching the `Clock` port's `now(): Date`. */
+    now(): Date;
+    /** Moves the clock to `at`. */
+    set(at: Date | number | string): void;
+    /** Moves the clock forward by `ms` milliseconds (negative moves it back). */
+    advance(ms: number): void;
+}

package/dist/clock.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * `FakeClock` -- the test double for the injected `Clock` port (`platform/clock`).
+ *
+ * Business code asks its `Clock` port for the time (`clock.now()`) instead of reading `Date.now()` or
+ * `new Date()` ambiently (`no-ambient-clock`, R79). A spec then drives time explicitly: it starts the
+ * clock at a chosen instant, advances it by a duration, or sets it to a new instant, all without a real
+ * sleep and without a race against the wall clock.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FakeClock = void 0;
+/** The test double for the injected `Clock` port: `{ now(): Date }`, plus spec-only time control. */
+class FakeClock {
+    _now;
+    /** @param at - The instant the clock starts at; defaults to now, once, at construction. */
+    constructor(at) {
+        this._now = at === undefined ? new Date() : new Date(at);
+    }
+    /** The current instant, matching the `Clock` port's `now(): Date`. */
+    now() {
+        return new Date(this._now.getTime());
+    }
+    /** Moves the clock to `at`. */
+    set(at) {
+        this._now = new Date(at);
+    }
+    /** Moves the clock forward by `ms` milliseconds (negative moves it back). */
+    advance(ms) {
+        this._now = new Date(this._now.getTime() + ms);
+    }
+}
+exports.FakeClock = FakeClock;

package/dist/entity-manager.d.ts

@@ -0,0 +1,114 @@
+/// <reference types="jest" preserve="true" />
+/**
+ * `mockEntityManager()` and `fakeTransaction()` -- the one typed double of a typeorm `EntityManager`.
+ *
+ * `mockEntityManager(stubs)` takes the answers a spec describes as `{ method: [Entity, result] }` (`query` takes
+ * `[sql, rows]`; several answers of one method are a list of pairs). Every method is a `jest.fn()`, so
+ * `expect(em.save).toHaveBeenCalledWith(...)` works, and a method the subject calls that the spec did NOT stub throws
+ * `mockEntityManager: em.<method>() was called but this spec did not stub it`. The absence of a stub is therefore the
+ * proof that the subject made no such call. A method stubbed for another entity (or another sql text) throws too and names
+ * both. Answers of one method and one entity are handed out in order and the last one repeats. There is no typeorm import
+ * at run time: the types come from `typeorm` (type-only), the runtime is a Proxy.
+ *
+ * `create(Entity, plain)` is pure construction and works without a stub. `transaction` needs `fakeTransaction`.
+ *
+ * `fakeTransaction(em)` makes `em.transaction(work)` (and `em.transaction(isolation, work)`) run `work` with a scoped view
+ * of the same double and record how it ended (`commit` when `work` resolves, `rollback` when it throws and the error is
+ * rethrown) and which writes it made, so a spec can assert that a rolled-back transaction committed nothing.
+ */
+import type { DeleteResult, EntityManager, InsertResult, UpdateResult } from "typeorm";
+import type { MockOf } from "./mock.ts";
+/** A typed double of `EntityManager`: assignable wherever an `EntityManager` is required, every method a jest mock. */
+export type MockEntityManager = MockOf<EntityManager>;
+/** An entity class. */
+export type EntityClass<E extends object = object> = new (...args: never[]) => E;
+type Row<C extends EntityClass> = InstanceType<C>;
+type Write<T> = Partial<Omit<T, "raw">> & {
+    readonly raw?: unknown;
+};
+/** The result type of each entity-taking `EntityManager` method, for the entity class `C`. */
+export interface EntityAnswers<C extends EntityClass> {
+    findOne: Row<C> | null;
+    findOneBy: Row<C> | null;
+    findOneOrFail: Row<C>;
+    findOneByOrFail: Row<C>;
+    find: ReadonlyArray<Row<C>>;
+    findBy: ReadonlyArray<Row<C>>;
+    findAndCount: readonly [ReadonlyArray<Row<C>>, number];
+    findAndCountBy: readonly [ReadonlyArray<Row<C>>, number];
+    count: number;
+    countBy: number;
+    exists: boolean;
+    existsBy: boolean;
+    save: Row<C> | ReadonlyArray<Row<C>>;
+    remove: Row<C> | ReadonlyArray<Row<C>>;
+    softRemove: Row<C> | ReadonlyArray<Row<C>>;
+    recover: Row<C> | ReadonlyArray<Row<C>>;
+    insert: Write<InsertResult>;
+    update: Write<UpdateResult>;
+    upsert: Write<InsertResult>;
+    delete: Write<DeleteResult>;
+    softDelete: Write<UpdateResult>;
+    restore: Write<UpdateResult>;
+    increment: Write<UpdateResult>;
+    decrement: Write<UpdateResult>;
+}
+/** The methods a spec may stub as `[Entity, result]`. */
+export type EntityMethod = keyof EntityAnswers<EntityClass>;
+type Pair<M extends EntityMethod, C extends EntityClass> = readonly [entity: C, result: EntityAnswers<C>[M]];
+type Untyped = readonly [unknown, unknown];
+/** One stub: `[Entity, result]` (`query`: `[sql, rows]`), or a list of such pairs answered in order. */
+export type StubOf<M extends string, V> = M extends "query" ? readonly [sql: string, rows: unknown] | ReadonlyArray<readonly [sql: string, rows: unknown]> : M extends EntityMethod ? V extends readonly [infer C extends EntityClass, unknown] ? Pair<M, C> : V extends ReadonlyArray<readonly [infer C extends EntityClass, unknown]> ? ReadonlyArray<Pair<M, C>> : never : never;
+/** The stubs of a spec, checked entry by entry against the entity each one names. */
+export type StubsOf<S> = {
+    readonly [M in keyof S & string]: StubOf<M, S[M]>;
+};
+/**
+ * A strict `EntityManager` double. Describe what the subject should see, `{ findOne: [OrderEntity, order] }`; any method
+ * the subject calls that the spec did not stub throws an error naming the method, and a wrong entity or sql text throws
+ * too. Results are typed against the entity: `findOne: [OrderEntity, 5]` is a compile error.
+ */
+export type MockEntityManagerFactory = <const S extends {
+    readonly [M in string]?: Untyped | ReadonlyArray<Untyped>;
+} = Record<never, never>>(stubs?: S & StubsOf<S>) => MockEntityManager;
+/** A write made inside a transaction. */
+export interface TransactionWrite {
+    readonly method: string;
+    readonly args: ReadonlyArray<unknown>;
+}
+/** The transaction attached to a double by `fakeTransaction`. */
+export interface FakeTransaction<M extends MockEntityManager = MockEntityManager> {
+    /** The double whose `transaction(work)` runs `work`. */
+    readonly em: M;
+    /** How each transaction ended, in call order. */
+    readonly outcomes: ReadonlyArray<"commit" | "rollback" | "pending">;
+    /** Number of transactions that committed. */
+    readonly commits: number;
+    /** Number of transactions that rolled back (the callback threw; the error was rethrown). */
+    readonly rollbacks: number;
+    /** The writes of the transactions that committed. */
+    readonly committedWrites: ReadonlyArray<TransactionWrite>;
+    /** The writes of the transactions that rolled back: what a real rollback would have discarded. */
+    readonly rolledBackWrites: ReadonlyArray<TransactionWrite>;
+}
+/** Makes `em.transaction(work)` run `work` with a scoped view whose queryRunner stays active until commit or rollback. */
+export type FakeTransactionFactory = <M extends MockEntityManager = MockEntityManager>(em?: M) => FakeTransaction<M>;
+/**
+ * The kit over a function factory (`makeFn(implementation)`); `mockEntityManager` and `fakeTransaction` below bind it to
+ * `jest.fn`. The seam lets the package spec run the kit without a jest runtime.
+ */
+export declare function createEntityManagerKit(makeFn: (implementation?: (...args: never[]) => unknown) => unknown): {
+    mockEntityManager: MockEntityManagerFactory;
+    fakeTransaction: FakeTransactionFactory;
+};
+/** Whether `manager` is the scoped view a `fakeTransaction` body received (used by `recordingEventBus` and `recordingQueueOutbox`). */
+export declare const isTransactionManager: (manager: unknown) => boolean;
+/**
+ * A strict `EntityManager` double. Describe what the subject should see, `{ findOne: [OrderEntity, order] }`; any method
+ * the subject calls that the spec did not stub throws an error naming the method, and a wrong entity or sql text throws
+ * too. Results are typed against the entity: `findOne: [OrderEntity, 5]` is a compile error.
+ */
+export declare const mockEntityManager: MockEntityManagerFactory;
+/** Makes `em.transaction(work)` run `work` with a scoped view whose queryRunner stays active until commit or rollback. */
+export declare const fakeTransaction: FakeTransactionFactory;
+export {};

package/dist/entity-manager.js

@@ -0,0 +1,138 @@
+"use strict";
+/// <reference types="jest" preserve="true" />
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fakeTransaction = exports.mockEntityManager = exports.isTransactionManager = void 0;
+exports.createEntityManagerKit = createEntityManagerKit;
+const mock_ts_1 = require("./mock.js");
+/** The manager views handed to a transaction body; `recordingEventBus` and `recordingQueueOutbox` ask whether a manager is one of them. */
+const TRANSACTION_MANAGERS = new WeakSet();
+/** Methods that change data; a write made inside a transaction is recorded on it. */
+const WRITE_METHODS = new Set([
+    "save", "insert", "update", "delete", "remove", "softRemove", "softDelete", "recover", "restore", "upsert",
+    "increment", "decrement", "clear",
+]);
+const WRITE_SQL = /^\s*(insert|update|delete|upsert|merge|truncate)\b/i;
+const describeTarget = (target) => typeof target === "function" ? target.name || "<anonymous class>" : JSON.stringify(String(target)).slice(0, 80);
+const isPair = (value) => Array.isArray(value) && value.length === 2 && (typeof value[0] === "function" || typeof value[0] === "string");
+/** `{ method: [target, result] | [[target, result], ...] }` as `Map<method, Array<{ target, result, used }>>`. */
+function tableOf(stubs) {
+    const table = new Map();
+    for (const [method, value] of Object.entries(stubs)) {
+        const pairs = isPair(value) ? [value] : value;
+        if (!Array.isArray(pairs) || !pairs.every(isPair)) {
+            throw new Error(`mockEntityManager: the stub of em.${method}() must be [Entity, result] (em.query: [sql, rows]) or a list of such pairs`);
+        }
+        table.set(method, pairs.map(([target, result]) => ({ target, result, used: false })));
+    }
+    return table;
+}
+/**
+ * The kit over a function factory (`makeFn(implementation)`); `mockEntityManager` and `fakeTransaction` below bind it to
+ * `jest.fn`. The seam lets the package spec run the kit without a jest runtime.
+ */
+function createEntityManagerKit(makeFn) {
+    function answerOf(method, entries) {
+        if (entries === undefined) {
+            return () => {
+                throw new Error(`mockEntityManager: em.${method}() was called but this spec did not stub it. Stub it with mockEntityManager({ ${method}: [Entity, result] }); an unstubbed call means the subject reached the database where the spec says it must not.`);
+            };
+        }
+        return async (...args) => {
+            const matches = entries.filter((entry) => entry.target === args[0]);
+            const last = matches[matches.length - 1];
+            if (last === undefined) {
+                throw new Error(`mockEntityManager: em.${method}(${describeTarget(args[0])}) was called but this spec stubbed em.${method} only for ${entries.map((entry) => describeTarget(entry.target)).join(", ")}`);
+            }
+            const entry = matches.find((candidate) => !candidate.used) ?? last;
+            entry.used = true;
+            return entry.result;
+        };
+    }
+    function mockEntityManager(stubs = {}) {
+        const table = tableOf(stubs);
+        const create = makeFn((target, plain) => Object.assign(new target(), plain));
+        return (0, mock_ts_1.createMock)((method) => makeFn(answerOf(method, table.get(method))))({ create });
+    }
+    function fakeTransaction(em = mockEntityManager()) {
+        const runs = [];
+        const scopedFor = (run) => {
+            const view = new Proxy(em, {
+                get(target, property, receiver) {
+                    if (property === "queryRunner")
+                        return { get isTransactionActive() { return run.outcome === "pending"; } };
+                    const value = Reflect.get(target, property, receiver);
+                    if (property === "transaction") {
+                        return (...args) => {
+                            const work = args[args.length - 1];
+                            if (typeof work !== "function")
+                                throw new TypeError(`${String(work)} is not a function`);
+                            return work(view);
+                        };
+                    }
+                    if (typeof property !== "string" || typeof value !== "function")
+                        return value;
+                    if (!WRITE_METHODS.has(property) && property !== "query")
+                        return value;
+                    return (...args) => {
+                        if (property !== "query" || WRITE_SQL.test(String(args[0])))
+                            run.writes.push({ method: property, args });
+                        return value(...args);
+                    };
+                },
+            });
+            TRANSACTION_MANAGERS.add(view);
+            return view;
+        };
+        Reflect.set(em, "transaction", makeFn(async (...args) => {
+            const work = args[args.length - 1];
+            if (typeof work !== "function")
+                throw new Error("fakeTransaction: em.transaction() needs a callback as its last argument");
+            const run = { outcome: "pending", writes: [] };
+            runs.push(run);
+            try {
+                const result = await work(scopedFor(run));
+                run.outcome = "commit";
+                return result;
+            }
+            catch (error) {
+                run.outcome = "rollback";
+                throw error;
+            }
+        }));
+        const writesOf = (outcome) => runs.filter((run) => run.outcome === outcome).flatMap((run) => run.writes);
+        return {
+            em,
+            /** How each transaction ended, in call order: "commit" or "rollback". */
+            get outcomes() {
+                return runs.map((run) => run.outcome);
+            },
+            get commits() {
+                return runs.filter((run) => run.outcome === "commit").length;
+            },
+            get rollbacks() {
+                return runs.filter((run) => run.outcome === "rollback").length;
+            },
+            /** The writes (`{ method, args }`) that ended in a commit, in call order. */
+            get committedWrites() {
+                return writesOf("commit");
+            },
+            /** The writes that a rollback discarded: made by a body that then threw. */
+            get rolledBackWrites() {
+                return writesOf("rollback");
+            },
+        };
+    }
+    return { mockEntityManager, fakeTransaction };
+}
+/** Whether `manager` is the scoped view a `fakeTransaction` body received (used by `recordingEventBus` and `recordingQueueOutbox`). */
+const isTransactionManager = (manager) => typeof manager === "object" && manager !== null && TRANSACTION_MANAGERS.has(manager);
+exports.isTransactionManager = isTransactionManager;
+const kit = createEntityManagerKit(mock_ts_1.jestFn);
+/**
+ * A strict `EntityManager` double. Describe what the subject should see, `{ findOne: [OrderEntity, order] }`; any method
+ * the subject calls that the spec did not stub throws an error naming the method, and a wrong entity or sql text throws
+ * too. Results are typed against the entity: `findOne: [OrderEntity, 5]` is a compile error.
+ */
+exports.mockEntityManager = kit.mockEntityManager;
+/** Makes `em.transaction(work)` run `work` with a scoped view whose queryRunner stays active until commit or rollback. */
+exports.fakeTransaction = kit.fakeTransaction;

package/dist/event-bus.d.ts

@@ -0,0 +1,52 @@
+/** An event as the bus port takes it: a class instance with a stable id; its name is the static `eventName` of its class. */
+export interface RecordedEvent {
+    readonly eventId: string;
+}
+/** The static side of an event class. */
+export interface RecordedEventClass {
+    readonly eventName: string;
+}
+/** One recorded publication. */
+export interface EventWrite<E extends RecordedEvent = RecordedEvent> {
+    readonly event: E;
+    readonly tx: unknown;
+    /** Whether `tx` was the view a `fakeTransaction` body received. */
+    readonly inTransaction: boolean;
+}
+/** A dead letter as the bus port returns it. */
+export interface RecordedDeadLetter {
+    readonly id: string;
+    readonly eventName: string;
+    readonly eventId: string;
+    readonly reason: string;
+    readonly attempts: number;
+}
+/** The bus operations `failNext` can make reject. */
+export type EventBusOperation = "publish" | "pendingRetries" | "deadLetters" | "requeue";
+/** An `EventBus` double that records publications and scripts the read side. */
+export interface RecordingEventBus<E extends RecordedEvent = RecordedEvent> {
+    publish(event: E, tx: unknown): Promise<void>;
+    pendingRetries(eventClass: RecordedEventClass): Promise<number>;
+    deadLetters(eventClass: RecordedEventClass): Promise<ReadonlyArray<RecordedDeadLetter>>;
+    requeue(id: string): Promise<void>;
+    /** What the outbox would hold: the first publication of each (event name, event id). */
+    readonly events: ReadonlyArray<E>;
+    /** Every publication with its manager, duplicates included. */
+    readonly entries: ReadonlyArray<EventWrite<E>>;
+    /** Every event published, duplicates included. */
+    readonly writes: ReadonlyArray<E>;
+    /** True when something was published and every publication went through a `fakeTransaction` manager. */
+    readonly allInTransaction: boolean;
+    eventsOf(eventClass: RecordedEventClass): ReadonlyArray<E>;
+    /** Sets the answer of `pendingRetries`. */
+    setPendingRetries(count: number): void;
+    /** Adds dead letters `deadLetters` hands out. */
+    queueDeadLetters(...items: ReadonlyArray<RecordedDeadLetter>): void;
+    /** The ids passed to `requeue`. */
+    readonly requeued: ReadonlyArray<string>;
+    /** Makes the next call of `operation` reject with `error`, once. */
+    failNext(operation: EventBusOperation, error: Error): void;
+    clear(): void;
+}
+/** The event bus double. */
+export declare function recordingEventBus<E extends RecordedEvent = RecordedEvent>(): RecordingEventBus<E>;

package/dist/event-bus.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordingEventBus = recordingEventBus;
+/**
+ * `recordingEventBus()` -- an `EventBus` double that records what a domain service publishes, so a spec asserts on `bus.events`.
+ *
+ * `publish(event, tx)` records the event with the manager it was written through. `events` is what the outbox would hold: one
+ * event per (event name, event id), like the real unique key, so a duplicate publication keeps one. `writes` is every call, duplicates
+ * included, and `entries` adds `inTransaction`: whether `tx` was the view a `fakeTransaction` body received, so a spec proves an event
+ * is published in the transaction of the change that caused it. The name of an event is the static `eventName` of its class.
+ *
+ * The read side is scripted: `setPendingRetries(count)` sets what `pendingRetries(eventClass)` answers, `deadLetters(eventClass)`
+ * returns what `queueDeadLetters(...letters)` filled, `requeue(id)` records the id, and `failNext(operation, error)` makes the next
+ * call of that operation reject once, so a spec drives the failure path.
+ */
+const entity_manager_ts_1 = require("./entity-manager.js");
+/** The name of an event: the static `eventName` of its class. */
+const nameOf = (event) => {
+    const eventClass = event.constructor;
+    return typeof eventClass === "function" && "eventName" in eventClass ? eventClass.eventName : undefined;
+};
+/** The event bus double. */
+function recordingEventBus() {
+    const written = [];
+    const letters = [];
+    const requeued = [];
+    const failures = new Map();
+    let pending = 0;
+    const failIfScripted = (operation) => {
+        const error = failures.get(operation);
+        if (error === undefined)
+            return;
+        failures.delete(operation);
+        throw error;
+    };
+    return {
+        async publish(event, tx) {
+            failIfScripted("publish");
+            written.push({ event, tx, inTransaction: (0, entity_manager_ts_1.isTransactionManager)(tx) });
+        },
+        async pendingRetries() {
+            failIfScripted("pendingRetries");
+            return pending;
+        },
+        async deadLetters(eventClass) {
+            failIfScripted("deadLetters");
+            return letters.filter((letter) => letter.eventName === eventClass.eventName);
+        },
+        async requeue(id) {
+            failIfScripted("requeue");
+            requeued.push(id);
+        },
+        /** The events the outbox would hold: the first publication of each (event name, event id). */
+        get events() {
+            const seen = new Set();
+            return written
+                .filter(({ event }) => {
+                const key = `${String(nameOf(event))}\u0000${event.eventId}`;
+                if (seen.has(key))
+                    return false;
+                seen.add(key);
+                return true;
+            })
+                .map(({ event }) => event);
+        },
+        /** Every publication, in order: `{ event, tx, inTransaction }`. */
+        get entries() {
+            return [...written];
+        },
+        /** Every event published, duplicates included. */
+        get writes() {
+            return written.map(({ event }) => event);
+        },
+        /** True when something was published and every publication went through a transaction manager. */
+        get allInTransaction() {
+            return written.length > 0 && written.every((entry) => entry.inTransaction);
+        },
+        /** The stored events of one class. */
+        eventsOf(eventClass) {
+            return this.events.filter((event) => nameOf(event) === eventClass.eventName);
+        },
+        /** Sets the answer of `pendingRetries`. */
+        setPendingRetries(count) {
+            pending = count;
+        },
+        /** Adds dead letters `deadLetters` hands out. */
+        queueDeadLetters(...items) {
+            letters.push(...items);
+        },
+        /** The ids passed to `requeue`, in order. */
+        get requeued() {
+            return [...requeued];
+        },
+        /** Makes the next call of `operation` reject with `error`, once. */
+        failNext(operation, error) {
+            failures.set(operation, error);
+        },
+        clear() {
+            written.length = 0;
+            letters.length = 0;
+            requeued.length = 0;
+            pending = 0;
+            failures.clear();
+        },
+    };
+}