@classytic/mongokit 3.40.0 → 3.40.1

package/dist/testkit/index.d.mts

@@ -1,7 +1,44 @@
-import { r as Repository } from "../Repository-CR8Y9g2E.mjs";
-import { n as CreateRepositoryConfig } from "../create-repository-CAle1MSU.mjs";
+import { r as Repository } from "../Repository-pnLw1rG5.mjs";
+import { n as CreateRepositoryConfig } from "../create-repository-BUx9vfG9.mjs";
 import { Connection, Model, Schema } from "mongoose";
 import { MongoMemoryReplSet, MongoMemoryServer } from "mongodb-memory-server";
+//#region src/testkit/query-plan.d.ts
+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<{
+  result: T;
+  commands: RecordedCommand[];
+}>;
+interface QueryPlanOptions {
+  connection: Connection;
+  /** Plan stages that fail the gate. Default `['COLLSCAN', 'SORT']` (a scan, an unindexed sort). */
+  forbid?: readonly string[];
+  /** The examined collection must hold at least this many documents. */
+  minDocs: number;
+  /** Every index scan must lead with these keys (directly, or after one equality scope field). */
+  leadingKeys?: readonly string[];
+  /** Only gate commands on these collections (default: every plannable command). */
+  collections?: readonly string[];
+}
+interface PlannedCommand {
+  name: string;
+  collection: string;
+  stages: string[];
+  indexes: string[][];
+}
+/**
+ * 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<{
+  result: T;
+  plans: PlannedCommand[];
+}>;
+//#endregion
 //#region src/testkit/index.d.ts
 interface MongoMemoryOptions {
   /**
@@ -132,4 +169,4 @@ interface MongoMemoryBackend {
  */
 declare function mongoMemoryBackend(options?: MongoMemoryOptions): MongoMemoryBackend;
 //#endregion
-export { CreateTestRepositoryOptions, MongoMemoryBackend, MongoMemoryHandle, MongoMemoryOptions, MongoTestContext, TestConnection, TestRepository, clearCollections, createMongoMemory, createTestConnection, createTestRepository, mongoMemoryBackend, withMongoMemory };
+export { CreateTestRepositoryOptions, MongoMemoryBackend, MongoMemoryHandle, MongoMemoryOptions, MongoTestContext, type PlannedCommand, type QueryPlanOptions, type RecordedCommand, TestConnection, TestRepository, assertQueryPlan, clearCollections, createMongoMemory, createTestConnection, createTestRepository, mongoMemoryBackend, recordCommands, withMongoMemory };

package/dist/testkit/index.mjs

@@ -1,5 +1,116 @@
-import { t as createRepository } from "../create-repository-BzBUMvd1.mjs";
+import { t as createRepository } from "../create-repository-BYyWzLbt.mjs";
 import { createConnection } from "mongoose";
