@starci/jest-preset 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,6 +1,10 @@
 # Changelog
 
-## 2.0.0 - unreleased
+## 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.

package/README.md

@@ -114,6 +114,13 @@ outbox.messages     // what the store would hold: the first write of each (queue
 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

package/outbox.cjs

@@ -7,13 +7,32 @@
  * 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). */
@@ -44,8 +63,61 @@ function recordingOutbox() {
     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() {
-      written.length = 0
+      for (const list of [written, backlog, claims, completed, retried, buried]) list.length = 0
+      failures.clear()
     },
   }
 }

package/outbox.d.ts

@@ -12,9 +12,37 @@ export interface OutboxWrite<M extends RecordedMessage = RecordedMessage> {
   /** 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. */
-export interface RecordingOutbox<M extends RecordedMessage = RecordedMessage> {
+/** 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>
@@ -25,8 +53,27 @@ export interface RecordingOutbox<M extends RecordedMessage = RecordedMessage> {
   /** 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>(): RecordingOutbox<M>
+export declare function recordingOutbox<M extends RecordedMessage = RecordedMessage, R extends ClaimedRecord = ClaimedRecord>(): RecordingOutbox<M, R>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/jest-preset",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "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(), recordingOutbox(), FakeClock, fakeIds(), builder() and the Outcome matchers toBeRefused/toSucceedWith.",
   "license": "UNLICENSED",
   "private": false,