@classytic/arc-testkit 0.4.0 → 0.5.0

package/README.md

@@ -60,6 +60,20 @@ const t = await bootModuleApp(mods, {
 | `TestkitContext` | what a module factory receives: `{ connection, mongoUri }` |
 | `BootModuleAppOptions` | `{ replset?, app?, backend? }` |
 
+## Cost and plan assertions (MongoDB)
+
+```ts
+import { assertConstantCommands, countCommands } from '@classytic/arc-testkit/mongo-commands';
+import { assertIndexServed } from '@classytic/arc-testkit/mongo-explain';
+
+// What the driver sent (the connection needs `monitorCommands: true` — it refuses otherwise).
+const { total, byCollection } = await countCommands(conn, () => placeOrder(), { collections: ['orders'] });
+// Same commands at every size, and at least one: a per-item read fails here.
+await assertConstantCommands(conn, (n) => reader.page(n), [5, 50]);
+// No COLLSCAN, an index scanned, optionally a named one and a docs-examined ceiling.
+assertIndexServed(await Model.find(filter).explain('executionStats'), { index: 'org_state', maxDocsExamined: 40 });
+```
+
 ## License
 
 MIT © Classytic

package/dist/mongo-commands.d.mts

@@ -0,0 +1,29 @@
+import { Connection } from "mongoose";
+//#region src/mongo-commands.d.ts
+type MongoClientLike = ReturnType<Connection["getClient"]>;
+interface CountCommandsOptions {
+  /** Count only commands against these collections. */
+  readonly collections?: readonly string[];
+  /** Count only these command names (`find`, `aggregate`, `insert`, …). */
+  readonly commands?: readonly string[];
+  /** Never count these command names — e.g. `createIndexes` a model may run lazily. */
+  readonly ignore?: readonly string[];
+}
+interface WireCommand {
+  readonly command: string;
+  /** The collection the command targets; `undefined` for session, transaction and admin commands. */
+  readonly collection: string | undefined;
+}
+interface CommandCount<T> {
+  readonly result: T;
+  readonly total: number;
+  /** Counted commands, in the order the driver sent them. */
+  readonly commands: readonly WireCommand[];
+  /** Counts keyed by collection (`(none)` for commands without one). */
+  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 };

package/dist/mongo-commands.mjs

@@ -0,0 +1,54 @@
+//#region 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");
+	const commands = [];
+	const onStarted = (e) => {
+		const collection = collectionOf(e.commandName, e.command);
+		if (options.ignore?.includes(e.commandName)) return;
+		if (options.commands && !options.commands.includes(e.commandName)) return;
+		if (options.collections && (collection === void 0 || !options.collections.includes(collection))) return;
+		commands.push({
+			command: e.commandName,
+			collection
+		});
+	};
+	client.on("commandStarted", onStarted);
+	let result;
+	try {
+		result = await fn();
+	} finally {
+		client.off("commandStarted", onStarted);
+	}
+	return {
+		result,
+		total: commands.length,
+		commands,
+		byCollection: tally(commands.map((c) => c.collection ?? "(none)")),
+		byCommand: tally(commands.map((c) => c.command))
+	};
+}
+async function assertConstantCommands(source, run, sizes, options = {}) {
+	if (new Set(sizes).size < 2) throw new Error("[arc-testkit] assertConstantCommands: needs at least two distinct sizes");
+	const counts = [];
+	for (const size of sizes) counts.push(await countCommands(source, () => run(size), options));
+	const shape = (c) => c.commands.map((w) => `${w.collection ?? "(none)"}.${w.command}`).join(", ");
+	const [first] = counts;
+	if (!first || first.total === 0) throw new Error(`[arc-testkit] assertConstantCommands: size ${sizes[0]} sent no counted command — the measurement saw nothing`);
+	if (counts.some((c) => shape(c) !== shape(first))) {
+		const lines = counts.map((c, i) => `  at ${sizes[i]}: ${c.total} [${shape(c)}]`).join("\n");
+		throw new Error(`[arc-testkit] assertConstantCommands: the commands grow with the size\n${lines}`);
+	}
+	return counts;
+}
+function collectionOf(name, command) {
+	const target = name === "getMore" ? command.collection : command[name];
+	return typeof target === "string" ? target : void 0;
+}
+function tally(keys) {
+	const out = {};
+	for (const k of keys) out[k] = (out[k] ?? 0) + 1;
+	return out;
+}
+//#endregion
+export { assertConstantCommands, countCommands };

package/dist/mongo-explain.d.mts

@@ -0,0 +1,34 @@
+//#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
+ * and query predicates are never read. `assertIndexServed` fails on a COLLSCAN, on a plan scanning
+ * no index (an explain of an empty or missing collection), and on every option not met.
+ *
+ * ```ts
+ * const explain = await Model.find({ organizationId, state: "posted" }).explain("executionStats");
+ * assertIndexServed(explain, { index: "org_state_date", maxDocsExamined: 40 });
+ * ```
+ */
+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). */
+  readonly indexes: readonly string[];
+  /** From the first `executionStats` block; `undefined` under `queryPlanner` verbosity. */
+  readonly docsExamined: number | undefined;
+  readonly keysExamined: number | undefined;
+  readonly returned: number | undefined;
+}
+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. */
+  readonly stages?: readonly string[];
+  /** 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 };

package/dist/mongo-explain.mjs

@@ -0,0 +1,67 @@
+//#region src/mongo-explain.ts
+/** Keys whose subtree is a rejected alternative or a query predicate — never plan structure. */
+const SKIPPED = /* @__PURE__ */ new Set([
+	"rejectedPlans",
+	"allPlansExecution",
+	"command",
+	"parsedQuery",
+	"filter",
+	"slotBasedPlan"
+]);
+const ID_LOOKUPS = /* @__PURE__ */ new Set(["IDHACK", "EXPRESS_IDHACK"]);
+function summarizeExplain(explain) {
+	const stages = [];
+	const indexes = [];
+	let stats;
+	const walk = (node, inPlan) => {
+		if (Array.isArray(node)) {
+			for (const item of node) walk(item, inPlan);
+			return;
+		}
+		if (!isRecord(node)) return;
+		if (inPlan && typeof node.stage === "string") {
+			stages.push(node.stage);
+			if (typeof node.indexName === "string") indexes.push(node.indexName);
+			else if (ID_LOOKUPS.has(node.stage)) indexes.push("_id_");
+		}
+		for (const [key, value] of Object.entries(node)) {
+			if (SKIPPED.has(key)) continue;
+			if (key === "executionStats" && isRecord(value) && typeof value.totalDocsExamined === "number") stats ??= value;
+			walk(value, inPlan || key === "winningPlan");
+		}
+	};
+	walk(explain, false);
+	return {
+		stages,
+		indexes: [...new Set(indexes)],
+		docsExamined: numberOr(stats?.totalDocsExamined),
+		keysExamined: numberOr(stats?.totalKeysExamined),
+		returned: numberOr(stats?.nReturned)
+	};
+}
+function assertIndexServed(explain, options = {}) {
+	const plan = summarizeExplain(explain);
+	const fail = (msg) => {
+		throw new Error(`[arc-testkit] assertIndexServed: ${msg} — plan [${plan.stages.join(" > ")}], indexes [${plan.indexes.join(", ")}]`);
+	};
+	if (plan.stages.length === 0) fail("no winning plan found — pass the result of explain()");
+	if (plan.stages.includes("COLLSCAN")) fail("the plan scans the collection");
+	if (plan.indexes.length === 0) fail("the plan scans no index — is the collection empty or missing?");
+	const unused = (typeof options.index === "string" ? [options.index] : options.index ?? []).filter((i) => !plan.indexes.includes(i));
+	if (unused.length > 0) fail(`index ${unused.map((i) => `"${i}"`).join(", ")} is not scanned`);
+	const absent = (options.stages ?? []).filter((s) => !plan.stages.includes(s));
+	if (absent.length > 0) fail(`stage ${absent.join(", ")} is not in the plan`);
+	if (options.maxDocsExamined !== void 0) {
+		if (plan.docsExamined === void 0) fail("maxDocsExamined needs explain('executionStats')");
+		else if (plan.docsExamined > options.maxDocsExamined) fail(`examined ${plan.docsExamined} documents, ceiling ${options.maxDocsExamined}`);
+	}
+	return plan;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function numberOr(value) {
+	return typeof value === "number" ? value : void 0;
+}
+//#endregion
+export { assertIndexServed, summarizeExplain };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc-testkit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Boot a real @classytic/arc app around the module(s) under test on in-memory MongoDB — the ecosystem test harness. Thin Mongo-typed wrapper over @classytic/arc/testing (arc 2.22+). If your arc module boots green here, it composes into any arc host.",
   "type": "module",
   "exports": {
@@ -15,6 +15,14 @@
     "./mongo": {
       "types": "./dist/mongo.d.mts",
       "default": "./dist/mongo.mjs"
+    },
+    "./mongo-commands": {
+      "types": "./dist/mongo-commands.d.mts",
+      "default": "./dist/mongo-commands.mjs"
+    },
+    "./mongo-explain": {
+      "types": "./dist/mongo-explain.d.mts",
+      "default": "./dist/mongo-explain.mjs"
     }
   },
   "main": "./dist/index.mjs",
@@ -41,7 +49,7 @@
     "mongodb-memory-server": ">=10.0.0"
   },
   "peerDependencies": {
-    "@classytic/arc": ">=2.33.0",
+    "@classytic/arc": ">=2.43.0",
     "mongoose": ">=9.4.1"
   },
   "keywords": [