+//#region src/testkit/query-plan.ts
+const PLANNABLE = /* @__PURE__ */ new Set([
+	"find",
+	"aggregate",
+	"count",
+	"distinct"
+]);
+/** Session/transport fields the server refuses inside an `explain`. */
+const STRIP = /* @__PURE__ */ new Set([
+	"lsid",
+	"txnNumber",
+	"autocommit",
+	"startTransaction",
+	"readConcern",
+	"maxTimeMS"
+]);
+function assertMonitored(connection) {
+	if (connection.getClient().options.monitorCommands !== true) throw new Error("[mongokit/testkit] the connection was not opened with { monitorCommands: true }: no command can be observed");
+}
+/** Run `fn` and return every command it started on `connection` (in start order). */
+async function recordCommands(connection, fn) {
+	assertMonitored(connection);
+	const client = connection.getClient();
+	const commands = [];
+	const listener = (event) => {
+		const target = event.command[event.commandName];
+		commands.push({
+			name: event.commandName,
+			collection: typeof target === "string" ? target : void 0,
+			command: event.command
+		});
+	};
+	client.on("commandStarted", listener);
+	try {
+		return {
+			result: await fn(),
+			commands
+		};
+	} finally {
+		client.off("commandStarted", listener);
+	}
+}
+function collectPlanNodes(node, out) {
+	if (Array.isArray(node)) {
+		for (const n of node) collectPlanNodes(n, out);
+		return;
+	}
+	if (!node || typeof node !== "object") return;
+	const obj = node;
+	if (typeof obj.stage === "string") out.push(obj);
+	for (const [key, value] of Object.entries(obj)) {
+		if (key === "rejectedPlans" || key === "allPlansExecution") continue;
+		collectPlanNodes(value, out);
+	}
+}
+function explainable(command) {
+	return Object.fromEntries(Object.entries(command).filter(([k]) => !k.startsWith("$") && !STRIP.has(k)));
+}
+/**
+* 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 { 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)));
+	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) {
+		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),
+			verbosity: "executionStats"
+		});
+		const nodes = [];
+		collectPlanNodes(explained.queryPlanner ?? explained.stages ?? explained, nodes);
+		const stages = nodes.map((n) => n.stage);
+		const indexes = nodes.filter((n) => n.keyPattern && typeof n.keyPattern === "object").map((n) => Object.keys(n.keyPattern));
+		plans.push({
+			name: c.name,
+			collection,
+			stages,
+			indexes
+		});
+		for (const stage of forbid) if (stages.includes(stage)) failures.push(`${c.name} on '${collection}': plan contains ${stage}`);
+		if (options.leadingKeys) {
+			const want = options.leadingKeys;
+			const leads = (key, at) => want.every((k, i) => key[at + i] === k);
+			if (indexes.length === 0) failures.push(`${c.name} on '${collection}': no index used, expected (${want.join(",")})`);
+			for (const key of indexes) if (!leads(key, 0) && !leads(key, 1)) failures.push(`${c.name} on '${collection}': index (${key.join(",")}) does not lead with (${want.join(",")})`);
+		}
+	}
+	if (failures.length > 0) {
+		const error = /* @__PURE__ */ new Error(`[mongokit/testkit] query plan gate failed:\n  ${failures.join("\n  ")}`);
+		Object.assign(error, {
+			code: "mongokit.testkit.query_plan",
+			plans
+		});
+		throw error;
+	}
+	return {
+		result,
+		plans
+	};
+}
+//#endregion
 //#region src/testkit/index.ts
 function idempotentStop(server) {
 	let stopped = false;
@@ -136,4 +247,4 @@ function mongoMemoryBackend(options = {}) {
 	} };
 }
 //#endregion
-export { clearCollections, createMongoMemory, createTestConnection, createTestRepository, mongoMemoryBackend, withMongoMemory };
+export { assertQueryPlan, clearCollections, createMongoMemory, createTestConnection, createTestRepository, mongoMemoryBackend, recordCommands, withMongoMemory };

package/dist/{timestamp.plugin-DF0gJB6p.mjs → timestamp.plugin-zfdLYZiO.mjs}

@@ -1,5 +1,6 @@
-import { i as ALL_OPERATIONS, o as OP_REGISTRY, t as HOOK_PRIORITY } from "./Repository-BMgPSkqZ.mjs";
+import { i as ALL_OPERATIONS, o as OP_REGISTRY, t as HOOK_PRIORITY } from "./Repository-CYhSC9ut.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
+import { n as declareCollectionScope } from "./join-scope-DSAznE8E.mjs";
 import { throwIfAborted, withRetry } from "@classytic/repo-core/repository";
 import mongoose from "mongoose";
 import { cachePlugin } from "@classytic/repo-core/cache";
