@starci/jest-preset 1.1.0 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 2.1.0 - 2026-09-30
+
+- Added: the claim side of `recordingOutbox()`, so a claim-side consumer is specced with the kit double the `OUTBOX` token requires (`spec-infra-double-from-kit`) instead of `mock<Outbox>()`. `queueRecords(...records)` fills a backlog that `claimDue(params)` hands out in order (only the asked queues, at most `limit`, removed once claimed; an empty backlog is an empty claim, a record queued twice is a duplicate delivery), `failNext(operation, error)` makes the next `enqueue`, `claimDue`, `complete`, `retry` or `bury` reject once, and `claims`, `completed`, `retried`, `buried` and `backlog` expose what happened. `RecordingOutbox<M, R>` takes the claimed record type as a second parameter; `ClaimedRecord`, `ClaimParams`, `RetryParams`, `BuryParams` and `OutboxOperation` are exported from `./outbox`. `clear()` resets the claim side too. No breaking change.
+
+## 2.0.0 - 2026-09-30
+
+- Breaking: `starciJestConfig()` takes no options. The repository `jest.config.js` is a managed file, exactly `module.exports = require("@starci/jest-preset").starciJestConfig()`, rendered by `hfs sync` and compared by `hfs check` (HFS_MANAGED_FILE_DRIFT), so `moduleNameMapper`, `roots`, `tsconfig`, `rootDir`, `unit` and `e2e` overrides are gone. `StarciJestOptions` is removed.
+- Added: the three path aliases (`@features/*`, `@modules/*`, `@tests/*`) are part of the preset (`MODULE_NAME_MAPPER`), matching the aliases the managed `tsconfig.json` declares.
+- Added: `coverageProvider: "v8"`, so branch coverage counts real source, not the helpers TypeScript emits.
+- Breaking: four projects, one per test kind (owner test layout 2026-09-30): `unit` (colocated `*.spec.ts`, ignores `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`, run one worker and share the test world's `globalSetup`/`globalTeardown` (`src/tests/world/global-setup.ts`, `global-teardown.ts`); there is no `setupFilesAfterEnv`. `src/tests/e2e/live/`, `E2E_LIVE` and `test:e2e:live` are gone: a provider sandbox is a contract spec. `typecheck:e2e` is replaced by `typecheck:tests`.
+- Unchanged: ts-jest with `diagnostics: false` (`isolatedModules` comes from `@starci/tsconfig`), `mock<T>()` and `FakeClock`.
+- Added (unit test standard, lane UT): the shared unit double kit on the package root, `mockEntityManager({ method: [Entity, result] })` (typed against the entity, `query: [sql, rows]`, a list of pairs for several answers, every method a `jest.fn`, any unstubbed method throws an error naming it, `create(Entity, plain)` works unstubbed), `fakeTransaction(em)` (`outcomes`, `commits`, `rollbacks`, `committedWrites`, `rolledBackWrites`), `fakeCache(clock)` (JSON round trip, TTL from the clock, `has`, `ttlOf`, `keys`, typed-key and cache-manager shapes), `fakeLock(clock)` (`acquire`, `release`, `isHeld`, `holderOf`, `fenceOf`), `recordingOutbox()` (`enqueue`, `messages`, `writes`, `entries` with `inTransaction`), `builder<T>(defaults)`, `fakeIds()` and the Outcome matchers `toBeRefused` and `toSucceedWith` (installed in the unit project through `setupFilesAfterEnv`). Sub-path exports `./cache`, `./lock`, `./outbox`, `./builders`, `./entity-manager`, `./ids` and `./matchers` were added next to `./mock` and `./clock`.
+- Breaking: coverage is collected from `src/**/*.service.ts` only (minus `src/tests/**`, `dist`, `coverage`), with a per-file threshold of 100 on lines, branches, functions and statements (`coverageThreshold` glob key `./src/**/*.service.ts`); the managed `test` script runs the unit project with `--coverage`. The previous denominator (`src/**/*.ts` and `apps/**/*.ts`) is gone. The unit project overlays `isolatedModules: false` and `importHelpers: true` on the repository tsconfig (exported as `UNIT_COMPILER_OPTIONS`) so a decorated service can reach 100 (no `design:paramtypes` guard branches, no inlined decorator helpers); repositories list `tslib` in devDependencies.
+- Breaking: `sonarCoverageExclusions()` is removed and coverage reporters are `text-summary` and `text` only (no `lcov`): Sonar does not depend on coverage and Codecov is not fed by the preset. `sonarExclusions()` remains and renders `sonar.exclusions`.
+- Breaking (convention): a unit spec exists only as `<name>.service.spec.ts` beside a `*.service.ts` and builds the service with `Test.createTestingModule({ providers })`; `mockEntityManager()` and `fakeTransaction()` from `src/tests/fixtures/database.ts` are replaced by the kit of this package.

package/README.md

@@ -1,31 +1,144 @@
 # @starci/jest-preset
 
-The jest config of a Nest repository, and the typed `mock<T>()` helper. Install it from the npm registry at the exact version in [`knowledge/hfs/canon-pins.yaml`](../../knowledge/hfs/canon-pins.yaml) (see [`packages/README.md`](../README.md)).
+The jest config of a Nest repository and the one shared unit-test double kit (`mock<T>()`, `mockEntityManager`, `fakeTransaction`, `fakeCache`, `fakeLock`, `recordingOutbox`, `builder`, `FakeClock`, `fakeIds` and the Outcome matchers). Install it from the npm registry at the exact version in [`knowledge/hfs/canon-pins.yaml`](../../knowledge/hfs/canon-pins.yaml) (see [`packages/README.md`](../README.md)).
 
 ```js
-// jest.config.js
-const { pathsToModuleNameMapper } = require("ts-jest")
-const { starciJestConfig } = require("@starci/jest-preset")
-const { compilerOptions } = require("./tsconfig.json")
-
-module.exports = starciJestConfig({
-    moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths, { prefix: `${__dirname}/` }),
-    e2e: { globalSetup: "<rootDir>/src/tests/e2e/setup/global-setup.js" },
-})
+// jest.config.js (a managed file: `hfs sync` renders it, `hfs check` compares it; do not edit)
+module.exports = require("@starci/jest-preset").starciJestConfig()
 ```
 
+`starciJestConfig()` takes no options: a repository has no jest setting to tune, so the file above is the whole config.
+
 ## What it sets
 
-- **Two projects**: `unit` (`**/*.spec.ts`, mocked, `clearMocks`) and `e2e` (`src/tests/e2e/**/*.e2e-spec.ts`, one worker, 120 s).
-  `src/tests/e2e/live/` is skipped unless `E2E_LIVE=1`; `test:e2e:live` is `E2E_LIVE=1 jest --selectProjects e2e src/tests/e2e/live`.
-- **ts-jest with `diagnostics: false`** in both. `isolatedModules: true` comes from `@starci/tsconfig` (ts-jest 29.4 reads it
-  there; its own option is deprecated). Types are checked once, by `typecheck` (unit specs included) and `typecheck:e2e`, and
-  `test:e2e` is `npm run typecheck:e2e && jest --selectProjects e2e`, so nobody runs e2e on code that does not type-check.
-- **Coverage that matches Sonar.** `collectCoverageFrom` is `src/**/*.ts` and `apps/**/*.ts` minus specs, e2e specs, `dist`,
-  `coverage`, `src/tests/**`, `*.d.ts` and `main.ts`: the same set Sonar counts. `sonarExclusions()` and
-  `sonarCoverageExclusions()` render the two `sonar-project.properties` values from the same lists, so the denominators
-  cannot drift. Reports are `coverage/lcov.info` (Codecov and Sonar read the one file) and a text summary. Thresholds are not
-  set here; Codecov's project and patch targets own the gate.
+- **Four projects, one per test kind**: `unit` (`**/*.spec.ts`, which by the unit standard means one `<name>.service.spec.ts` beside each `*.service.ts`; `clearMocks`; the Outcome matchers are installed through `setupFilesAfterEnv`; ignores
+  `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`, run one worker, and start the one test world through `globalSetup`/`globalTeardown`
+  (`src/tests/world/global-setup.ts`, `global-teardown.ts`); only the unit project has a `setupFilesAfterEnv`. The managed scripts select one
+  project each: `test`, `test:integration`, `test:e2e`, `test:contract`; a contract spec skips itself without sandbox config.
+- **The three path aliases** `@features/*`, `@modules/*`, `@tests/*` (`MODULE_NAME_MAPPER`), the same ones the managed `tsconfig.json` declares.
+- **ts-jest with `diagnostics: false`** in every project. `isolatedModules: true` comes from `@starci/tsconfig` (ts-jest 29.4 reads it
+  there; its own option is deprecated). Types are checked once, by `typecheck` (unit specs included) and `typecheck:tests`
+  (`src/tests/tsconfig.json`), and `test:integration`/`test:e2e`/`test:contract` run `typecheck:tests` first, so no world spec
+  runs on code that does not type-check.
+- **Coverage of services only, per-file 100.** `collectCoverageFrom` is `src/**/*.service.ts` minus `src/tests/**`, `dist` and
+  `coverage`, and `coverageThreshold` is `{ "./src/**/*.service.ts": { lines: 100, branches: 100, functions: 100, statements: 100 } }`,
+  a glob key that applies to each file on its own, so every service 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: false` and `importHelpers: true` on the repository tsconfig (ts-jest merges an
+  inline `tsconfig` object over the `tsconfig.json` it finds): with `isolatedModules` on, TypeScript emits an unreachable
+  `typeof Dep !== "undefined" ? Dep : Object` guard per class-typed constructor parameter, and inlined decorator helpers carry branches
+  of their own, so 100 would be unreachable. The repository lists `tslib` in its devDependencies (`UNIT_COMPILER_OPTIONS`). Reporters are `text-summary` and
+  `text`; there is no `lcov`.
+- **Sonar does not read coverage.** `sonarCoverageExclusions()` and the lcov report are removed. `sonarExclusions()` still renders
+  `sonar.exclusions` (`**/*.spec.ts,**/*.e2e-spec.ts,**/dist/**,**/coverage/**`); the quality gate fails on imported issues only.
+
+## The unit standard in one page
+
+Only services are unit-tested, through `Test.createTestingModule`, with the doubles of this package and nothing else:
+
+```ts
+import { Test } from "@nestjs/testing"
+import { FakeClock, mockEntityManager } from "@starci/jest-preset"
+
+const clock = new FakeClock("2026-01-01T00:00:00.000Z")
+const entityManager = mockEntityManager({ findOne: [Accrual, null] })
+const moduleRef = await Test.createTestingModule({
+  providers: [
+    CommissionService,
+    { provide: PRIMARY_ENTITY_MANAGER, useValue: entityManager },   // exactly the constructor dependencies
+    { provide: CLOCK, useValue: clock },
+  ],
+}).compile()
+const service = moduleRef.get(CommissionService)
+```
+
+No `new` of the service, no `imports`, no `overrideProvider`, no `jest.mock`, no casts, no `Date.now()` and no `process.env`. The
+full rules and the dependency-to-double-to-cases table are `knowledge/patterns/be/test.yaml` (BE-TEST-1 to BE-TEST-15). Every
+export below is on the package root (`@starci/jest-preset`); the sub-paths `./mock`, `./clock`, `./entity-manager`, `./ids`,
+`./matchers`, `./cache`, `./lock`, `./outbox` and `./builders` exist as well.
+
+## `mockEntityManager` and `fakeTransaction`
+
+A strict, typed `EntityManager` double. Describe what the subject should see; every method is a `jest.fn`, and any method the
+subject calls that the spec did not stub throws an error naming the method, so the absence of a stub proves the absence of that
+database call. A wrong entity or SQL text throws too. `create(Entity, plain)` works without a stub.
+
+```ts
+import { mockEntityManager, fakeTransaction } from "@starci/jest-preset"
+
+// [Entity, result], typed against the entity: `findOne: [Order, 5]` is a compile error
+const em = mockEntityManager({ findOne: [Order, order], save: [Order, saved] })
+expect(em.save).toHaveBeenCalledWith(expect.objectContaining({ status: "paid" }))
+
+// a raw query: [sql, rows]
+const reader = mockEntityManager({ query: ["select 1", [{ n: 1 }]] })
+
+// lists: a list of pairs answers several calls in order
+const two = mockEntityManager({ find: [[Order, [orderA]], [Order, [orderB]]] })
+
+// a transaction: work runs with a scoped view; commits, rollbacks and writes are recorded
+const tx = fakeTransaction(mockEntityManager({ save: [Order, saved] }))
+await service.place(params)                       // service calls em.transaction(async (manager) => ...)
+expect(tx.commits).toBe(1)
+expect(tx.committedWrites).toHaveLength(1)        // after a throwing body: tx.rollbacks, tx.rolledBackWrites, tx.outcomes
+```
+
+The stubbable methods are `findOne`, `findOneBy`, `findOneOrFail`, `findOneByOrFail`, `find`, `findBy`, `findAndCount`,
+`findAndCountBy`, `count`, `countBy`, `exists`, `existsBy`, `save`, `remove`, `softRemove`, `recover`, `insert`, `update`, `upsert`,
+`delete`, `softDelete`, `restore`, `increment`, `decrement` and `query`. `fakeTransaction(em)` returns `{ em, outcomes, commits,
+rollbacks, committedWrites, rolledBackWrites }`.
+
+## `fakeCache(clock)`, `fakeLock(clock)` and `recordingOutbox()`
+
+```ts
+const clock = new FakeClock("2026-01-01T00:00:00.000Z")
+
+const cache = fakeCache(clock)     // JSON round trip; TTL from the clock
+await cache.set({ key, args: ["u1"], value: profile })   // the typed-key port: get/set/del({ key, args, value })
+await cache.get({ key, args: ["u1"] })
+await cache.set("raw-key", value, 60_000)                // the cache-manager shape: get(text), set(text, value, ttlMs)
+cache.has({ key, args: ["u1"] })                          // a live entry exists
+cache.ttlOf({ key, args: ["u1"] })                        // seconds left (rounded up), null when absent or expired
+cache.keys()                                              // the texts of the live entries
+clock.advance(301_000)                                    // entries with a 300 s TTL are now expired
+
+const lock = fakeLock(clock)       // acquire, contention, release, expiry, growing fence
+const grant = await lock.acquire({ name: "writer", holder: "a", ttlMs: 30_000 })   // null when held by another
+lock.isHeld("writer"); lock.holderOf("writer"); lock.fenceOf("writer")
+await lock.release({ grant })
+
+const outbox = recordingOutbox()   // enqueue(manager, message)
+outbox.messages     // what the store would hold: the first write of each (queue, eventId)
+outbox.writes       // every message written, duplicates included
+outbox.entries      // every write with its manager and `inTransaction`
+outbox.allInTransaction; outbox.messagesOf("queue"); outbox.clear()
+
+// the claim side: script what a worker's claim returns
+outbox.queueRecords(record)                 // the backlog claimDue hands out, in order, filtered by queue and cut at limit
+outbox.queueRecords(record, record)         // a duplicate delivery
+await outbox.claimDue(params)               // [] when the backlog is empty
+outbox.failNext("complete", new Error("db down"))   // the next call of that operation rejects once
+outbox.claims; outbox.completed; outbox.retried; outbox.buried; outbox.backlog
+```
+
+## `builder`, `fakeIds` and the Outcome matchers
+
+```ts
+import { builder, fakeIds } from "@starci/jest-preset"
+
+const options = builder<CommissionOptions>({ bps: 3000, enabled: true })   // a function returning the defaults with overrides applied
+const disabled = options({ enabled: false })
+const ids = fakeIds()             // ids.next() === "00000000-0000-4000-8000-000000000001", then ...0002; ids.issued, ids.reset()
+
+expect(outcome).toBeRefused("COMMISSION_SELF_REFERRAL")                     // { kind: "refused" } with this code
+expect(outcome).toBeRefused({ code: "PLAN_LIMIT", params: { max: 3 } })    // and these params
+expect(outcome).toSucceedWith(accrual)                                      // { kind: "ok" } whose value equals `accrual`
+```
+
+The matchers are installed in the unit project only (`setupFilesAfterEnv`); their types are declared globally by importing the
+package.
 
 ## `mock<T>()`
 

package/builders.cjs

@@ -0,0 +1,15 @@
+"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
+ * 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
+ */
+function builder(defaults) {
+  return (overrides) => ({ ...defaults, ...overrides })
+}
+
+module.exports = { builder }

package/builders.d.ts

@@ -0,0 +1,2 @@
+/** 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/cache.cjs

@@ -0,0 +1,67 @@
+"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.
+ */
+
+const textOf = (request) => (typeof request === "string" ? request : [request.key.name, ...(request.args ?? [])].join(":"))
+
+/** @param {{ now(): Date }} clock */
+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
+  }
+
+  return {
+    async 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 set(request, value, ttlMs) {
+      const text = textOf(request)
+      const typed = typeof request !== "string"
+      const stored = typed ? request.value : value
+      const lifetimeMs = typed ? request.key.ttl.seconds * 1000 : ttlMs
+      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 })
+    },
+    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(),
+  }
+}
+
+module.exports = { fakeCache }

