@starci/jest-preset 2.5.0 → 2.5.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2.5.1 - 2026-10-29
+
+- Fixed: `fakeTransaction` records a `query` that calls a migration's database function the way `callDbFunction` writes it (`SELECT * FROM "<schema>"."<fn>"(...)`, any schema but `pg_catalog`) as a write, so a rolled-back inbox claim or event send appears in `rolledBackWrites`; any other `SELECT` stays a read.
+- Added: `fakeInbox().claimRow(source, eventId, tx, { entity, row })`, the double of the lite `EntityInbox` claim: it refuses a missing or blank id (`DATABASE_WEBHOOK_DELIVERY_ID_REQUIRED`), claims the trimmed id and, for the winning claim only, records the row `row(id)` builds in `receipts` (with the manager and `inTransaction`) and answers `receipt-<n>`; a repeat, or a pair marked by `receiptExists(source, eventId)`, answers undefined. `failNext("claimRow", error)` scripts a failure.
+
 ## 2.5.0 - 2026-10-29
 
 - Added: `fakeQueryBuilder(answers)` and `queueQueryBuilders(em, answers)` (also at `@starci/jest-preset/query-builder`), the double of `createQueryBuilder(Entity, "alias")` beside `mockEntityManager`: every chained call is recorded and returned to the chain, the terminals resolve the spec's answers. Lite persistence reads through entities and that builder (ruling `lite-persistence-typeorm-entities`), so the double moves here from the apps.

package/README.md

@@ -103,7 +103,9 @@ expect(tx.committedWrites).toHaveLength(1)        // after a throwing body: tx.r
 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 }`.
+rollbacks, committedWrites, rolledBackWrites }`. A write is a write method, a `query` of a DML statement, or a `query` that calls a
+migration's database function the way `callDbFunction` does (`SELECT * FROM "public"."inbox_claim_event"($1, $2)`, any schema but
+`pg_catalog`); any other `SELECT` is a read.
 
 ## `fakeQueryBuilder` and `queueQueryBuilders`
 
@@ -156,6 +158,10 @@ 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()
+// claimRow: the EntityInbox claim that inserts the receipt row only for the winning claim and answers its id
+await inbox.claimRow("webhook.sepay", "e-3", tx, { entity: SepayInboxEntity, row: (deliveryId) => ({ deliveryId }) })  // "receipt-1"
+inbox.receipts                           // every inserted receipt: id, source, eventId, entity, row, tx, inTransaction
+inbox.receiptExists("webhook.sepay", "e-4") // the receipt row is already there: the winning claim inserts nothing, answers undefined
 
 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" } }))

package/dist/entity-manager.d.ts

@@ -14,7 +14,9 @@
  *
  * `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.
+ * rethrown) and which writes it made, so a spec can assert that a rolled-back transaction committed nothing. A write is a
+ * write method (`save`, `insert`, ...), a `query` of a DML statement, or a `query` calling a migration's database function
+ * the way `callDbFunction` does (`SELECT * FROM "public"."inbox_claim_event"($1, $2)`); any other `SELECT` is a read.
  */
 import type { DeleteResult, EntityManager, InsertResult, UpdateResult } from "typeorm";
 import type { MockOf } from "./mock.js";

package/dist/entity-manager.js

@@ -12,6 +12,14 @@ const WRITE_METHODS = new Set([
     "increment", "decrement", "clear",
 ]);
 const WRITE_SQL = /^\s*(insert|update|delete|upsert|merge|truncate)\b/i;
+/**
+ * A call of a migration's database function in the shape `callDbFunction` writes (`SELECT * FROM "<schema>"."<fn>"(...)`), in
+ * any schema but the pg_catalog built-ins: such a function holds a write TypeORM cannot express (an inbox claim, an event send),
+ * so the transaction that makes the call records it as a write.
+ */
+const DB_FUNCTION_SQL = /^\s*select\s+\*\s+from\s+"(?!pg_catalog")[^"]+"\."[^"]+"\s*\(/i;
+/** Whether a `query` writes: a DML statement, or a call of a migration's database function. */
+const isWriteSql = (sql) => WRITE_SQL.test(String(sql)) || DB_FUNCTION_SQL.test(String(sql));
 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 }>>`. */
