@starci/jest-preset 1.1.0 → 2.1.0

package/index.cjs

@@ -1,29 +1,31 @@
 "use strict"
 
 const { mock, createMock } = require("./mock.cjs")
+const { mockEntityManager, fakeTransaction } = require("./entity-manager.cjs")
+const { FakeClock } = require("./clock.cjs")
+const { fakeCache } = require("./cache.cjs")
+const { fakeLock } = require("./lock.cjs")
+const { recordingOutbox } = require("./outbox.cjs")
+const { builder } = require("./builders.cjs")
+const { fakeIds, FakeIds } = require("./ids.cjs")
 
 /**
- * What Sonar counts as production code, expressed once. `sonarCoverageExclusions` renders the same list for
- * `sonar.coverage.exclusions`, so the jest denominator and the Sonar denominator cannot drift.
- *
- * Sonar side (canon sonar-project.properties): sources = src,apps; exclusions = specs, e2e specs, dist, coverage;
- * coverage.exclusions = src/tests/**, e2e specs, entrypoints and declaration files.
+ * Coverage is measured on services only: the one place business logic lives (owner-locked unit standard). Handlers,
+ * resolvers, controllers and consumers are thin, and helpers called by a service are covered through the service's own
+ * spec, so every `*.service.ts` under `src` is the whole denominator and every file in it must reach 100 on every metric.
+ * Sonar does not read coverage at all (the gate fails on imported issues only), so there is no second list to keep in step.
  */
-const COVERAGE_SOURCES = ["src/**/*.ts", "apps/**/*.ts"]
-/** Sonar `sonar.exclusions`: not analysed at all, so neither counted nor covered. */
-const SONAR_EXCLUSIONS = ["**/*.spec.ts", "**/*.e2e-spec.ts", "**/dist/**", "**/coverage/**"]
-/** Sonar `sonar.coverage.exclusions`: analysed, but outside the coverage denominator. */
-const COVERAGE_ONLY_EXCLUSIONS = ["src/tests/**", "**/*.d.ts", "**/main.ts"]
-const COVERAGE_EXCLUDES = [...SONAR_EXCLUSIONS, ...COVERAGE_ONLY_EXCLUSIONS]
+const COVERAGE_SOURCES = ["src/**/*.service.ts"]
+const COVERAGE_EXCLUDES = ["src/tests/**", "**/dist/**", "**/coverage/**"]
+/** The four metrics, each held at 100 per file. */
+const COVERAGE_THRESHOLD = Object.freeze({ lines: 100, branches: 100, functions: 100, statements: 100 })
 
 function collectCoverageFrom() {
   return [...COVERAGE_SOURCES, ...COVERAGE_EXCLUDES.map((glob) => `!${glob}`)]
 }
 
