@classytic/arc-testkit 0.5.0 → 0.7.0

package/dist/index.d.mts

@@ -1,10 +1,7 @@
 import { BootModuleAppOptions as BootModuleAppOptions$1, BootModulesInput, ModuleTestApp as ModuleTestApp$1, TestkitContext as TestkitContext$1 } from "@classytic/arc/testing";
 import { Connection } from "mongoose";
-//#region src/index.d.ts
-type TestkitContext = TestkitContext$1<Connection>;
-type ModulesInput = BootModulesInput<Connection>;
-type BootModuleAppOptions = BootModuleAppOptions$1<Connection>;
-type ModuleTestApp = ModuleTestApp$1<Connection>;
-declare function bootModuleApp(modules: ModulesInput, options?: BootModuleAppOptions): Promise<ModuleTestApp>;
-//#endregion
-export { BootModuleAppOptions, ModuleTestApp, ModulesInput, TestkitContext, bootModuleApp };
+export type TestkitContext = TestkitContext$1<Connection>;
+export type ModulesInput = BootModulesInput<Connection>;
+export type BootModuleAppOptions = BootModuleAppOptions$1<Connection>;
+export type ModuleTestApp = ModuleTestApp$1<Connection>;
+export declare function bootModuleApp(modules: ModulesInput, options?: BootModuleAppOptions): Promise<ModuleTestApp>;

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { bootModuleApp as bootModuleApp$1 } from "@classytic/arc/testing";
-//#region src/index.ts
+// src/index.ts
 /**
 * @classytic/arc-testkit — boots a REAL arc app around the module(s) under
 * test on in-memory MongoDB. The contributor contract: if your module boots
@@ -23,5 +23,4 @@ import { bootModuleApp as bootModuleApp$1 } from "@classytic/arc/testing";
 function bootModuleApp(modules, options = {}) {
 	return bootModuleApp$1(modules, options);
 }
-//#endregion
 export { bootModuleApp };

package/dist/mongo-commands.d.mts

@@ -1,7 +1,6 @@
 import { Connection } from "mongoose";
-//#region src/mongo-commands.d.ts
 type MongoClientLike = ReturnType<Connection["getClient"]>;
-interface CountCommandsOptions {
+export interface CountCommandsOptions {
   /** Count only commands against these collections. */
   readonly collections?: readonly string[];
   /** Count only these command names (`find`, `aggregate`, `insert`, …). */
@@ -9,12 +8,12 @@ interface CountCommandsOptions {
   /** Never count these command names — e.g. `createIndexes` a model may run lazily. */
   readonly ignore?: readonly string[];
 }
