@classytic/mongokit 3.6.4 → 3.8.0

package/dist/{validation-chain.plugin-7A5qGEQq.mjs → validation-chain.plugin-DwoOOWse.mjs}

@@ -1,10 +1,136 @@
-import { a as warn, i as debug, n as parseDuplicateKeyError, t as createError } from "./error-Bpbi_NKo.mjs";
-import { a as exists, c as getOrCreate, d as deleteByQuery, g as upsert, i as count, m as createMany, n as updateByQuery, o as getById, p as create, s as getByQuery, t as update, u as deleteById, v as distinct, y as LookupBuilder } from "./update-AVfKWNGt.mjs";
-import { t as PaginationEngine } from "./PaginationEngine-CunXkR9p.mjs";
+import { n as debug, r as warn } from "./logger-DJ7egMnd.mjs";
+import { _ as upsert, a as count, b as LookupBuilder, c as getByQuery, d as deleteById, f as deleteByQuery, h as createMany, l as getOrCreate, m as create, n as update, o as exists, r as updateByQuery, s as getById, t as findOneAndUpdate, y as distinct } from "./update-yjSoNnWy.mjs";
+import { n as parseDuplicateKeyError, t as createError } from "./error-Lw9GEAro.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-C2_tAvAD.mjs";
 import { hasNearOperator, rewriteNearForCount } from "./query/primitives/geo.mjs";
-import { r as isValidIdForType, t as getSchemaIdType } from "./id-resolution-LZ-cCwR5.mjs";
-import { a as byIdKey, c as listQueryKey, l as modelPattern, o as byQueryKey, r as getFieldsForUser, u as versionKey } from "./field-selection-C5o7jyyA.mjs";
+import { r as isValidIdForType, t as getSchemaIdType } from "./id-resolution-e4BT9zAV.mjs";
+import { a as byIdKey, c as listQueryKey, l as modelPattern, o as byQueryKey, r as getFieldsForUser, u as versionKey } from "./field-selection-dI0m4RBs.mjs";
 import mongoose from "mongoose";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/operations.ts
