@starci/jest-preset 2.3.6 → 2.4.0

package/dist/queue.d.ts

@@ -0,0 +1,30 @@
+/** One recorded job write. */
+export interface QueueWrite {
+    readonly queue: string;
+    readonly payload: object;
+    readonly tx: unknown;
+    /** Whether `tx` was the view a `fakeTransaction` body received. */
+    readonly inTransaction: boolean;
+}
+/** A `QueueOutbox` double that records the jobs a typed producer writes. */
+export interface RecordingQueueOutbox {
+    write(tx: unknown, queue: string, payload: object): Promise<void>;
+    /** Every job written, in order. */
+    readonly jobs: ReadonlyArray<{
+        readonly queue: string;
+        readonly payload: object;
+    }>;
+    /** Every write with its manager. */
+    readonly entries: ReadonlyArray<QueueWrite>;
+    jobsOf(queue: string): ReadonlyArray<{
+        readonly queue: string;
+        readonly payload: object;
+    }>;
+    /** True when something was written and every write went through a `fakeTransaction` manager. */
+    readonly allInTransaction: boolean;
+    /** Makes the next write reject with `error`, once. */
+    failNext(operation: "write", error: Error): void;
+    clear(): void;
+}
+/** The queue outbox double. */
+export declare function recordingQueueOutbox(): RecordingQueueOutbox;

package/dist/queue.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordingQueueOutbox = recordingQueueOutbox;
+/**
+ * `recordingQueueOutbox()` -- a `QueueOutbox` double that records what a typed queue producer writes, so a spec asserts on `outbox.jobs`.
+ *
+ * `write(tx, queue, payload)` records the job with the manager it was written through. `jobs` is every job in order, `jobsOf(queue)`
+ * the jobs of one queue, and `entries` adds `inTransaction`: whether `tx` was the view a `fakeTransaction` body received, so a spec proves
+ * a job is enqueued in the transaction of the change that needs it. `failNext('write', error)` makes the next write reject once.
+ */
+const entity_manager_ts_1 = require("./entity-manager.js");
+/** The queue outbox double. */
+function recordingQueueOutbox() {
+    const written = [];
+    const failures = new Map();
+    return {
+        async write(tx, queue, payload) {
+            const error = failures.get("write");
+            if (error !== undefined) {
+                failures.delete("write");
+                throw error;
+            }
+            written.push({ queue, payload, tx, inTransaction: (0, entity_manager_ts_1.isTransactionManager)(tx) });
+        },
+        /** Every job written, in order: `{ queue, payload }`. */
+        get jobs() {
+            return written.map(({ queue, payload }) => ({ queue, payload }));
+        },
+        /** Every write with its manager and `inTransaction`. */
+        get entries() {
+            return [...written];
+        },
+        /** The jobs of one queue. */
+        jobsOf(queue) {
+            return this.jobs.filter((job) => job.queue === queue);
+        },
+        /** True when something was written and every write went through a transaction manager. */
+        get allInTransaction() {
+            return written.length > 0 && written.every((entry) => entry.inTransaction);
+        },
+        /** Makes the next write reject with `error`, once. */
+        failNext(operation, error) {
+            failures.set(operation, error);
+        },
+        clear() {
+            written.length = 0;
+            failures.clear();
+        },
+    };
+}

package/dist/sonar-exclusions.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Sonar `sonar.exclusions`: specs, e2e specs, dist and coverage output are not analysed at all. A plain list with no require, so
+ * @starci/hfs ships the built file (packages/hfs/runtime, scripts/hfs/sync-runtime.mjs) and `starci app scaffold` renders
+ * the same exclusions before any app dependency is installed.
+ */
+declare const SONAR_EXCLUSIONS: readonly string[];
+export = SONAR_EXCLUSIONS;

package/dist/sonar-exclusions.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Sonar `sonar.exclusions`: specs, e2e specs, dist and coverage output are not analysed at all. A plain list with no require, so
+ * @starci/hfs ships the built file (packages/hfs/runtime, scripts/hfs/sync-runtime.mjs) and `starci app scaffold` renders
+ * the same exclusions before any app dependency is installed.
+ */
+const SONAR_EXCLUSIONS = Object.freeze(["**/*.spec.ts", "**/*.e2e-spec.ts", "**/dist/**", "**/coverage/**"]);
+module.exports = SONAR_EXCLUSIONS;

