@classytic/arc-testkit 0.6.0 → 0.7.0

package/dist/mongo.d.mts

@@ -1,9 +1,121 @@
 import { TestServerProvider } from "./pool.mjs";
 import { Connection } from "mongoose";
+/**
+ * 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.
  *
@@ -11,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.
  *
@@ -36,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, {
@@ -55,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. */
@@ -81,5 +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>;
-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 };

package/dist/mongo.mjs

@@ -1,4 +1,285 @@
-import { cpus, freemem, totalmem } from "node:os";
+import { t as registerProcessCleanup } from "./process-cleanup-1iBIS_o_.mjs";
+import { rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { cpus, freemem, tmpdir, totalmem } from "node:os";
+import { mkdir, mkdtemp, readFile, readdir, rm, stat } from "node:fs/promises";
+// src/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 = "arc-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;
+	return {
+		server,
+		ownedDirs,
+		async stop() {
+			if (stopped) return;
+			stopped = true;
+			if (await server.stop(cleanup) !== false) for (const dir of ownedDirs) removeDirSync(dir);
+		},
+		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);
+		}
+	};
+}
+/**
+* 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.
+*/
+function stopOnProcessExit(handle) {
+	return registerProcessCleanup({
+		stop: () => handle.stop(),
+		stopSync: () => handle.stopSync()
+	});
+}
 // src/mongo.ts
 /**
 * `@classytic/arc-testkit/mongo` — the Mongo adapter for the driver-agnostic pool.
@@ -138,16 +419,22 @@ function mongoServerProvider(options = {}) {
 			* half-the-machine cache default exactly where nobody is watching.
 			*/
 			const create = opts?.createOptions;
-			const server = kind === "transactional" ? await mms.MongoMemoryReplSet.create(create ?? { replSet: {
+			sweepStaleMongoMemoryDirsOnce();
+			/**
+			* Started through `launchMongoMemory`, not `create()`: it always stops
+			* with cleanup, cleans up a failed start (mongodb-memory-server keeps
+			* that dir "for investigation"), honours `TEST_MONGO_TMPDIR`, and gives
+			* the pool a synchronous `stopSync` for its process `exit` handler.
+			*/
+			const launched = kind === "transactional" ? await launchMongoMemory(mms.MongoMemoryReplSet, "replset", create ?? { replSet: {
 				count: 1,
 				storageEngine: "wiredTiger",
 				args
-			} }) : await mms.MongoMemoryServer.create(create ?? { instance: { args } });
+			} }) : await launchMongoMemory(mms.MongoMemoryServer, "standalone", create ?? { instance: { args } });
 			return {
-				uri: server.getUri(),
-				stop: async () => {
-					await server.stop();
-				}
+				uri: launched.server.getUri(),
+				stop: () => launched.stop(),
+				stopSync: () => launched.stopSync()
 			};
 		},
 		/**
@@ -225,4 +512,4 @@ function mongoServerProvider(options = {}) {
 		}
 	};
 }
-export { awaitIndexBuilds, cacheSizeGB, mongoServerProvider, mongodMemoryArgs, safePoolSize, safeWorkerCount, withDbName };
+export { MONGO_MEM_DIR_PREFIX, awaitIndexBuilds, cacheSizeGB, isPidAlive, launchMongoMemory, mongoMemoryTmpBase, mongoServerProvider, mongodMemoryArgs, safePoolSize, safeWorkerCount, staleMongoMemoryAgeMs, stopOnProcessExit, sweepStaleMongoMemoryDirs, withDbName };

package/dist/pool.d.mts

@@ -1,11 +1,17 @@
 import { TestDatabase, TestDatabaseFactory } from "@classytic/arc/testing";
 /** Which server shape a suite needs. */
-type ServerKind = "standalone" | "transactional";
+export type ServerKind = "standalone" | "transactional";
 /** A running server the pool may hand out namespaces on. */