+/**
+* The registry. Order intentionally groups by category for readability.
+* Adding a new RepositoryOperation requires exactly one entry here, after
+* which every bundled plugin auto-classifies it correctly.
+*/
+const OP_REGISTRY = {
+	create: {
+		policyKey: "data",
+		mutates: true,
+		hasIdContext: false
+	},
+	update: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: true
+	},
+	findOneAndUpdate: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: false
+	},
+	delete: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: true
+	},
+	restore: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: true
+	},
+	createMany: {
+		policyKey: "dataArray",
+		mutates: true,
+		hasIdContext: false
+	},
+	updateMany: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: false
+	},
+	deleteMany: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: false
+	},
+	bulkWrite: {
+		policyKey: "operations",
+		mutates: true,
+		hasIdContext: false
+	},
+	getById: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: true
+	},
+	getByQuery: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	getOne: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	findAll: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	getOrCreate: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	count: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	exists: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	distinct: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	aggregate: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	getAll: {
+		policyKey: "filters",
+		mutates: false,
+		hasIdContext: false
+	},
+	aggregatePaginate: {
+		policyKey: "filters",
+		mutates: false,
+		hasIdContext: false
+	},
+	lookupPopulate: {
+		policyKey: "filters",
+		mutates: false,
+		hasIdContext: false
+	}
+};
+/** All known repository operations, in registry order. */
+const ALL_OPERATIONS = Object.keys(OP_REGISTRY);
+/** Operations that mutate the database. Drives audit + cache invalidation lists. */
+const MUTATING_OPERATIONS = ALL_OPERATIONS.filter((op) => OP_REGISTRY[op].mutates);
+/** Operations that don't mutate. Drives default cacheable ops. */
+const READ_OPERATIONS = ALL_OPERATIONS.filter((op) => !OP_REGISTRY[op].mutates);
+/** Filter ops by their policy injection key. */
+function operationsByPolicyKey(key) {
+	return ALL_OPERATIONS.filter((op) => OP_REGISTRY[op].policyKey === key);
+}
+//#endregion
 //#region src/plugins/aggregate-helpers.plugin.ts
 /**
 * Aggregate helpers plugin
@@ -97,6 +223,22 @@ function auditLogPlugin(logger) {
 					organizationId: context.organizationId
 				});
 			});
+			repo.on("after:findOneAndUpdate", ({ context, result }) => {
+				if (!result) return;
+				logger?.info?.("Document upserted/updated (findOneAndUpdate)", {
+					model: context.model || repo.model,
+					id: result?.[repo.idField || "_id"],
+					userId: context.user?._id || context.user?.id,
+					organizationId: context.organizationId
+				});
+			});
+			repo.on("error:findOneAndUpdate", ({ context, error }) => {
+				logger?.error?.("findOneAndUpdate failed", {
+					model: context.model || repo.model,
+					error: error.message,
+					userId: context.user?._id || context.user?.id
+				});
+			});
 			repo.on("after:delete", ({ context }) => {
 				logger?.info?.("Document deleted", {
 					model: context.model || repo.model,
@@ -176,6 +318,7 @@ function getAuditModel(collectionName, ttlDays) {
 			enum: [
 				"create",
 				"update",
+				"findOneAndUpdate",
 				"delete"
 			]
 		},
@@ -325,6 +468,19 @@ function auditTrailPlugin(options = {}) {
 					});
 				});
 			}
+			if (opsSet.has("findOneAndUpdate")) repo.on("after:findOneAndUpdate", ({ context, result }) => {
+				if (!result) return;
+				const doc = result;
+				const idKey = repo.idField || "_id";
+				writeAudit(AuditModel, {
+					model: context.model || repo.model,
+					operation: "findOneAndUpdate",
+					documentId: doc?.[idKey],
+					userId: getUserId(context),
+					orgId: context.organizationId,
+					metadata: metadata?.(context)
+				});
+			});
 			if (opsSet.has("delete")) repo.on("after:delete", ({ context }) => {
 				writeAudit(AuditModel, {
 					model: context.model || repo.model,
@@ -1228,6 +1384,40 @@ function ensureLookupProjectionIncludesCursorFields(projection, sort) {
 	return nextProjection;
 }
 /**
+* Ordered pairs that produce wrong behavior when registered out of order.
+* Each tuple is `[mustComeFirst, mustComeAfter, reason]`.
+*
+* Plugin names are read from `plugin.name` (Plugin objects). Plain-function
+* plugins without a name are skipped — no false positives.
+*/
+const PLUGIN_ORDER_CONSTRAINTS = [[
+	"soft-delete",
+	"batch-operations",
+	"soft-delete must precede batch-operations so bulk deletes/updates see the soft-delete filter"
+], [
+	"multi-tenant",
+	"cache",
+	"multi-tenant must precede cache so tenant scoping is baked into cache keys (prevents cross-tenant cache poisoning)"
+]];
+function pluginName(plugin) {
+	if (!plugin || typeof plugin === "function") return void 0;
+	const name = plugin.name;
+	return typeof name === "string" ? name : void 0;
+}
+function validatePluginOrder(plugins, modelName, mode) {
+	if (mode === "off") return;
+	const names = plugins.map(pluginName);
+	for (const [first, after, reason] of PLUGIN_ORDER_CONSTRAINTS) {
+		const firstIdx = names.indexOf(first);
+		const afterIdx = names.indexOf(after);
+		if (firstIdx === -1 || afterIdx === -1) continue;
+		if (firstIdx < afterIdx) continue;
+		const message = `[mongokit] Repository "${modelName}": plugin order issue — ${reason}. Got: [..., '${after}' at index ${afterIdx}, '${first}' at index ${firstIdx}]. Swap them, or pass { pluginOrderChecks: 'off' } to silence.`;
+		if (mode === "throw") throw new Error(message);
+		warn(message);
+	}
+}
+/**
 * Plugin phase priorities (lower = runs first)
 * Policy hooks (multi-tenant, soft-delete, validation) MUST run before cache
 * to ensure filters are injected before cache keys are computed.
@@ -1262,6 +1452,7 @@ var Repository = class {
 		this.searchMode = options.searchMode ?? "text";
 		this.searchFields = options.searchFields;
 		if (this.searchMode === "regex" && (!this.searchFields || this.searchFields.length === 0)) warn(`[mongokit] Repository "${this.model}" configured with searchMode: 'regex' but no searchFields provided. getAll({ search }) will throw until searchFields is set.`);
+		validatePluginOrder(plugins, this.model, options.pluginOrderChecks ?? "warn");
 		plugins.forEach((plugin) => {
 			this.use(plugin);
 		});
@@ -1539,10 +1730,10 @@ var Repository = class {
 	*/
 	async findAll(filters = {}, options = {}) {
 		const context = await this._buildContext("findAll", {
-			filters,
+			query: filters,
 			...options
 		});
-		const resolvedFilters = context.filters ?? filters;
+		const resolvedFilters = context.query ?? filters;
 		try {
 			const query = this.Model.find(resolvedFilters);
 			const sortSpec = context.sort || options.sort;
@@ -1835,6 +2026,64 @@ var Repository = class {
 		}
 	}
 	/**
+	* Atomic findOneAndUpdate (compare-and-set primitive).
+	*
+	* Single round-trip match-and-mutate for outbox relays, distributed locks,
+	* and workflow semaphores. Goes through the full hook pipeline so
+	* multi-tenant scope, soft-delete, audit, and cache plugins all apply.
+	*
+	* Returns the matched document (post-update by default) or `null` when no
+	* document matches and `upsert` is false.
+	*
+	* @example FIFO claim-lease for an outbox worker
+	* ```ts
+	* const claimed = await outboxRepo.findOneAndUpdate(
+	*   { status: 'pending', leaseExpiresAt: { $lt: new Date() } },
+	*   { $set: { status: 'processing', leaseExpiresAt: leaseUntil, leasedBy: workerId } },
+	*   { sort: { createdAt: 1 }, returnDocument: 'after' },
+	* );
+	* if (!claimed) return; // queue empty
+	* ```
+	*
+	* @example CAS upsert
+	* ```ts
+	* const lock = await locksRepo.findOneAndUpdate(
+	*   { _id: lockKey, ownerId: { $in: [null, workerId] } },
+	*   { $set: { ownerId: workerId, expiresAt: leaseUntil } },
+	*   { upsert: true },
+	* );
+	* ```
+	*/
+	async findOneAndUpdate(filter, update, options = {}) {
+		const context = await this._buildContext("findOneAndUpdate", {
+			query: filter,
+			data: update,
+			...options
+		});
+		try {
+			const finalQuery = context.query || filter;
+			const finalUpdate = context.data || update;
+			const result = await findOneAndUpdate(this.Model, finalQuery, finalUpdate, {
+				...options,
+				sort: options.sort,
+				returnDocument: options.returnDocument ?? "after",
+				upsert: options.upsert ?? false,
+				session: options.session
+			});
+			await this._emitHook("after:findOneAndUpdate", {
+				context,
+				result
+			});
+			return result;
+		} catch (error) {
+			await this._emitErrorHook("error:findOneAndUpdate", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
 	* Delete a document by ID.
 	*
 	* By default the behavior is decided by the plugin stack:
@@ -2063,12 +2312,13 @@ var Repository = class {
 			};
 			if (isKeyset && sort) {
 				const parsedSort = this._parseSort(sort);
-				const { validateKeysetSort } = await import("./sort-C-BJEWUZ.mjs").then((n) => n.n);
-				const { encodeCursor, resolveCursorFilter } = await import("./cursor-CHToazHy.mjs").then((n) => n.t);
-				const { getPrimaryField } = await import("./sort-C-BJEWUZ.mjs").then((n) => n.n);
-				const normalizedSort = validateKeysetSort(parsedSort);
+				const { validateKeysetSort } = await import("./sort-CrZjTK25.mjs").then((n) => n.n);
+				const { encodeCursor, resolveCursorFilter } = await import("./cursor-J84rR6wG.mjs").then((n) => n.t);
+				const { getPrimaryField } = await import("./sort-CrZjTK25.mjs").then((n) => n.n);
+				const normalizedSort = validateKeysetSort(parsedSort, this._pagination.config.strictKeysetSortFields);
 				const cursorVersion = this._pagination.config.cursorVersion ?? 1;
-				const matchFilters = after ? resolveCursorFilter(after, normalizedSort, cursorVersion, { ...filters || {} }) : { ...filters || {} };
+				const minCursorVersion = this._pagination.config.minCursorVersion ?? 1;
+				const matchFilters = after ? resolveCursorFilter(after, normalizedSort, cursorVersion, { ...filters || {} }, minCursorVersion) : { ...filters || {} };
 				if (projection) {
 					if (Object.values(projection).some((v) => v === 1)) {
 						for (const sortField of Object.keys(normalizedSort)) if (!(sortField in projection)) projection[sortField] = 1;
@@ -2415,6 +2665,28 @@ var Repository = class {
 * ```
 */
 /**
+* Resolve the user's jitter config into a deterministic `ttl -> ttl` function.
+*
+* - `undefined` / `0`: identity (no jitter).
+* - number in (0, 1]: symmetric fractional jitter. `0.1` → uniform in [0.9, 1.1].
+* - function: used as-is; caller owns the math. Clamped to >= 1s below.
+*
+* The final TTL is always clamped to a whole second >= 1 so adapters that
+* treat 0 as "no expiry" (Redis SETEX semantics) don't accidentally persist
+* entries forever.
+*/
+function resolveJitter(jitter) {
+	if (!jitter) return (ttl) => ttl;
+	if (typeof jitter === "function") return (ttl) => Math.max(1, Math.round(jitter(ttl)));
+	const fraction = Math.min(1, Math.max(0, jitter));
+	if (fraction === 0) return (ttl) => ttl;
+	return (ttl) => {
+		const delta = ttl * fraction;
+		const jittered = ttl - delta + Math.random() * 2 * delta;
+		return Math.max(1, Math.round(jittered));
+	};
+}
+/**
 * Cache plugin factory
 *
 * @param options - Cache configuration
@@ -2428,7 +2700,8 @@ function cachePlugin(options) {
 		queryTtl: options.queryTtl ?? options.ttl ?? 60,
 		prefix: options.prefix ?? "mk",
 		debug: options.debug ?? false,
-		skipIfLargeLimit: options.skipIf?.largeLimit ?? 100
+		skipIfLargeLimit: options.skipIf?.largeLimit ?? 100,
+		applyJitter: resolveJitter(options.jitter)
 	};
 	const stats = {
 		hits: 0,
@@ -2468,7 +2741,7 @@ function cachePlugin(options) {
 			async function bumpVersion() {
 				const newVersion = Date.now();
 				try {
-					await config.adapter.set(versionKey(config.prefix, model), newVersion, config.ttl * 10);
+					await config.adapter.set(versionKey(config.prefix, model), newVersion, config.applyJitter(config.ttl * 10));
 					stats.invalidations++;
 					log(`Bumped version for ${model} to:`, newVersion);
 				} catch (e) {
@@ -2647,7 +2920,7 @@ function cachePlugin(options) {
 					populate: context.populate,
 					lean: context.lean
 				});
-				const ttl = context.cacheTtl ?? config.byIdTtl;
+				const ttl = config.applyJitter(context.cacheTtl ?? config.byIdTtl);
 				try {
 					await config.adapter.set(key, result, ttl);
 					trackByIdKey(id, key);
@@ -2671,7 +2944,7 @@ function cachePlugin(options) {
 					select: context.select,
 					populate: context.populate
 				});
-				const ttl = context.cacheTtl ?? config.queryTtl;
+				const ttl = config.applyJitter(context.cacheTtl ?? config.queryTtl);
 				try {
 					await config.adapter.set(key, result, ttl);
 					stats.sets++;
@@ -2693,7 +2966,7 @@ function cachePlugin(options) {
 					populate: context.populate
 				});
 				try {
-					await config.adapter.set(key, result, context.cacheTtl ?? config.queryTtl);
+					await config.adapter.set(key, result, config.applyJitter(context.cacheTtl ?? config.queryTtl));
 					stats.sets++;
 				} catch (e) {
 					log(`Failed to cache getOne:`, e);
@@ -2726,7 +2999,7 @@ function cachePlugin(options) {
 					countStrategy: context.countStrategy
 				};
 				const key = listQueryKey(config.prefix, model, collectionVersion, params);
-				const ttl = context.cacheTtl ?? config.queryTtl;
+				const ttl = config.applyJitter(context.cacheTtl ?? config.queryTtl);
 				try {
 					await config.adapter.set(key, result, ttl);
 					stats.sets++;
@@ -2762,6 +3035,22 @@ function cachePlugin(options) {
 				await bumpVersion();
 			});
 			/**
+			* after:findOneAndUpdate — atomic CAS may insert (upsert) or mutate.
+			* Result carries the matched/inserted doc; invalidate that ID and bump
+			* version. Null result (no match, no upsert) is a no-op.
+			*/
+			repo.on("after:findOneAndUpdate", async (payload) => {
+				const { result } = payload;
+				if (!result) return;
+				const idKey = repo.idField || "_id";
+				const id = result?.[idKey];
+				if (id == null) {
+					await bumpVersion();
+					return;
+				}
+				await Promise.all([invalidateById(String(id)), bumpVersion()]);
+			});
+			/**
 			* after:delete - Invalidate by ID and bump version
 			*/
 			repo.on("after:delete", async (payload) => {
@@ -3720,45 +4009,20 @@ function mongoOperationsPlugin() {
 */
 function multiTenantPlugin(options = {}) {
 	const { tenantField = "organizationId", contextKey = "organizationId", required = true, skipOperations = [], skipWhen, resolveContext, fieldType = "string" } = options;
-	const filterOps = [
-		"getAll",
-		"findAll",
-		"aggregatePaginate",
-		"lookupPopulate"
-	];
-	const queryReadOps = [
-		"getById",
-		"getByQuery",
-		"getOne",
-		"count",
-		"exists",
-		"getOrCreate",
-		"distinct",
-		"aggregate"
-	];
-	const constrainedWriteOps = [
-		"update",
-		"delete",
-		"restore"
-	];
-	const filterReadOps = ["getDeleted"];
-	const createOps = ["create", "createMany"];
-	const batchQueryOps = ["updateMany", "deleteMany"];
-	const bulkOps = ["bulkWrite"];
-	const allOps = [
-		...filterOps,
-		...filterReadOps,
-		...queryReadOps,
-		...constrainedWriteOps,
-		...createOps,
-		...batchQueryOps,
-		...bulkOps
-	];
+	const extraOps = [{
+		op: "getDeleted",
+		policyKey: "filters"
+	}];
 	return {
 		name: "multi-tenant",
 		apply(repo) {
-			for (const op of allOps) {
+			const allOps = [...ALL_OPERATIONS.map((op) => ({
+				op,
+				policyKey: OP_REGISTRY[op].policyKey
+			})), ...extraOps];
+			for (const { op, policyKey } of allOps) {
 				if (skipOperations.includes(op)) continue;
+				if (policyKey === "none") continue;
 				repo.on(`before:${op}`, (context) => {
 					if (skipWhen?.(context, op)) return;
 					let tenantId = context[contextKey];
@@ -3769,45 +4033,49 @@ function multiTenantPlugin(options = {}) {
 					if (!tenantId && required) throw new Error(`[mongokit] Multi-tenant: Missing '${contextKey}' in context for '${op}'. Pass it via options or set required: false.`);
 					if (!tenantId) return;
 					const castId = fieldType === "objectId" ? new mongoose.Types.ObjectId(tenantId) : tenantId;
-					if (filterOps.includes(op) || filterReadOps.includes(op)) context.filters = {
-						...context.filters,
-						[tenantField]: castId
-					};
-					if (queryReadOps.includes(op)) context.query = {
-						...context.query,
-						[tenantField]: castId
-					};
-					if (op === "create" && context.data) context.data[tenantField] = castId;
-					if (op === "createMany" && context.dataArray) {
-						for (const doc of context.dataArray) if (doc && typeof doc === "object") doc[tenantField] = castId;
-					}
-					if (constrainedWriteOps.includes(op)) context.query = {
-						...context.query,
-						[tenantField]: castId
-					};
-					if (batchQueryOps.includes(op)) context.query = {
-						...context.query,
-						[tenantField]: castId
-					};
-					if (op === "bulkWrite" && context.operations) {
-						const ops = context.operations;
-						for (const subOp of ops) {
-							for (const key of [
-								"updateOne",
-								"updateMany",
-								"deleteOne",
-								"deleteMany",
-								"replaceOne"
-							]) {
-								const opBody = subOp[key];
-								if (opBody?.filter) opBody.filter = {
-									...opBody.filter,
-									[tenantField]: castId
-								};
+					switch (policyKey) {
+						case "filters":
+							context.filters = {
+								...context.filters,
+								[tenantField]: castId
+							};
+							break;
+						case "query":
+							context.query = {
+								...context.query,
+								[tenantField]: castId
+							};
+							break;
+						case "data":
+							if (context.data) context.data[tenantField] = castId;
+							break;
+						case "dataArray":
+							if (context.dataArray) {
+								for (const doc of context.dataArray) if (doc && typeof doc === "object") doc[tenantField] = castId;
 							}
-							const insertBody = subOp.insertOne;
-							if (insertBody?.document) insertBody.document[tenantField] = castId;
-						}
+							break;
+						case "operations":
+							if (context.operations) {
+								const ops = context.operations;
+								for (const subOp of ops) {
+									for (const key of [
+										"updateOne",
+										"updateMany",
+										"deleteOne",
+										"deleteMany",
+										"replaceOne"
+									]) {
+										const opBody = subOp[key];
+										if (opBody?.filter) opBody.filter = {
+											...opBody.filter,
+											[tenantField]: castId
+										};
+									}
+									const insertBody = subOp.insertOne;
+									if (insertBody?.document) insertBody.document[tenantField] = castId;
+								}
+							}
+							break;
 					}
 				}, { priority: HOOK_PRIORITY.POLICY });
 			}
@@ -3816,24 +4084,26 @@ function multiTenantPlugin(options = {}) {
 }
 //#endregion
 //#region src/plugins/observability.plugin.ts
-const DEFAULT_OPS = [
-	"create",
-	"createMany",
-	"update",
-	"delete",
-	"getById",
-	"getByQuery",
-	"getOne",
-	"getAll",
-	"findAll",
-	"getOrCreate",
-	"count",
-	"exists",
-	"distinct",
-	"aggregate",
-	"aggregatePaginate",
-	"lookupPopulate"
-];
+/**
+* Observability Plugin
+*
+* Adds operation timing, structured metrics, and APM hook points.
+* Works with any monitoring system — just provide an onMetric callback.
+*
+* @example
+* ```typescript
+* const repo = new Repository(User, [
+*   observabilityPlugin({
+*     onMetric: (metric) => {
+*       // Send to DataDog, New Relic, OpenTelemetry, or console
+*       console.log(`${metric.operation} took ${metric.durationMs}ms`);
+*       statsd.histogram('mongokit.operation', metric.durationMs, { op: metric.operation });
+*     },
+*   }),
+* ]);
+* ```
+*/
+const DEFAULT_OPS = ALL_OPERATIONS;
 const timers = /* @__PURE__ */ new WeakMap();
 function observabilityPlugin(options) {
 	const { onMetric, slowThresholdMs } = options;
@@ -4004,22 +4274,19 @@ function softDeletePlugin(options = {}) {
 					};
 				}
 			};
-			for (const op of [
-				"getAll",
-				"findAll",
-				"aggregatePaginate",
-				"lookupPopulate"
-			]) repo.on(`before:${op}`, injectDeleteFilterToFilters, { priority: HOOK_PRIORITY.POLICY });
-			for (const op of [
-				"getById",
-				"getOne",
-				"getByQuery",
-				"count",
-				"exists",
-				"getOrCreate",
-				"distinct",
-				"aggregate"
-			]) repo.on(`before:${op}`, injectDeleteFilterToQuery, { priority: HOOK_PRIORITY.POLICY });
+			const SOFT_DELETE_SPECIAL = new Set([
+				"updateMany",
+				"deleteMany",
+				"bulkWrite"
+			]);
+			for (const op of ALL_OPERATIONS) {
+				if (SOFT_DELETE_SPECIAL.has(op)) continue;
+				const desc = OP_REGISTRY[op];
+				const isFilterableMutation = op === "findOneAndUpdate";
+				if (desc.mutates && !isFilterableMutation) continue;
+				if (desc.policyKey === "filters") repo.on(`before:${op}`, injectDeleteFilterToFilters, { priority: HOOK_PRIORITY.POLICY });
+				else if (desc.policyKey === "query") repo.on(`before:${op}`, injectDeleteFilterToQuery, { priority: HOOK_PRIORITY.POLICY });
+			}
 			repo.on("before:updateMany", (context) => {
 				if (options.soft !== false) {
 					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
@@ -4041,24 +4308,6 @@ function softDeletePlugin(options = {}) {
 					context.softDeleted = true;
 				}
 			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:aggregate", (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.query = {
-						...context.query || {},
-						...deleteFilter
-					};
-				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:aggregatePaginate", (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.filters = {
-						...context.filters || {},
-						...deleteFilter
-					};
-				}
-			}, { priority: HOOK_PRIORITY.POLICY });
 			if (addRestoreMethod) {
 				const restoreMethod = async function(id, restoreOptions = {}) {
 					const context = await this._buildContext("restore", {
@@ -4215,6 +4464,57 @@ function subdocumentPlugin() {
 	};
 }
 //#endregion
+//#region src/plugins/tenant-context.ts
+/**
+* Request-scoped tenant context via AsyncLocalStorage.
+*
+* The multi-tenant plugin already accepts a `resolveContext` callback for
+* reading tenant ID from an external store. This helper wraps Node's
+* `AsyncLocalStorage` into a tiny, batteries-included API so apps don't need
+* to wire the plumbing by hand — a common source of cross-tenant leaks.
+*
+* @example
+*   import { createTenantContext, multiTenantPlugin } from '@classytic/mongokit';
+*
+*   const tenantContext = createTenantContext();
+*
+*   // In your HTTP middleware (Express / Fastify / NestJS):
+*   app.use((req, _res, next) => {
+*     tenantContext.run({ tenantId: req.auth.organizationId }, next);
+*   });
+*
+*   // In your repository definition:
+*   const repo = new Repository(Invoice, [
+*     multiTenantPlugin({
+*       tenantField: 'organizationId',
+*       resolveContext: () => tenantContext.getTenantId(),
+*     }),
+*   ]);
+*
+*   // In your handler — no need to pass organizationId manually:
+*   await repo.getAll({ filters: { status: 'paid' } });
+*/
+function createTenantContext() {
+	const storage = new AsyncLocalStorage();
+	return {
+		storage,
+		run(store, fn) {
+			return storage.run(store, fn);
+		},
+		getStore() {
+			return storage.getStore();
+		},
+		getTenantId() {
+			return storage.getStore()?.tenantId;
+		},
+		requireTenantId() {
+			const id = storage.getStore()?.tenantId;
+			if (!id) throw new Error("[mongokit] No tenant context active. Wrap the request in tenantContext.run({ tenantId }, fn).");
+			return id;
+		}
+	};
+}
+//#endregion
 //#region src/plugins/timestamp.plugin.ts
 /**
 * Timestamp plugin that auto-injects timestamps
@@ -4236,6 +4536,20 @@ function timestampPlugin() {
 				if (!context.data) return;
 				context.data.updatedAt = /* @__PURE__ */ new Date();
 			});
+			repo.on("before:findOneAndUpdate", (context) => {
+				if (!context.data) return;
+				const now = /* @__PURE__ */ new Date();
+				if (Array.isArray(context.data)) return;
+				const update = context.data;
+				if (Object.keys(update).some((k) => k.startsWith("$"))) {
+					const set = update.$set || {};
+					set.updatedAt = now;
+					update.$set = set;
+					const setOnInsert = update.$setOnInsert || {};
+					if (!("createdAt" in setOnInsert)) setOnInsert.createdAt = now;
+					update.$setOnInsert = setOnInsert;
+				} else update.updatedAt = now;
+			});
 		}
 	};
 }
@@ -4262,6 +4576,7 @@ function validationChainPlugin(validators = [], options = {}) {
 	const validatorsByOperation = {
 		create: [],
 		update: [],
+		findOneAndUpdate: [],
 		delete: [],
 		createMany: []
 	};
@@ -4300,6 +4615,7 @@ function validationChainPlugin(validators = [], options = {}) {
 			repo.on("before:create", async (context) => runValidators("create", context));
 			repo.on("before:createMany", async (context) => runValidators("createMany", context));
 			repo.on("before:update", async (context) => runValidators("update", context));
+			repo.on("before:findOneAndUpdate", async (context) => runValidators("findOneAndUpdate", context));
 			repo.on("before:delete", async (context) => runValidators("delete", context));
 		}
 	};
@@ -4388,4 +4704,4 @@ function uniqueField(field, errorMessage) {
 	};
 }
 //#endregion
-export { auditTrailPlugin as A, HOOK_PRIORITY as C, AggregationBuilder as D, withTransaction as E, aggregateHelpersPlugin as M, batchOperationsPlugin as O, cachePlugin as S, isTransactionUnsupported as T, dateSequentialId as _, uniqueField as a, sequentialId as b, subdocumentPlugin as c, multiTenantPlugin as d, mongoOperationsPlugin as f, customIdPlugin as g, elasticSearchPlugin as h, requireField as i, auditLogPlugin as j, AuditTrailQuery as k, softDeletePlugin as l, fieldFilterPlugin as m, blockIf as n, validationChainPlugin as o, methodRegistryPlugin as p, immutableField as r, timestampPlugin as s, autoInject as t, observabilityPlugin as u, getNextSequence as v, Repository as w, cascadePlugin as x, prefixedId as y };
+export { AuditTrailQuery as A, cachePlugin as C, withTransaction as D, isTransactionUnsupported as E, MUTATING_OPERATIONS as F, OP_REGISTRY as I, READ_OPERATIONS as L, auditLogPlugin as M, aggregateHelpersPlugin as N, AggregationBuilder as O, ALL_OPERATIONS as P, operationsByPolicyKey as R, cascadePlugin as S, Repository as T, customIdPlugin as _, uniqueField as a, prefixedId as b, createTenantContext as c, observabilityPlugin as d, multiTenantPlugin as f, elasticSearchPlugin as g, fieldFilterPlugin as h, requireField as i, auditTrailPlugin as j, batchOperationsPlugin as k, subdocumentPlugin as l, methodRegistryPlugin as m, blockIf as n, validationChainPlugin as o, mongoOperationsPlugin as p, immutableField as r, timestampPlugin as s, autoInject as t, softDeletePlugin as u, dateSequentialId as v, HOOK_PRIORITY as w, sequentialId as x, getNextSequence as y };