@starci/jest-preset 2.3.5 → 2.3.7

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 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.
+
+## 2.3.6 - 2026-10-25
+- Added: the fake inbox records client operations and sweeps (`clientEntries`, `sweeps`) and the entity-manager and index doubles follow the idempotent client inbox of the alpha.31 cohort; the lite and full example back ends spec against them.
+
 ## 2.3.5 - 2026-10-23
 - Changed: the preset sets no `testTimeout` (the jest default applies; a world spec sets its own), owner ruling 2026-10-22: no loosening.
 - Changed: the type probes assert their compiler diagnostics (file, line, code) from their own rejected fixtures instead of inline ts directives; the generated metadata anchor carries no coverage-exclusion comment; a spec refuses any inline suppression in the package.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) StarCi contributors
+Copyright (c) 2026 starci183
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,6 +1,6 @@
 # @starci/jest-preset
 
-The jest config of a Nest repository and the one shared unit-test double kit (`mock<T>()`, `mockEntityManager`, `fakeTransaction`, `fakeCache`, `fakeLock`, `recordingEventBus`, `recordingQueueOutbox`, `fakeInbox`, `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)).
+The jest config of a Nest repository and the one shared unit-test double kit (`mock<T>()`, `mockEntityManager`, `fakeTransaction`, `fakeCache`, `fakeLock`, `recordingEventBus`, `recordingQueueOutbox`, `fakeInbox`, `builder`, `FakeClock`, `fakeIds` and the Outcome matchers). Install it from the npm registry at the exact version in the StarCi runtime's `knowledge/stack/pins.yaml` (see [`packages/README.md`](../README.md)).
 
 ```js
 // jest.config.js (a managed file: `starci app sync` renders it, `starci app check` compares it; do not edit)
@@ -24,7 +24,7 @@ and the exclusions. A repository has no other jest setting to tune.
   (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,
   because the test world resets a slot's data when a file boots. The runner reads test-world state protocol 2 only: pin
-  the two packages together (canon-pins); another protocol fails with `JEST_PRESET_WORLD_PAIR_MISMATCH`. Only the unit project has a `setupFilesAfterEnv`. The managed scripts select one
+  the two packages together (`knowledge/stack/pins.yaml`); another protocol fails with `JEST_PRESET_WORLD_PAIR_MISMATCH`. 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
@@ -33,7 +33,7 @@ and the exclusions. A repository has no other jest setting to tune.
   runs on code that does not type-check.
 - **Coverage of the measured logic, per-file 100.** `collectCoverageFrom` is one glob per `coverage.roots` entry covering `<root>/**/*.{<roles>}.ts`
   (the `ruleParams.be.logicRoles` of the rendered scope), minus its `excludes`, `dist` and `coverage`, and `coverageThreshold` holds
-  `{ lines: 100, branches: 100, functions: 100, statements: 100 }` on each of those globs — a glob key applies to each file on its own, so every file of a
+  `{ lines: 100, branches: 100, functions: 100, statements: 100 }` on one union glob of those roots. Jest applies a glob threshold to each file on its own, so every file of a
   `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
@@ -70,7 +70,7 @@ 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
+full rules and the dependency-to-double-to-cases table are `contexts/code/be/test.md` (the BE-TEST rules). Every
 export below is on the package root (`@starci/jest-preset`); the sub-paths `./mock`, `./clock`, `./entity-manager`, `./ids`,
 `./matchers`, `./cache`, `./lock`, `./event-bus`, `./queue`, `./inbox` and `./builders` exist as well.
 
@@ -141,8 +141,21 @@ await inbox.claim("sepay", "e-1")        // true the first time, false for the s
 await inbox.release("sepay", "e-1")      // gives the claim back: the next claim answers true
 inbox.seen("sepay", "e-2")               // a redelivery: the next claim of the pair answers false
 inbox.claims; inbox.claimed; inbox.released; inbox.failNext("claim", new Error("db down")); inbox.clear()
+
+const clientInbox = fakeInbox(clock)     // the driven clock stamps client claims for retention tests
+await clientInbox.runClient({ principalId: "p-1", operation: "checkout.place", idempotencyKey: "key-1", request: { quantity: 2 } }, tx, async () => ({ kind: "ok", value: { orderId: "o-1" } }))
+clientInbox.clientEntries               // every client claim with its tx and inTransaction flag
+await clientInbox.sweepClients(cutoff, tx)
+clientInbox.sweeps                      // every sweep attempt's cutoff, tx and inTransaction flag, failures included
 ```
 
+Client repeats replay the stored JSON outcome, including a refusal; a different request for the same namespace and key
+rejects with `IDEMPOTENCY_KEY_REUSED`. Concurrent repeats wait for the first effect. A rejected effect gives its claim back.
+Delivery `release` preserves client receipts and their outcomes.
+The double records the transaction passed to it; a later outer transaction rollback needs real database integration proof.
+Without a clock, client claims use the Unix epoch. The sweep removes one bounded batch of completed expired client claims
+and preserves delivery claims.
+
 ## `builder`, `fakeIds` and the Outcome matchers
 
 ```ts

package/entity-manager.cjs

@@ -85,6 +85,7 @@ function createEntityManagerKit(makeFn) {
     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) => args[args.length - 1](view)
           if (typeof property !== "string" || typeof value !== "function") return value

package/entity-manager.d.ts

@@ -90,7 +90,7 @@ export interface FakeTransaction<M extends MockEntityManager = MockEntityManager
   readonly rolledBackWrites: ReadonlyArray<TransactionWrite>
 }
 
-/** Makes `em.transaction(work)` run `work` with a scoped view of the double and record commit, rollback and writes. */
+/** Makes `em.transaction(work)` run `work` with a scoped view whose queryRunner stays active until commit or rollback. */
 export declare function fakeTransaction<M extends MockEntityManager = MockEntityManager>(em?: M): FakeTransaction<M>
 
 /** Whether `manager` is the view a `fakeTransaction` body received (used by `recordingEventBus` and `recordingQueueOutbox`). */

package/inbox.cjs

@@ -1,19 +1,46 @@
 "use strict"
 
+const { isDeepStrictEqual } = require("node:util")
+const { isTransactionManager } = require("./entity-manager.cjs")
+const CLIENT_SWEEP_BATCH = 500
+
+/** The fake carries the production refusal code without depending on an application's error family. */
+const inboxError = (code) => Object.assign(new Error(code), { code })
+
+/** Clone JSON values directly so toJSON cannot change the request or the stored outcome. */
+const snapshot = (value, ancestors = new Set()) => {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value
+  if (typeof value === "number" && Number.isFinite(value)) return value === 0 ? 0 : value
+  if (typeof value !== "object" || ancestors.has(value)) throw inboxError("IDEMPOTENCY_REQUEST_INVALID")
+  ancestors.add(value)
+  let result
+  if (Array.isArray(value)) result = Array.from(value, (member) => snapshot(member, ancestors))
+  else {
+    const prototype = Object.getPrototypeOf(value)
+    if (prototype !== Object.prototype && prototype !== null) throw inboxError("IDEMPOTENCY_REQUEST_INVALID")
+    result = Object.fromEntries(Object.entries(value).map(([key, member]) => [key, snapshot(member, ancestors)]))
+  }
+  ancestors.delete(value)
+  return result
+}
+
 /**
- * `fakeInbox()` -- the twin of `recordingOutbox()` for the delivery side: an `Inbox` double with the behaviour of the real
- * claim, so a spec asserts what a consumer or a signed webhook did with a delivery instead of stubbing `claim` by hand.
+ * `fakeInbox(clock?)` records delivery and client claims, so a spec asserts deduplication and the transaction passed by
+ * its service. Client calls replay JSON outcomes; `clock` gives retention tests a driven claim timestamp.
  *
  * `claim(source, eventId)` answers `true` for the first call of a (source, eventId) pair and `false` for every later one, like the
- * real unique key; `release(source, eventId)` gives the claim back, so the next claim of the pair answers `true` again.
+ * real unique key; `release(source, eventId)` gives an ordinary delivery claim back while preserving client outcomes.
  * `claims` is every claim in order, `claimed` the pairs that are held now, `released` every release, `seen(source, eventId)` marks a
  * pair as already delivered (a redelivery), and `failNext(operation, error)` makes the next call of that operation reject once, so
  * a spec drives the failure path.
  */
-function fakeInbox() {
+function fakeInbox(clock) {
   const held = new Set()
   const claims = []
   const released = []
+  const clients = new Map()
+  const clientEntries = []
+  const sweeps = []
   const failures = new Map()
   const keyOf = (source, eventId) => `${source}\u0000${eventId}`
   const failIfScripted = (operation) => {
@@ -34,7 +61,60 @@ function fakeInbox() {
     async release(source, eventId) {
       failIfScripted("release")
       released.push({ source, eventId })
-      held.delete(keyOf(source, eventId))
+      const key = keyOf(source, eventId)
+      if (!clients.has(key)) held.delete(key)
+    },
+    async runClient(request, tx, effect) {
+      failIfScripted("runClient")
+      const { principalId, operation, idempotencyKey } = request
+      if (!principalId.trim() || principalId.includes(":") || !operation.trim() || operation.includes(":")
+        || !idempotencyKey.trim() || idempotencyKey.length > 64) {
+        throw inboxError("IDEMPOTENCY_REQUEST_INVALID")
+      }
+      const source = `client:${principalId}:${operation}`
+      const key = keyOf(source, idempotencyKey)
+      const body = snapshot(request.request)
+      claims.push({ source, eventId: idempotencyKey })
+      clientEntries.push({ source, eventId: idempotencyKey, tx, inTransaction: isTransactionManager(tx) })
+      const previous = clients.get(key)
+      if (previous !== undefined) {
+        if (!isDeepStrictEqual(previous.request, body)) throw inboxError("IDEMPOTENCY_KEY_REUSED")
+        return snapshot(await previous.result)
+      }
+      if (held.has(key)) throw inboxError("IDEMPOTENCY_KEY_REUSED")
+      const entry = { request: body, claimedAt: clock === undefined ? new Date(0) : clock.now(), completed: false }
+      held.add(key)
+      clients.set(key, entry)
+      entry.result = Promise.resolve().then(effect).then((value) => {
+        let stored
+        try {
+          stored = snapshot(value)
+        } catch (cause) {
+          throw Object.assign(inboxError("INBOX_OUTCOME_INVALID"), { cause })
+        }
+        entry.completed = true
+        return stored
+      }).catch((error) => {
+        if (clients.get(key) === entry) {
+          clients.delete(key)
+          held.delete(key)
+        }
+        throw error
+      })
+      return snapshot(await entry.result)
+    },
+    async sweepClients(cutoff, tx) {
+      sweeps.push({ cutoff: new Date(cutoff), tx, inTransaction: isTransactionManager(tx) })
+      failIfScripted("sweepClients")
+      let swept = 0
+      for (const [key, entry] of clients) {
+        if (swept === CLIENT_SWEEP_BATCH) break
+        if (!entry.completed || entry.claimedAt >= cutoff) continue
+        clients.delete(key)
+        held.delete(key)
+        swept += 1
+      }
+      return swept
     },
     /** Marks a pair as already claimed, so the next `claim` of it answers `false` (a redelivery). */
     seen(source, eventId) {
@@ -59,11 +139,22 @@ function fakeInbox() {
     get released() {
       return [...released]
     },
+    /** Every client claim, including repeats, with the domain transaction it used. */
+    get clientEntries() {
+      return [...clientEntries]
+    },
+    /** Every retention attempt with its cutoff and domain transaction, including a scripted failure. */
+    get sweeps() {
+      return [...sweeps]
+    },
     clear() {
       held.clear()
       claims.length = 0
       released.length = 0
       failures.clear()
+      clients.clear()
+      clientEntries.length = 0
+      sweeps.length = 0
     },
   }
 }

package/inbox.d.ts

@@ -4,14 +4,39 @@ export interface InboxEntry {
   readonly eventId: string
 }
 /** The inbox operations `failNext` can make reject. */
-export type InboxOperation = "claim" | "release"
+export type InboxOperation = "claim" | "release" | "runClient" | "sweepClients"
+
+/** The client operation namespace, exact key and JSON request whose outcome the inbox stores. */
+export interface InboxClientOperation {
+  readonly principalId: string
+  readonly operation: string
+  readonly idempotencyKey: string
+  readonly request: unknown
+}
+
+/** A client claim with the manager passed by its caller. */
+export interface InboxClientEntry extends InboxEntry {
+  readonly tx: unknown
+  readonly inTransaction: boolean
+}
+
+/** One retention sweep with the cutoff instant and manager passed by its caller. */
+export interface InboxSweep {
+  readonly cutoff: Date
+  readonly tx: unknown
+  readonly inTransaction: boolean
+}
 
 /** An `Inbox` double with the behaviour of the real claim. */
 export interface FakeInbox {
   /** True for the first claim of a (source, eventId) pair, false for every later one until it is released. */
   claim(source: string, eventId: string): Promise<boolean>
-  /** Gives the claim back, so the next claim of the pair answers true. */
+  /** Gives an ordinary delivery claim back while preserving client receipts and their outcomes. */
   release(source: string, eventId: string): Promise<void>
+  /** Runs once for the client namespace and key, replays the JSON outcome and refuses a different body. */
+  runClient<T>(request: InboxClientOperation, tx: unknown, effect: () => Promise<T>): Promise<T>
+  /** Deletes at most one batch of completed client claims older than the cutoff. */
+  sweepClients(cutoff: Date, tx: unknown): Promise<number>
   /** Marks a pair as already claimed (a redelivery). */
   seen(source: string, eventId: string): void
   /** Makes the next call of `operation` reject with `error`, once. */
@@ -22,8 +47,12 @@ export interface FakeInbox {
   readonly claimed: ReadonlyArray<InboxEntry>
   /** Every release, in order. */
   readonly released: ReadonlyArray<InboxEntry>
+  /** Every client claim with its manager; this double records transaction ownership, not database commit semantics. */
+  readonly clientEntries: ReadonlyArray<InboxClientEntry>
+  /** Every sweep attempt with its cutoff and transaction, including a scripted failure. */
+  readonly sweeps: ReadonlyArray<InboxSweep>
   clear(): void
 }
 
-/** The inbox double. */
-export declare function fakeInbox(): FakeInbox
+/** The inbox double. Pass a driven clock to test retention; omitted clocks stamp client claims at the Unix epoch. */
+export declare function fakeInbox(clock?: { now(): Date }): FakeInbox

package/index.cjs

@@ -37,6 +37,14 @@ function collectCoverageFrom(coverage) {
   return [...coverage.roots.map((root) => rootGlob(root, coverage.roles)), ...[...coverage.excludes, ...COVERAGE_EXCLUDES].map((glob) => `!${glob}`)]
 }
 
+/** One union glob keeps Jest's per-file checks while a scoped map may contain files from only one measured root. */
+function coverageThresholdOf(coverage, root) {
+  const rootGlobs = coverage.roots.map((entry) => rootGlob(entry, coverage.roles)).filter((glob) => hasCoverageSubjects(root, glob))
+  if (rootGlobs.length === 0) return {}
+  const glob = rootGlobs.length === 1 ? rootGlobs[0] : `{${rootGlobs.join(",")}}`
+  return { [`./${glob}`]: { ...COVERAGE_THRESHOLD } }
+}
+
 /**
  * Sonar `sonar.exclusions`: specs, e2e specs, dist and coverage output are not analysed at all. The list lives in sonar-exclusions.cjs, a
  * require-free module @starci/hfs also ships byte for byte (packages/hfs/runtime, scripts/hfs/sync-runtime.mjs), so `starci app scaffold`
@@ -236,7 +244,7 @@ function starciJestConfig(options) {
     ...(shard ? {} : {
       collectCoverageFrom: collectCoverageFrom(coverage),
       // A glob key is applied to every matching file on its own: each measured file must reach 100, not the average.
-      coverageThreshold: Object.fromEntries(coverage.roots.map((root) => rootGlob(root, coverage.roles)).filter((glob) => hasCoverageSubjects(process.cwd(), glob)).map((glob) => [`./${glob}`, { ...COVERAGE_THRESHOLD }])),
+      coverageThreshold: coverageThresholdOf(coverage, root),
     }),
     coverageDirectory: "coverage",
     // lcov is what Sonar imports (coverage/lcov.info); text-summary and text are what the developer reads; a shard writes the json the merge reads.

package/package.json

@@ -1,8 +1,18 @@
 {
   "name": "@starci/jest-preset",
-  "version": "2.3.5",
+  "version": "2.3.7",
   "description": "The StarCi jest config for Nest repositories (unit, integration, e2e and contract projects, ts-jest with diagnostics off, per-file 100 coverage of *.service.ts only) and the one shared unit-test double kit: typed mock<T>(), mockEntityManager(), fakeTransaction(), fakeCache(), fakeLock(), recordingEventBus(), recordingQueueOutbox(), fakeInbox(), FakeClock, fakeIds(), builder() and the Outcome matchers toBeRefused/toSucceedWith.",
   "license": "MIT",
+  "author": "starci183",
+  "homepage": "https://github.com/starci183/starci-harness/tree/main/packages/jest-preset#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/starci183/starci-harness.git",
+    "directory": "packages/jest-preset"
+  },
+  "bugs": {
+    "url": "https://github.com/starci183/starci-harness/issues"
+  },
   "private": false,
   "main": "index.cjs",
   "types": "index.d.ts",