@classytic/mongokit 3.43.0 → 3.44.0

package/dist/testkit/index.mjs

@@ -1,12 +1,343 @@
-import { t as createRepository } from "../create-repository-UjwPWR1z.mjs";
+import { t as createRepository } from "../create-repository-D7MQpIZo.mjs";
 import { createConnection } from "mongoose";
-//#region src/testkit/query-plan.ts
+import { rmSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, readdir, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+// src/testkit/mongo-tmp.ts
+/** Prefix mongodb-memory-server gives its data dirs (and that ours use). */
+const MONGO_MEM_DIR_PREFIX = "mongo-mem-";
+/** Replica-set keyfile dirs: no lock file to prove them dead, so never swept. */
+const KEYFILE_DIR_PREFIX = "mongo-mem-keyfile-";
+const HOUR_MS = 36e5;
+const DEFAULT_MAX_AGE_HOURS = 6;
+/** The dedicated base dir from `TEST_MONGO_TMPDIR`, resolved, or undefined. */
+function mongoMemoryTmpBase() {
+	const raw = process.env.TEST_MONGO_TMPDIR?.trim();
+	return raw ? resolve(raw) : void 0;
+}
+/** Minimum age (ms) of a dir the sweep may remove; `null` when the sweep is off. */
+function staleMongoMemoryAgeMs() {
+	const raw = process.env.TEST_MONGO_SWEEP_HOURS?.trim().toLowerCase();
+	if (raw === "0" || raw === "off" || raw === "false") return null;
+	const hours = Number(raw);
+	return raw && Number.isFinite(hours) && hours > 0 ? hours * HOUR_MS : DEFAULT_MAX_AGE_HOURS * HOUR_MS;
+}
+/** Whether a process with this pid exists. EPERM means it exists but is not ours. */
+function isPidAlive(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return err.code === "EPERM";
+	}
+}
+/** The pid in a data dir's `mongod.lock`. mongod empties it on a clean shutdown. */
+async function lockPid(dir) {
+	try {
+		const pid = Number.parseInt((await readFile(join(dir, "mongod.lock"), "utf8")).trim(), 10);
+		return Number.isInteger(pid) && pid > 0 ? pid : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Newest mtime of the dir and its direct entries. The dir's own mtime changes
+* only when an entry is added or removed; a live mongod's activity shows in its
+* files (WiredTiger.wt, sizeStorer.wt, the journal), so those count too.
+*/
+async function newestMtimeMs(dir) {
+	let newest = (await stat(dir)).mtimeMs;
+	let names = [];
+	try {
+		names = await readdir(dir);
+	} catch {}
+	for (const name of names) try {
+		const { mtimeMs } = await stat(join(dir, name));
+		if (mtimeMs > newest) newest = mtimeMs;
+	} catch {}
+	return newest;
+}
+function defaultSweepDirs() {
+	const base = mongoMemoryTmpBase();
+	return base ? [tmpdir(), base] : [tmpdir()];
+}
+/**
+* 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.
+*/
+async function sweepStaleMongoMemoryDirs(options = {}) {
+	const result = {
+		removed: [],
+		kept: [],
+		failed: []
+	};
+	const maxAgeMs = options.maxAgeMs === void 0 ? staleMongoMemoryAgeMs() : options.maxAgeMs;
+	if (maxAgeMs === null) return result;
+	const now = options.now ?? Date.now();
+	const alive = options.isAlive ?? isPidAlive;
+	const bases = new Set((options.dirs ?? defaultSweepDirs()).map((d) => resolve(d)));
+	for (const base of bases) {
+		let entries;
+		try {
+			entries = await readdir(base, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			if (!entry.isDirectory()) continue;
+			if (!entry.name.startsWith("mongo-mem-")) continue;
+			if (entry.name.startsWith(KEYFILE_DIR_PREFIX)) continue;
+			const path = join(base, entry.name);
+			try {
+				const pid = await lockPid(path);
+				if (pid !== void 0 && alive(pid)) {
+					result.kept.push({
+						path,
+						reason: "live-process"
+					});
+					continue;
+				}
+				if (now - await newestMtimeMs(path) < maxAgeMs) {
+					result.kept.push({
+						path,
+						reason: "recent"
+					});
+					continue;
+				}
+				await rm(path, {
+					recursive: true,
+					force: true,
+					maxRetries: 2,
+					retryDelay: 100
+				});
+				result.removed.push(path);
+			} catch (err) {
+				result.failed.push({
+					path,
+					error: err.message
+				});
+			}
+		}
+	}
+	return result;
+}
+let processSweep;
+/**
+* Run the sweep at most once per process, in the background. Started before a
+* process boots its first server; never awaited there, because a first sweep
+* after a long leak can have gigabytes to delete. Logs one line when it removed
+* anything, so a machine that keeps leaking is noticed.
+*/
+function sweepStaleMongoMemoryDirsOnce(label = "mongokit/testkit") {
+	processSweep ??= sweepStaleMongoMemoryDirs().then((r) => {
+		if (r.removed.length > 0) console.warn(`[${label}] removed ${r.removed.length} abandoned mongo-mem-* temp dir(s) left by killed or crashed test runs`);
+		return r;
+	}, () => ({
+		removed: [],
+		kept: [],
+		failed: []
+	}));
+	return processSweep;
+}
+async function newDataDir(base) {
+	await mkdir(base, { recursive: true });
+	return mkdtemp(join(base, MONGO_MEM_DIR_PREFIX));
+}
+/**
+* Point every member at a fresh dir under `base`, unless the caller set its own
+* `dbPath` / `instanceOpts` (then the caller owns that location).
+*/
+async function withDedicatedDataDirs(kind, opts, base, owned) {
+	if (kind === "standalone") {
+		const instance = opts.instance ?? {};
+		if (instance.dbPath !== void 0) return opts;
+		const dbPath = await newDataDir(base);
+		owned.push(dbPath);
+		return {
+			...opts,
+			instance: {
+				...instance,
+				dbPath
+			}
+		};
+	}
+	const existing = opts.instanceOpts;
+	if (existing && existing.length > 0) return opts;
+	const count = Number(opts.replSet?.count ?? 1);
+	const instanceOpts = [];
+	for (let i = 0; i < Math.max(1, count); i += 1) {
+		const dbPath = await newDataDir(base);
+		owned.push(dbPath);
+		instanceOpts.push({ dbPath });
+	}
+	return {
+		...opts,
+		instanceOpts
+	};
+}
+function instancesOf(server) {
+	const members = server.servers;
+	return Array.isArray(members) ? members : [server];
+}
+const sleepCell = new Int32Array(new SharedArrayBuffer(4));
+/** Synchronous sleep, for the `exit` path where no timer fires. */
+function sleepSync(ms) {
+	Atomics.wait(sleepCell, 0, 0, ms);
+}
+/**
+* Remove a dir synchronously, retrying for up to `timeoutMs`. A killed mongod
+* is reported gone before Windows releases its file handles, so the first
+* attempts can fail with EPERM / EBUSY.
+*/
+function removeDirSync(dir, timeoutMs = 0) {
+	const deadline = Date.now() + timeoutMs;
+	for (;;) try {
+		rmSync(dir, {
+			recursive: true,
+			force: true
+		});
+		return;
+	} catch {
+		if (Date.now() >= deadline) return;
+		sleepSync(50);
+	}
+}
+/** Block until none of `pids` is alive, at most `timeoutMs`. */
+function waitForExitSync(pids, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	while (pids.some(isPidAlive) && Date.now() < deadline) sleepSync(25);
+}
+/**
+* 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.
+*/
+async function launchMongoMemory(Ctor, kind, createOptions = {}) {
+	const base = mongoMemoryTmpBase();
+	const ownedDirs = [];
+	const opts = base ? await withDedicatedDataDirs(kind, createOptions, base, ownedDirs) : createOptions;
+	const cleanup = {
+		doCleanup: true,
+		force: ownedDirs.length > 0
+	};
+	const server = new Ctor(opts);
+	try {
+		await server.start();
+	} catch (err) {
+		await server.stop(cleanup).catch(() => void 0);
+		for (const dir of ownedDirs) removeDirSync(dir, 2e3);
+		throw err;
+	}
+	let stopped = false;
+	let stopping;
+	return {
+		server,
+		ownedDirs,
+		stop() {
+			if (stopped) return Promise.resolve();
+			stopping ??= (async () => {
+				try {
+					if (await server.stop(cleanup) === false && kind === "replset") throw new Error("[mongokit/testkit] mongodb-memory-server could not stop every replica-set member; stop() can be retried, and the process-exit fallback still covers it");
+					for (const dir of ownedDirs) removeDirSync(dir);
+					stopped = true;
+				} finally {
+					stopping = void 0;
+				}
+			})();
+			return stopping;
+		},
+		stopSync() {
+			if (stopped) return;
+			stopped = true;
+			const dirs = new Set(ownedDirs);
+			const pids = [];
+			for (const member of instancesOf(server)) {
+				const info = member.instanceInfo;
+				const pid = info?.instance?.mongodProcess?.pid;
+				if (pid) {
+					pids.push(pid);
+					try {
+						process.kill(pid, "SIGKILL");
+					} catch {}
+				}
+				if (info?.tmpDir) dirs.add(info.tmpDir);
+			}
+			waitForExitSync(pids, 5e3);
+			for (const dir of dirs) removeDirSync(dir, 5e3);
+		}
+	};
+}
+const tracked = /* @__PURE__ */ new Set();
+let exitHooked = false;
+/**
+* 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.
+*/
+function stopOnProcessExit(handle) {
+	tracked.add(handle);
+	if (!exitHooked) {
+		exitHooked = true;
+		const onSignal = (signal) => {
+			const all = [...tracked];
+			Promise.all(all.map((h) => h.stop().then(() => {
+				tracked.delete(h);
+			}, () => void 0))).finally(() => {
+				for (const h of all) {
+					if (!tracked.has(h)) continue;
+					h.stopSync();
+					tracked.delete(h);
+				}
+				process.removeListener(signal, onSignal);
+				process.kill(process.pid, signal);
+			});
+		};
+		for (const signal of [
+			"SIGINT",
+			"SIGTERM",
+			"SIGHUP",
+			"SIGBREAK"
+		]) process.once(signal, onSignal);
+		process.once("exit", () => {
+			for (const h of tracked) h.stopSync();
+			tracked.clear();
+		});
+	}
+	return () => {
+		tracked.delete(handle);
+	};
+}
+// src/testkit/query-plan.ts
 const PLANNABLE = /* @__PURE__ */ new Set([
 	"find",
 	"aggregate",
 	"count",
 	"distinct"
 ]);
+/**
+* Every command the server can explain. A write command is explained, never run again (an
+* explain does not write), so a captured `findOneAndUpdate` / `updateOne` / `deleteMany` can be
+* planned after the fact.
+*/
+const EXPLAINABLE = /* @__PURE__ */ new Set([
+	...PLANNABLE,
+	"findAndModify",
+	"update",
+	"delete"
+]);
+function commandSet(names) {
+	for (const name of names) if (!EXPLAINABLE.has(name)) throw new Error(`[mongokit/testkit] '${name}' cannot be explained (explainable: ${[...EXPLAINABLE].join(", ")})`);
+	return new Set(names);
+}
 /** Session/transport fields the server refuses inside an `explain`. */
 const STRIP = /* @__PURE__ */ new Set([
 	"lsid",
@@ -59,24 +390,80 @@ function explainable(command) {
 	return Object.fromEntries(Object.entries(command).filter(([k]) => !k.startsWith("$") && !STRIP.has(k)));
 }
 /**
+* What to send to `explain` for one recorded command. The server explains an `update` / `delete`
+* of ONE statement only, so a bulk command becomes one explain per statement.
+*/
+function explainTargets(c) {
+	const base = explainable(c.command);
+	const list = c.name === "update" ? "updates" : c.name === "delete" ? "deletes" : void 0;
+	if (list === void 0) return [base];
+	return (Array.isArray(base[list]) ? base[list] : []).map((statement) => ({
+		...base,
+		[list]: [statement]
+	}));
+}
+/**
+* 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
+* ```
+*/
+async function explainCommands(run, options) {
+	const names = commandSet(options.commands ?? [...EXPLAINABLE]);
+	const { result, commands } = await recordCommands(options.connection, run);
+	const db = options.connection.db;
+	if (!db) throw new Error("[mongokit/testkit] connection has no db handle");
+	const matched = commands.filter((c) => names.has(c.name) && c.collection !== void 0 && (!options.collections || options.collections.includes(c.collection)));
+	if (matched.length === 0) throw new Error(`[mongokit/testkit] explainCommands saw no matching command (saw: ${commands.map((c) => `${c.name}${c.collection ? `:${c.collection}` : ""}`).join(", ") || "none"})`);
+	const explains = [];
+	for (const c of matched) for (const target of explainTargets(c)) {
+		const explain = await db.command({
+			explain: target,
+			verbosity: options.verbosity ?? "executionStats"
+		});
+		explains.push({
+			...c,
+			collection: c.collection,
+			explained: target,
+			explain
+		});
+	}
+	return {
+		result,
+		explains
+	};
+}
+/**
 * 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.
 */
 async function assertQueryPlan(run, options) {
 	const forbid = options.forbid ?? ["COLLSCAN", "SORT"];
+	const gated = commandSet(options.commands ?? [...PLANNABLE]);
 	const { result, commands } = await recordCommands(options.connection, run);
 	const db = options.connection.db;
 	if (!db) throw new Error("[mongokit/testkit] connection has no db handle");
-	const plannable = commands.filter((c) => PLANNABLE.has(c.name) && c.collection !== void 0 && (!options.collections || options.collections.includes(c.collection)));
+	const plannable = commands.filter((c) => gated.has(c.name) && c.collection !== void 0 && (!options.collections || options.collections.includes(c.collection)));
 	if (plannable.length === 0) throw new Error(`[mongokit/testkit] assertQueryPlan saw no plannable command (saw: ${commands.map((c) => c.name).join(", ") || "none"})`);
 	const plans = [];
 	const failures = [];
-	for (const c of plannable) {
+	for (const { c, target } of plannable.flatMap((c) => explainTargets(c).map((target) => ({
+		c,
+		target
+	})))) {
 		const collection = c.collection;
 		const size = await db.collection(collection).countDocuments({});
 		if (size < options.minDocs) throw new Error(`[mongokit/testkit] '${collection}' holds ${size} documents, below minDocs ${options.minDocs}: the plan would not be representative`);
 		const explained = await db.command({
-			explain: explainable(c.command),
+			explain: target,
 			verbosity: "executionStats"
 		});
 		const nodes = [];
@@ -110,14 +497,23 @@ async function assertQueryPlan(run, options) {
 		plans
 	};
 }
-//#endregion
-//#region src/testkit/index.ts
-function idempotentStop(server) {
+// src/testkit/index.ts
+/**
+* Stop with cleanup; leave the process-exit list only once that SUCCEEDED. A failed
+* stop rejects, keeps the exit tracking, and a later call retries.
+*/
+function idempotentStop(launched, untrack) {
 	let stopped = false;
-	return async () => {
-		if (stopped) return;
-		stopped = true;
-		await server.stop().catch(() => void 0);
+	let stopping;
+	return () => {
+		if (stopped) return Promise.resolve();
+		stopping ??= launched.stop().then(() => {
+			stopped = true;
+			untrack();
+		}).finally(() => {
+			stopping = void 0;
+		});
+		return stopping;
 	};
 }
 /**
@@ -133,19 +529,22 @@ async function createMongoMemory(options = {}) {
 	};
 	const { MongoMemoryServer, MongoMemoryReplSet } = await import("mongodb-memory-server");
 	const dbName = options.dbName ?? "mongokit-test";
+	sweepStaleMongoMemoryDirsOnce();
 	if (options.replset) {
-		const rs = await MongoMemoryReplSet.create({ replSet: { count: 1 } });
+		const launched = await launchMongoMemory(MongoMemoryReplSet, "replset", { replSet: { count: 1 } });
+		const untrack = stopOnProcessExit(launched);
 		return {
-			uri: rs.getUri(dbName),
-			server: rs,
-			stop: idempotentStop(rs)
+			uri: launched.server.getUri(dbName),
+			server: launched.server,
+			stop: idempotentStop(launched, untrack)
 		};
 	}
-	const server = await MongoMemoryServer.create();
+	const launched = await launchMongoMemory(MongoMemoryServer, "standalone");
+	const untrack = stopOnProcessExit(launched);
 	return {
-		uri: server.getUri(dbName),
-		server,
-		stop: idempotentStop(server)
+		uri: launched.server.getUri(dbName),
+		server: launched.server,
+		stop: idempotentStop(launched, untrack)
 	};
 }
 /** Drop every document in every collection on a connection (models preserved). */
@@ -169,9 +568,9 @@ async function createTestConnection(options = {}) {
 		clear: () => clearCollections(connection),
 		close: async () => {
 			if (closed) return;
-			closed = true;
 			await connection.close().catch(() => void 0);
 			await handle.stop();
+			closed = true;
 		}
 	};
 }
@@ -246,5 +645,4 @@ function mongoMemoryBackend(options = {}) {
 		};
 	} };
 }
-//#endregion
-export { assertQueryPlan, clearCollections, createMongoMemory, createTestConnection, createTestRepository, mongoMemoryBackend, recordCommands, withMongoMemory };
+export { MONGO_MEM_DIR_PREFIX, assertQueryPlan, clearCollections, createMongoMemory, createTestConnection, createTestRepository, explainCommands, isPidAlive, launchMongoMemory, mongoMemoryBackend, mongoMemoryTmpBase, recordCommands, staleMongoMemoryAgeMs, stopOnProcessExit, sweepStaleMongoMemoryDirs, withMongoMemory };