-/** The `sonar.coverage.exclusions` value that matches `collectCoverageFrom`; `sonar.exclusions` is `sonarExclusions()`. */
-function sonarCoverageExclusions() {
-  return COVERAGE_ONLY_EXCLUSIONS.join(",")
-}
+/** Sonar `sonar.exclusions`: specs, e2e specs, dist and coverage output are not analysed at all. */
+const SONAR_EXCLUSIONS = ["**/*.spec.ts", "**/*.e2e-spec.ts", "**/dist/**", "**/coverage/**"]
 
 function sonarExclusions() {
   return SONAR_EXCLUSIONS.join(",")
@@ -33,8 +35,8 @@ const TS_TRANSFORM = String.raw`^.+\.ts$`
 
 /**
  * ts-jest without a type check (`diagnostics: false`; `isolatedModules: true` comes from @starci/tsconfig, which is where
- * ts-jest 29.4 reads it — the ts-jest option of the same name is deprecated): types are checked once, by `typecheck` / `typecheck:e2e`, never per test file.
- * `npm run test:e2e` must be `npm run typecheck:e2e && jest --selectProjects e2e` so nobody runs e2e on code that
+ * ts-jest 29.4 reads it — the ts-jest option of the same name is deprecated): types are checked once, by `typecheck` / `typecheck:tests`, never per test file.
+ * `npm run test:e2e` (and `test:integration`, `test:contract`) runs `npm run typecheck:tests` first so nobody runs a world spec on code that
  * does not type-check.
  */
 function transform(tsconfig) {
@@ -42,59 +44,114 @@ function transform(tsconfig) {
 }
 
 /**
- * The whole jest config of a Nest repository: one `unit` project and one `e2e` project.
+ * The compiler options the UNIT project overlays on the repository tsconfig (ts-jest merges an inline `tsconfig` object over the
+ * `tsconfig.json` it finds under `rootDir`). They exist so that per-file 100 coverage is reachable for a decorated service:
+ *  - `isolatedModules: false`: with it on, TypeScript cannot tell whether an imported name is a class, and emits a
+ *    `typeof (_a = typeof Dep !== "undefined" && Dep) === "function" ? _a : Object` guard per class-typed constructor parameter for
+ *    `design:paramtypes`; the `Object` arm can never run, so the branch stays uncovered. With the full language service the
+ *    metadata is emitted as plain `Dep`.
+ *  - `importHelpers: true`: the decorator helpers (`__decorate`, `__param`, `__metadata`) come from `tslib`, not inlined per file
+ *    with branches of their own. The repository lists `tslib` in its devDependencies.
+ * Integration, e2e and contract keep the repository setting: they measure nothing.
+ */
+const UNIT_COMPILER_OPTIONS = Object.freeze({ isolatedModules: false, importHelpers: true })
+
+function unitTransform() {
+  return transform({ ...UNIT_COMPILER_OPTIONS })
+}
+
+/**
+ * The path aliases of a StarCi back end: the same three `paths` the managed `tsconfig.json` declares, so jest resolves what
+ * `tsc` resolves. They are part of the preset, not an option: a repository has no other alias.
+ */
+const MODULE_NAME_MAPPER = Object.freeze({
+  "^@features/(.*)$": "<rootDir>/src/features/$1",
+  "^@modules/(.*)$": "<rootDir>/src/modules/$1",
+  "^@tests/(.*)$": "<rootDir>/src/tests/$1",
+})
+
+/** The test folders under `src/tests/` that a project other than `unit` owns (owner test layout 2026-09-30). */
+const TEST_KIND_FOLDERS = Object.freeze(["world", "integration", "e2e", "contract"])
+const underTests = (folder) => String.raw`[\\/]src[\\/]tests[\\/]` + folder + String.raw`[\\/]`
+
+/**
+ * The whole jest config of a Nest repository: projects `unit` (colocated `<name>.spec.ts`), `integration`
+ * (`src/tests/integration/<capability>/<name>.integration-spec.ts`), `e2e` (`src/tests/e2e/<area>/<name>.e2e-spec.ts`) and
+ * `contract` (`src/tests/contract/<provider>/<name>.contract-spec.ts`). It takes no options: the repository's `jest.config.js` is a managed file
+ * (R05), rendered by `hfs sync` as `module.exports = require("@starci/jest-preset").starciJestConfig()`.
  *
- * @param {object} options
- * @param {string} [options.tsconfig]            ts-jest tsconfig, default `tsconfig.json`
- * @param {Record<string,string|string[]>} [options.moduleNameMapper]  path aliases for both projects
- * @param {string[]} [options.roots]             default `<rootDir>/src`, `<rootDir>/apps`
- * @param {object} [options.unit]                extra jest project options for unit (setupFiles, ...)
- * @param {object} [options.e2e]                 extra jest project options for e2e (globalSetup, ...)
+ * The managed scripts select one project each (`test` = unit, `test:integration`, `test:e2e`, `test:contract`); the
+ * contract project is never part of `test` or `test:e2e`, and a contract spec skips itself without sandbox config. The
+ * test tree compiles against `src/tests/tsconfig.json`, the nearest config of every file under `src/tests/`. The
+ * integration, e2e and contract projects share the world's `global-setup.ts`/`global-teardown.ts` (`src/tests/world/`) and
+ * run one worker; the unit project alone has a `setupFilesAfterEnv` (the Outcome matchers).
+ * Coverage is collected from every `*.service.ts` only, with a per-file threshold of 100 on lines, branches, functions and
+ * statements: the `test` script runs the unit project with `--coverage` and fails below it. It uses v8: istanbul instruments the helpers TypeScript emits (`__decorate`, `__param`, `__awaiter`, interop wrappers)
+ * as thousands of branches no spec can cover, while v8 measures the real source.
  */
-function starciJestConfig(options = {}) {
-  const tsconfig = options.tsconfig ?? "tsconfig.json"
+function starciJestConfig() {
   const shared = {
     preset: "ts-jest",
     testEnvironment: "node",
-    rootDir: options.rootDir ?? ".",
-    roots: options.roots ?? ["<rootDir>/src", "<rootDir>/apps"],
-    moduleNameMapper: options.moduleNameMapper ?? {},
-    transform: transform(tsconfig),
+    rootDir: ".",
+    roots: ["<rootDir>/src", "<rootDir>/apps"],
+    moduleNameMapper: { ...MODULE_NAME_MAPPER },
   }
-  const live = process.env.E2E_LIVE === "1"
+  const suite = (displayName, suffix) => ({
+    ...shared,
+    transform: transform("src/tests/tsconfig.json"),
+    displayName,
+    maxWorkers: 1,
+    testMatch: [`<rootDir>/src/tests/${displayName}/**/*.${suffix}.ts`],
+    // The one test world: started once per run of a project that has a test to run, torn down after it.
+    globalSetup: "<rootDir>/src/tests/world/global-setup.ts",
+    globalTeardown: "<rootDir>/src/tests/world/global-teardown.ts",
+  })
   return {
     testTimeout: 120_000,
+    coverageProvider: "v8",
     collectCoverageFrom: collectCoverageFrom(),
+    // A glob key is applied to every matching file on its own: each service file must reach 100, not the average.
+    coverageThreshold: { "./src/**/*.service.ts": { ...COVERAGE_THRESHOLD } },
     coverageDirectory: "coverage",
-    coverageReporters: ["lcov", "text-summary"],
+    coverageReporters: ["text-summary", "text"],
     projects: [
       {
         ...shared,
+        transform: unitTransform(),
         displayName: "unit",
         clearMocks: true,
+        // The Outcome matchers (`toBeRefused`, `toSucceedWith`) exist in the unit project only.
+        setupFilesAfterEnv: [require.resolve("./matchers.cjs")],
         testMatch: ["**/*.spec.ts"],
-        testPathIgnorePatterns: ["/node_modules/", "\.e2e-spec\.ts$", "[\\/]src[\\/]tests[\\/]e2e[\\/]"],
-        ...options.unit,
-      },
-      {
-        ...shared,
-        displayName: "e2e",
-        maxWorkers: 1,
-        testMatch: ["<rootDir>/src/tests/e2e/**/*.e2e-spec.ts"],
-        testPathIgnorePatterns: live ? ["/node_modules/"] : ["/node_modules/", "[\\/]src[\\/]tests[\\/]e2e[\\/]live[\\/]"],
-        ...options.e2e,
+        testPathIgnorePatterns: ["/node_modules/", ...TEST_KIND_FOLDERS.map(underTests)],
       },
+      suite("integration", "integration-spec"),
+      suite("e2e", "e2e-spec"),
+      suite("contract", "contract-spec"),
     ],
   }
 }
 
 module.exports = {
   starciJestConfig,
+  TEST_KIND_FOLDERS,
+  MODULE_NAME_MAPPER,
   mock,
   createMock,
+  mockEntityManager,
+  fakeTransaction,
+  FakeClock,
+  fakeCache,
+  fakeLock,
+  recordingOutbox,
+  builder,
+  fakeIds,
+  FakeIds,
   collectCoverageFrom,
-  sonarCoverageExclusions,
   sonarExclusions,
   COVERAGE_SOURCES,
   COVERAGE_EXCLUDES,
+  COVERAGE_THRESHOLD,
+  UNIT_COMPILER_OPTIONS,
 }

package/index.d.ts

@@ -1,19 +1,22 @@
 import type { Config } from "jest"
 
 export { mock, createMock, MockOf } from "./mock"
+export { mockEntityManager, fakeTransaction, MockEntityManager, FakeTransaction, EntityClass } from "./entity-manager"
+export { fakeCache, FakeCache } from "./cache"
+export { fakeLock, FakeLock } from "./lock"
+export { recordingOutbox, RecordingOutbox } from "./outbox"
+export { builder } from "./builders"
+export { FakeClock } from "./clock"
+export { fakeIds, FakeIds } from "./ids"
+export { RefusalReason } from "./matchers"
 
-export interface StarciJestOptions {
-  rootDir?: string
-  tsconfig?: string
-  moduleNameMapper?: Record<string, string | string[]>
-  roots?: string[]
-  unit?: Record<string, unknown>
-  e2e?: Record<string, unknown>
-}
-
-export declare function starciJestConfig(options?: StarciJestOptions): Config
+/** The whole jest config: projects `unit`, `integration`, `e2e` and `contract`. It takes no options; the repository config is a managed file. */
+export declare function starciJestConfig(): Config
+export declare const MODULE_NAME_MAPPER: Readonly<Record<string, string>>
 export declare function collectCoverageFrom(): string[]
-export declare function sonarCoverageExclusions(): string
 export declare function sonarExclusions(): string
 export declare const COVERAGE_SOURCES: string[]
 export declare const COVERAGE_EXCLUDES: string[]
+/** The compiler options the unit project overlays on the repository tsconfig so per-file 100 coverage of a decorated service is reachable. */
+export declare const UNIT_COMPILER_OPTIONS: Readonly<{ isolatedModules: false; importHelpers: true }>
+export declare const COVERAGE_THRESHOLD: Readonly<{ lines: 100; branches: 100; functions: 100; statements: 100 }>

package/lock.cjs

@@ -0,0 +1,56 @@
+"use strict"
+
+/**
+ * `fakeLock(clock)` -- a behavioural in-memory double of a lease (cross-replica lock with fencing).
+ *
+ * `acquire({ name, holder, ttlMs, at? })` grants `{ name, holder, fence }` when nobody holds the name (or the previous
+ * ttl ran out on the clock) and answers `null` on contention; the fence grows with every grant of one name.
+ * `release({ grant })` lets go only when the grant is still current. A holder acquiring its own live lease renews it.
+ * Inspection: `isHeld(name)`, `holderOf(name)`, `fenceOf(name)`. Expiry is driven by the `FakeClock`; a request may carry
+ * its own `at`, which wins.
+ */
+
+/** @param {{ now(): Date }} [clock] */
+function fakeLock(clock) {
+  const state = new Map()
+  const fences = new Map()
+  const nowOf = (params) => {
+    const at = params.at ?? clock?.now()
+    if (at === undefined) throw new Error("fakeLock: pass the FakeClock, fakeLock(clock), or an `at` on each acquire")
+    return at.getTime()
+  }
+  const liveHold = (name) => {
+    const hold = state.get(name)
+    if (hold === undefined) return undefined
+    if (clock !== undefined && clock.now().getTime() >= hold.expiresAt) {
+      state.delete(name)
+      return undefined
+    }
+    return hold
+  }
+
+  return {
+    async acquire(params) {
+      const at = nowOf(params)
+      const held = state.get(params.name)
+      const alive = held !== undefined && at < held.expiresAt
+      if (alive && held.holder !== params.holder) return null
+      const fence = alive ? held.fence : (fences.get(params.name) ?? 0) + 1
+      fences.set(params.name, fence)
+      state.set(params.name, { holder: params.holder, fence, expiresAt: at + params.ttlMs })
+      return { name: params.name, holder: params.holder, fence }
+    },
+    async release({ grant }) {
+      const held = state.get(grant.name)
+      if (held !== undefined && held.fence === grant.fence && held.holder === grant.holder) state.delete(grant.name)
+    },
+    /** Whether a live lease exists for `name`. */
+    isHeld: (name) => liveHold(name) !== undefined,
+    /** The holder of the live lease, or null. */
+    holderOf: (name) => liveHold(name)?.holder ?? null,
+    /** The fence of the latest grant of `name`, or null when it was never granted. */
+    fenceOf: (name) => fences.get(name) ?? null,
+  }
+}
+
+module.exports = { fakeLock }

package/lock.d.ts

@@ -0,0 +1,26 @@
+/** What a caller asks for when it wants a named lease. */
+export interface FakeLockAcquire {
+  readonly name: string
+  readonly holder: string
+  readonly ttlMs: number
+  /** The instant of the request; defaults to the clock of the double. */
+  readonly at?: Date
+}
+/** A granted lease. */
+export interface FakeLockGrant {
+  readonly name: string
+  readonly holder: string
+  readonly fence: number
+}
+
+/** A behavioural in-memory lease: acquire, contention, release, ttl expiry on the clock, growing fence. */
+export interface FakeLock {
+  acquire(params: FakeLockAcquire): Promise<FakeLockGrant | null>
+  release(params: { readonly grant: FakeLockGrant }): Promise<void>
+  isHeld(name: string): boolean
+  holderOf(name: string): string | null
+  fenceOf(name: string): number | null
+}
+
+/** The lock double; expiry follows `clock`, so `clock.advance(ms)` frees a lease whose ttl ran out. */
+export declare function fakeLock(clock?: { now(): Date }): FakeLock

package/matchers.cjs

@@ -0,0 +1,45 @@
+"use strict"
+
+/**
+ * Outcome matchers, registered by the `unit` project's `setupFilesAfterEnv` (nowhere else).
+ *
+ * They match the platform `Outcome<V, C>` structurally: `{ kind: "ok", value }` or `{ kind: "refused", code, params? }`.
+ * `expect(outcome).toBeRefused("STOCK_EXHAUSTED")` (or `{ code, params }`) and `expect(outcome).toSucceedWith(value)`.
+ */
+
+const isOutcome = (received) => typeof received === "object" && received !== null && (received.kind === "ok" || received.kind === "refused")
+
+const notOutcome = (utils, received) => `expected an Outcome ({ kind: "ok" | "refused" }), received ${utils.printReceived(received)}`
+
+const matchers = {
+  toBeRefused(received, reason) {
+    if (!isOutcome(received)) return { pass: false, message: () => notOutcome(this.utils, received) }
+    const expected = typeof reason === "string" ? { code: reason } : reason
+    const pass =
+      received.kind === "refused" &&
+      received.code === expected.code &&
+      (!("params" in expected) || this.equals(received.params, expected.params))
+    return {
+      pass,
+      message: () =>
+        pass
+          ? `expected the outcome not to be refused with ${this.utils.printExpected(expected)}`
+          : `expected the outcome to be refused with ${this.utils.printExpected(expected)}, received ${this.utils.printReceived(received)}`,
+    }
+  },
+  toSucceedWith(received, value) {
+    if (!isOutcome(received)) return { pass: false, message: () => notOutcome(this.utils, received) }
+    const pass = received.kind === "ok" && this.equals(received.value, value)
+    return {
+      pass,
+      message: () =>
+        pass
+          ? `expected the outcome not to succeed with ${this.utils.printExpected(value)}`
+          : `expected the outcome to succeed with ${this.utils.printExpected(value)}, received ${this.utils.printReceived(received)}`,
+    }
+  },
+}
+
+if (typeof expect !== "undefined" && typeof expect.extend === "function") expect.extend(matchers)
+
+module.exports = { matchers }

package/matchers.d.ts

@@ -0,0 +1,17 @@
+/// <reference types="jest" />
+
+/** The refusal a matcher expects: a capability code, or a code with the parameters of its display text. */
+export type RefusalReason = string | { readonly code: string; readonly params?: Record<string, unknown> }
+
+declare global {
+  namespace jest {
+    interface Matchers<R> {
+      /** The received `Outcome` is `{ kind: "refused" }` with this code (and these params, when given). */
+      toBeRefused(reason: RefusalReason): R
+      /** The received `Outcome` is `{ kind: "ok" }` whose value equals `value` (recursive equality). */
+      toSucceedWith(value: unknown): R
+    }
+  }
+}
+
+export declare const matchers: Record<"toBeRefused" | "toSucceedWith", (this: jest.MatcherContext, received: unknown, expected: unknown) => jest.CustomMatcherResult>

package/mock.cjs

@@ -8,8 +8,8 @@
  * type-checks against `Repo["find"]`. Values passed in `overrides` win over the generated functions and may be
  * partial: the return type is still `T`.
  *
- * `createMock` takes the function factory as an argument so the helper has no hard dependency on a global
- * `jest`; `mock` binds it to `jest.fn`.
+ * `createMock` takes the function factory as an argument (called with the property name) so the helper has no hard
+ * dependency on a global `jest`; `mock` binds it to `jest.fn`.
  */
 
 // Probed by promise resolution, jest matchers and serializers: they must read as absent, not as a mock function.
@@ -24,7 +24,7 @@ function createMock(makeFn) {
         if (Object.hasOwn(target, property)) return Reflect.get(target, property, receiver)
         if (typeof property === "symbol" || property in Object.prototype) return Reflect.get(target, property, receiver)
         if (ABSENT.has(property)) return undefined
-        if (!own.has(property)) own.set(property, makeFn())
+        if (!own.has(property)) own.set(property, makeFn(property))
         return own.get(property)
       },
       set(target, property, value) {
@@ -41,13 +41,13 @@ function createMock(makeFn) {
 
 // jest-runtime hands every module it loads, this one included, a module-scoped `jest` object; it is not a property
 // of globalThis, so it is read as a free identifier. @jest/globals is the fallback for a runner that does not.
-function jestFn() {
-  if (typeof jest !== "undefined" && typeof jest.fn === "function") return jest.fn()
+function jestFn(implementation) {
+  if (typeof jest !== "undefined" && typeof jest.fn === "function") return jest.fn(implementation)
   try {
-    return require("@jest/globals").jest.fn()
+    return require("@jest/globals").jest.fn(implementation)
   } catch {
     throw new Error("@starci/jest-preset mock<T>() needs the jest runtime; call it from a jest test")
   }
 }
 
-module.exports = { mock: createMock(jestFn), createMock }
+module.exports = { mock: createMock(() => jestFn()), createMock, jestFn }

package/outbox.cjs

@@ -0,0 +1,125 @@
+"use strict"
+
+/**
+ * `recordingOutbox()` -- an outbox double that records what a service writes, so a spec asserts on `outbox.messages`.
+ *
+ * `enqueue(manager, message)` records the message with the manager it was written through. `messages` is what the store
+ * would hold: one message per (queue, eventId), like the real unique key, so a duplicate write keeps one. `writes` is every
+ * call, duplicates included, and `entries` adds `inTransaction`: whether the manager was the view a `fakeTransaction` body
+ * received, so a spec proves a message is written in the transaction of the change that caused it.
+ *
+ * The claim side scripts what a worker's claim returns. `queueRecords(...records)` fills the backlog; `claimDue(params)` hands
+ * out, in order, up to `params.limit` backlog records whose queue is in `params.queues` and removes them, so an empty backlog is
+ * an empty claim and queueing the same record twice is a duplicate delivery. `claims` keeps every claim's params, `completed`,
+ * `retried` and `buried` keep what the worker reported, and `failNext(operation, error)` makes the next call of that operation
+ * reject once, so a spec drives the failure path.
+ */
+const { isTransactionManager } = require("./entity-manager.cjs")
+
+function recordingOutbox() {
+  const written = []
+  const backlog = []
+  const claims = []
+  const completed = []
+  const retried = []
+  const buried = []
+  const failures = new Map()
+  const failIfScripted = (operation) => {
+    if (!failures.has(operation)) return
+    const error = failures.get(operation)
+    failures.delete(operation)
+    throw error
+  }
+  return {
+    async enqueue(manager, message) {
+      failIfScripted("enqueue")
+      written.push({ message, manager, inTransaction: isTransactionManager(manager) })
+    },
+    /** The messages the store would hold: the first write of each (queue, eventId). */
+    get messages() {
+      const seen = new Set()
+      return written
+        .filter(({ message }) => {
+          const key = `${message.queue}\u0000${message.eventId}`
+          if (seen.has(key)) return false
+          seen.add(key)
+          return true
+        })
+        .map(({ message }) => message)
+    },
+    /** Every write, in order: `{ message, manager, inTransaction }`. */
+    get entries() {
+      return [...written]
+    },
+    /** Every message written, duplicates included. */
+    get writes() {
+      return written.map(({ message }) => message)
+    },
+    /** True when something was written and every write went through a transaction manager. */
+    get allInTransaction() {
+      return written.length > 0 && written.every((entry) => entry.inTransaction)
+    },
+    /** The stored messages of one queue. */
+    messagesOf(queue) {
+      return this.messages.filter((message) => message.queue === queue)
+    },
+    /** Adds records to the backlog `claimDue` hands out. */
+    queueRecords(...records) {
+      backlog.push(...records)
+    },
+    async claimDue(params) {
+      claims.push(params)
+      failIfScripted("claimDue")
+      const claimed = []
+      for (const record of [...backlog]) {
+        if (claimed.length >= params.limit) break
+        if (!params.queues.includes(record.queue)) continue
+        claimed.push(record)
+        backlog.splice(backlog.indexOf(record), 1)
+      }
+      return claimed
+    },
+    async complete(id) {
+      failIfScripted("complete")
+      completed.push(id)
+    },
+    async retry(params) {
+      failIfScripted("retry")
+      retried.push(params)
+    },
+    async bury(params) {
+      failIfScripted("bury")
+      buried.push(params)
+    },
+    /** Makes the next call of `operation` reject with `error`, once. */
+    failNext(operation, error) {
+      failures.set(operation, error)
+    },
+    /** The params of every `claimDue` call, in order. */
+    get claims() {
+      return [...claims]
+    },
+    /** The ids passed to `complete`, in order. */
+    get completed() {
+      return [...completed]
+    },
+    /** The params of every `retry`, in order. */
+    get retried() {
+      return [...retried]
+    },
+    /** The params of every `bury`, in order. */
+    get buried() {
+      return [...buried]
+    },
+    /** The records still waiting for a claim. */
+    get backlog() {
+      return [...backlog]
+    },
+    clear() {
+      for (const list of [written, backlog, claims, completed, retried, buried]) list.length = 0
+      failures.clear()
+    },
+  }
+}
+
+module.exports = { recordingOutbox }

package/outbox.d.ts

@@ -0,0 +1,79 @@
+/** A message as the outbox port takes it. */
+export interface RecordedMessage {
+  readonly queue: string
+  readonly eventId: string
+  readonly payload: object
+  readonly availableAt?: Date
+}
+/** One recorded write. */
+export interface OutboxWrite<M extends RecordedMessage = RecordedMessage> {
+  readonly message: M
+  readonly manager: unknown
+  /** Whether the manager was the view a `fakeTransaction` body received. */
+  readonly inTransaction: boolean
+}
+/** A message a worker has claimed, as the outbox port returns it. */
+export interface ClaimedRecord {
+  readonly id: string
+  readonly queue: string
+  readonly eventId: string
+  readonly payload: unknown
+  readonly attempts: number
+}
+/** What a worker asks for when it claims due messages. */
+export interface ClaimParams {
+  readonly at: Date
+  readonly queues: ReadonlyArray<string>
+  readonly limit: number
+  readonly visibilityMs: number
+}
+/** What a worker reports when a delivery failed and should be tried again. */
+export interface RetryParams {
+  readonly id: string
+  readonly at: Date
+  readonly error: string
+}
+/** What a worker reports when a message will not be delivered any more. */
+export interface BuryParams {
+  readonly id: string
+  readonly error: string
+}
+/** The outbox operations `failNext` can make reject. */
+export type OutboxOperation = "enqueue" | "claimDue" | "complete" | "retry" | "bury"
+
+/** An outbox double that records writes and scripts the claim side. */
+export interface RecordingOutbox<M extends RecordedMessage = RecordedMessage, R extends ClaimedRecord = ClaimedRecord> {
+  enqueue(manager: unknown, message: M): Promise<void>
+  /** What the store would hold: the first write of each (queue, eventId). */
+  readonly messages: ReadonlyArray<M>
+  /** Every write with its manager, duplicates included. */
+  readonly entries: ReadonlyArray<OutboxWrite<M>>
+  /** Every message written, duplicates included. */
+  readonly writes: ReadonlyArray<M>
+  /** True when something was written and every write went through a `fakeTransaction` manager. */
+  readonly allInTransaction: boolean
+  messagesOf(queue: string): ReadonlyArray<M>
+  /** Adds records to the backlog `claimDue` hands out; the same record twice is a duplicate delivery. */
+  queueRecords(...records: ReadonlyArray<R>): void
+  /** Hands out, in order, up to `limit` backlog records of the asked queues and removes them; an empty backlog is an empty claim. */
+  claimDue(params: ClaimParams): Promise<Array<R>>
+  complete(id: string): Promise<void>
+  retry(params: RetryParams): Promise<void>
+  bury(params: BuryParams): Promise<void>
+  /** Makes the next call of `operation` reject with `error`, once. */
+  failNext(operation: OutboxOperation, error: Error): void
+  /** The params of every `claimDue` call. */
+  readonly claims: ReadonlyArray<ClaimParams>
+  /** The ids passed to `complete`. */
+  readonly completed: ReadonlyArray<string>
+  /** The params of every `retry`. */
+  readonly retried: ReadonlyArray<RetryParams>
+  /** The params of every `bury`. */
+  readonly buried: ReadonlyArray<BuryParams>
+  /** The records still waiting for a claim. */
+  readonly backlog: ReadonlyArray<R>
+  clear(): void
+}
+
+/** The outbox double. */
+export declare function recordingOutbox<M extends RecordedMessage = RecordedMessage, R extends ClaimedRecord = ClaimedRecord>(): RecordingOutbox<M, R>