@starci/jest-preset 2.4.1 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 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`
 
@@ -105,6 +105,21 @@ The stubbable methods are `findOne`, `findOneBy`, `findOneOrFail`, `findOneByOrF
 `delete`, `softDelete`, `restore`, `increment`, `decrement` and `query`. `fakeTransaction(em)` returns `{ em, outcomes, commits,
 rollbacks, committedWrites, rolledBackWrites }`.
 
+## `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()`
 
 ```ts

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.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(), 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"