package/dist/unit-metadata.d.ts

@@ -0,0 +1,23 @@
+import type TS from "typescript";
+type TypeScript = typeof TS;
+/** What the transformer reads of the ts-jest compiler: the TypeScript module the project compiles with. */
+interface MetadataCompiler {
+    readonly configSet: {
+        readonly compilerModule: TypeScript;
+    };
+}
+/** Only synthetic conditional guards inside compiler-emitted parameter metadata map to the generated-metadata anchor: a zero-width position at its end, which no line covers, so they are measured nowhere and source metadata calls stay measured. */
+declare function factory(compiler: MetadataCompiler): TS.TransformerFactory<TS.SourceFile>;
+/** Unit transforms delegate compilation and caching to ts-jest; the after-transformer changes metadata mappings only. */
+declare function createTransformer(options?: Parameters<typeof import("ts-jest").default.createTransformer>[0]): {
+    getCacheKey: (fileContent: string, filePath: string, transformOptions: import("ts-jest").TsJestTransformOptions) => string;
+    process: (sourceText: string, sourcePath: string, transformOptions: import("ts-jest").TsJestTransformOptions) => import("@jest/transform").TransformedSource;
+    processAsync: (sourceText: string, sourcePath: string, transformOptions: import("ts-jest").TsJestTransformOptions) => Promise<import("@jest/transform").TransformedSource>;
+};
+declare const unitMetadata: {
+    name: string;
+    version: number;
+    factory: typeof factory;
+    createTransformer: typeof createTransformer;
+};
+export = unitMetadata;

package/dist/unit-metadata.js

@@ -0,0 +1,71 @@
+"use strict";
+const node_fs_1 = require("node:fs");
+const METADATA_SOURCE = require.resolve("./unit-metadata.generated.js");
+const METADATA_TEXT = (0, node_fs_1.readFileSync)(METADATA_SOURCE, "utf8");
+const hasEmitFlags = (ts) => "getEmitFlags" in ts && typeof ts.getEmitFlags === "function";
+function emitFlagsOf(ts, node) {
+    if (!hasEmitFlags(ts))
+        throw new TypeError("ts.getEmitFlags is not a function");
+    return ts.getEmitFlags(node);
+}
+/** Only synthetic conditional guards inside compiler-emitted parameter metadata map to the generated-metadata anchor: a zero-width position at its end, which no line covers, so they are measured nowhere and source metadata calls stay measured. */
+function factory(compiler) {
+    const ts = compiler.configSet.compilerModule;
+    const source = ts.createSourceMapSource(METADATA_SOURCE, METADATA_TEXT);
+    return (context) => {
+        const visit = (node) => {
+            if (isGeneratedMetadata(ts, node)) {
+                const guard = (child) => {
+                    if (isGeneratedGuard(ts, child)) {
+                        ts.setSourceMapRange(child, { pos: METADATA_TEXT.length, end: METADATA_TEXT.length, source });
+                        ts.setEmitFlags(child, emitFlagsOf(ts, child) | ts.EmitFlags.NoNestedSourceMaps);
+                        return child;
+                    }
+                    return ts.visitEachChild(child, guard, context);
+                };
+                return ts.visitEachChild(node, guard, context);
+            }
+            return ts.visitEachChild(node, visit, context);
+        };
+        return (file) => ts.visitNode(file, visit, ts.isSourceFile);
+    };
+}
+/** Only TypeScript's synthetic __metadata("design:paramtypes", ...) call is eligible; source calls remain measured. */
+function isGeneratedMetadata(ts, node) {
+    if (node.pos >= 0 || !ts.isCallExpression(node))
+        return false;
+    const key = node.arguments[0];
+    return ts.isIdentifier(node.expression) && node.expression.text === "__metadata" && node.arguments.length === 2 && key !== undefined && ts.isStringLiteral(key) && key.text === "design:paramtypes";
+}
+/** A metadata exclusion requires TypeScript's synthetic `typeof value === "function" ? value : Object` guard shape. */
+function isGeneratedGuard(ts, node) {
+    if (node.pos >= 0 || !ts.isConditionalExpression(node))
+        return false;
+    const condition = node.condition;
+    return ts.isBinaryExpression(condition) && condition.operatorToken.kind === ts.SyntaxKind.EqualsEqualsEqualsToken && ts.isTypeOfExpression(condition.left) && ts.isStringLiteral(condition.right) && condition.right.text === "function" && ts.isIdentifier(node.whenFalse) && node.whenFalse.text === "Object";
+}
+/** ts-jest normalizes map sources to the input file; restore the generated metadata anchor before Jest reads the map. */
+function restoreMetadataSource(result) {
+    const prefix = "sourceMappingURL=data:application/json;charset=utf-8;base64,";
+    const offset = result.code.lastIndexOf(prefix);
+    if (offset < 0)
+        return result;
+    const start = offset + prefix.length;
+    const map = JSON.parse(Buffer.from(result.code.slice(start), "base64").toString("utf8"));
+    if (map.sourcesContent?.length !== 2 || map.sourcesContent[1] !== METADATA_TEXT)
+        return result;
+    map.sources = [map.sources[0] ?? "", METADATA_SOURCE];
+    return { ...result, code: result.code.slice(0, start) + Buffer.from(JSON.stringify(map)).toString("base64") };
+}
+/** Unit transforms delegate compilation and caching to ts-jest; the after-transformer changes metadata mappings only. */
+function createTransformer(options) {
+    const tsJest = require("ts-jest");
+    const delegate = tsJest.default.createTransformer(options);
+    return {
+        getCacheKey: (...args) => delegate.getCacheKey(...args) + ":starci-unit-metadata-6",
+        process: (...args) => restoreMetadataSource(delegate.process(...args)),
+        processAsync: async (...args) => restoreMetadataSource(await delegate.processAsync(...args)),
+    };
+}
+const unitMetadata = { name: "starci-unit-metadata", version: 6, factory, createTransformer };
+module.exports = unitMetadata;

