@classytic/mongokit 3.43.1 → 3.44.0

package/dist/testkit/index.d.mts

@@ -1,15 +1,126 @@
-import { r as Repository } from "../Repository-DnL4xk5w.mjs";
-import { n as CreateRepositoryConfig } from "../create-repository-CJtVdwig.mjs";
+import { n as CreateRepositoryConfig } from "../create-repository-BOFUYj1l.mjs";
+import { r as Repository } from "../Repository-B6oL6OMv.mjs";
 import { Connection, Model, Schema } from "mongoose";
 import { MongoMemoryReplSet, MongoMemoryServer } from "mongodb-memory-server";
-//#region src/testkit/query-plan.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 once it succeeded; a failed stop
+   * rejects and can be retried, and `stopSync()` stays effective until one succeeds.
+   */
+  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.
+ */
+export declare function stopOnProcessExit(handle: LaunchedMongoMemory<MmsServerLike>): () => void;
 interface RecordedCommand {
   name: string;
   collection: string | undefined;
   command: Record<string, unknown>;
 }
 /** Run `fn` and return every command it started on `connection` (in start order). */
-declare function recordCommands<T>(connection: Connection, fn: () => Promise<T>): Promise<{
+export declare function recordCommands<T>(connection: Connection, fn: () => Promise<T>): Promise<{
   result: T;
   commands: RecordedCommand[];
 }>;
@@ -23,6 +134,12 @@ interface QueryPlanOptions {
   leadingKeys?: readonly string[];
   /** Only gate commands on these collections (default: every plannable command). */
   collections?: readonly string[];
+  /**
+   * Command names to gate. Default the reads: `find`, `aggregate`, `count`, `distinct`. Add
+   * `findAndModify`, `update` or `delete` to gate a write's match as well (explained, never
+   * re-run). Any other name throws.
+   */
+  commands?: readonly string[];
 }
 interface PlannedCommand {
   name: string;
@@ -30,17 +147,53 @@ interface PlannedCommand {
   stages: string[];
   indexes: string[][];
 }
+interface ExplainCommandsOptions {
+  connection: Connection;
+  /**
+   * Command names to explain. Default every explainable one: `find`, `aggregate`, `count`,
+   * `distinct`, `findAndModify` (`findOneAndUpdate`, `findOneAndDelete`, ...), `update`,
+   * `delete`. Any other name throws.
+   */
+  commands?: readonly string[];
+  /** Only explain commands on these collections (default: every collection). */
+  collections?: readonly string[];
+  /** Explain verbosity. Default `'executionStats'`. */
+  verbosity?: 'queryPlanner' | 'executionStats' | 'allPlansExecution';
+}
+interface ExplainedCommand extends RecordedCommand {
+  collection: string;
+  /** The command as handed to `explain`: session fields stripped, one statement for update / delete. */
+  explained: Record<string, unknown>;
+  /** The server's explain output as returned (`queryPlanner`, `executionStats`, ...). */
+  explain: Record<string, unknown>;
+}
+/**
+ * Run `run` and explain the commands it ACTUALLY sent, so a test plans the filter, sort and
+ * update a repository method or plugin built (a `leasePlugin` claim, a tenant-scoped read)
+ * rather than a copy of it. The explains run after `run` returns and never write. Throws when no
+ * command matched, so a renamed collection cannot pass vacuously. The connection must be opened
+ * with `{ monitorCommands: true }`.
+ *
+ * ```ts
+ * const { explains } = await explainCommands(() => repo.lease({ leaseFor, leasedBy }), {
+ *   connection, commands: ['findAndModify'], collections: ['jobs'],
+ * });
+ * explains[0].explain.executionStats; // what the claim examined
+ * ```
+ */
+export declare function explainCommands<T>(run: () => Promise<T>, options: ExplainCommandsOptions): Promise<{
+  result: T;
+  explains: ExplainedCommand[];
+}>;
 /**
  * Run `run`, explain every read it issued and throw on a forbidden stage, a wrong leading index,
  * an undersized fixture, or no plannable command at all. Returns what each command used.
  */
-declare function assertQueryPlan<T>(run: () => Promise<T>, options: QueryPlanOptions): Promise<{
+export declare function assertQueryPlan<T>(run: () => Promise<T>, options: QueryPlanOptions): Promise<{
   result: T;
   plans: PlannedCommand[];
 }>;
-//#endregion
-//#region src/testkit/index.d.ts
-interface MongoMemoryOptions {
+export interface MongoMemoryOptions {
   /**
    * Boot a single-node replica set instead of a standalone mongod. Required for
    * any code that opens a `session.startTransaction()` — a standalone server
@@ -62,12 +215,16 @@ interface MongoMemoryOptions {
    */
   uri?: string;
 }
-interface MongoMemoryHandle {
+export interface MongoMemoryHandle {
   /** Connection string for the running (or external) server. */
   uri: string;
   /** The in-memory server; `undefined` when an external `uri` is used. */
   server?: MongoMemoryServer | MongoMemoryReplSet;
-  /** Stop the in-memory server. No-op for an external URI. Idempotent. */
+  /**
+   * Stop the in-memory server. No-op for an external URI. Idempotent once it
+   * succeeded; a failed stop rejects and can be retried, and the server stays
+   * on the process-exit list (killed synchronously on exit) until one succeeds.
+   */
   stop(): Promise<void>;
 }
 /**
@@ -75,8 +232,8 @@ interface MongoMemoryHandle {
  * a `stop()` teardown. Prefer `createTestConnection` / `createTestRepository`
  * unless you need the server without a mongoose connection.
  */
-declare function createMongoMemory(options?: MongoMemoryOptions): Promise<MongoMemoryHandle>;
-interface TestConnection {
+export declare function createMongoMemory(options?: MongoMemoryOptions): Promise<MongoMemoryHandle>;
+export interface TestConnection {
   /** An isolated mongoose connection (never the global `mongoose.connection`). */
   connection: Connection;
   uri: string;
@@ -86,13 +243,13 @@ interface TestConnection {
   close(): Promise<void>;
 }
 /** Drop every document in every collection on a connection (models preserved). */
-declare function clearCollections(connection: Connection): Promise<void>;
+export declare function clearCollections(connection: Connection): Promise<void>;
 /**
  * Start (or resolve) a server AND open an isolated mongoose connection over it.
  * Each call gets its own connection — model registries are per-connection, so
  * repeated boots in one process never collide.
  */
-declare function createTestConnection(options?: MongoMemoryOptions): Promise<TestConnection>;
+export declare function createTestConnection(options?: MongoMemoryOptions): Promise<TestConnection>;
 /**
  * Scoped harness: start a connection, run `fn`, and tear down in a `finally`
  * even if `fn` throws.
@@ -104,8 +261,8 @@ declare function createTestConnection(options?: MongoMemoryOptions): Promise<Tes
  * });
  * ```
  */
-declare function withMongoMemory<T>(fn: (ctx: TestConnection) => Promise<T> | T, options?: MongoMemoryOptions): Promise<T>;
-interface CreateTestRepositoryOptions<TDoc> extends MongoMemoryOptions {
+export declare function withMongoMemory<T>(fn: (ctx: TestConnection) => Promise<T> | T, options?: MongoMemoryOptions): Promise<T>;
+export interface CreateTestRepositoryOptions<TDoc> extends MongoMemoryOptions {
   /** Model / collection name (unique per test to avoid cross-file collisions). */
   name: string;
   /** Mongoose schema for the model. */
@@ -113,7 +270,7 @@ interface CreateTestRepositoryOptions<TDoc> extends MongoMemoryOptions {
   /** mongokit `createRepository` config — tenant, softDelete, plugins, cache… */
   config?: CreateRepositoryConfig;
 }
-interface TestRepository<TDoc> {
+export interface TestRepository<TDoc> {
   /** A live mongokit repository over an in-memory collection. */
   repository: Repository<TDoc>;
   /** The underlying mongoose model (bound to the isolated connection). */
@@ -137,9 +294,9 @@ interface TestRepository<TDoc> {
  * await t.close();
  * ```
  */
-declare function createTestRepository<TDoc>(options: CreateTestRepositoryOptions<TDoc>): Promise<TestRepository<TDoc>>;
+export declare function createTestRepository<TDoc>(options: CreateTestRepositoryOptions<TDoc>): Promise<TestRepository<TDoc>>;
 /** The context a module receives from the Mongo backend (live connection + URI). */
-interface MongoTestContext {
+export interface MongoTestContext {
   connection: Connection;
   uri: string;
 }
@@ -148,7 +305,7 @@ interface MongoTestContext {
  * a `TestBackend<MongoTestContext>` — no import of arc-testkit, so mongokit
  * never depends on it (one-way: arc-testkit consumes this by shape).
  */
-interface MongoMemoryBackend {
+export interface MongoMemoryBackend {
   setup(): Promise<{
     ctx: MongoTestContext;
     teardown: () => Promise<void>;
@@ -167,6 +324,5 @@ interface MongoMemoryBackend {
  * );
  * ```
  */
-declare function mongoMemoryBackend(options?: MongoMemoryOptions): MongoMemoryBackend;
-//#endregion
-export { CreateTestRepositoryOptions, MongoMemoryBackend, MongoMemoryHandle, MongoMemoryOptions, MongoTestContext, type PlannedCommand, type QueryPlanOptions, type RecordedCommand, TestConnection, TestRepository, assertQueryPlan, clearCollections, createMongoMemory, createTestConnection, createTestRepository, mongoMemoryBackend, recordCommands, withMongoMemory };
+export declare function mongoMemoryBackend(options?: MongoMemoryOptions): MongoMemoryBackend;
+export type { ExplainCommandsOptions, ExplainedCommand, LaunchedMongoMemory, MmsServerLike, MongoMemoryKind, PlannedCommand, QueryPlanOptions, RecordedCommand, SweepMongoMemoryOptions, SweepMongoMemoryResult };