-interface WireCommand {
+export interface WireCommand {
   readonly command: string;
   /** The collection the command targets; `undefined` for session, transaction and admin commands. */
   readonly collection: string | undefined;
 }
-interface CommandCount<T> {
+export interface CommandCount<T> {
   readonly result: T;
   readonly total: number;
   /** Counted commands, in the order the driver sent them. */
@@ -23,7 +22,6 @@ interface CommandCount<T> {
   readonly byCollection: Readonly<Record<string, number>>;
   readonly byCommand: Readonly<Record<string, number>>;
 }
-declare function countCommands<T>(source: Connection | MongoClientLike, fn: () => Promise<T>, options?: CountCommandsOptions): Promise<CommandCount<T>>;
-declare function assertConstantCommands<T>(source: Connection | MongoClientLike, run: (size: number) => Promise<T>, sizes: readonly number[], options?: CountCommandsOptions): Promise<readonly CommandCount<T>[]>;
-//#endregion
-export { CommandCount, CountCommandsOptions, WireCommand, assertConstantCommands, countCommands };
+export declare function countCommands<T>(source: Connection | MongoClientLike, fn: () => Promise<T>, options?: CountCommandsOptions): Promise<CommandCount<T>>;
+export declare function assertConstantCommands<T>(source: Connection | MongoClientLike, run: (size: number) => Promise<T>, sizes: readonly number[], options?: CountCommandsOptions): Promise<readonly CommandCount<T>[]>;
+export {};

package/dist/mongo-commands.mjs

@@ -1,4 +1,4 @@
-//#region src/mongo-commands.ts
+// src/mongo-commands.ts
 async function countCommands(source, fn, options = {}) {
 	const client = "getClient" in source ? source.getClient() : source;
 	if (client.options.monitorCommands !== true) throw new Error("[arc-testkit] countCommands: the client was created without `monitorCommands: true` — the driver emits no command events, so every count would read 0");
@@ -50,5 +50,4 @@ function tally(keys) {
 	for (const k of keys) out[k] = (out[k] ?? 0) + 1;
 	return out;
 }
-//#endregion
 export { assertConstantCommands, countCommands };

package/dist/mongo-explain.d.mts

@@ -1,4 +1,3 @@
-//#region src/mongo-explain.d.ts
 /**
  * Read a MongoDB `explain()` result — find, aggregate, classic or SBE — as the WINNING plan's stage
  * names, the indexes it scans, and its execution stats (`executionStats` verbosity). Rejected plans
@@ -9,8 +8,17 @@
  * const explain = await Model.find({ organizationId, state: "posted" }).explain("executionStats");
  * assertIndexServed(explain, { index: "org_state_date", maxDocsExamined: 40 });
  * ```
+ *
+ * `explainCaptured` explains the query a piece of code ACTUALLY sends (a repository method, a
+ * plugin-built filter) instead of a copy of it: it runs the code with command monitoring, captures
+ * the matching command and explains exactly that.
+ *
+ * ```ts
+ * const { explain } = await explainCaptured(conn, () => timers.claim(now), { collection: "timers", commands: ["findAndModify"] });
+ * assertIndexServed(explain, { index: "state_due", maxDocsExamined: 6 });
+ * ```
  */
-interface ExplainSummary {
+export interface ExplainSummary {
   /** Stage names of the winning plan(s), outermost first. */
   readonly stages: readonly string[];
   /** Index names the winning plan scans (`_id_` for an id lookup). */
@@ -20,7 +28,7 @@ interface ExplainSummary {
   readonly keysExamined: number | undefined;
   readonly returned: number | undefined;
 }
-interface IndexServedOptions {
+export interface IndexServedOptions {
   /** Every one of these must be scanned. */
   readonly index?: string | readonly string[];
   /** Every one of these stages must appear — e.g. `OR` for a `$or` served arm by arm. */
@@ -28,7 +36,49 @@ interface IndexServedOptions {
   /** Ceiling on `totalDocsExamined`; requires `executionStats` verbosity. */
   readonly maxDocsExamined?: number;
 }
-declare function summarizeExplain(explain: unknown): ExplainSummary;
-declare function assertIndexServed(explain: unknown, options?: IndexServedOptions): ExplainSummary;
-//#endregion
-export { ExplainSummary, IndexServedOptions, assertIndexServed, summarizeExplain };
+export declare function summarizeExplain(explain: unknown): ExplainSummary;
+export declare function assertIndexServed(explain: unknown, options?: IndexServedOptions): ExplainSummary;
+/** A `commandStarted` event, as far as `explainCaptured` reads it. */
+export interface CommandStartedLike {
+  readonly commandName: string;
+  readonly databaseName: string;
+  readonly command: Readonly<Record<string, unknown>>;
+}
+/** A MongoDB driver client (`connection.getClient()` of mongoose, or a `MongoClient`). */
+export interface MonitoredClientLike {
+  readonly options: {
+    readonly monitorCommands?: boolean;
+  };
+  on(event: "commandStarted", listener: (event: CommandStartedLike) => void): unknown;
+  off(event: "commandStarted", listener: (event: CommandStartedLike) => void): unknown;
+  db(name: string): {
+    command(command: Record<string, unknown>): Promise<unknown>;
+  };
+}
+export interface ExplainCapturedOptions {
+  /** The collection the command targets. */
+  readonly collection: string;
+  /** Command names to capture. Default: `find`, `aggregate`, `findAndModify`, `count`, `distinct`, `update`, `delete`. */
+  readonly commands?: readonly string[];
+  /** Which captured command to explain (0-based). Required when more than one matches. */
+  readonly index?: number;
+  /** Default: `executionStats` (what `maxDocsExamined` needs). */
+  readonly verbosity?: "queryPlanner" | "executionStats" | "allPlansExecution";
+}
+export interface ExplainCaptured<T> {
+  readonly result: T;
+  /** The explain of the chosen command, ready for `assertIndexServed`. */
+  readonly explain: unknown;
+  /** The chosen command as the driver sent it, minus session and transport fields. */
+  readonly command: Readonly<Record<string, unknown>>;
+  /** Every matching command, in the order sent (same fields removed). */
+  readonly captured: readonly Readonly<Record<string, unknown>>[];
+}
+/**
+ * Runs `run` with command monitoring, captures the commands it sends to `collection` and explains
+ * the chosen one (the explain never applies a write). Refuses a client without
+ * `monitorCommands: true`, a run that sent no matching command, and an ambiguous capture.
+ */
+export declare function explainCaptured<T>(source: {
+  getClient(): MonitoredClientLike;
+} | MonitoredClientLike, run: () => Promise<T>, options: ExplainCapturedOptions): Promise<ExplainCaptured<T>>;

package/dist/mongo-explain.mjs

@@ -1,4 +1,4 @@
-//#region src/mongo-explain.ts
+// src/mongo-explain.ts
 /** Keys whose subtree is a rejected alternative or a query predicate — never plan structure. */
 const SKIPPED = /* @__PURE__ */ new Set([
 	"rejectedPlans",
@@ -57,11 +57,80 @@ function assertIndexServed(explain, options = {}) {
 	}
 	return plan;
 }
+const EXPLAINABLE = [
+	"find",
+	"aggregate",
+	"findAndModify",
+	"count",
+	"distinct",
+	"update",
+	"delete"
+];
+/** Fields the driver adds to a command that an `explain` wrapper must not carry. */
+const TRANSPORT = /* @__PURE__ */ new Set([
+	"lsid",
+	"$db",
+	"$clusterTime",
+	"$readPreference",
+	"txnNumber",
+	"autocommit",
+	"startTransaction",
+	"readConcern",
+	"writeConcern",
+	"apiVersion",
+	"apiStrict",
+	"apiDeprecationErrors"
+]);
+/**
+* Runs `run` with command monitoring, captures the commands it sends to `collection` and explains
+* the chosen one (the explain never applies a write). Refuses a client without
+* `monitorCommands: true`, a run that sent no matching command, and an ambiguous capture.
+*/
+async function explainCaptured(source, run, options) {
+	const client = "getClient" in source ? source.getClient() : source;
+	const fail = (msg) => {
+		throw new Error(`[arc-testkit] explainCaptured: ${msg}`);
+	};
+	if (client.options.monitorCommands !== true) fail("the client was created without `monitorCommands: true` — the driver emits no command events, so nothing can be captured");
+	const names = options.commands ?? EXPLAINABLE;
+	const seen = [];
+	const onStarted = (e) => {
+		if (!names.includes(e.commandName) || e.command[e.commandName] !== options.collection) return;
+		const command = {};
+		for (const [key, value] of Object.entries(e.command)) if (!TRANSPORT.has(key)) command[key] = value;
+		seen.push({
+			db: e.databaseName,
+			command
+		});
+	};
+	client.on("commandStarted", onStarted);
+	let result;
+	try {
+		result = await run();
+	} finally {
+		client.off("commandStarted", onStarted);
+	}
+	const what = `${names.join("/")} on "${options.collection}"`;
+	if (seen.length === 0) fail(`run sent no ${what}`);
+	if (options.index === void 0 && seen.length > 1) fail(`run sent ${seen.length} ${what} (${seen.map((s) => Object.keys(s.command)[0]).join(", ")}): pass \`index\` to pick one`);
+	const chosen = seen[options.index ?? 0];
+	if (chosen === void 0) fail(`no captured command at index ${options.index} (${seen.length} captured)`);
+	const { db, command } = chosen;
+	const explain = await client.db(db).command({
+		explain: command,
+		verbosity: options.verbosity ?? "executionStats"
+	});
+	return {
+		result,
+		explain,
+		command,
+		captured: seen.map((s) => s.command)
+	};
+}
 function isRecord(value) {
 	return typeof value === "object" && value !== null;
 }
 function numberOr(value) {
 	return typeof value === "number" ? value : void 0;
 }
-//#endregion
-export { assertIndexServed, summarizeExplain };
+export { assertIndexServed, explainCaptured, summarizeExplain };

package/dist/mongo.d.mts

@@ -1,10 +1,121 @@
 import { TestServerProvider } from "./pool.mjs";
 import { Connection } from "mongoose";
-//#region src/mongo.d.ts
+/**
+ * mongodb-memory-server temp-dir hygiene: start, stop and sweep so that a test
+ * run that is killed, crashes or times out does not leave its data dir behind.
+ *
+ * ## Why this exists
+ *
+ * mongodb-memory-server creates `mongo-mem-XXXXXX` under `os.tmpdir()` for every
+ * server and removes it in `stop()` (`doCleanup: true` is the default since v9).
+ * That only covers the orderly path. A run killed from an IDE, a CI cancel, a
+ * worker terminated on timeout or a hard crash never reaches `stop()`, and the
+ * dir (a full WiredTiger data set, ~15 MB at minimum) stays forever. On one
+ * development machine that came to 3,698 dirs, about 57 GB, in `%TEMP%`.
+ * mongodb-memory-server also stops a server that FAILED to start with
+ * `doCleanup: false` ("for investigation"), so a failed boot leaks one too.
+ *
+ * Three measures, each one usable on its own:
+ *
+ * 1. `launchMongoMemory` always stops with cleanup, cleans up after a failed
+ *    start, and has a synchronous `stopSync()` for a process `exit` handler,
+ *    where nothing async completes.
+ * 2. `sweepStaleMongoMemoryDirs` removes `mongo-mem-*` dirs that are old AND
+ *    whose `mongod.lock` names no live process. Both conditions, always: a live
+ *    mongod rewrites its WiredTiger files on every checkpoint (60 s), so its dir
+ *    is never old, and its lock names a live pid.
+ * 3. `TEST_MONGO_TMPDIR` puts the data dirs under a dedicated base (for example
+ *    a project-local `.tmp`), so whatever does leak is contained and visible.
+ *
+ * Environment:
+ * - `TEST_MONGO_TMPDIR`: base dir for new data dirs. Unset: mongodb-memory-server's
+ *   own default (`os.tmpdir()`).
+ * - `TEST_MONGO_SWEEP_HOURS`: minimum age of a dir the sweep may remove. Default 6.
+ *   `0`, `off` or `false` turns the sweep off.
+ */
+/** Prefix mongodb-memory-server gives its data dirs (and that ours use). */
+export declare const MONGO_MEM_DIR_PREFIX = "mongo-mem-";
+/** The dedicated base dir from `TEST_MONGO_TMPDIR`, resolved, or undefined. */
+export declare function mongoMemoryTmpBase(): string | undefined;
+/** Minimum age (ms) of a dir the sweep may remove; `null` when the sweep is off. */
+export declare function staleMongoMemoryAgeMs(): number | null;
+/** Whether a process with this pid exists. EPERM means it exists but is not ours. */
+export declare function isPidAlive(pid: number): boolean;
+interface SweepMongoMemoryOptions {
+  /** Dirs to scan. Default: `os.tmpdir()` plus `TEST_MONGO_TMPDIR` when set. */
+  readonly dirs?: readonly string[];
+  /** Minimum age in ms; `null` turns the sweep off. Default: `staleMongoMemoryAgeMs()`. */
+  readonly maxAgeMs?: number | null;
+  /** Clock, for tests. Default `Date.now()`. */
+  readonly now?: number;
+  /** Liveness probe, for tests. Default `isPidAlive`. */
+  readonly isAlive?: (pid: number) => boolean;
+}
+interface SweepMongoMemoryResult {
+  readonly removed: string[];
+  readonly kept: Array<{
+    path: string;
+    reason: "live-process" | "recent";
+  }>;
+  readonly failed: Array<{
+    path: string;
+    error: string;
+  }>;
+}
+/**
+ * Remove abandoned `mongo-mem-*` data dirs.
+ *
+ * A dir is removed only when BOTH hold: its `mongod.lock` names no live process
+ * (or is empty or missing), and nothing in it changed for `maxAgeMs`. Keyfile
+ * dirs and anything without the prefix are never touched. Errors are collected,
+ * never thrown: a sweep must not fail a test run.
+ */
+export declare function sweepStaleMongoMemoryDirs(options?: SweepMongoMemoryOptions): Promise<SweepMongoMemoryResult>;
+/** The parts of `MongoMemoryServer` / `MongoMemoryReplSet` this module uses. */
+interface MmsServerLike {
+  getUri(dbName?: string): string;
+  start(): Promise<unknown>;
+  stop(cleanup?: {
+    doCleanup?: boolean;
+    force?: boolean;
+  }): Promise<unknown>;
+}
+type MongoMemoryKind = "standalone" | "replset";
+interface LaunchedMongoMemory<S extends MmsServerLike> {
+  readonly server: S;
+  /** Data dirs this module created under `TEST_MONGO_TMPDIR` (empty when unset). */
+  readonly ownedDirs: readonly string[];
+  /** Stop and remove the data dirs. Idempotent. */
+  stop(): Promise<void>;
+  /**
+   * Best-effort SYNCHRONOUS stop for a process `exit` handler, where no async
+   * work completes: kill the mongod processes and remove their data dirs.
+   * Idempotent, never throws.
+   */
+  stopSync(): void;
+}
+/**
+ * Create and start a `MongoMemoryServer` (`standalone`) or `MongoMemoryReplSet`
+ * (`replset`) with the cleanup guarantees described at the top of this file.
+ *
+ * `Ctor` is the class itself, so a caller that loads mongodb-memory-server its
+ * own way (by resolved path, through an alias) keeps doing so.
+ */
+export declare function launchMongoMemory<S extends MmsServerLike>(Ctor: new (opts?: never) => S, kind: MongoMemoryKind, createOptions?: Record<string, unknown>): Promise<LaunchedMongoMemory<S>>;
+/**
+ * Stop a launched server when the process ends without its teardown: Ctrl-C /
+ * SIGTERM stop it properly, then re-raise so the exit code stays truthful; an
+ * `exit` (including an uncaught exception) kills mongod and removes the dir
+ * synchronously. Returns an untrack function for the orderly path.
+ *
+ * Uses the package's ONE shared process hook, so tracking many servers adds no
+ * listeners beyond one per event.
+ */
+export declare function stopOnProcessExit(handle: LaunchedMongoMemory<MmsServerLike>): () => void;
 /** WiredTiger cache per server, in GB. 0.25 is mongod's own floor. */
-declare function cacheSizeGB(): number;
+export declare function cacheSizeGB(): number;
 /** mongod CLI args that bound a test server's footprint. */
-declare function mongodMemoryArgs(): string[];
+export declare function mongodMemoryArgs(): string[];
 /**
  * Worker count bounded by cores AND memory.
  *
@@ -12,11 +123,11 @@ declare function mongodMemoryArgs(): string[];
  * app plus every server it holds live. `envVar` lets a host keep its existing
  * override name rather than forcing a rename through every CI config.
  */
-declare function safeWorkerCount(envVar?: string): number;
+export declare function safeWorkerCount(envVar?: string): number;
 /** How many servers the run may boot, bounded by FREE memory at call time. */
-declare function safePoolSize(requested: number): number;
+export declare function safePoolSize(requested: number): number;
 /** Splice a database name into a mongodb:// URI, preserving its query string. */
-declare function withDbName(baseUri: string, dbName: string): string;
+export declare function withDbName(baseUri: string, dbName: string): string;
 /**
  * Block until every registered model's index build has finished.
  *
@@ -37,14 +148,14 @@ declare function withDbName(baseUri: string, dbName: string): string;
  * that does not exist, and it would pass for the wrong reason — precisely the
  * failure this function was added to remove.
  */
-declare function awaitIndexBuilds(connection?: {
+export declare function awaitIndexBuilds(connection?: {
   readyState: number;
   models: Record<string, {
     init(): Promise<unknown>;
   }>;
 }): Promise<void>;
 /** The subset of the mongoose module this adapter uses. */
-interface MongooseLike {
+export interface MongooseLike {
   connection: {
     readyState: number;
     models: Record<string, {
@@ -56,7 +167,7 @@ interface MongooseLike {
   connect(uri: string): Promise<unknown>;
   disconnect(): Promise<unknown>;
 }
-interface MongoServerProviderOptions {
+export interface MongoServerProviderOptions {
   /** Extra mongod args, appended after the memory bounds. */
   readonly args?: readonly string[];
   /** Await index builds after each lease connects. Default true — see above. */
@@ -82,6 +193,5 @@ interface MongoServerProviderOptions {
  * transactions, and a strict superset of a standalone. That is what lets the
  * pool serve both kinds from one process when sharing is on.
  */
-declare function mongoServerProvider(options?: MongoServerProviderOptions): TestServerProvider<Connection>;
-//#endregion
-export { MongoServerProviderOptions, MongooseLike, awaitIndexBuilds, cacheSizeGB, mongoServerProvider, mongodMemoryArgs, safePoolSize, safeWorkerCount, withDbName };
+export declare function mongoServerProvider(options?: MongoServerProviderOptions): TestServerProvider<Connection>;
+export type { LaunchedMongoMemory, MmsServerLike, MongoMemoryKind, SweepMongoMemoryOptions, SweepMongoMemoryResult };