package/dist/world-runner.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The runner of the integration, e2e and contract projects: every spec file runs in a process of its own, bound to one data
+ * slot of the test world.
+ *
+ * Why a process per file: jest runs a file in a fresh vm context, but a context still reaches the globals of the process that
+ * hosts it, and jest-environment-node exposes every global the host process had when the environment loaded. The test world's
+ * globalSetup runs in jest's main process and loads application code there (the migrate step and its modules), so a framework
+ * that keeps its registry on a process global (`@nestjs/graphql` keeps `GqlTypeMetadataStorage` on `global`) leaks it into
+ * every file jest runs in that process; and a worker that runs several files carries whatever the first one left on its own
+ * global. A process per file isolates every framework at once.
+ *
+ * Why slots: the test world resets a slot's data (its databases, realm users, Redis DB, buckets and fakes) when a file boots,
+ * so two files must never share a slot at the same time. The globalSetup of `@starci/test-world` provisions N slots, each a
+ * complete, independent set of data namespaces, and publishes them in its state file (`STARCI_TEST_WORLD_STATE`, protocol
+ * {@link WORLD_STATE_VERSION}). The runner runs up to `min(--maxWorkers, N)` files at once and gives each a free slot: the
+ * file's process is forked with `STARCI_TEST_WORLD_SLOT=<k>`; the slot goes back to the pool when the file ends.
+ *
+ * How: the stock jest-runner, driven one file at a time per slot with a single-worker farm (`maxWorkers: 1` per file), which
+ * forks a fresh child, runs the file there and ends the child. jest-worker forks in the farm's constructor, which jest-runner
+ * calls before its first `await`, so the slot variable is set on `process.env` only for that synchronous span. Never in band,
+ * even when jest would choose it (`--runInBand`): the main process holds the globalSetup's state.
+ *
+ * The pair is exact: this runner reads protocol {@link WORLD_STATE_VERSION} only. Any other state file is the wrong
+ * `@starci/test-world` beside this preset, a typed failure naming both versions (re-pin both per canon-pins), never a fallback.
+ */
+import type TestRunner from "jest-runner";
+import type { Test, TestEvents, TestWatcher, UnsubscribeFn } from "jest-runner";
+/** The slot count the world published; a missing or foreign state file is a pair mismatch. */
+declare function worldSlots(env?: NodeJS.ProcessEnv): number;
+declare const StockRunner: typeof TestRunner;
+declare class WorldRunner extends StockRunner {
+    #private;
+    static readonly WORLD_STATE_VERSION = 2;
+    static readonly SLOT_ENV = "STARCI_TEST_WORLD_SLOT";
+    static readonly WORLD_PAIR_MISMATCH = "JEST_PRESET_WORLD_PAIR_MISMATCH";
+    static readonly worldSlots: typeof worldSlots;
+    /** Jest subscribes before the run; the subscriptions are handed to the per-file runner of each file. */
+    on<Name extends keyof TestEvents>(eventName: Name, listener: (eventData: TestEvents[Name]) => void | Promise<void>): UnsubscribeFn;
+    /** Runs the files up to `min(--maxWorkers, slots)` at once, each in a fresh process bound to a free slot; never in band. */
+    runTests(tests: Test[], watcher: TestWatcher): Promise<void>;
+}
+export = WorldRunner;