-interface TestServerHandle {
+export interface TestServerHandle {
   /** Base connection string, WITHOUT a namespace selected. */
   readonly uri: string;
   stop(): Promise<void>;
+  /**
+   * Optional: best-effort SYNCHRONOUS stop, for a process `exit` handler where
+   * no async work completes. Without it an `exit` only starts `stop()`, the
+   * process ends before it finishes, and the server's data dir is left behind.
+   */
+  stopSync?(): void;
 }
 /**
  * What a driver must supply. Two methods, deliberately.
@@ -14,7 +20,7 @@ interface TestServerHandle {
  * is the same in every driver, so putting it here would duplicate it per driver
  * — which is precisely the failure this module exists to end.
  */
-interface TestServerProvider<TConn> {
+export interface TestServerProvider<TConn> {
   /** Human name, used only in diagnostics. */
   readonly name: string;
   /**
@@ -66,7 +72,7 @@ interface TestServerProvider<TConn> {
    */
   afterBoot?(): Promise<void>;
 }
-interface TestDatabasePoolOptions {
+export interface TestDatabasePoolOptions {
   /**
    * Env-var prefix for the cross-worker handshake. Two runs with different
    * prefixes (a spine run and a host run) can share a machine without either
@@ -144,7 +150,7 @@ interface TestDatabasePoolOptions {
   /** Escape hatch: force per-suite private servers (the unpooled behaviour). */
   readonly disabled?: boolean;
 }
-interface TestDatabasePool<TConn> {
+export interface TestDatabasePool<TConn> {
   /** Hand to `bootModuleApp({ database })`. */
   readonly factory: TestDatabaseFactory<TConn>;
   /** Wrap a boot function so it defaults to the pool. */
@@ -177,12 +183,11 @@ interface TestDatabasePool<TConn> {
     live: number;
   };
 }
-declare function createTestDatabasePool<TConn>(provider: TestServerProvider<TConn>, options?: TestDatabasePoolOptions): TestDatabasePool<TConn>;
+export declare function createTestDatabasePool<TConn>(provider: TestServerProvider<TConn>, options?: TestDatabasePoolOptions): TestDatabasePool<TConn>;
 /**
  * Publish a started server so other worker PROCESSES reuse it.
  *
  * Only a process that owns servers calls this — typically an eager
  * `globalSetup` in a run that prefers boot-cost-up-front over laziness.
  */
-declare function publishPoolServers(servers: Partial<Record<ServerKind, readonly string[]>>, envPrefix?: string): void;
-export { ServerKind, TestDatabasePool, TestDatabasePoolOptions, TestServerHandle, TestServerProvider, createTestDatabasePool, publishPoolServers };
+export declare function publishPoolServers(servers: Partial<Record<ServerKind, readonly string[]>>, envPrefix?: string): void;

package/dist/pool.mjs

@@ -1,3 +1,4 @@
+import { n as unregisterProcessCleanup, t as registerProcessCleanup } from "./process-cleanup-1iBIS_o_.mjs";
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { randomBytes } from "node:crypto";
@@ -207,35 +208,37 @@ function createTestDatabasePool(provider, options = {}) {
 	* started on a machine with less memory than the one before.
 	*
 	* `exit` handlers must be SYNCHRONOUS, so the async `stop()` is not awaited
-	* there; it is a best-effort kill on the way out. The signal handlers get to
-	* await properly, which is the path that actually matters for Ctrl-C.
+	* there; a handle with `stopSync()` (the Mongo adapter's) is killed and its
+	* data dir removed synchronously, any other gets a best-effort `stop()`.
+	* The signal handlers get to await properly, which is the path that actually
+	* matters for Ctrl-C.
+	*/
+	const processCleanup = {
+		stop: () => stopAll(),
+		stopSync: () => {
+			const handles = [...started.values(), ...privateHandles];
+			started.clear();
+			starting.clear();
+			privateHandles.clear();
+			for (const handle of handles) if (handle.stopSync) handle.stopSync();
+			else handle.stop();
+		}
+	};
+	/**
+	* Registered with the package's ONE shared process hook rather than adding
+	* listeners per pool: a suite that builds many pools would otherwise pass
+	* Node's listener limit (`MaxListenersExceededWarning`). Unregistered by
+	* `stopAll()`, re-registered on the next server this pool owns.
 	*/
-	let exitHooked = false;
 	function hookProcessExit() {
-		if (exitHooked) return;
-		exitHooked = true;
-		const onSignal = (signal) => {
-			stopAll().finally(() => {
-				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 handle of started.values()) handle.stop();
-			for (const handle of privateHandles) handle.stop();
-		});
+		registerProcessCleanup(processCleanup);
 	}
 	async function stopAll() {
 		const handles = [...started.values(), ...privateHandles];
 		started.clear();
 		starting.clear();
 		privateHandles.clear();
+		unregisterProcessCleanup(processCleanup);
 		await Promise.all(handles.map((h) => h.stop().catch(() => void 0)));
 	}
 	const factory = async (opts) => {

package/dist/process-cleanup-1iBIS_o_.mjs

@@ -0,0 +1,66 @@
+// src/process-cleanup.ts
+/** Signals that end a test run; SIGBREAK is Windows Ctrl-Break. */
+const CLEANUP_SIGNALS = [
+	"SIGINT",
+	"SIGTERM",
+	"SIGHUP",
+	"SIGBREAK"
+];
+const STATE_KEY = Symbol.for("@classytic/arc-testkit/process-cleanup");
+function state() {
+	const g = globalThis;
+	const existing = g[STATE_KEY];
+	if (existing) return existing;
+	const entries = /* @__PURE__ */ new Set();
+	const created = {
+		entries,
+		hooked: false,
+		onSignal: (signal) => {
+			const all = [...entries];
+			entries.clear();
+			unhook(created);
+			Promise.all(all.map((e) => e.stop().catch(() => void 0))).finally(() => {
+				process.kill(process.pid, signal);
+			});
+		},
+		onExit: () => {
+			const all = [...entries];
+			entries.clear();
+			unhook(created);
+			for (const e of all) try {
+				e.stopSync();
+			} catch {}
+		}
+	};
+	g[STATE_KEY] = created;
+	return created;
+}
+function hook(s) {
+	if (s.hooked) return;
+	s.hooked = true;
+	for (const signal of CLEANUP_SIGNALS) process.on(signal, s.onSignal);
+	process.on("exit", s.onExit);
+}
+function unhook(s) {
+	if (!s.hooked) return;
+	s.hooked = false;
+	for (const signal of CLEANUP_SIGNALS) process.removeListener(signal, s.onSignal);
+	process.removeListener("exit", s.onExit);
+}
+/**
+* Stop `entry` if the process ends before it is unregistered. Registering the
+* same entry twice is a no-op. Returns the unregister function for the
+* orderly path; once nothing is registered the process listeners are removed.
+*/
+function registerProcessCleanup(entry) {
+	const s = state();
+	s.entries.add(entry);
+	hook(s);
+	return () => unregisterProcessCleanup(entry);
+}
+function unregisterProcessCleanup(entry) {
+	const s = state();
+	s.entries.delete(entry);
+	if (s.entries.size === 0) unhook(s);
+}
+export { unregisterProcessCleanup as n, registerProcessCleanup as t };