package/cache.d.ts

@@ -0,0 +1,31 @@
+/** 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/entity-manager.cjs

@@ -0,0 +1,145 @@
+"use strict"
+
+/**
+ * `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
+ * here: the types come from `entity-manager.d.ts` (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.
+ */
+const { createMock, jestFn } = require("./mock.cjs")
+
+/** The manager views handed to a transaction body; `recordingOutbox` asks 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])
+      if (matches.length === 0) {
+        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) ?? matches[matches.length - 1]
+      entry.used = true
+      return entry.result
+    }
+  }
+
+  /** @param {Record<string, unknown>} [stubs] */
+  function mockEntityManager(stubs = {}) {
+    const table = tableOf(stubs)
+    const create = makeFn((target, plain) => Object.assign(new target(), plain))
+    return createMock((method) => makeFn(answerOf(method, table.get(method))))({ create })
+  }
+
+  /** @param {object} [em] - The double to attach the transaction to; a fresh `mockEntityManager()` by default. */
+  function fakeTransaction(em = mockEntityManager()) {
+    const runs = []
+    const scopedFor = (run) => {
+      const view = new Proxy(em, {
+        get(target, property, receiver) {
+          const value = Reflect.get(target, property, receiver)
+          if (property === "transaction") return (...args) => args[args.length - 1](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
+    }
+    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. */
+const isTransactionManager = (manager) => typeof manager === "object" && manager !== null && TRANSACTION_MANAGERS.has(manager)
+
+module.exports = { ...createEntityManagerKit(jestFn), createEntityManagerKit, isTransactionManager }

package/entity-manager.d.ts

@@ -0,0 +1,103 @@
+/// <reference types="jest" />
+import type { DeleteResult, EntityManager, InsertResult, UpdateResult } from "typeorm"
+import type { MockOf } from "./mock"
+
+/** 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 declare function mockEntityManager<
+  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 of the double and record commit, rollback and writes. */
+export declare function fakeTransaction<M extends MockEntityManager = MockEntityManager>(em?: M): FakeTransaction<M>
+
+/** Whether `manager` is the view a `fakeTransaction` body received (used by `recordingOutbox`). */
+export declare function isTransactionManager(manager: unknown): boolean
+
+/** The kit over a function factory, for callers that bring their own (used by the package spec). */
+export declare function createEntityManagerKit(makeFn: (implementation?: (...args: never[]) => unknown) => unknown): {
+  mockEntityManager: typeof mockEntityManager
+  fakeTransaction: typeof fakeTransaction
+}

package/ids.cjs

@@ -0,0 +1,41 @@
+"use strict"
+
+/**
+ * `fakeIds()` -- the test double for the platform ids port (`{ next(): string }`; the production adapter is
+ * `randomUUID()` behind the port). Ids are deterministic and UUID-shaped, so a spec can assert on the exact persisted id:
+ * the first is `00000000-0000-4000-8000-000000000001`, the second `...0002`, and so on. A `prefix` (1 to 8 hex digits)
+ * changes the leading group so two generators in one spec never collide.
+ */
+class FakeIds {
+  /** @param {string} [prefix] - 1 to 8 hex digits for the first group; default "00000000". */
+  constructor(prefix = "00000000") {
+    if (!/^[0-9a-f]{1,8}$/i.test(prefix)) throw new Error("fakeIds: the prefix is 1 to 8 hex digits")
+    this._prefix = prefix.padStart(8, "0").toLowerCase()
+    this._issued = []
+  }
+
+  /** The next id. */
+  next() {
+    const n = String(this._issued.length + 1).padStart(12, "0")
+    const id = `${this._prefix}-0000-4000-8000-${n}`
+    this._issued.push(id)
+    return id
+  }
+
+  /** Every id handed out so far, in order. */
+  get issued() {
+    return [...this._issued]
+  }
+
+  /** Starts the sequence over. */
+  reset() {
+    this._issued = []
+  }
+}
+
+/** @param {string} [prefix] */
+function fakeIds(prefix) {
+  return new FakeIds(prefix)
+}
+
+module.exports = { fakeIds, FakeIds }

package/ids.d.ts

@@ -0,0 +1,13 @@
+/** The platform ids port a spec injects `fakeIds()` for: `{ next(): string }`. */
+export declare class FakeIds {
+  constructor(prefix?: string)
+  /** The next deterministic UUID-shaped id. */
+  next(): string
+  /** Every id handed out so far, in order. */
+  readonly issued: ReadonlyArray<string>
+  /** Starts the sequence over. */
+  reset(): void
+}
+
+/** A deterministic id generator: `00000000-0000-4000-8000-000000000001`, `...0002`, ... */
+export declare function fakeIds(prefix?: string): FakeIds