@starci/jest-preset 2.4.1 → 2.5.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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.
+
 ## 2.4.1 - 2026-10-28
 
 - Changed: `@starci/ai-router` joins the ESM-only dependencies jest compiles to CommonJS, so a spec that builds an AppModule registering the AI pool loads it.

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 the StarCi runtime's `knowledge/stack/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`, `fakeQueryBuilder`, `queueQueryBuilders`, `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)
@@ -72,7 +72,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 `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.
+`./query-builder`, `./matchers`, `./cache`, `./lock`, `./event-bus`, `./queue`, `./inbox` and `./builders` exist as well.
 
 ## `mockEntityManager` and `fakeTransaction`
 
@@ -103,7 +103,24 @@ 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`
+
+The double of `createQueryBuilder(Entity, "alias")`, the builder a lite service reads with. Every chained method records
+`{ method, args }` and returns the builder; a terminal (`execute`, `getMany`, `getOne`, `getRawMany`, `getRawOne`, `getCount`,
+`getManyAndCount`) resolves the answer the spec gave it, and a function answer is called when the terminal runs.
+
+```ts
+import { mockEntityManager, queueQueryBuilders } from "@starci/jest-preset"
+
+const em = mockEntityManager()
+const [open] = queueQueryBuilders(em, [{ getMany: [order] }])   // one fake per createQueryBuilder call, in order
+await service.listOpen(owner)
+expect(open.callsOf("where")).toEqual([["o.ownerId = :owner", { owner }]])
+```
 
 ## `fakeCache(clock)`, `fakeLock(clock)`, `recordingEventBus()` and `recordingQueueOutbox()`
 
@@ -141,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/dist/index.d.ts

@@ -1,6 +1,7 @@
 import type { Config } from "jest";
 import { mock, createMock } from "./mock.js";
 import { mockEntityManager, fakeTransaction } from "./entity-manager.js";
+import { fakeQueryBuilder, queueQueryBuilders } from "./query-builder.js";
 import { FakeClock } from "./clock.js";
 import { fakeCache } from "./cache.js";
 import { fakeLock } from "./lock.js";
@@ -11,6 +12,7 @@ import { builder } from "./builders.js";
 import { fakeIds, FakeIds } from "./ids.js";
 export type { MockOf } from "./mock.js";
 export type { MockEntityManager, FakeTransaction, EntityClass } from "./entity-manager.js";
+export type { FakeQueryBuilder, QueryBuilderAnswers, QueryBuilderCall, QueryBuilderHost } from "./query-builder.js";
 export type { FakeCache } from "./cache.js";
 export type { FakeLock } from "./lock.js";
 export type { RecordingEventBus } from "./event-bus.js";
@@ -111,4 +113,4 @@ declare const WORLD_RUNNER: string;
 declare function hasCoverageSubjects(root: string, glob: string): boolean;
 /** The whole jest config: projects `unit`, `integration`, `e2e` and `contract`. It takes the coverage scope the managed repository config renders; without it it refuses. */
 declare function starciJestConfig(options: StarciJestOptions): StarciJestConfig;
-export { starciJestConfig, TEST_KIND_FOLDERS, MODULE_NAME_MAPPER, mock, createMock, mockEntityManager, fakeTransaction, FakeClock, fakeCache, fakeLock, recordingEventBus, recordingQueueOutbox, fakeInbox, builder, fakeIds, FakeIds, collectCoverageFrom, rootGlob, sonarExclusions, hasCoverageSubjects, COVERAGE_EXCLUDES, COVERAGE_THRESHOLD, UNIT_COMPILER_OPTIONS, WORLD_RUNNER, };
+export { starciJestConfig, TEST_KIND_FOLDERS, MODULE_NAME_MAPPER, mock, createMock, mockEntityManager, fakeTransaction, fakeQueryBuilder, queueQueryBuilders, FakeClock, fakeCache, fakeLock, recordingEventBus, recordingQueueOutbox, fakeInbox, builder, fakeIds, FakeIds, collectCoverageFrom, rootGlob, sonarExclusions, hasCoverageSubjects, COVERAGE_EXCLUDES, COVERAGE_THRESHOLD, UNIT_COMPILER_OPTIONS, WORLD_RUNNER, };

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WORLD_RUNNER = exports.UNIT_COMPILER_OPTIONS = exports.COVERAGE_THRESHOLD = exports.COVERAGE_EXCLUDES = exports.FakeIds = exports.fakeIds = exports.builder = exports.fakeInbox = exports.recordingQueueOutbox = exports.recordingEventBus = exports.fakeLock = exports.fakeCache = exports.FakeClock = exports.fakeTransaction = exports.mockEntityManager = exports.createMock = exports.mock = exports.MODULE_NAME_MAPPER = exports.TEST_KIND_FOLDERS = void 0;
+exports.WORLD_RUNNER = exports.UNIT_COMPILER_OPTIONS = exports.COVERAGE_THRESHOLD = exports.COVERAGE_EXCLUDES = exports.FakeIds = exports.fakeIds = exports.builder = exports.fakeInbox = exports.recordingQueueOutbox = exports.recordingEventBus = exports.fakeLock = exports.fakeCache = exports.FakeClock = exports.queueQueryBuilders = exports.fakeQueryBuilder = exports.fakeTransaction = exports.mockEntityManager = exports.createMock = exports.mock = exports.MODULE_NAME_MAPPER = exports.TEST_KIND_FOLDERS = void 0;
 exports.starciJestConfig = starciJestConfig;
 exports.collectCoverageFrom = collectCoverageFrom;
 exports.rootGlob = rootGlob;