package/dist/world-runner.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * The runner of the integration, e2e and contract projects: every spec file runs in a process of its own, bound to one data
+ * slot of the test world.
+ *
+ * Why a process per file: jest runs a file in a fresh vm context, but a context still reaches the globals of the process that
+ * hosts it, and jest-environment-node exposes every global the host process had when the environment loaded. The test world's
+ * globalSetup runs in jest's main process and loads application code there (the migrate step and its modules), so a framework
+ * that keeps its registry on a process global (`@nestjs/graphql` keeps `GqlTypeMetadataStorage` on `global`) leaks it into
+ * every file jest runs in that process; and a worker that runs several files carries whatever the first one left on its own
+ * global. A process per file isolates every framework at once.
+ *
+ * Why slots: the test world resets a slot's data (its databases, realm users, Redis DB, buckets and fakes) when a file boots,
+ * so two files must never share a slot at the same time. The globalSetup of `@starci/test-world` provisions N slots, each a
+ * complete, independent set of data namespaces, and publishes them in its state file (`STARCI_TEST_WORLD_STATE`, protocol
+ * {@link WORLD_STATE_VERSION}). The runner runs up to `min(--maxWorkers, N)` files at once and gives each a free slot: the
+ * file's process is forked with `STARCI_TEST_WORLD_SLOT=<k>`; the slot goes back to the pool when the file ends.
+ *
+ * How: the stock jest-runner, driven one file at a time per slot with a single-worker farm (`maxWorkers: 1` per file), which
+ * forks a fresh child, runs the file there and ends the child. jest-worker forks in the farm's constructor, which jest-runner
+ * calls before its first `await`, so the slot variable is set on `process.env` only for that synchronous span. Never in band,
+ * even when jest would choose it (`--runInBand`): the main process holds the globalSetup's state.
+ *
+ * The pair is exact: this runner reads protocol {@link WORLD_STATE_VERSION} only. Any other state file is the wrong
+ * `@starci/test-world` beside this preset, a typed failure naming both versions (re-pin both per canon-pins), never a fallback.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": 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). */
+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";
+/** The variable that tells a file's process which slot it owns (1-based). */
+const SLOT_ENV = "STARCI_TEST_WORLD_SLOT";
+/** The failure code of a state file this runner cannot drive. */
+const WORLD_PAIR_MISMATCH = "JEST_PRESET_WORLD_PAIR_MISMATCH";
+const PRESET = (() => {
+    // dist/ sits one level below the package root that holds package.json
+    const own = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(__dirname, "..", "package.json"), "utf8"));
+    return `${own.name}@${own.version}`;
+})();
+/** A typed failure of the runner: `code` names it, the message says what to do. */
+function runnerError(code, detail) {
+    const error = new Error(`${code}: ${detail}`);
+    return Object.assign(error, { code });
+}
+/** A property of an unknown value, `undefined` when the value is not an object that has it. */
+const fieldOf = (value, name) => (typeof value === "object" && value !== null && name in value ? Reflect.get(value, name) : undefined);
+/** 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)`;
+    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}`);
+    }
+    let state;
+    try {
+        state = JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
+    }
+    catch (cause) {
+        throw runnerError(WORLD_PAIR_MISMATCH, `the world state file ${file} cannot be read (${cause instanceof Error ? cause.message : String(cause)}); ${fix}`);
+    }
+    const published = fieldOf(state, "library");
+    const library = typeof published === "string" ? published : "@starci/test-world before 1.1.0";
+    const slots = fieldOf(state, "slots");
+    if (fieldOf(state, "version") !== WORLD_STATE_VERSION || !Array.isArray(slots) || slots.length < 1) {
+        throw runnerError(WORLD_PAIR_MISMATCH, `${library} wrote state protocol ${String(fieldOf(state, "version"))}, ${PRESET} needs ${WORLD_STATE_VERSION}; ${fix}`);
+    }
+    return slots.length;
+}
+/**
+ * The stock jest-runner of the jest that loads this preset: resolved through jest's own dependency chain
+ * (jest -> @jest/core -> jest-runner) from the repository root, so the runner always matches the running jest.
+ */
+function stockRunner(root = process.cwd()) {
+    const fromRoot = (0, node_module_1.createRequire)(node_path_1.default.join(root, "package.json"));
+    const fromJest = (0, node_module_1.createRequire)(fromRoot.resolve("jest/package.json"));
+    const fromCore = (0, node_module_1.createRequire)(fromJest.resolve("@jest/core"));
+    const loaded = fromCore("jest-runner");
+    return loaded.default ?? loaded;
+}
+const StockRunner = stockRunner();
+class WorldRunner extends StockRunner {
+    static WORLD_STATE_VERSION = WORLD_STATE_VERSION;
+    static SLOT_ENV = SLOT_ENV;
+    static WORLD_PAIR_MISMATCH = WORLD_PAIR_MISMATCH;
+    static worldSlots = worldSlots;
+    #listeners = [];
+    /** Jest subscribes before the run; the subscriptions are handed to the per-file runner of each file. */
+    on(eventName, listener) {
+        const entry = { attach: (runner) => runner.on(eventName, listener) };
+        this.#listeners.push(entry);
+        return () => {
+            this.#listeners = this.#listeners.filter((candidate) => candidate !== entry);
+        };
+    }
+    /** Runs the files up to `min(--maxWorkers, slots)` at once, each in a fresh process bound to a free slot; never in band. */
+    async runTests(tests, watcher) {
+        const slots = worldSlots();
+        const width = Math.max(1, Math.min(this._globalConfig.maxWorkers ?? 1, slots));
+        const queue = [...tests];
+        // one lane per slot: a lane owns its slot for the whole run and takes the next file when its current one ends
+        const lane = async (slot) => {
+            for (let test = queue.shift(); test !== undefined; test = queue.shift()) {
+                if (watcher.isInterrupted())
+                    return;
+                await this.#runOne(test, watcher, slot);
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(width, tests.length) }, (_, index) => lane(index + 1)));
+    }
+    /** One file in a fresh single-worker farm whose child is forked with the slot in its environment. */
+    async #runOne(test, watcher, slot) {
+        const runner = new StockRunner({ ...this._globalConfig, maxWorkers: 1 }, this._context);
+        const unsubscribe = this.#listeners.map(({ attach }) => attach(runner));
+        const before = process.env[SLOT_ENV];
+        let running;
+        process.env[SLOT_ENV] = String(slot);
+        try {
+            // the farm (and its child) is created synchronously inside this call, before jest-runner's first await
+            running = runner.runTests([test], watcher, { serial: false });
+        }
+        finally {
+            if (before === undefined)
+                delete process.env[SLOT_ENV];
+            else
+                process.env[SLOT_ENV] = before;
+        }
+        try {
+            await running;
+        }
+        finally {
+            for (const stop of unsubscribe)
+                stop();
+        }
+    }
+}
+module.exports = WorldRunner;

