@starci/jest-preset 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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.
+- Fixed: the built declarations name `.js` (`dist/index.d.ts` and `dist/entity-manager.d.ts` named `.ts` files a consumer tsc cannot read).
+- Fixed: the pair-mismatch message names state protocol 2 as test-world 1.1 and later write it, not "test-world 1.1.x"; release C pins this preset beside `@starci/test-world` 1.2.3, which speaks protocol 2.
+
 ## 2.4.0 - 2026-10-28
 
 - Changed: the source is TypeScript in `src/`, built to CommonJS JavaScript in `dist/` (`npm run build`; `prepack` builds), and the declarations are emitted from it instead of hand-written; `main`, `types` and every export (`.`, `./mock`, `./clock`, `./entity-manager`, `./ids`, `./matchers`, `./cache`, `./lock`, `./event-bus`, `./queue`, `./inbox`, `./builders`, `./merge`) point into `dist/`. No rule or behaviour changed; the specifiers are unchanged. The files jest loads by path are now `dist/world-runner.js`, `dist/unit-metadata.js`, `dist/unit-metadata.generated.js` (the coverage anchor, copied byte for byte from `assets/`) and `dist/lcov.js`; `@starci/jest-preset/merge` now has types.

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/entity-manager.d.ts

@@ -17,7 +17,7 @@
  * rethrown) and which writes it made, so a spec can assert that a rolled-back transaction committed nothing.
  */
 import type { DeleteResult, EntityManager, InsertResult, UpdateResult } from "typeorm";
-import type { MockOf } from "./mock.ts";
+import type { MockOf } from "./mock.js";
 /** A typed double of `EntityManager`: assignable wherever an `EntityManager` is required, every method a jest mock. */
 export type MockEntityManager = MockOf<EntityManager>;
 /** An entity class. */

package/dist/index.d.ts

@@ -1,22 +1,24 @@
 import type { Config } from "jest";
