@classytic/mongokit 3.17.0 → 3.19.0

package/dist/validation-chain.plugin-DHZbpb4t.mjs

@@ -0,0 +1,1056 @@
+import { s as ALL_OPERATIONS } from "./Repository-B01VW_fU.mjs";
+import { _ as upsert } from "./update-CvCMv5Cl.mjs";
+import { n as warn } from "./logger-B8wf-Mtb.mjs";
+import { t as createError } from "./error-BTeepSNL.mjs";
+import { r as getFieldsForUser } from "./field-selection-d1qdRiMr.mjs";
+import mongoose from "mongoose";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/plugins/aggregate-helpers.plugin.ts
+/**
+* Aggregate helpers plugin
+*
+* @example
+* const repo = new Repository(Model, [
+*   methodRegistryPlugin(),
+*   aggregateHelpersPlugin(),
+* ]);
+*
+* const groups = await repo.groupBy('category');
+* const total = await repo.sum('amount', { status: 'completed' });
+*/
+function aggregateHelpersPlugin() {
+	return {
+		name: "aggregate-helpers",
+		apply(repo) {
+			if (!repo.registerMethod) throw new Error("aggregateHelpersPlugin requires methodRegistryPlugin");
+			/**
+			* Group by field
+			*/
+			repo.registerMethod("groupBy", async function(field, options = {}) {
+				const pipeline = [{ $group: {
+					_id: `$${field}`,
+					count: { $sum: 1 }
+				} }, { $sort: { count: -1 } }];
+				if (options.limit) pipeline.push({ $limit: options.limit });
+				return this.aggregatePipeline(pipeline, options);
+			});
+			const aggregateOperation = async function(field, operator, resultKey, query = {}, options = {}) {
+				const pipeline = [{ $match: query }, { $group: {
+					_id: null,
+					[resultKey]: { [operator]: `$${field}` }
+				} }];
+				return (await this.aggregatePipeline(pipeline, options))[0]?.[resultKey] || 0;
+			};
+			/**
+			* Sum field values
+			*/
+			repo.registerMethod("sum", async function(field, query = {}, options = {}) {
+				return aggregateOperation.call(this, field, "$sum", "total", query, options);
+			});
+			/**
+			* Average field values
+			*/
+			repo.registerMethod("average", async function(field, query = {}, options = {}) {
+				return aggregateOperation.call(this, field, "$avg", "avg", query, options);
+			});
+			/**
+			* Get minimum value
+			*/
+			repo.registerMethod("min", async function(field, query = {}, options = {}) {
+				return aggregateOperation.call(this, field, "$min", "min", query, options);
+			});
+			/**
+			* Get maximum value
+			*/
+			repo.registerMethod("max", async function(field, query = {}, options = {}) {
+				return aggregateOperation.call(this, field, "$max", "max", query, options);
+			});
+		}
+	};
+}
+//#endregion
+//#region src/plugins/cascade.plugin.ts
+/**
+* Cascade Delete Plugin
+*
+* Automatically deletes related documents when a parent document is deleted.
+*
+* Two routing modes per relation:
+*
+*   1. **Repo-routed (preferred)** — pass `repo: targetRepo` on the relation.
+*      Cascade calls `targetRepo.delete(id, { mode })` / `targetRepo.deleteMany(
+*      query, { mode })`, so the target's `before:delete` / `before:deleteMany`
+*      hooks fire. Multi-tenant scoping, audit logging, cache invalidation,
+*      and the target's own `softDeletePlugin` (with its configured
+*      `deletedField`) all run correctly.
+*
+*   2. **Model-routed (legacy)** — pass `model: 'TargetModelName'`. Cascade
+*      writes directly via `mongoose.models[name].updateMany / deleteMany`,
+*      **bypassing** the target's hooks. Safe only for trivial targets with
+*      no policy plugins. Retained for backwards compatibility — prefer the
+*      repo-routed form for new code.
+*
+* The parent's delete mode propagates: a hard-deleted parent cascades hard,
+* a soft-deleted parent cascades soft — unless `relation.softDelete` overrides
+* the decision per-relation.
+*
+* @example Repo-routed (new)
+* ```ts
+* const productRepo = new Repository(Product, [
+*   methodRegistryPlugin(),
+*   cascadePlugin({
+*     relations: [
+*       { repo: stockEntryRepo,    foreignKey: 'product' },
+*       { repo: stockMovementRepo, foreignKey: 'product' },
+*     ],
+*   }),
+* ]);
+* ```
+*
+* @example Model-routed (legacy)
+* ```ts
+* cascadePlugin({
+*   relations: [
+*     { model: 'StockEntry', foreignKey: 'product' },
+*   ],
+* });
+* ```
+*/
+/**
+* Collect top-level parent-context fields that a target plugin (multi-tenant,
+* audit) will likely need. We can't know the target's contextKey, so we
+* forward a well-known allow-list: `organizationId`, `tenantId`, and `user`.
+* These are the conventions enforced by the built-in plugins.
+*/
+function collectScopeForward(context) {
+	const out = {};
+	if (context.organizationId !== void 0) out.organizationId = context.organizationId;
+	if (context.tenantId !== void 0) out.tenantId = context.tenantId;
+	if (context.user !== void 0) out.user = context.user;
+	return out;
+}
+/**
+* Cascade delete plugin.
+*/
+function cascadePlugin(options) {
+	const { relations, parallel = true, logger } = options;
+	if (!relations || relations.length === 0) throw new Error("cascadePlugin requires at least one relation");
+	for (const rel of relations) {
+		if (!rel.repo && !rel.model) throw new Error("cascadePlugin: each relation needs either `repo` (preferred) or `model` (legacy)");
+		if (!rel.foreignKey) throw new Error("cascadePlugin: each relation needs `foreignKey`");
+	}
+	return {
+		name: "cascade",
+		apply(repo) {
+			repo.on("after:delete", async (payload) => {
+				const { context } = payload;
+				const deletedId = context.id;
+				if (!deletedId) {
+					logger?.warn?.("Cascade delete skipped: no document ID in context", { model: context.model });
+					return;
+				}
+				const isSoftParent = context.softDeleted === true;
+				const scopeForward = collectScopeForward(context);
+				const cascadeOne = async (relation) => {
+					const shouldSoftDelete = relation.softDelete ?? isSoftParent;
+					const cascadeCtx = {
+						targetModelName: relation.repo ? relation.repo.Model?.modelName ?? "<unknown>" : relation.model ?? "<unknown>",
+						session: context.session,
+						shouldSoftDelete,
+						user: context.user,
+						scopeForward
+					};
+					try {
+						if (relation.repo) await cascadeViaRepoBulk(relation, deletedId, cascadeCtx);
+						else await cascadeViaLegacyModel(relation, deletedId, cascadeCtx, logger);
+					} catch (error) {
+						logger?.error?.(`Cascade delete failed for '${cascadeCtx.targetModelName}'`, {
+							parentModel: context.model,
+							parentId: String(deletedId),
+							relatedModel: cascadeCtx.targetModelName,
+							foreignKey: relation.foreignKey,
+							error: error.message
+						});
+						throw error;
+					}
+				};
+				await runCascades(relations, cascadeOne, parallel);
+			});
+			repo.on("before:deleteMany", async (context) => {
+				const query = context.query;
+				if (!query || Object.keys(query).length === 0) return;
+				const idField = repo.idField || "_id";
+				context._cascadeIds = (await repo.Model.find(query, { [idField]: 1 }).lean().session(context.session ?? null)).map((doc) => doc[idField]);
+			});
+			repo.on("after:deleteMany", async (payload) => {
+				const { context } = payload;
+				const ids = context._cascadeIds;
+				if (!ids || ids.length === 0) return;
+				const isSoftParent = context.softDeleted === true;
+				const scopeForward = collectScopeForward(context);
+				const cascadeBulk = async (relation) => {
+					const shouldSoftDelete = relation.softDelete ?? isSoftParent;
+					const cascadeCtx = {
+						targetModelName: relation.repo ? relation.repo.Model?.modelName ?? "<unknown>" : relation.model ?? "<unknown>",
+						session: context.session,
+						shouldSoftDelete,
+						user: context.user,
+						scopeForward
+					};
+					try {
+						if (relation.repo) await cascadeViaRepoBulkMany(relation, ids, cascadeCtx);
+						else await cascadeViaLegacyModelMany(relation, ids, cascadeCtx, logger);
+					} catch (error) {
+						logger?.error?.(`Cascade deleteMany failed for '${cascadeCtx.targetModelName}'`, {
+							parentModel: context.model,
+							relatedModel: cascadeCtx.targetModelName,
+							foreignKey: relation.foreignKey,
+							error: error.message
+						});
+						throw error;
+					}
+				};
+				await runCascades(relations, cascadeBulk, parallel);
+			});
+		}
+	};
+}
+/**
+* Repo-routed cascade for a single parent delete.
+* Calls `repo.deleteMany({ [fk]: parentId }, { mode })` — respects all target
+* hooks (multi-tenant, audit, target's own soft-delete plugin).
+*/
+async function cascadeViaRepoBulk(relation, parentId, ctx) {
+	const targetRepo = relation.repo;
+	if (typeof targetRepo.deleteMany !== "function") throw new Error(`cascadePlugin: target repo for '${ctx.targetModelName}' is missing deleteMany(). Ensure the target is a mongokit Repository or implements the StandardRepo deleteMany contract.`);
+	await targetRepo.deleteMany({ [relation.foreignKey]: parentId }, {
+		...ctx.scopeForward,
+		mode: ctx.shouldSoftDelete ? "soft" : "hard",
+		session: ctx.session
+	});
+}
+/**
+* Repo-routed cascade for a bulk parent deleteMany — `$in` over snapshot ids.
+*/
+async function cascadeViaRepoBulkMany(relation, parentIds, ctx) {
+	const targetRepo = relation.repo;
+	if (typeof targetRepo.deleteMany !== "function") throw new Error(`cascadePlugin: target repo for '${ctx.targetModelName}' is missing deleteMany(). Ensure the target is a mongokit Repository or implements the StandardRepo deleteMany contract.`);
+	await targetRepo.deleteMany({ [relation.foreignKey]: { $in: parentIds } }, {
+		...ctx.scopeForward,
+		mode: ctx.shouldSoftDelete ? "soft" : "hard",
+		session: ctx.session
+	});
+}
+/**
+* Legacy cascade via `mongoose.models[name]`. Bypasses target hooks.
+* Retained for backwards compatibility with existing cascadePlugin consumers.
+*/
+async function cascadeViaLegacyModel(relation, parentId, ctx, logger) {
+	const RelatedModel = mongoose.models[relation.model];
+	if (!RelatedModel) {
+		logger?.warn?.(`Cascade delete skipped: model '${relation.model}' not found`);
+		return;
+	}
+	const query = { [relation.foreignKey]: parentId };
+	if (ctx.shouldSoftDelete) await RelatedModel.updateMany(query, {
+		deletedAt: /* @__PURE__ */ new Date(),
+		...ctx.user ? { deletedBy: ctx.user._id || ctx.user.id } : {}
+	}, { session: ctx.session });
+	else await RelatedModel.deleteMany(query, { session: ctx.session });
+}
+async function cascadeViaLegacyModelMany(relation, parentIds, ctx, logger) {
+	const RelatedModel = mongoose.models[relation.model];
+	if (!RelatedModel) {
+		logger?.warn?.(`Cascade deleteMany skipped: model '${relation.model}' not found`);
+		return;
+	}
+	const query = { [relation.foreignKey]: { $in: parentIds } };
+	if (ctx.shouldSoftDelete) await RelatedModel.updateMany(query, {
+		deletedAt: /* @__PURE__ */ new Date(),
+		...ctx.user ? { deletedBy: ctx.user._id || ctx.user.id } : {}
+	}, { session: ctx.session });
+	else await RelatedModel.deleteMany(query, { session: ctx.session });
+}
+/**
+* Execute a list of cascade operations, honoring the `parallel` flag.
+* Uses `allSettled` so one failure doesn't abort siblings; throws the first
+* rejection (with a composite message if several failed) after all complete.
+*/
+async function runCascades(relations, fn, parallel) {
+	if (parallel) {
+		const failures = (await Promise.allSettled(relations.map(fn))).filter((r) => r.status === "rejected");
+		if (failures.length) {
+			const err = failures[0].reason;
+			if (failures.length > 1) err.message = `${failures.length} cascade deletes failed. First: ${err.message}`;
+			throw err;
+		}
+	} else for (const relation of relations) await fn(relation);
+}
+//#endregion
+//#region src/plugins/elastic.plugin.ts
+function elasticSearchPlugin(options) {
+	return {
+		name: "elastic-search",
+		apply(repo) {
+			if (!repo.registerMethod) throw new Error("[mongokit] elasticSearchPlugin requires methodRegistryPlugin to be registered first. Add methodRegistryPlugin() before elasticSearchPlugin() in your repository plugins array.");
+			repo.registerMethod("search", async function(searchQuery, searchOptions = {}) {
+				const { client, index, idField = "_id" } = options;
+				const limit = Math.min(Math.max(searchOptions.limit || 20, 1), 1e3);
+				const from = Math.max(searchOptions.from || 0, 0);
+				const esResponse = await client.search({
+					index,
+					body: {
+						query: searchQuery,
+						size: limit,
+						from
+					}
+				});
+				const hits = esResponse.hits?.hits || esResponse.body?.hits?.hits || [];
+				if (hits.length === 0) return {
+					data: [],
+					total: 0,
+					limit,
+					from
+				};
+				const totalValue = esResponse.hits?.total?.value ?? esResponse.hits?.total ?? esResponse.body?.hits?.total?.value ?? esResponse.body?.hits?.total ?? 0;
+				const total = typeof totalValue === "number" ? totalValue : 0;
+				const docsOrder = /* @__PURE__ */ new Map();
+				const scores = /* @__PURE__ */ new Map();
+				const ids = [];
+				hits.forEach((hit, idx) => {
+					const docId = hit._source?.[idField] || hit[idField] || hit._id;
+					if (docId) {
+						const strId = String(docId);
+						docsOrder.set(strId, idx);
+						if (hit._score !== void 0) scores.set(strId, hit._score);
+						ids.push(strId);
+					}
+				});
+				if (ids.length === 0) return {
+					data: [],
+					total,
+					limit,
+					from
+				};
+				const mongoIdField = repo.idField || "_id";
+				const mongoQuery = this.Model.find({ [mongoIdField]: { $in: ids } });
+				if (searchOptions.mongoOptions?.select) mongoQuery.select(searchOptions.mongoOptions.select);
+				if (searchOptions.mongoOptions?.populate) mongoQuery.populate(searchOptions.mongoOptions.populate);
+				if (searchOptions.mongoOptions?.lean !== false) mongoQuery.lean();
+				return {
+					data: (await mongoQuery.exec()).sort((a, b) => {
+						const aId = String(a[mongoIdField]);
+						const bId = String(b[mongoIdField]);
+						return (docsOrder.get(aId) ?? Number.MAX_SAFE_INTEGER) - (docsOrder.get(bId) ?? Number.MAX_SAFE_INTEGER);
+					}).map((doc) => {
+						const strId = String(doc[mongoIdField]);
+						if (searchOptions.mongoOptions?.lean !== false) return {
+							...doc,
+							_score: scores.get(strId)
+						};
+						return doc;
+					}),
+					total,
+					limit,
+					from
+				};
+			});
+		}
+	};
+}
+//#endregion
+//#region src/plugins/field-filter.plugin.ts
+/**
+* Field filter plugin that restricts fields based on user context
+*
+* @example
+* const fieldPreset = {
+*   public: ['id', 'name'],
+*   authenticated: ['email'],
+*   admin: ['createdAt', 'internalNotes']
+* };
+*
+* const repo = new Repository(Model, [fieldFilterPlugin(fieldPreset)]);
+*/
+function fieldFilterPlugin(fieldPreset) {
+	return {
+		name: "fieldFilter",
+		apply(repo) {
+			const applyFieldFiltering = (context) => {
+				if (!fieldPreset) return;
+				const presetSelect = getFieldsForUser(context.context?.user || context.user, fieldPreset).join(" ");
+				if (context.select) context.select = `${presetSelect} ${context.select}`;
+				else context.select = presetSelect;
+			};
+			repo.on("before:getAll", applyFieldFiltering);
+			repo.on("before:findAll", applyFieldFiltering);
+			repo.on("before:getById", applyFieldFiltering);
+			repo.on("before:getByQuery", applyFieldFiltering);
+			repo.on("before:getOne", applyFieldFiltering);
+		}
+	};
+}
+//#endregion
+//#region src/plugins/lease.plugin.ts
+function leasePlugin(options = {}) {
+	const statusField = options.statusField ?? "status";
+	const leasedByField = options.leasedByField ?? "leasedBy";
+	const leaseExpiresAtField = options.leaseExpiresAtField ?? "leaseExpiresAt";
+	const pendingStatus = options.pendingStatus ?? "pending";
+	const processingStatus = options.processingStatus ?? "processing";
+	const doneStatus = options.doneStatus ?? "done";
+	const sort = options.sort ?? { createdAt: 1 };
+	return {
+		name: "lease",
+		apply(repo) {
+			if (!repo.registerMethod) throw new Error("leasePlugin requires methodRegistryPlugin. Add methodRegistryPlugin() before leasePlugin().");
+			/**
+			* Atomic FIFO lease claim — the canonical
+			*   findOneAndUpdate({ status: pending, OR leaseExpiresAt < now },
+			*                    { $set: { status: processing, leasedBy, leaseExpiresAt } },
+			*                    { sort })
+			* pattern, distilled.
+			*/
+			repo.registerMethod("lease", async function(opts) {
+				if (typeof opts?.leaseFor !== "number" || opts.leaseFor <= 0) throw createError(400, "leasePlugin.lease: leaseFor must be a positive number (ms)");
+				if (typeof opts.leasedBy !== "string" || opts.leasedBy.length === 0) throw createError(400, "leasePlugin.lease: leasedBy must be a non-empty string");
+				const now = /* @__PURE__ */ new Date();
+				const leaseUntil = new Date(now.getTime() + opts.leaseFor);
+				const claimFilter = {
+					...opts.filter ?? {},
+					$or: [{ [statusField]: pendingStatus }, { [leaseExpiresAtField]: { $lt: now } }]
+				};
+				return this.findOneAndUpdate(claimFilter, { $set: {
+					[statusField]: processingStatus,
+					[leasedByField]: opts.leasedBy,
+					[leaseExpiresAtField]: leaseUntil
+				} }, {
+					...opts.options ?? {},
+					sort,
+					returnDocument: "after"
+				});
+			});
+			repo.registerMethod("extend", async function(id, opts) {
+				if (typeof opts?.leaseFor !== "number" || opts.leaseFor <= 0) throw createError(400, "leasePlugin.extend: leaseFor must be a positive number (ms)");
+				const now = /* @__PURE__ */ new Date();
+				const leaseUntil = new Date(now.getTime() + opts.leaseFor);
+				const idField = this.idField || "_id";
+				return this.findOneAndUpdate({
+					[idField]: id,
+					[leasedByField]: opts.leasedBy,
+					[leaseExpiresAtField]: { $gt: now }
+				}, { $set: { [leaseExpiresAtField]: leaseUntil } }, {
+					...opts.options ?? {},
+					returnDocument: "after"
+				});
+			});
+			repo.registerMethod("release", async function(id, opts) {
+				if (typeof opts?.leasedBy !== "string" || opts.leasedBy.length === 0) throw createError(400, "leasePlugin.release: leasedBy must be a non-empty string (the holder finalising the lease)");
+				const finalStatus = opts.finalStatus ?? doneStatus;
+				const now = /* @__PURE__ */ new Date();
+				const idField = this.idField || "_id";
+				return this.findOneAndUpdate({
+					[idField]: id,
+					[leasedByField]: opts.leasedBy,
+					[leaseExpiresAtField]: { $gt: now }
+				}, {
+					$set: { [statusField]: finalStatus },
+					$unset: {
+						[leasedByField]: "",
+						[leaseExpiresAtField]: ""
+					}
+				}, {
+					...opts.options ?? {},
+					returnDocument: "after"
+				});
+			});
+		}
+	};
+}
+//#endregion
+//#region src/plugins/mongo-operations.plugin.ts
+/**
+* MongoDB Operations Plugin
+*
+* Adds MongoDB-specific operations to repositories.
+* Requires method-registry.plugin.js to be loaded first.
+*/
+/**
+* MongoDB operations plugin
+*
+* Adds MongoDB-specific atomic operations to repositories:
+* - upsert: Create or update document
+* - increment/decrement: Atomic numeric operations
+* - pushToArray/pullFromArray/addToSet: Array operations
+* - setField/unsetField/renameField: Field operations
+* - multiplyField: Multiply numeric field
+* - setMin/setMax: Conditional min/max updates
+*
+* @example Basic usage (no TypeScript autocomplete)
+* ```typescript
+* const repo = new Repository(ProductModel, [
+*   methodRegistryPlugin(),
+*   mongoOperationsPlugin(),
+* ]);
+*
+* // Works at runtime but TypeScript doesn't know about these methods
+* await (repo as any).increment(productId, 'views', 1);
+* await (repo as any).pushToArray(productId, 'tags', 'featured');
+* ```
+*
+* @example With TypeScript type safety (recommended)
+* ```typescript
+* import { Repository, mongoOperationsPlugin, methodRegistryPlugin } from '@classytic/mongokit';
+* import type { MongoOperationsMethods } from '@classytic/mongokit';
+*
+* class ProductRepo extends Repository<IProduct> {
+*   // Add your custom methods here
+* }
+*
+* // Create with type assertion to get autocomplete for plugin methods
+* type ProductRepoWithPlugins = ProductRepo & MongoOperationsMethods<IProduct>;
+*
+* const repo = new ProductRepo(ProductModel, [
+*   methodRegistryPlugin(),
+*   mongoOperationsPlugin(),
+* ]) as ProductRepoWithPlugins;
+*
+* // Now TypeScript provides autocomplete and type checking!
+* await repo.increment(productId, 'views', 1);
+* await repo.upsert({ sku: 'ABC' }, { name: 'Product', price: 99 });
+* await repo.pushToArray(productId, 'tags', 'featured');
+* ```
+*/
+function mongoOperationsPlugin() {
+	return {
+		name: "mongo-operations",
+		apply(repo) {
+			if (!repo.registerMethod) throw new Error("mongoOperationsPlugin requires methodRegistryPlugin. Add methodRegistryPlugin() before mongoOperationsPlugin() in plugins array.");
+			/**
+			* Update existing document or insert new one
+			*/
+			repo.registerMethod("upsert", async function(query, data, options = {}) {
+				return upsert(this.Model, query, data, options);
+			});
+			const validateAndUpdateNumeric = async function(id, field, value, operator, operationName, options) {
+				if (typeof value !== "number") throw createError(400, `${operationName} value must be a number`);
+				return this.update(id, { [operator]: { [field]: value } }, options);
+			};
+			/**
+			* Atomically increment numeric field
+			*/
+			repo.registerMethod("increment", async function(id, field, value = 1, options = {}) {
+				return validateAndUpdateNumeric.call(this, id, field, value, "$inc", "Increment", options);
+			});
+			/**
+			* Atomically decrement numeric field
+			*/
+			repo.registerMethod("decrement", async function(id, field, value = 1, options = {}) {
+				return validateAndUpdateNumeric.call(this, id, field, -value, "$inc", "Decrement", options);
+			});
+			const applyOperator = function(id, field, value, operator, options) {
+				return this.update(id, { [operator]: { [field]: value } }, options);
+			};
+			/**
+			* Push value to array field
+			*/
+			repo.registerMethod("pushToArray", async function(id, field, value, options = {}) {
+				return applyOperator.call(this, id, field, value, "$push", options);
+			});
+			/**
+			* Remove value from array field
+			*/
+			repo.registerMethod("pullFromArray", async function(id, field, value, options = {}) {
+				return applyOperator.call(this, id, field, value, "$pull", options);
+			});
+			/**
+			* Add value to array only if not already present (unique)
+			*/
+			repo.registerMethod("addToSet", async function(id, field, value, options = {}) {
+				return applyOperator.call(this, id, field, value, "$addToSet", options);
+			});
+			/**
+			* Set field value (alias for update with $set)
+			*/
+			repo.registerMethod("setField", async function(id, field, value, options = {}) {
+				return applyOperator.call(this, id, field, value, "$set", options);
+			});
+			/**
+			* Unset (remove) field from document
+			*/
+			repo.registerMethod("unsetField", async function(id, fields, options = {}) {
+				const unsetObj = (Array.isArray(fields) ? fields : [fields]).reduce((acc, field) => {
+					acc[field] = "";
+					return acc;
+				}, {});
+				return this.update(id, { $unset: unsetObj }, options);
+			});
+			/**
+			* Rename field in document
+			*/
+			repo.registerMethod("renameField", async function(id, oldName, newName, options = {}) {
+				return this.update(id, { $rename: { [oldName]: newName } }, options);
+			});
+			/**
+			* Multiply numeric field by value
+			*/
+			repo.registerMethod("multiplyField", async function(id, field, multiplier, options = {}) {
+				return validateAndUpdateNumeric.call(this, id, field, multiplier, "$mul", "Multiplier", options);
+			});
+			/**
+			* Set field to minimum value (only if current value is greater)
+			*/
+			repo.registerMethod("setMin", async function(id, field, value, options = {}) {
+				return applyOperator.call(this, id, field, value, "$min", options);
+			});
+			/**
+			* Set field to maximum value (only if current value is less)
+			*/
+			repo.registerMethod("setMax", async function(id, field, value, options = {}) {
+				return applyOperator.call(this, id, field, value, "$max", options);
+			});
+			/**
+			* Atomic conditional increment — only increments when the current
+			* value is strictly below `ceiling`. Returns the updated document
+			* on success, or `null` when the row is already at/above the
+			* ceiling (or the id doesn't match).
+			*
+			* Single round-trip via `findOneAndUpdate({ _id, [field]: { $lt:
+			* ceiling } }, { $inc: { [field]: by } })` — race-free across
+			* concurrent callers. The standard pattern for per-document
+			* concurrency limits / quotas / capacity caps that would
+			* otherwise need a 150-line lease loop.
+			*
+			* @example streamline strict-concurrency: claim a worker slot
+			* ```ts
+			* const claimed = await repo.incrementIfBelow(
+			*   tenantId,
+			*   'activeRuns',
+			*   maxConcurrent,
+			* );
+			* if (!claimed) return; // already at limit; another caller won
+			* ```
+			*/
+			repo.registerMethod("incrementIfBelow", async function(id, field, ceiling, by = 1, options = {}) {
+				if (typeof ceiling !== "number") throw createError(400, "incrementIfBelow ceiling must be a number");
+				if (typeof by !== "number") throw createError(400, "incrementIfBelow `by` must be a number");
+				if (typeof field !== "string" || field.length === 0) throw createError(400, "incrementIfBelow field must be a non-empty string");
+				for (const segment of field.split(".")) {
+					if (segment.length === 0) throw createError(400, `incrementIfBelow field has an empty segment ("${field}")`);
+					if (segment.startsWith("$")) throw createError(400, `incrementIfBelow field segment cannot start with '$' ("${segment}") — Mongo would treat it as an operator`);
+					if (segment === "__proto__" || segment === "constructor" || segment === "prototype") throw createError(400, `incrementIfBelow field segment "${segment}" is reserved (prototype-pollution guard)`);
+				}
+				const idField = this.idField || "_id";
+				return this.findOneAndUpdate({
+					[idField]: id,
+					[field]: { $lt: ceiling }
+				}, { $inc: { [field]: by } }, {
+					...options,
+					returnDocument: "after"
+				});
+			});
+			/**
+			* Atomic update with multiple MongoDB operators in a single call
+			*
+			* Combines $inc, $set, $push, $pull, $addToSet, $unset, $setOnInsert, $min, $max, $mul, $rename
+			* into one atomic database operation.
+			*
+			* @example
+			* // Combine $inc + $set in one atomic call
+			* await repo.atomicUpdate(id, {
+			*   $inc: { views: 1, commentCount: 1 },
+			*   $set: { lastActiveAt: new Date() }
+			* });
+			*
+			* // Multiple operators: $inc + $set + $push
+			* await repo.atomicUpdate(id, {
+			*   $inc: { 'metrics.total': 1 },
+			*   $set: { updatedAt: new Date() },
+			*   $push: { history: { action: 'update', at: new Date() } }
+			* });
+			*
+			* // $push with $each modifier
+			* await repo.atomicUpdate(id, {
+			*   $push: { tags: { $each: ['featured', 'popular'] } },
+			*   $inc: { tagCount: 2 }
+			* });
+			*
+			* // With arrayFilters for positional updates
+			* await repo.atomicUpdate(id, {
+			*   $set: { 'items.$[elem].quantity': 5 }
+			* }, { arrayFilters: [{ 'elem._id': itemId }] });
+			*/
+			repo.registerMethod("atomicUpdate", async function(id, operators, options = {}) {
+				const validOperators = new Set([
+					"$inc",
+					"$set",
+					"$unset",
+					"$push",
+					"$pull",
+					"$addToSet",
+					"$pop",
+					"$rename",
+					"$min",
+					"$max",
+					"$mul",
+					"$setOnInsert",
+					"$bit",
+					"$currentDate"
+				]);
+				const keys = Object.keys(operators);
+				if (keys.length === 0) throw createError(400, "atomicUpdate requires at least one operator");
+				for (const key of keys) if (!validOperators.has(key)) throw createError(400, `Invalid update operator: '${key}'. Valid operators: ${[...validOperators].join(", ")}`);
+				return this.update(id, operators, options);
+			});
+		}
+	};
+}
+//#endregion
+//#region src/plugins/observability.plugin.ts
+/**
+* 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;
+	const ops = options.operations ?? DEFAULT_OPS;
+	const isSkipped = (context) => {
+		const list = context.skipPlugins;
+		return Array.isArray(list) && list.includes("observability");
+	};
+	return {
+		name: "observability",
+		apply(repo) {
+			for (const op of ops) {
+				repo.on(`before:${op}`, (context) => {
+					if (isSkipped(context)) return;
+					timers.set(context, performance.now());
+				}, { priority: 300 });
+				repo.on(`after:${op}`, ({ context }) => {
+					if (isSkipped(context)) return;
+					const start = timers.get(context);
+					if (start == null) return;
+					const durationMs = Math.round((performance.now() - start) * 100) / 100;
+					timers.delete(context);
+					if (slowThresholdMs != null && durationMs < slowThresholdMs) return;
+					onMetric({
+						operation: op,
+						model: context.model || repo.model,
+						durationMs,
+						success: true,
+						startedAt: new Date(Date.now() - durationMs),
+						userId: context.user?._id?.toString() || context.user?.id?.toString(),
+						organizationId: context.organizationId?.toString()
+					});
+				});
+				repo.on(`error:${op}`, ({ context, error }) => {
+					if (isSkipped(context)) return;
+					const start = timers.get(context);
+					if (start == null) return;
+					const durationMs = Math.round((performance.now() - start) * 100) / 100;
+					timers.delete(context);
+					onMetric({
+						operation: op,
+						model: context.model || repo.model,
+						durationMs,
+						success: false,
+						error: error.message,
+						startedAt: new Date(Date.now() - durationMs),
+						userId: context.user?._id?.toString() || context.user?.id?.toString(),
+						organizationId: context.organizationId?.toString()
+					});
+				});
+			}
+		}
+	};
+}
+//#endregion
+//#region src/plugins/subdocument.plugin.ts
+/**
+* Subdocument plugin for managing nested arrays
+*
+* @example
+* const repo = new Repository(Model, [
+*   methodRegistryPlugin(),
+*   subdocumentPlugin(),
+* ]);
+*
+* await repo.addSubdocument(parentId, 'items', { name: 'Item 1' });
+* await repo.updateSubdocument(parentId, 'items', itemId, { name: 'Updated Item' });
+*/
+function subdocumentPlugin() {
+	return {
+		name: "subdocument",
+		apply(repo) {
+			if (!repo.registerMethod) throw new Error("subdocumentPlugin requires methodRegistryPlugin");
+			/**
+			* Add subdocument to array
+			*/
+			repo.registerMethod("addSubdocument", async function(parentId, arrayPath, subData, options = {}) {
+				return this.update(parentId, { $push: { [arrayPath]: subData } }, options);
+			});
+			/**
+			* Get subdocument from array
+			*/
+			repo.registerMethod("getSubdocument", async function(parentId, arrayPath, subId, options = {}) {
+				return this._executeQuery(async (Model) => {
+					const parent = await Model.findById(parentId).session(options.session).exec();
+					if (!parent) throw createError(404, "Parent not found");
+					const arrayField = parent[arrayPath];
+					if (!arrayField || typeof arrayField.id !== "function") throw createError(404, "Array field not found");
+					const sub = arrayField.id(subId);
+					if (!sub) throw createError(404, "Subdocument not found");
+					return options.lean && typeof sub.toObject === "function" ? sub.toObject() : sub;
+				});
+			});
+			/**
+			* Update subdocument in array
+			*/
+			repo.registerMethod("updateSubdocument", async function(parentId, arrayPath, subId, updateData, options = {}) {
+				return this._executeQuery(async (Model) => {
+					const query = {
+						_id: parentId,
+						[`${arrayPath}._id`]: subId
+					};
+					const update = { $set: { [`${arrayPath}.$`]: {
+						...updateData,
+						_id: subId
+					} } };
+					const result = await Model.findOneAndUpdate(query, update, {
+						returnDocument: "after",
+						runValidators: true,
+						session: options.session
+					}).exec();
+					if (!result) throw createError(404, "Parent or subdocument not found");
+					return result;
+				});
+			});
+			/**
+			* Delete subdocument from array
+			*/
+			repo.registerMethod("deleteSubdocument", async function(parentId, arrayPath, subId, options = {}) {
+				return this.update(parentId, { $pull: { [arrayPath]: { _id: subId } } }, options);
+			});
+		}
+	};
+}
+//#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/validation-chain.plugin.ts
+/**
+* Validation chain plugin
+*
+* @example
+* const repo = new Repository(Model, [
+*   validationChainPlugin([
+*     requireField('email'),
+*     uniqueField('email', 'Email already exists'),
+*     blockIf('no-delete-admin', ['delete'], ctx => ctx.data?.role === 'admin', 'Cannot delete admin'),
+*   ])
+* ]);
+*/
+function validationChainPlugin(validators = [], options = {}) {
+	const { stopOnFirstError = true } = options;
+	validators.forEach((v, idx) => {
+		if (!v.name || typeof v.name !== "string") throw new Error(`Validator at index ${idx} missing 'name' (string)`);
+		if (typeof v.validate !== "function") throw new Error(`Validator '${v.name}' missing 'validate' function`);
+	});
+	const validatorsByOperation = {
+		create: [],
+		update: [],
+		findOneAndUpdate: [],
+		delete: [],
+		createMany: []
+	};
+	const allOperationsValidators = [];
+	validators.forEach((v) => {
+		if (!v.operations || v.operations.length === 0) allOperationsValidators.push(v);
+		else v.operations.forEach((op) => {
+			if (validatorsByOperation[op]) validatorsByOperation[op].push(v);
+		});
+	});
+	return {
+		name: "validation-chain",
+		apply(repo) {
+			const getValidatorsForOperation = (operation) => {
+				const specific = validatorsByOperation[operation] || [];
+				return [...allOperationsValidators, ...specific];
+			};
+			const runValidators = async (operation, context) => {
+				const operationValidators = getValidatorsForOperation(operation);
+				const errors = [];
+				for (const validator of operationValidators) try {
+					await validator.validate(context, repo);
+				} catch (error) {
+					if (stopOnFirstError) throw error;
+					errors.push({
+						validator: validator.name,
+						error: error.message || String(error)
+					});
+				}
+				if (errors.length > 0) {
+					const err = createError(400, `Validation failed: ${errors.map((e) => `[${e.validator}] ${e.error}`).join("; ")}`);
+					err.validationErrors = errors;
+					throw err;
+				}
+			};
+			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));
+		}
+	};
+}
+/**
+* Block operation if condition is true
+*
+* @example
+* blockIf('block-library', ['delete'], ctx => ctx.data?.managed, 'Cannot delete managed records')
+*/
+function blockIf(name, operations, condition, errorMessage) {
+	return {
+		name,
+		operations,
+		validate: (context) => {
+			if (condition(context)) throw createError(403, errorMessage);
+		}
+	};
+}
+/**
+* Require a field to be present
+*/
+function requireField(field, operations = ["create"]) {
+	return {
+		name: `require-${field}`,
+		operations,
+		validate: (context) => {
+			if (!context.data || context.data[field] === void 0 || context.data[field] === null) throw createError(400, `Field '${field}' is required`);
+		}
+	};
+}
+/**
+* Auto-inject a value if not present
+*/
+function autoInject(field, getter, operations = ["create"]) {
+	return {
+		name: `auto-inject-${field}`,
+		operations,
+		validate: (context) => {
+			if (context.data && !(field in context.data)) {
+				const value = getter(context);
+				if (value !== null && value !== void 0) context.data[field] = value;
+			}
+		}
+	};
+}
+/**
+* Make a field immutable (cannot be updated)
+*/
+function immutableField(field) {
+	return {
+		name: `immutable-${field}`,
+		operations: ["update"],
+		validate: (context) => {
+			if (context.data && field in context.data) throw createError(400, `Field '${field}' cannot be modified`);
+		}
+	};
+}
+/**
+* Ensure field value is unique
+*/
+function uniqueField(field, errorMessage) {
+	return {
+		name: `unique-${field}`,
+		operations: ["create", "update"],
+		validate: async (context, repo) => {
+			if (!context.data?.[field]) return;
+			if (!repo) {
+				warn(`[mongokit] uniqueField('${field}'): repo not available, skipping uniqueness check`);
+				return;
+			}
+			const query = { [field]: context.data[field] };
+			const getByQuery = repo.getByQuery;
+			if (typeof getByQuery !== "function") {
+				warn(`[mongokit] uniqueField('${field}'): getByQuery not available on repo, skipping uniqueness check`);
+				return;
+			}
+			const idKey = repo.idField || "_id";
+			const existing = await getByQuery.call(repo, query, {
+				select: idKey,
+				lean: true,
+				throwOnNotFound: false
+			});
+			if (existing && String(existing[idKey]) !== String(context.id)) throw createError(409, errorMessage || `${field} already exists`);
+		}
+	};
+}
+//#endregion
+export { uniqueField as a, subdocumentPlugin as c, leasePlugin as d, fieldFilterPlugin as f, aggregateHelpersPlugin as h, requireField as i, observabilityPlugin as l, cascadePlugin as m, blockIf as n, validationChainPlugin as o, elasticSearchPlugin as p, immutableField as r, createTenantContext as s, autoInject as t, mongoOperationsPlugin as u };