package/package.json

@@ -1,69 +1,79 @@
 {
   "name": "@starci/jest-preset",
-  "version": "2.3.6",
+  "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.",
   "license": "MIT",
+  "author": "starci183",
+  "homepage": "https://github.com/starci183/starci-harness/tree/main/packages/jest-preset#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/starci183/starci-harness.git",
+    "directory": "packages/jest-preset"
+  },
+  "bugs": {
+    "url": "https://github.com/starci183/starci-harness/issues"
+  },
   "private": false,
-  "main": "index.cjs",
-  "types": "index.d.ts",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./index.d.ts",
-      "default": "./index.cjs"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
     "./mock": {
-      "types": "./mock.d.ts",
-      "default": "./mock.cjs"
+      "types": "./dist/mock.d.ts",
+      "default": "./dist/mock.js"
     },
     "./clock": {
-      "types": "./clock.d.ts",
-      "default": "./clock.cjs"
+      "types": "./dist/clock.d.ts",
+      "default": "./dist/clock.js"
     },
     "./entity-manager": {
-      "types": "./entity-manager.d.ts",
-      "default": "./entity-manager.cjs"
+      "types": "./dist/entity-manager.d.ts",
+      "default": "./dist/entity-manager.js"
     },
     "./ids": {
-      "types": "./ids.d.ts",
-      "default": "./ids.cjs"
+      "types": "./dist/ids.d.ts",
+      "default": "./dist/ids.js"
     },
     "./matchers": {
-      "types": "./matchers.d.ts",
-      "default": "./matchers.cjs"
+      "types": "./dist/matchers.d.ts",
+      "default": "./dist/matchers.js"
     },
     "./cache": {
-      "types": "./cache.d.ts",
-      "default": "./cache.cjs"
+      "types": "./dist/cache.d.ts",
+      "default": "./dist/cache.js"
     },
     "./lock": {
-      "types": "./lock.d.ts",
-      "default": "./lock.cjs"
+      "types": "./dist/lock.d.ts",
+      "default": "./dist/lock.js"
     },
     "./event-bus": {
-      "types": "./event-bus.d.ts",
-      "default": "./event-bus.cjs"
+      "types": "./dist/event-bus.d.ts",
+      "default": "./dist/event-bus.js"
     },
     "./queue": {
-      "types": "./queue.d.ts",
-      "default": "./queue.cjs"
+      "types": "./dist/queue.d.ts",
+      "default": "./dist/queue.js"
     },
     "./inbox": {
-      "types": "./inbox.d.ts",
-      "default": "./inbox.cjs"
+      "types": "./dist/inbox.d.ts",
+      "default": "./dist/inbox.js"
     },
     "./builders": {
-      "types": "./builders.d.ts",
-      "default": "./builders.cjs"
+      "types": "./dist/builders.d.ts",
+      "default": "./dist/builders.js"
     },
     "./merge": {
-      "default": "./merge.cjs"
+      "types": "./dist/merge.d.ts",
+      "default": "./dist/merge.js"
     }
   },
   "files": [
+    "dist",
     "LICENSE",
-    "*.cjs",
-    "*.d.ts",
-    "!*.spec.*",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -78,7 +88,10 @@
     "typeorm": ">=0.3"
   },
   "scripts": {
-    "test": "node --test \"*.spec.mjs\""
+    "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')\"",
+    "typecheck": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "npm run build && npm run typecheck && node --test \"test/**/*.spec.ts\""
   },
   "peerDependenciesMeta": {
     "typeorm": {
@@ -89,11 +102,18 @@
     }
   },
   "devDependencies": {
+    "@starci/tsconfig": "file:../tsconfig",
+    "@types/istanbul-lib-coverage": "2.0.6",
+    "@types/istanbul-lib-report": "3.0.3",
+    "@types/istanbul-reports": "3.0.4",
     "@types/jest": "29.5.14",
+    "@types/node": "24.19.2",
     "jest": "29.7.0",
+    "jest-runner": "29.7.0",
     "jest-util": "29.7.0",
     "ts-jest": "29.4.12",
     "tslib": "2.8.1",
+    "typeorm": "0.3.27",
     "typescript": "5.9.3"
   }
 }