@@ -74,7 +82,7 @@ function createEntityManagerKit(makeFn) {
                     if (!WRITE_METHODS.has(property) && property !== "query")
                         return value;
                     return (...args) => {
-                        if (property !== "query" || WRITE_SQL.test(String(args[0])))
+                        if (property !== "query" || isWriteSql(args[0]))
                             run.writes.push({ method: property, args });
                         return value(...args);
                     };

package/dist/inbox.d.ts

@@ -4,7 +4,20 @@ export interface InboxEntry {
     readonly eventId: string;
 }
 /** The inbox operations `failNext` can make reject. */
-export type InboxOperation = "claim" | "release" | "runClient" | "sweepClients";
+export type InboxOperation = "claim" | "claimRow" | "release" | "runClient" | "sweepClients";
+/** The receipt `claimRow` inserts for a winning claim: its entity, and its row built from the normalized delivery id. */
+export interface InboxReceiptRequest<Row> {
+    readonly entity: unknown;
+    readonly row: (eventId: string) => Row;
+}
+/** One receipt row `claimRow` inserted, with the id it answered and the manager passed by its caller. */
+export interface InboxReceipt extends InboxEntry {
+    readonly id: string;
+    readonly entity: unknown;
+    readonly row: unknown;
+    readonly tx: unknown;
+    readonly inTransaction: boolean;
+}
 /** The client operation namespace, exact key and JSON request whose outcome the inbox stores. */
 export interface InboxClientOperation {
     readonly principalId: string;
@@ -27,6 +40,13 @@ export interface InboxSweep {
 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>;
+    /**
+     * The `EntityInbox` claim: refuses a missing or blank delivery id, claims the trimmed id, and only for the winning claim
+     * inserts the receipt row and answers its id (`receipt-<n>`); a repeat, or a receipt that already exists, answers undefined.
+     */
+    claimRow<Row>(source: string, eventId: string | undefined, tx: unknown, receipt: InboxReceiptRequest<Row>): Promise<string | undefined>;
+    /** Marks the receipt row of a pair as already inserted: its next winning `claimRow` inserts nothing and answers undefined. */
+    receiptExists(source: string, eventId: string): void;
     /** 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. */
@@ -47,6 +67,8 @@ export interface FakeInbox {
     readonly clientEntries: ReadonlyArray<InboxClientEntry>;
     /** Every sweep attempt with its cutoff and transaction, including a scripted failure. */
     readonly sweeps: ReadonlyArray<InboxSweep>;
+    /** Every receipt row `claimRow` inserted, in order, with its id, row and manager. */
+    readonly receipts: ReadonlyArray<InboxReceipt>;
     clear(): void;
 }
 /**
@@ -57,7 +79,9 @@ export interface FakeInbox {
  * 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.
+ * a spec drives the failure path. `claimRow(source, eventId, tx, { entity, row })` is the `EntityInbox` claim: it refuses a
+ * missing or blank id with `DATABASE_WEBHOOK_DELIVERY_ID_REQUIRED`, claims the trimmed id and, for the winning claim only, records
+ * the receipt row `row(id)` builds in `receipts` and answers its id; `receiptExists(source, eventId)` makes that insert a no-op.
  */
 /** The inbox double. Pass a driven clock to test retention; omitted clocks stamp client claims at the Unix epoch. */
 export declare function fakeInbox(clock?: {

package/dist/inbox.js

@@ -35,7 +35,9 @@ const snapshot = (value, ancestors = new Set()) => {
  * 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.
+ * a spec drives the failure path. `claimRow(source, eventId, tx, { entity, row })` is the `EntityInbox` claim: it refuses a
+ * missing or blank id with `DATABASE_WEBHOOK_DELIVERY_ID_REQUIRED`, claims the trimmed id and, for the winning claim only, records
+ * the receipt row `row(id)` builds in `receipts` and answers its id; `receiptExists(source, eventId)` makes that insert a no-op.
  */
 /** The inbox double. Pass a driven clock to test retention; omitted clocks stamp client claims at the Unix epoch. */
 function fakeInbox(clock) {
@@ -45,6 +47,8 @@ function fakeInbox(clock) {
     const clients = new Map();
     const clientEntries = [];
     const sweeps = [];
+    const receipts = [];
+    const existingReceipts = new Set();
     const failures = new Map();
     const keyOf = (source, eventId) => `${source}\u0000${eventId}`;
     const failIfScripted = (operation) => {
@@ -106,6 +110,27 @@ function fakeInbox(clock) {
             held.add(key);
             return true;
         },
+        async claimRow(source, eventId, tx, receipt) {
+            failIfScripted("claimRow");
+            const normalized = eventId?.trim();
+            if (!normalized)
+                throw inboxError("DATABASE_WEBHOOK_DELIVERY_ID_REQUIRED");
+            claims.push({ source, eventId: normalized });
+            const key = keyOf(source, normalized);
+            if (held.has(key))
+                return undefined;
+            held.add(key);
+            if (existingReceipts.has(key))
+                return undefined;
+            existingReceipts.add(key);
+            const id = `receipt-${String(receipts.length + 1)}`;
+            receipts.push({ id, source, eventId: normalized, entity: receipt.entity, row: receipt.row(normalized), tx, inTransaction: (0, entity_manager_ts_1.isTransactionManager)(tx) });
+            return id;
+        },
+        /** Marks the receipt row of a pair as already inserted, so its next winning `claimRow` answers undefined. */
+        receiptExists(source, eventId) {
+            existingReceipts.add(keyOf(source, eventId));
+        },
         async release(source, eventId) {
             failIfScripted("release");
             released.push({ source, eventId });
@@ -160,7 +185,13 @@ function fakeInbox(clock) {
         get sweeps() {
             return [...sweeps];
         },
+        /** Every receipt row `claimRow` inserted, in order. */
+        get receipts() {
+            return [...receipts];
+        },
         clear() {
+            receipts.length = 0;
+            existingReceipts.clear();
             held.clear();
             claims.length = 0;
             released.length = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/jest-preset",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "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(), fakeQueryBuilder(), queueQueryBuilders(), fakeCache(), fakeLock(), recordingEventBus(), recordingQueueOutbox(), fakeInbox(), FakeClock, fakeIds(), builder() and the Outcome matchers toBeRefused/toSucceedWith.",
   "license": "MIT",
   "author": "starci183",