-import { mock, createMock } from "./mock.ts";
-import { mockEntityManager, fakeTransaction } from "./entity-manager.ts";
-import { FakeClock } from "./clock.ts";
-import { fakeCache } from "./cache.ts";
-import { fakeLock } from "./lock.ts";
-import { recordingEventBus } from "./event-bus.ts";
-import { recordingQueueOutbox } from "./queue.ts";
-import { fakeInbox } from "./inbox.ts";
-import { builder } from "./builders.ts";
-import { fakeIds, FakeIds } from "./ids.ts";
-export type { MockOf } from "./mock.ts";
-export type { MockEntityManager, FakeTransaction, EntityClass } from "./entity-manager.ts";
-export type { FakeCache } from "./cache.ts";
-export type { FakeLock } from "./lock.ts";
-export type { RecordingEventBus } from "./event-bus.ts";
-export type { RecordingQueueOutbox } from "./queue.ts";
-export type { FakeInbox } from "./inbox.ts";
-export type { RefusalReason } from "./matchers.ts";
+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";
+import { recordingEventBus } from "./event-bus.js";
+import { recordingQueueOutbox } from "./queue.js";
+import { fakeInbox } from "./inbox.js";
+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";
+export type { RecordingQueueOutbox } from "./queue.js";
+export type { FakeInbox } from "./inbox.js";
+export type { RefusalReason } from "./matchers.js";
 /** The coverage scope `starci app sync` renders from the slot manifest: the measured roots (a directory pattern per measured slot, a placeholder folder written as a star), the logic roles measured in them and the directories inside a root that are never measured (each ending in a double star). */
 export interface StarciCoverageScope {
     readonly roots: readonly string[];
@@ -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");
@@ -87,9 +90,10 @@ function transform(tsconfig) {
  * The runtime dependencies of a back end that ship ECMAScript modules only: jest's CommonJS runtime cannot load them, so their
  * files are compiled to CommonJS like the repository's own (ts-jest with `allowJs`) instead of being skipped as node_modules.
  * `jose` is the Supabase access-token verifier of every lite back end (be.integrations.supabase); a lite app keeps full's unit
- * run (ruling:R212/case-1, amended by ruling:R212/case-4), so a spec that imports its guard must load it.
+ * run (ruling:R212/case-1, amended by ruling:R212/case-4), so a spec that imports its guard must load it. `@starci/ai-router`
+ * is the AI pool module a back end registers in its AppModule, so a spec that builds the AppModule must load it.
  */
-const ESM_ONLY_DEPENDENCIES = Object.freeze(["jose"]);
+const ESM_ONLY_DEPENDENCIES = Object.freeze(["jose", String.raw `@starci[\\/]ai-router`]);
 const ESM_DEPENDENCY_TRANSFORM = String.raw `^.+[\\/]node_modules[\\/](?:${ESM_ONLY_DEPENDENCIES.join("|")})[\\/].+\.js$`;
 function esmDependencyTransform() {
     return { [ESM_DEPENDENCY_TRANSFORM]: ["ts-jest", { tsconfig: { allowJs: true, module: "commonjs", target: "es2022", esModuleInterop: true }, diagnostics: false }] };

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/dist/world-runner.js

@@ -30,7 +30,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_module_1 = require("node:module");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
-/** The state-file protocol of `@starci/test-world` this runner speaks (test-world 1.1.x). */
+/** The state-file protocol of `@starci/test-world` this runner speaks (test-world 1.1 and later). */
 const WORLD_STATE_VERSION = 2;
 /** The variable that carries the path of the world's state file (set by its globalSetup in this process). */
 const STATE_FILE_ENV = "STARCI_TEST_WORLD_STATE";
@@ -53,7 +53,7 @@ const fieldOf = (value, name) => (typeof value === "object" && value !== null &&
 /** The slot count the world published; a missing or foreign state file is a pair mismatch. */
 function worldSlots(env = process.env) {
     const file = env[STATE_FILE_ENV];
-    const fix = `pin @starci/test-world and @starci/jest-preset together as knowledge/hfs/canon-pins.yaml pairs them (${PRESET} speaks state protocol ${WORLD_STATE_VERSION}, @starci/test-world 1.1.x)`;
+    const fix = `pin @starci/test-world and @starci/jest-preset together as knowledge/hfs/canon-pins.yaml pairs them (${PRESET} speaks state protocol ${WORLD_STATE_VERSION}, as @starci/test-world 1.1 and later write it)`;
     if (file === undefined || file === "") {
         throw runnerError(WORLD_PAIR_MISMATCH, `${STATE_FILE_ENV} is not set: the world's globalSetup published no state file for ${PRESET}; ${fix}`);
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@starci/jest-preset",
-  "version": "2.4.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(), 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"
@@ -88,7 +92,7 @@
     "typeorm": ">=0.3"
   },
   "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\" && tsc -p tsconfig.build.json && node -e \"require('node:fs').copyFileSync('assets/unit-metadata.generated.js', 'dist/unit-metadata.generated.js')\"",
+    "build": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\" && tsc -p tsconfig.build.json && node -e \"const fs = require('node:fs'); for (const f of fs.readdirSync('dist', {recursive: true}).filter((n) => n.endsWith('.d.ts'))) fs.writeFileSync('dist/' + f, fs.readFileSync('dist/' + f, 'utf8').replace(/((?:from |import\\()['\\x22]\\.\\.?\\/[^'\\x22]+)\\.ts(['\\x22])/g, (all, head, quote) => head + '.js' + quote))\" && node -e \"require('node:fs').copyFileSync('assets/unit-metadata.generated.js', 'dist/unit-metadata.generated.js')\"",
     "typecheck": "tsc -p tsconfig.json",
     "prepack": "npm run build",
     "test": "npm run build && npm run typecheck && node --test \"test/**/*.spec.ts\""