@@ -1067,6 +1068,41 @@ function multiTenantPlugin(options = {}) {
 		name: "multi-tenant",
 		apply(repo) {
 			declareTenantContextKey(repo, contextKey);
+			/** The one tenant decision, shared by the hook and the join rule below. */
+			const decide = (context, op) => {
+				if (context.bypassTenant === true) return { bypass: "option" };
+				if (skipWhen?.(context, op) === true) return { bypass: "callback" };
+				let tenantId = context[contextKey];
+				if (!tenantId && resolveContext) tenantId = resolveContext();
+				return { tenantId };
+			};
+			const castTenant = (tenantId) => fieldType === "objectId" ? new mongoose.Types.ObjectId(tenantId) : tenantId;
+			const missingTenant = (op) => new Error([
+				`[mongokit] Multi-tenant: Missing '${contextKey}' in context for '${op}'.`,
+				"",
+				"Three ways to provide it — pick the one that fits the call site:",
+				"",
+				`  1. Per-call:        repo.${op}(..., { ${contextKey}: '<id>' })`,
+				"  2. Ambient (ALS):   `createTenantContext()` + `resolveContext` —",
+				"                       wrap the request in `tenantContext.run({ tenantId }, fn)`,",
+				"                       then every repo call inside the closure inherits the",
+				"                       tenant with no options-bag plumbing. See",
+				"                       `createTenantContext` in @classytic/mongokit.",
+				"  3. Cross-tenant:    `bypassTenant: true` per-call (admin / migration /",
+				"                       support), or `skipWhen: adminBypass({...})` at plugin",
+				"                       construction for an always-on role-based bypass.",
+				"",
+				"Or set `required: false` if this collection is genuinely not tenant-scoped."
+			].join("\n"));
+			if (repo.Model) declareCollectionScope(repo.Model, (context, op) => {
+				const d = decide(context, op);
+				if ("bypass" in d) return void 0;
+				if (!d.tenantId) {
+					if (required) throw missingTenant(op);
+					return;
+				}
+				return { [tenantField]: castTenant(d.tenantId) };
+			}, { tenantField });
 			const allOps = [...ALL_OPERATIONS.map((op) => ({
 				op,
 				policyKey: OP_REGISTRY[op].policyKey
@@ -1075,41 +1111,21 @@ function multiTenantPlugin(options = {}) {
 				if (skipOperations.includes(op)) continue;
 				if (policyKey === "none") continue;
 				repo.on(`before:${op}`, (context) => {
-					const perCallBypass = context.bypassTenant === true;
-					const callbackBypass = !perCallBypass && skipWhen?.(context, op) === true;
-					if (perCallBypass || callbackBypass) {
+					const decision = decide(context, op);
+					if ("bypass" in decision) {
 						repo.emit("after:tenant-bypass", {
 							context,
 							operation: op,
-							reason: perCallBypass ? "option" : "callback"
+							reason: decision.bypass
 						});
 						return;
 					}
-					let tenantId = context[contextKey];
-					if (!tenantId && resolveContext) {
-						tenantId = resolveContext();
-						if (tenantId) context[contextKey] = tenantId;
-					}
+					const tenantId = decision.tenantId;
+					if (tenantId && !context[contextKey]) context[contextKey] = tenantId;
 					if (!tenantId && allowDataInjection && payloadHasTenantField(context, policyKey, tenantField)) return;
-					if (!tenantId && required) throw new Error([
-						`[mongokit] Multi-tenant: Missing '${contextKey}' in context for '${op}'.`,
-						"",
-						"Three ways to provide it — pick the one that fits the call site:",
-						"",
-						`  1. Per-call:        repo.${op}(..., { ${contextKey}: '<id>' })`,
-						"  2. Ambient (ALS):   `createTenantContext()` + `resolveContext` —",
-						"                       wrap the request in `tenantContext.run({ tenantId }, fn)`,",
-						"                       then every repo call inside the closure inherits the",
-						"                       tenant with no options-bag plumbing. See",
-						"                       `createTenantContext` in @classytic/mongokit.",
-						"  3. Cross-tenant:    `bypassTenant: true` per-call (admin / migration /",
-						"                       support), or `skipWhen: adminBypass({...})` at plugin",
-						"                       construction for an always-on role-based bypass.",
-						"",
-						"Or set `required: false` if this collection is genuinely not tenant-scoped."
-					].join("\n"));
+					if (!tenantId && required) throw missingTenant(op);
 					if (!tenantId) return;
-					const castId = fieldType === "objectId" ? new mongoose.Types.ObjectId(tenantId) : tenantId;
+					const castId = castTenant(tenantId);
 					const assertTenantValue = (supplied, where) => {
 						if (onMismatch === "overwrite") return;
 						if (supplied === void 0 || supplied === null) return;
@@ -1318,6 +1334,7 @@ function softDeletePlugin(options = {}) {
 	return {
 		name: "softDelete",
 		apply(repo) {
+			if (repo.Model) declareCollectionScope(repo.Model, () => buildDeletedFilter(deletedField, filterMode, false));
 			try {
 				const schemaPaths = repo.Model.schema.paths;
 				if (!schemaPaths[deletedField]) warn(`[softDeletePlugin] Model '${repo.Model.modelName}' has no '${deletedField}' schema path. Soft-delete marks documents by \`$set\`-ing '${deletedField}', but Mongoose strict mode drops updates to undeclared paths — so delete() will SILENTLY no-op (documents are never soft-deleted). Declare it on the schema: { ${deletedField}: { type: Date, default: ${filterMode === "null" ? "null" : "undefined"} } }`);
@@ -1378,7 +1395,8 @@ function softDeletePlugin(options = {}) {
 			const SOFT_DELETE_SPECIAL = /* @__PURE__ */ new Set([
 				"updateMany",
 				"deleteMany",
-				"bulkWrite"
+				"bulkWrite",
+				"bulkUpsert"
 			]);
 			for (const op of ALL_OPERATIONS) {
 				if (SOFT_DELETE_SPECIAL.has(op)) continue;
@@ -1409,7 +1427,7 @@ function softDeletePlugin(options = {}) {
 			* `deleteMode: 'hard'` still bypasses, exactly as the single-doc path does — a purge
 			* is a deliberate physical delete, and it reaches the driver directly anyway.
 			*/
-			repo.on("before:bulkWrite", (context) => {
+			const scopeSubOps = (context) => {
 				if (options.soft === false || context.deleteMode === "hard") return;
 				const ops = context.operations;
 				if (!Array.isArray(ops)) return;
@@ -1440,7 +1458,8 @@ function softDeletePlugin(options = {}) {
 						delete subOp[key];
 					}
 				}
-			}, { priority: HOOK_PRIORITY.POLICY });
+			};
+			for (const op of ["bulkWrite", "bulkUpsert"]) repo.on(`before:${op}`, scopeSubOps, { priority: HOOK_PRIORITY.POLICY });
 			repo.on("before:deleteMany", async (context) => {
 				if (context.deleteMode === "hard") return;
 				if (options.soft !== false) {

package/dist/{to-plain-k7SjNlSS.d.mts → to-plain-CjgEInWV.d.mts}

@@ -1,5 +1,5 @@
-import { v as UserContext } from "./repository-odl03582.mjs";
-import { r as FieldPreset } from "./plugin-options-Zk46lD6F.mjs";
+import { v as UserContext } from "./repository-DNHfjAZX.mjs";
+import { r as FieldPreset } from "./plugin-options-CRhIvSzx.mjs";
 import mongoose, { Schema } from "mongoose";
 import { CacheAdapter } from "@classytic/repo-core/cache";
 import { HttpError } from "@classytic/repo-core/errors";

package/dist/{transaction-B5L9glO0.mjs → transaction-BrRYtH_b.mjs}

@@ -1,3 +1,6 @@
+import { d as setTransactionDeadline } from "./query-defaults-BxUcSOoF.mjs";
+import mongoose from "mongoose";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
 //#region src/capabilities.ts
 /**
 * Read the provenance of a capability descriptor's `transactions` flag.
@@ -52,7 +55,13 @@ const MONGOKIT_CAPABILITIES = Object.freeze({
 	lean: true,
 	lookupPopulate: true,
 	lookupCoerce: true,
-	streaming: true
+	streaming: true,
+	getByIdsOrdered: true,
+	scopedJoins: true,
+	paginationProperties: true,
+	bulkUpsert: true,
+	readModel: true,
+	mergeKeyset: true
 });
 /**
 * Driver `ServerType`s that positively imply a session-capable, transaction-
@@ -272,6 +281,9 @@ const SESSION_OPTIONS_INDEX = Object.freeze({
 	aggregatePipelinePaginate: 0,
 	lookupPopulate: 0,
 	cursor: 1,
+	iterate: 1,
+	bulkUpsert: 1,
+	keysetCursor: 1,
 	claim: 3,
 	claimVersion: 3,
 	applyTransition: 3,
@@ -381,11 +393,30 @@ function createTxBoundRepo(outer, session) {
 //#endregion
 //#region src/transaction.ts
 /**
+* Cross-repo transaction helper.
+*
+* `Repository#withTransaction` is convenient when every write in a transaction
+* lives on the same repository, but real workflows usually span several:
+*
+*   await withTransaction(connection, async (session) => {
+*     const txn = await revenue.transaction.create(data, { session });
+*     await ledger.entry.create(journal, { session });
+*     await revenue.transaction.verify(txn._id, {}, { session });
+*   });
+*
+* This module-level helper accepts a Mongoose connection (or anything with a
+* compatible `startSession()`), so hosts don't need to arbitrarily pick one
+* repository to hang the transaction off.
+*
+* The Repository instance method delegates to this function — one source of
+* truth for retry semantics, standalone fallback, and session lifecycle.
+*/
+/**
 * Run a callback inside a MongoDB transaction on the given connection.
 *
-* - Starts a session, runs `session.withTransaction(callback)` (which auto-retries
-*   on `TransientTransactionError` and `UnknownTransactionCommitResult`), and
-*   always ends the session in `finally`.
+* - Starts a session and runs the callback in a transaction with the driver's retry rules
+*   (`TransientTransactionError` → retry the attempt, `UnknownTransactionCommitResult` → retry
+*   the commit), ending the session in `finally`. See {@link runTransaction}.
 * - When `allowFallback` is true and the deployment doesn't support transactions
 *   (e.g. standalone MongoDB in dev), the callback runs once without a
 *   transaction on the same session. `onFallback` is invoked with the original
@@ -406,7 +437,7 @@ function createTxBoundRepo(outer, session) {
 async function withTransaction(connection, callback, options = {}) {
 	const session = await connection.startSession();
 	try {
-		return await session.withTransaction(() => callback(session), options.transactionOptions);
+		return await runTransaction(session, callback, options.transactionOptions);
 	} catch (error) {
 		const err = error;
 		if (options.allowFallback && isTransactionUnsupported(err)) {
@@ -418,6 +449,97 @@ async function withTransaction(connection, callback, options = {}) {
 		await session.endSession();
 	}
 }
+const MAX_TRANSACTION_TIMEOUT_MS = 12e4;
+const BACKOFF_INITIAL_MS = 5;
+const BACKOFF_MAX_MS = 500;
+const MAX_TIME_MS_EXPIRED = 50;
+function hasLabel(err, label) {
+	const e = err;
+	if (typeof e?.hasErrorLabel === "function") return e.hasErrorLabel(label);
+	return Array.isArray(e?.errorLabels) && e.errorLabels.includes(label);
+}
+function isMaxTimeMSExpired(err) {
+	const e = err;
+	return e?.code === MAX_TIME_MS_EXPIRED || e?.writeConcernError?.code === MAX_TIME_MS_EXPIRED;
+}
+function timeoutError(cause, csot) {
+	if (!csot || cause instanceof mongoose.mongo.MongoOperationTimeoutError) return cause;
+	const error = new mongoose.mongo.MongoOperationTimeoutError("Timed out during withTransaction", { cause: cause instanceof Error ? cause : void 0 });
+	if (cause instanceof mongoose.mongo.MongoError) for (const label of cause.errorLabels) error.addErrorLabel(label);
+	return error;
+}
+/**
+* The driver's convenient-transaction algorithm (start → callback → commit, label-based retry,
+* jittered backoff, a deadline), run here so the driver never attaches a session `timeoutContext`:
+* with one, every legacy bulk write (`insertMany`, `bulkWrite`) in the transaction is refused once
+* the client carries `timeoutMS` (driver <= 7.7: the bulk path re-resolves the inherited client
+* `timeoutMS` as a per-op one). Each operation keeps its own per-op CSOT budget instead.
+* Deadline: `transactionOptions.timeoutMS`, else the client's `timeoutMS`, else 120 s (as the driver).
+* Pinned by `tests/integration/csot-transaction-matrix.test.ts`.
+*/
+async function runTransaction(session, callback, transactionOptions = {}) {
+	const { timeoutMS: explicitTimeout, ...startOptions } = transactionOptions;
+	const clientTimeout = session.timeoutMS;
+	const timeoutMS = explicitTimeout ?? clientTimeout;
+	const csot = timeoutMS != null;
+	const deadline = performance.now() + (timeoutMS ?? MAX_TRANSACTION_TIMEOUT_MS);
+	let lastError;
+	if (csot) setTransactionDeadline(session, deadline);
+	try {
+		for (let attempt = 0;; attempt++) {
+			if (attempt > 0) {
+				const backoff = Math.random() * Math.min(BACKOFF_INITIAL_MS * 1.5 ** (attempt - 1), BACKOFF_MAX_MS);
+				if (performance.now() + backoff >= deadline) throw timeoutError(lastError, csot);
+				await setTimeout$1(backoff);
+			}
+			session.startTransaction(startOptions);
+			let result;
+			try {
+				result = await callback(session);
+				if (!session.inTransaction()) return result;
+			} catch (err) {
+				lastError = err;
+				await abortKeepingError(session, err);
+				if (err instanceof mongoose.mongo.MongoError && hasLabel(err, "TransientTransactionError")) {
+					if (performance.now() >= deadline) throw timeoutError(err, csot);
+					continue;
+				}
+				throw err;
+			}
+			for (;;) {
+				const left = deadline - performance.now();
+				if (csot && left <= 0) {
+					const late = new mongoose.mongo.MongoOperationTimeoutError("Transaction budget exhausted before commit; the transaction was aborted, nothing was committed");
+					await abortKeepingError(session, late);
+					throw late;
+				}
+				try {
+					await session.commitTransaction(csot ? { timeoutMS: Math.max(1, Math.floor(left)) } : void 0);
+					return result;
+				} catch (err) {
+					lastError = err;
+					if (hasLabel(err, "UnknownTransactionCommitResult") && !isMaxTimeMSExpired(err)) {
+						if (performance.now() >= deadline) throw timeoutError(err, csot);
+						continue;
+					}
+					if (hasLabel(err, "TransientTransactionError")) break;
+					throw err;
+				}
+			}
+		}
+	} finally {
+		if (csot) setTransactionDeadline(session, void 0);
+	}
+}
+/** Abort if still in progress; an abort failure rides along as `abortError`, never replacing `original`. */
+async function abortKeepingError(session, original) {
+	if (!session.inTransaction()) return;
+	try {
+		await session.abortTransaction();
+	} catch (abortError) {
+		if (original && typeof original === "object") Object.assign(original, { abortError });
+	}
+}
 /**
 * Multi-repo transactional batch — every repo in `repos` becomes a
 * session-bound proxy inside the callback. Eliminates the per-call