package/builders.d.ts

@@ -1,2 +0,0 @@
-/** Makes a builder of `T`: a function returning the defaults with `overrides` applied. */
-export declare function builder<T extends object>(defaults: T): (overrides?: Partial<T>) => T

package/cache.cjs

@@ -1,67 +0,0 @@
-"use strict"
-
-/**
- * `fakeCache(clock)` -- a behavioural in-memory double of a cache port.
- *
- * It keeps entries as JSON text (like a Redis-backed cache, so a Date comes back as a string and a `key.parse` narrows
- * what was stored), expires them from the `FakeClock` (`clock.advance(ms)` is a TTL expiry, no sleep), and offers the
- * inspection a spec needs: `has(key)`, `ttlOf(key)`, `keys()`.
- *
- * Two call shapes are served by the same object, so it stands in for either kind of cache dependency:
- *   - the typed-key port: `get({ key, args })`, `set({ key, args, value })`, `del({ key, args })`, where `key` is
- *     `{ name, ttl: { seconds }, parse? }` and the entry text is `<name>:<arg>:...`;
- *   - the cache-manager shape: `get(text)`, `set(text, value, ttlMs?)`, `del(text)`.
- * `has`, `ttlOf` and `del` accept a request or the entry text.
- */
-
-const textOf = (request) => (typeof request === "string" ? request : [request.key.name, ...(request.args ?? [])].join(":"))
-
-/** @param {{ now(): Date }} clock */
-function fakeCache(clock) {
-  if (!clock || typeof clock.now !== "function") throw new Error("fakeCache: pass the FakeClock the spec drives, fakeCache(clock)")
-  const entries = new Map()
-
-  const live = (text) => {
-    const entry = entries.get(text)
-    if (entry === undefined) return undefined
-    if (entry.expiresAt !== null && clock.now().getTime() >= entry.expiresAt) {
-      entries.delete(text)
-      return undefined
-    }
-    return entry
-  }
-
-  return {
-    async get(request) {
-      const entry = live(textOf(request))
-      if (entry === undefined) return null
-      const stored = JSON.parse(entry.json)
-      return typeof request === "string" || typeof request.key.parse !== "function" ? stored : request.key.parse(stored)
-    },
-    async set(request, value, ttlMs) {
-      const text = textOf(request)
-      const typed = typeof request !== "string"
-      const stored = typed ? request.value : value
-      const lifetimeMs = typed ? request.key.ttl.seconds * 1000 : ttlMs
-      if (lifetimeMs !== undefined && !(lifetimeMs > 0)) throw new Error(`fakeCache: the ttl of ${text} must be positive`)
-      entries.set(text, { json: JSON.stringify(stored), expiresAt: lifetimeMs === undefined ? null : clock.now().getTime() + lifetimeMs })
-    },
-    async del(request) {
-      entries.delete(textOf(request))
-    },
-    /** Whether a live (not expired) entry exists. */
-    has: (request) => live(textOf(request)) !== undefined,
-    /** Seconds left before the entry expires (rounded up), null when there is no live entry or it never expires. */
-    ttlOf(request) {
-      const entry = live(textOf(request))
-      if (entry === undefined || entry.expiresAt === null) return null
-      return Math.ceil((entry.expiresAt - clock.now().getTime()) / 1000)
-    },
-    /** The texts of the live entries. */
-    keys: () => [...entries.keys()].filter((text) => live(text) !== undefined),
-    /** Drops every entry. */
-    clear: () => entries.clear(),
-  }
-}
-
-module.exports = { fakeCache }