@@ -14,6 +14,9 @@ Object.defineProperty(exports, "createMock", { enumerable: true, get: function (
 const entity_manager_ts_1 = require("./entity-manager.js");
 Object.defineProperty(exports, "mockEntityManager", { enumerable: true, get: function () { return entity_manager_ts_1.mockEntityManager; } });
 Object.defineProperty(exports, "fakeTransaction", { enumerable: true, get: function () { return entity_manager_ts_1.fakeTransaction; } });
+const query_builder_ts_1 = require("./query-builder.js");
+Object.defineProperty(exports, "fakeQueryBuilder", { enumerable: true, get: function () { return query_builder_ts_1.fakeQueryBuilder; } });
+Object.defineProperty(exports, "queueQueryBuilders", { enumerable: true, get: function () { return query_builder_ts_1.queueQueryBuilders; } });
 const clock_ts_1 = require("./clock.js");
 Object.defineProperty(exports, "FakeClock", { enumerable: true, get: function () { return clock_ts_1.FakeClock; } });
 const cache_ts_1 = require("./cache.js");

package/dist/query-builder.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `fakeQueryBuilder()` and `queueQueryBuilders()` -- the double of a typeorm `SelectQueryBuilder` (and its insert, update
+ * and delete siblings) that `mockEntityManager` hands out from `createQueryBuilder(Entity, "alias")`.
+ *
+ * A lite service reads with `createQueryBuilder(Entity, "alias")` and named parameters (persistence.md BE-PERSISTENCE-4).
+ * The fake is a Proxy: every chained method (`where`, `andWhere`, `innerJoin`, `orderBy`, `take`, `setLock`, `returning`,
+ * ...) records `{ method, args }` and returns the builder; a terminal method (`execute`, `getMany`, `getOne`,
+ * `getRawMany`, `getRawOne`, `getCount`, `getManyAndCount`) records too and resolves the answer the spec gave it (a function
+ * answer is called when the terminal runs). A spec asserts the statement it expects through `calls` or `callsOf(method)`.
+ *
+ * `queueQueryBuilders(em, answers)` queues one fake per answer on `em.createQueryBuilder` of a `mockEntityManager()`, in
+ * call order, and returns the fakes so the spec can read each one's calls.
+ */
+/** One chained call recorded on a fake query builder. */
+export interface QueryBuilderCall {
+    /** The builder method that was called. */
+    readonly method: string;
+    /** The arguments it was called with. */
+    readonly args: ReadonlyArray<unknown>;
+}
+/** What the terminal methods of a fake query builder answer; a function is called when the terminal runs and its result returned. */
+export interface QueryBuilderAnswers {
+    /** The answer of `execute()`. */
+    readonly execute?: unknown;
+    /** The answer of `getMany()`. */
+    readonly getMany?: ReadonlyArray<unknown> | (() => unknown);
+    /** The answer of `getOne()`. */
+    readonly getOne?: unknown;
+    /** The answer of `getRawMany()`. */
+    readonly getRawMany?: ReadonlyArray<unknown> | (() => unknown);
+    /** The answer of `getRawOne()`. */
+    readonly getRawOne?: unknown;
+    /** The answer of `getCount()`. */
+    readonly getCount?: number | (() => unknown);
+    /** The answer of `getManyAndCount()`. */
+    readonly getManyAndCount?: readonly [ReadonlyArray<unknown>, number] | (() => unknown);
+}
+/** A chainable stand-in for a typeorm query builder that records every chained call. */
+export interface FakeQueryBuilder {
+    /** The builder to hand back from `entityManager.createQueryBuilder`. */
+    readonly builder: object;
+    /** Every chained call, in order. */
+    readonly calls: ReadonlyArray<QueryBuilderCall>;
+    /** The argument lists of every call of one builder method, in order. */
+    callsOf(method: string): ReadonlyArray<ReadonlyArray<unknown>>;
+}
+/** Builds a chainable query-builder double: every method returns the builder, the terminal methods resolve `answers`. */
+export declare const fakeQueryBuilder: (answers?: QueryBuilderAnswers) => FakeQueryBuilder;
+/** The part of a `mockEntityManager()` this helper queues on: its `createQueryBuilder` jest mock. */
+export interface QueryBuilderHost {
+    readonly createQueryBuilder: {
+        mockReturnValueOnce(value: never): unknown;
+    };
+}
+/** Queues one fake query builder per answer on `manager.createQueryBuilder`, handed out in call order, and returns them. */
+export declare const queueQueryBuilders: (manager: QueryBuilderHost, answers: ReadonlyArray<QueryBuilderAnswers>) => ReadonlyArray<FakeQueryBuilder>;

package/dist/query-builder.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * `fakeQueryBuilder()` and `queueQueryBuilders()` -- the double of a typeorm `SelectQueryBuilder` (and its insert, update
+ * and delete siblings) that `mockEntityManager` hands out from `createQueryBuilder(Entity, "alias")`.
+ *
+ * A lite service reads with `createQueryBuilder(Entity, "alias")` and named parameters (persistence.md BE-PERSISTENCE-4).
+ * The fake is a Proxy: every chained method (`where`, `andWhere`, `innerJoin`, `orderBy`, `take`, `setLock`, `returning`,
+ * ...) records `{ method, args }` and returns the builder; a terminal method (`execute`, `getMany`, `getOne`,
+ * `getRawMany`, `getRawOne`, `getCount`, `getManyAndCount`) records too and resolves the answer the spec gave it (a function
+ * answer is called when the terminal runs). A spec asserts the statement it expects through `calls` or `callsOf(method)`.
+ *
+ * `queueQueryBuilders(em, answers)` queues one fake per answer on `em.createQueryBuilder` of a `mockEntityManager()`, in
+ * call order, and returns the fakes so the spec can read each one's calls.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queueQueryBuilders = exports.fakeQueryBuilder = void 0;
+/** The methods that end a chain and resolve the spec's answer. */
+const TERMINALS = ["execute", "getMany", "getOne", "getRawMany", "getRawOne", "getCount", "getManyAndCount"];
+const isTerminal = (method) => TERMINALS.some((name) => name === method);
+/** Builds a chainable query-builder double: every method returns the builder, the terminal methods resolve `answers`. */
+const fakeQueryBuilder = (answers = {}) => {
+    const calls = [];
+    const builder = new Proxy({}, {
+        get: (_target, property) => {
+            // `then` stays undefined so an awaited builder is not mistaken for a promise.
+            if (typeof property !== "string" || property === "then")
+                return undefined;
+            return (...args) => {
+                calls.push({ method: property, args });
+                if (!isTerminal(property))
+                    return builder;
+                const answer = answers[property];
+                return Promise.resolve(typeof answer === "function" ? answer() : answer);
+            };
+        },
+    });
+    return {
+        builder,
+        calls,
+        callsOf: (method) => calls.filter((call) => call.method === method).map((call) => call.args),
+    };
+};
+exports.fakeQueryBuilder = fakeQueryBuilder;
+/** Queues one fake query builder per answer on `manager.createQueryBuilder`, handed out in call order, and returns them. */
+const queueQueryBuilders = (manager, answers) => {
+    const fakes = answers.map((answer) => (0, exports.fakeQueryBuilder)(answer));
+    for (const fake of fakes)
+        manager.createQueryBuilder.mockReturnValueOnce(fake.builder);
+    return fakes;
+};
+exports.queueQueryBuilders = queueQueryBuilders;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@starci/jest-preset",
-  "version": "2.4.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(), fakeCache(), fakeLock(), recordingEventBus(), recordingQueueOutbox(), fakeInbox(), FakeClock, fakeIds(), builder() and the Outcome matchers toBeRefused/toSucceedWith.",
+  "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",
   "homepage": "https://github.com/starci183/starci-harness/tree/main/packages/jest-preset#readme",
@@ -34,6 +34,10 @@
       "types": "./dist/entity-manager.d.ts",
       "default": "./dist/entity-manager.js"
     },
+    "./query-builder": {
+      "types": "./dist/query-builder.d.ts",
+      "default": "./dist/query-builder.js"
+    },
     "./ids": {
       "types": "./dist/ids.d.ts",
       "default": "./dist/ids.js"