package/cache.d.ts

@@ -1,31 +0,0 @@
-/** The declared key of a typed cache entry: `{ name, ttl, parse? }`. */
-export interface FakeCacheKey<TValue = unknown> {
-  readonly name: string
-  readonly ttl: { readonly seconds: number }
-  readonly parse?: (stored: unknown) => TValue | null
-}
-/** The typed-key request: the key plus the arguments that make the entry unique. */
-export interface FakeCacheRequest<TValue = unknown> {
-  readonly key: FakeCacheKey<TValue>
-  readonly args?: ReadonlyArray<string>
-}
-export type FakeCacheEntry<TValue = unknown> = FakeCacheRequest<TValue> & { readonly value: TValue }
-
-/** A behavioural in-memory cache: JSON round trip, expiry driven by the clock, inspection helpers. */
-export interface FakeCache {
-  get<TValue>(request: FakeCacheRequest<TValue>): Promise<TValue | null>
-  get(text: string): Promise<unknown>
-  set<TValue>(entry: FakeCacheEntry<TValue>): Promise<void>
-  set(text: string, value: unknown, ttlMs?: number): Promise<void>
-  del(request: FakeCacheRequest | string): Promise<void>
-  /** Whether a live (not expired) entry exists. */
-  has(request: FakeCacheRequest | string): boolean
-  /** Seconds left before the entry expires (rounded up); null when absent, expired or without a ttl. */
-  ttlOf(request: FakeCacheRequest | string): number | null
-  /** The texts of the live entries. */
-  keys(): string[]
-  clear(): void
-}
-
-/** The cache double; `clock` is the `FakeClock` of the spec, so `clock.advance(ms)` expires entries. */
-export declare function fakeCache(clock: { now(): Date }): FakeCache