@classytic/mongokit 3.11.1 → 3.13.0

package/dist/validation-chain.plugin-_-WuNml2.mjs

@@ -0,0 +1,2399 @@
+import { _ as upsert } from "./update-DLcSSa5b.mjs";
+import { n as warn } from "./logger-DprijP5h.mjs";
+import { t as createError } from "./error-B00pI7dV.mjs";
+import { l as OP_REGISTRY, s as ALL_OPERATIONS, t as HOOK_PRIORITY } from "./Repository-BY40uhcv.mjs";
+import { r as getFieldsForUser } from "./field-selection-Br3WPOEb.mjs";
+import mongoose from "mongoose";
+import { cachePlugin } from "@classytic/repo-core/cache";
+import { adminBypass, payloadHasTenantField } from "@classytic/repo-core/plugins";
+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/audit-log.plugin.ts
+/**
+* Audit log plugin that logs all repository operations
+*
+* @example
+* const repo = new Repository(Model, [auditLogPlugin(console)]);
+*
+* Hot-path opt-out — skip per call by passing `skipPlugins: ['auditLog']`
+* in the operation options. The plugin honors the flag for every
+* listener it registers; security/correctness plugins (multi-tenant,
+* cache invalidation, soft-delete) deliberately do NOT honor it.
+*/
+const PLUGIN_NAME = "auditLog";
+/** True when the caller passed `skipPlugins: ['auditLog', ...]`. */
+function isSkipped(context) {
+	const list = context.skipPlugins;
+	return Array.isArray(list) && list.includes(PLUGIN_NAME);
+}
+function auditLogPlugin(logger) {
+	return {
+		name: PLUGIN_NAME,
+		apply(repo) {
+			repo.on("after:create", ({ context, result }) => {
+				if (isSkipped(context)) return;
+				const idKey = repo.idField || "_id";
+				logger?.info?.("Document created", {
+					model: context.model || repo.model,
+					id: result?.[idKey],
+					userId: context.user?._id || context.user?.id,
+					organizationId: context.organizationId
+				});
+			});
+			repo.on("after:update", ({ context, result }) => {
+				if (isSkipped(context)) return;
+				logger?.info?.("Document updated", {
+					model: context.model || repo.model,
+					id: context.id || result?.[repo.idField || "_id"],
+					userId: context.user?._id || context.user?.id,
+					organizationId: context.organizationId
+				});
+			});
+			repo.on("after:findOneAndUpdate", ({ context, result }) => {
+				if (isSkipped(context)) return;
+				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 }) => {
+				if (isSkipped(context)) return;
+				logger?.error?.("findOneAndUpdate failed", {
+					model: context.model || repo.model,
+					error: error.message,
+					userId: context.user?._id || context.user?.id
+				});
+			});
+			repo.on("after:delete", ({ context }) => {
+				if (isSkipped(context)) return;
+				logger?.info?.("Document deleted", {
+					model: context.model || repo.model,
+					id: context.id,
+					userId: context.user?._id || context.user?.id,
+					organizationId: context.organizationId
+				});
+			});
+			repo.on("error:create", ({ context, error }) => {
+				if (isSkipped(context)) return;
+				logger?.error?.("Create failed", {
+					model: context.model || repo.model,
+					error: error.message,
+					userId: context.user?._id || context.user?.id
+				});
+			});
+			repo.on("error:update", ({ context, error }) => {
+				if (isSkipped(context)) return;
+				logger?.error?.("Update failed", {
+					model: context.model || repo.model,
+					id: context.id,
+					error: error.message,
+					userId: context.user?._id || context.user?.id
+				});
+			});
+			repo.on("error:delete", ({ context, error }) => {
+				if (isSkipped(context)) return;
+				logger?.error?.("Delete failed", {
+					model: context.model || repo.model,
+					id: context.id,
+					error: error.message,
+					userId: context.user?._id || context.user?.id
+				});
+			});
+		}
+	};
+}
+//#endregion
+//#region src/plugins/audit-trail.plugin.ts
+/**
+* Audit Trail Plugin
+*
+* Persists operation audit entries to a MongoDB collection.
+* Fire-and-forget: writes happen async and never block or fail the main operation.
+*
+* Features:
+* - Tracks create, update, delete operations
+* - Field-level change tracking (before/after diff on updates)
+* - TTL auto-cleanup via MongoDB TTL index
+* - Custom metadata per entry (IP, user-agent, etc.)
+* - Shared `audit_trails` collection across all models
+*
+* @example
+* ```typescript
+* const repo = new Repository(Job, [
+*   auditTrailPlugin({
+*     operations: ['create', 'update', 'delete'],
+*     trackChanges: true,
+*     ttlDays: 90,
+*     metadata: (context) => ({
+*       ip: context.req?.ip,
+*     }),
+*   }),
+* ]);
+* ```
+*/
+const modelCache = /* @__PURE__ */ new Map();
+function getAuditModel(collectionName, ttlDays) {
+	const existing = modelCache.get(collectionName);
+	if (existing) return existing;
+	const schema = new mongoose.Schema({
+		model: {
+			type: String,
+			required: true,
+			index: true
+		},
+		operation: {
+			type: String,
+			required: true,
+			enum: [
+				"create",
+				"update",
+				"findOneAndUpdate",
+				"delete"
+			]
+		},
+		documentId: {
+			type: mongoose.Schema.Types.Mixed,
+			required: true,
+			index: true
+		},
+		userId: {
+			type: mongoose.Schema.Types.Mixed,
+			index: true
+		},
+		orgId: {
+			type: mongoose.Schema.Types.Mixed,
+			index: true
+		},
+		changes: { type: mongoose.Schema.Types.Mixed },
+		document: { type: mongoose.Schema.Types.Mixed },
+		metadata: { type: mongoose.Schema.Types.Mixed },
+		timestamp: {
+			type: Date,
+			default: Date.now,
+			index: true
+		}
+	}, {
+		collection: collectionName,
+		versionKey: false
+	});
+	schema.index({
+		model: 1,
+		documentId: 1,
+		timestamp: -1
+	});
+	schema.index({
+		orgId: 1,
+		userId: 1,
+		timestamp: -1
+	});
+	if (ttlDays !== void 0 && ttlDays > 0) {
+		const ttlSeconds = ttlDays * 24 * 60 * 60;
+		schema.index({ timestamp: 1 }, { expireAfterSeconds: ttlSeconds });
+	}
+	const modelName = `AuditTrail_${collectionName}`;
+	const model = mongoose.models[modelName] || mongoose.model(modelName, schema);
+	modelCache.set(collectionName, model);
+	return model;
+}
+/** Compute field-level diff between previous and updated document */
+function computeChanges(prev, next, excludeFields) {
+	const changes = {};
+	const exclude = new Set(excludeFields);
+	for (const key of Object.keys(next)) {
+		if (exclude.has(key)) continue;
+		if (key === "_id" || key === "__v" || key === "updatedAt") continue;
+		const prevVal = prev[key];
+		const nextVal = next[key];
+		if (!deepEqual(prevVal, nextVal)) changes[key] = {
+			from: prevVal,
+			to: nextVal
+		};
+	}
+	return Object.keys(changes).length > 0 ? changes : void 0;
+}
+/** Simple deep equality check for audit diffing */
+function deepEqual(a, b) {
+	if (a === b) return true;
+	if (a == null && b == null) return true;
+	if (a == null || b == null) return false;
+	if (typeof a === "object" && typeof b === "object") {
+		const aStr = a.toString?.();
+		const bStr = b.toString?.();
+		if (aStr && bStr && aStr === bStr) return true;
+	}
+	if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+	try {
+		return JSON.stringify(a) === JSON.stringify(b);
+	} catch {
+		return false;
+	}
+}
+/** Extract user ID from context */
+function getUserId(context) {
+	return context.user?._id || context.user?.id;
+}
+/**
+* Fire-and-forget audit write. Never throws into the caller's promise
+* chain (audit failures must not break the primary operation), but
+* routes errors to `onWriteError` for compliance hosts that need
+* surface visibility. Default behavior: `console.warn`-only.
+*/
+function writeAudit(AuditModel, entry, onWriteError) {
+	Promise.resolve().then(() => {
+		AuditModel.create({
+			...entry,
+			timestamp: /* @__PURE__ */ new Date()
+		}).catch((err) => {
+			if (onWriteError) try {
+				onWriteError(err, entry);
+			} catch (cbErr) {
+				warn(`[auditTrailPlugin] onWriteError callback itself threw: ${cbErr.message}`);
+			}
+			else warn(`[auditTrailPlugin] Failed to write audit entry: ${err.message}`);
+		});
+	});
+}
+const snapshots = /* @__PURE__ */ new WeakMap();
+function auditTrailPlugin(options = {}) {
+	const { operations = [
+		"create",
+		"update",
+		"delete"
+	], trackChanges = true, trackDocument = false, ttlDays, collectionName = "audit_trails", metadata, excludeFields = [], onWriteError } = options;
+	const opsSet = new Set(operations);
+	const isSkipped = (context) => {
+		const list = context.skipPlugins;
+		return Array.isArray(list) && list.includes("auditTrail");
+	};
+	return {
+		name: "auditTrail",
+		apply(repo) {
+			const AuditModel = getAuditModel(collectionName, ttlDays);
+			if (opsSet.has("create")) repo.on("after:create", ({ context, result }) => {
+				if (isSkipped(context)) return;
+				const doc = toPlainObject(result);
+				const idKey = repo.idField || "_id";
+				writeAudit(AuditModel, {
+					model: context.model || repo.model,
+					operation: "create",
+					documentId: doc?.[idKey],
+					userId: getUserId(context),
+					orgId: context.organizationId,
+					document: trackDocument ? sanitizeDoc(doc, excludeFields) : void 0,
+					metadata: metadata?.(context)
+				}, onWriteError);
+			});
+			if (opsSet.has("update")) {
+				if (trackChanges) repo.on("before:update", async (context) => {
+					if (isSkipped(context)) return;
+					if (!context.id) return;
+					try {
+						const prev = await repo.Model.findById(context.id).lean();
+						if (prev) snapshots.set(context, prev);
+					} catch (err) {
+						warn(`[auditTrailPlugin] Failed to snapshot before update: ${err.message}`);
+					}
+				});
+				repo.on("after:update", ({ context, result }) => {
+					if (isSkipped(context)) return;
+					const doc = result;
+					let changes;
+					if (trackChanges) {
+						const prev = snapshots.get(context);
+						if (prev && context.data) changes = computeChanges(prev, context.data, excludeFields);
+						snapshots.delete(context);
+					}
+					writeAudit(AuditModel, {
+						model: context.model || repo.model,
+						operation: "update",
+						documentId: context.id || doc?.[repo.idField || "_id"],
+						userId: getUserId(context),
+						orgId: context.organizationId,
+						changes,
+						metadata: metadata?.(context)
+					}, onWriteError);
+				});
+			}
+			if (opsSet.has("findOneAndUpdate")) repo.on("after:findOneAndUpdate", ({ context, result }) => {
+				if (isSkipped(context)) return;
+				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)
+				}, onWriteError);
+			});
+			if (opsSet.has("delete")) repo.on("after:delete", ({ context }) => {
+				if (isSkipped(context)) return;
+				writeAudit(AuditModel, {
+					model: context.model || repo.model,
+					operation: "delete",
+					documentId: context.id,
+					userId: getUserId(context),
+					orgId: context.organizationId,
+					metadata: metadata?.(context)
+				}, onWriteError);
+			});
+			if (typeof repo.registerMethod === "function")
+ /**
+			* Get audit trail for a specific document
+			*/
+			repo.registerMethod("getAuditTrail", async function(documentId, queryOptions = {}) {
+				const { page = 1, limit = 20, operation } = queryOptions;
+				const skip = (page - 1) * limit;
+				const filter = {
+					model: this.model,
+					documentId
+				};
+				if (operation) filter.operation = operation;
+				const [data, total] = await Promise.all([AuditModel.find(filter).sort({ timestamp: -1 }).skip(skip).limit(limit).lean(), AuditModel.countDocuments(filter)]);
+				return {
+					data,
+					page,
+					limit,
+					total,
+					pages: Math.ceil(total / limit),
+					hasNext: page < Math.ceil(total / limit),
+					hasPrev: page > 1
+				};
+			});
+		}
+	};
+}
+/** Convert Mongoose document to plain object */
+function toPlainObject(doc) {
+	if (!doc) return {};
+	if (typeof doc.toObject === "function") return doc.toObject();
+	return doc;
+}
+/** Remove excluded fields from a document snapshot */
+function sanitizeDoc(doc, excludeFields) {
+	if (excludeFields.length === 0) return doc;
+	const result = { ...doc };
+	for (const field of excludeFields) delete result[field];
+	return result;
+}
+/**
+* Standalone audit trail query utility.
+* Use this to query audits across all models — e.g., admin dashboards, audit APIs.
+*
+* @example
+* ```typescript
+* import { AuditTrailQuery } from '@classytic/mongokit';
+*
+* const auditQuery = new AuditTrailQuery(); // defaults to 'audit_trails' collection
+*
+* // All audits for an org
+* const orgAudits = await auditQuery.query({ orgId: '...' });
+*
+* // All updates by a user
+* const userUpdates = await auditQuery.query({
+*   userId: '...',
+*   operation: 'update',
+* });
+*
+* // All audits for a specific document
+* const docHistory = await auditQuery.query({
+*   model: 'Job',
+*   documentId: '...',
+* });
+*
+* // Date range
+* const recent = await auditQuery.query({
+*   from: new Date('2025-01-01'),
+*   to: new Date(),
+*   page: 1,
+*   limit: 50,
+* });
+*
+* // Direct model access for custom queries
+* const model = auditQuery.getModel();
+* const count = await model.countDocuments({ operation: 'delete' });
+* ```
+*/
+var AuditTrailQuery = class {
+	model;
+	constructor(collectionName = "audit_trails", ttlDays) {
+		this.model = getAuditModel(collectionName, ttlDays);
+	}
+	/**
+	* Get the underlying Mongoose model for custom queries
+	*/
+	getModel() {
+		return this.model;
+	}
+	/**
+	* Query audit entries with filters and pagination
+	*/
+	async query(options = {}) {
+		const { page = 1, limit = 20 } = options;
+		const skip = (page - 1) * limit;
+		const filter = {};
+		if (options.model) filter.model = options.model;
+		if (options.documentId) filter.documentId = options.documentId;
+		if (options.userId) filter.userId = options.userId;
+		if (options.orgId) filter.orgId = options.orgId;
+		if (options.operation) filter.operation = options.operation;
+		if (options.from || options.to) {
+			const dateFilter = {};
+			if (options.from) dateFilter.$gte = options.from;
+			if (options.to) dateFilter.$lte = options.to;
+			filter.timestamp = dateFilter;
+		}
+		const [data, total] = await Promise.all([this.model.find(filter).sort({ timestamp: -1 }).skip(skip).limit(limit).lean(), this.model.countDocuments(filter)]);
+		const pages = Math.ceil(total / limit);
+		return {
+			data,
+			page,
+			limit,
+			total,
+			pages,
+			hasNext: page < pages,
+			hasPrev: page > 1
+		};
+	}
+	/**
+	* Get audit trail for a specific document
+	*/
+	async getDocumentTrail(model, documentId, options = {}) {
+		return this.query({
+			model,
+			documentId,
+			...options
+		});
+	}
+	/**
+	* Get all audits for a user
+	*/
+	async getUserTrail(userId, options = {}) {
+		return this.query({
+			userId,
+			...options
+		});
+	}
+	/**
+	* Get all audits for an organization
+	*/
+	async getOrgTrail(orgId, options = {}) {
+		return this.query({
+			orgId,
+			...options
+		});
+	}
+};
+//#endregion
+//#region src/plugins/batch-operations.plugin.ts
+/**
+* Batch operations plugin.
+*
+* @example
+* const repo = new Repository(Model, [
+*   methodRegistryPlugin(),
+*   batchOperationsPlugin(),
+* ]);
+*
+* // updateMany + deleteMany are primitives on Repository — no plugin needed.
+* await repo.updateMany({ status: 'pending' }, { status: 'active' });
+* await repo.deleteMany({ status: 'deleted' });
+*
+* // bulkWrite is what this plugin contributes.
+* await repo.bulkWrite([...ops]);
+*/
+function batchOperationsPlugin() {
+	return {
+		name: "batch-operations",
+		apply(repo) {
+			if (!repo.registerMethod) throw new Error("batchOperationsPlugin requires methodRegistryPlugin");
+			/**
+			* Execute heterogeneous bulk write operations in a single database call.
+			*
+			* Supports insertOne, updateOne, updateMany, deleteOne, deleteMany, and replaceOne
+			* operations mixed together for maximum efficiency.
+			*
+			* @example
+			* await repo.bulkWrite([
+			*   { insertOne: { document: { name: 'New Item', price: 10 } } },
+			*   { updateOne: { filter: { _id: id1 }, update: { $inc: { views: 1 } } } },
+			*   { updateMany: { filter: { status: 'draft' }, update: { $set: { status: 'published' } } } },
+			*   { deleteOne: { filter: { _id: id2 } } },
+			* ]);
+			*/
+			repo.registerMethod("bulkWrite", async function(operations, options = {}) {
+				const context = await this._buildContext("bulkWrite", {
+					operations,
+					...options
+				});
+				try {
+					const finalOps = context.operations || operations;
+					if (!finalOps || finalOps.length === 0) throw createError(400, "bulkWrite requires at least one operation");
+					const result = await this.Model.bulkWrite(finalOps, {
+						ordered: options.ordered ?? true,
+						session: options.session
+					});
+					const bulkResult = {
+						ok: result.ok,
+						insertedCount: result.insertedCount,
+						upsertedCount: result.upsertedCount,
+						matchedCount: result.matchedCount,
+						modifiedCount: result.modifiedCount,
+						deletedCount: result.deletedCount,
+						insertedIds: result.insertedIds,
+						upsertedIds: result.upsertedIds
+					};
+					await this.emitAsync("after:bulkWrite", {
+						context,
+						result: bulkResult
+					});
+					return bulkResult;
+				} catch (error) {
+					this.emit("error:bulkWrite", {
+						context,
+						error
+					});
+					throw this._handleError(error);
+				}
+			});
+		}
+	};
+}
+//#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/custom-id.plugin.ts
+/**
+* Custom ID Plugin
+*
+* Generates custom document IDs using pluggable generators.
+* Supports atomic counters for sequential IDs (e.g., INV-2026-0001),
+* date-partitioned sequences, and fully custom generators.
+*
+* Uses MongoDB's atomic `findOneAndUpdate` with `$inc` on a dedicated
+* counters collection — guaranteeing no duplicate IDs under concurrency.
+*
+* @example Basic sequential counter
+* ```typescript
+* const invoiceRepo = new Repository(InvoiceModel, [
+*   customIdPlugin({
+*     field: 'invoiceNumber',
+*     generator: sequentialId({
+*       prefix: 'INV',
+*       model: InvoiceModel,
+*     }),
+*   }),
+* ]);
+*
+* const inv = await invoiceRepo.create({ amount: 100 });
+* // inv.invoiceNumber → "INV-0001"
+* ```
+*
+* @example Date-partitioned counter (resets monthly)
+* ```typescript
+* const billRepo = new Repository(BillModel, [
+*   customIdPlugin({
+*     field: 'billNumber',
+*     generator: dateSequentialId({
+*       prefix: 'BILL',
+*       model: BillModel,
+*       partition: 'monthly',
+*       separator: '-',
+*       padding: 4,
+*     }),
+*   }),
+* ]);
+*
+* const bill = await billRepo.create({ total: 250 });
+* // bill.billNumber → "BILL-2026-02-0001"
+* ```
+*
+* @example Custom generator function
+* ```typescript
+* const orderRepo = new Repository(OrderModel, [
+*   customIdPlugin({
+*     field: 'orderRef',
+*     generator: async (context) => {
+*       const region = context.data?.region || 'US';
+*       const seq = await getNextSequence('orders');
+*       return `ORD-${region}-${seq}`;
+*     },
+*   }),
+* ]);
+* ```
+*/
+/** Schema for the internal counters collection */
+const counterSchema = new mongoose.Schema({
+	_id: {
+		type: String,
+		required: true
+	},
+	seq: {
+		type: Number,
+		default: 0
+	}
+}, {
+	collection: "_mongokit_counters",
+	versionKey: false
+});
+/**
+* Get or create the Counter model on the given connection.
+* Falls back to the default mongoose connection if none is provided.
+* Lazy-init to avoid model registration errors if mongoose isn't connected yet.
+*/
+function getCounterModel(connection) {
+	const conn = connection ?? mongoose.connection;
+	if (conn.models._MongoKitCounter) return conn.models._MongoKitCounter;
+	return conn.model("_MongoKitCounter", counterSchema);
+}
+/**
+* Atomically increment and return the next sequence value for a given key.
+* Uses `findOneAndUpdate` with `upsert` + `$inc` — fully atomic even under
+* heavy concurrency.
+*
+* @param counterKey - Unique key identifying this counter (e.g., "Invoice" or "Invoice:2026-02")
+* @param increment - Value to increment by (default: 1)
+* @param connection - Mongoose connection to use (defaults to the default connection)
+* @param session - Optional client session. When provided, the counter bump
+*   participates in the caller's transaction — if the surrounding transaction
+*   aborts, the counter does NOT advance. Without a session, the bump commits
+*   immediately and is not rolled back if a sibling write fails.
+* @returns The next sequence number (after increment)
+*
+* @example
+* const seq = await getNextSequence('invoices');
+* // First call → 1, second → 2, ...
+*
+* @example Batch increment for createMany
+* const startSeq = await getNextSequence('invoices', 5);
+* // If current was 10, returns 15 (you use 11, 12, 13, 14, 15)
+*
+* @example Transactional counter bump
+* await withTransaction(conn, async (session) => {
+*   const seq = await getNextSequence('invoices', 1, conn, session);
+*   await invoiceRepo.create({ invoiceNumber: `INV-${seq}` }, { session });
+*   // if this throws, the counter is rolled back with the insert
+* });
+*/
+async function getNextSequence(counterKey, increment = 1, connection, session) {
+	const result = await getCounterModel(connection).findOneAndUpdate({ _id: counterKey }, { $inc: { seq: increment } }, {
+		upsert: true,
+		returnDocument: "after",
+		session
+	});
+	if (!result) throw new Error(`Failed to increment counter '${counterKey}'`);
+	return result.seq;
+}
+/**
+* Generator: Simple sequential counter.
+* Produces IDs like `INV-0001`, `INV-0002`, etc.
+*
+* Uses atomic MongoDB counters — safe under concurrency.
+*
+* @example
+* ```typescript
+* customIdPlugin({
+*   field: 'invoiceNumber',
+*   generator: sequentialId({ prefix: 'INV', model: InvoiceModel }),
+* })
+* ```
+*/
+function sequentialId(options) {
+	const { prefix, model, padding = 4, separator = "-", counterKey } = options;
+	const key = counterKey || model.modelName;
+	return async (context) => {
+		const seq = await getNextSequence(key, 1, context._counterConnection, context.session);
+		return `${prefix}${separator}${String(seq).padStart(padding, "0")}`;
+	};
+}
+/**
+* Generator: Date-partitioned sequential counter.
+* Counter resets per period — great for invoice/bill numbering.
+*
+* Produces IDs like:
+* - yearly:  `BILL-2026-0001`
+* - monthly: `BILL-2026-02-0001`
+* - daily:   `BILL-2026-02-20-0001`
+*
+* @example
+* ```typescript
+* customIdPlugin({
+*   field: 'billNumber',
+*   generator: dateSequentialId({
+*     prefix: 'BILL',
+*     model: BillModel,
+*     partition: 'monthly',
+*   }),
+* })
+* ```
+*/
+function dateSequentialId(options) {
+	const { prefix, model, partition = "monthly", padding = 4, separator = "-" } = options;
+	return async (context) => {
+		const now = /* @__PURE__ */ new Date();
+		const year = String(now.getFullYear());
+		const month = String(now.getMonth() + 1).padStart(2, "0");
+		const day = String(now.getDate()).padStart(2, "0");
+		let datePart;
+		let counterKey;
+		switch (partition) {
+			case "yearly":
+				datePart = year;
+				counterKey = `${model.modelName}:${year}`;
+				break;
+			case "daily":
+				datePart = `${year}${separator}${month}${separator}${day}`;
+				counterKey = `${model.modelName}:${year}-${month}-${day}`;
+				break;
+			default:
+				datePart = `${year}${separator}${month}`;
+				counterKey = `${model.modelName}:${year}-${month}`;
+				break;
+		}
+		const seq = await getNextSequence(counterKey, 1, context._counterConnection, context.session);
+		return `${prefix}${separator}${datePart}${separator}${String(seq).padStart(padding, "0")}`;
+	};
+}
+/**
+* Generator: Prefix + random alphanumeric suffix.
+* Does NOT require a database round-trip — purely in-memory.
+*
+* Produces IDs like: `USR_a7b3xk9m2p1q`
+*
+* Good for: user-facing IDs where ordering doesn't matter.
+* Not suitable for sequential numbering.
+*
+* @example
+* ```typescript
+* customIdPlugin({
+*   field: 'publicId',
+*   generator: prefixedId({ prefix: 'USR', length: 10 }),
+* })
+* ```
+*/
+function prefixedId(options) {
+	const { prefix, separator = "_", length = 12 } = options;
+	const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+	return (_context) => {
+		let result = "";
+		const bytes = new Uint8Array(length);
+		if (typeof globalThis.crypto?.getRandomValues === "function") {
+			globalThis.crypto.getRandomValues(bytes);
+			for (let i = 0; i < length; i++) result += chars[bytes[i] % 36];
+		} else for (let i = 0; i < length; i++) result += chars[Math.floor(Math.random() * 36)];
+		return `${prefix}${separator}${result}`;
+	};
+}
+/**
+* Custom ID plugin — injects generated IDs into documents before creation.
+*
+* @param options - Configuration for ID generation
+* @returns Plugin instance
+*
+* @example
+* ```typescript
+* import { Repository, customIdPlugin, sequentialId } from '@classytic/mongokit';
+*
+* const invoiceRepo = new Repository(InvoiceModel, [
+*   customIdPlugin({
+*     field: 'invoiceNumber',
+*     generator: sequentialId({ prefix: 'INV', model: InvoiceModel }),
+*   }),
+* ]);
+*
+* const inv = await invoiceRepo.create({ amount: 100 });
+* console.log(inv.invoiceNumber); // "INV-0001"
+* ```
+*/
+function customIdPlugin(options) {
+	const fieldName = options.field || "customId";
+	const generateOnlyIfEmpty = options.generateOnlyIfEmpty !== false;
+	return {
+		name: "custom-id",
+		apply(repo) {
+			const repoConnection = repo.Model.db;
+			repo.on("before:create", async (context) => {
+				if (!context.data) return;
+				if (generateOnlyIfEmpty && context.data[fieldName]) return;
+				context._counterConnection = repoConnection;
+				context.data[fieldName] = await options.generator(context);
+			});
+			repo.on("before:createMany", async (context) => {
+				if (!context.dataArray) return;
+				context._counterConnection = repoConnection;
+				const docsNeedingIds = [];
+				for (const doc of context.dataArray) {
+					if (generateOnlyIfEmpty && doc[fieldName]) continue;
+					docsNeedingIds.push(doc);
+				}
+				if (docsNeedingIds.length === 0) return;
+				for (const doc of docsNeedingIds) doc[fieldName] = await options.generator({
+					...context,
+					data: doc
+				});
+			});
+		}
+	};
+}
+//#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/method-registry.plugin.ts
+/**
+* Method registry plugin that enables dynamic method registration
+*/
+function methodRegistryPlugin() {
+	return {
+		name: "method-registry",
+		apply(repo) {
+			const registeredMethods = [];
+			/**
+			* Register a new method on the repository instance
+			*/
+			repo.registerMethod = (name, fn) => {
+				if (repo[name]) throw new Error(`Cannot register method '${name}': Method already exists on repository. Choose a different name or use a plugin that doesn't conflict.`);
+				if (!name || typeof name !== "string") throw new Error("Method name must be a non-empty string");
+				if (typeof fn !== "function") throw new Error(`Method '${name}' must be a function`);
+				repo[name] = fn.bind(repo);
+				registeredMethods.push(name);
+				repo.emit("method:registered", {
+					name,
+					fn
+				});
+			};
+			/**
+			* Check if a method is registered
+			*/
+			repo.hasMethod = (name) => typeof repo[name] === "function";
+			/**
+			* Get list of all dynamically registered methods
+			*/
+			repo.getRegisteredMethods = () => [...registeredMethods];
+		}
+	};
+}
+//#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/multi-tenant.plugin.ts
+/**
+* Multi-Tenant Plugin
+*
+* Automatically injects tenant isolation filters into all queries.
+* Ensures data isolation by adding organizationId (or custom tenant field)
+* to every read and write operation.
+*
+* Uses HOOK_PRIORITY.POLICY (100) to ensure tenant filters are injected
+* BEFORE cache keys are computed (HOOK_PRIORITY.CACHE = 200).
+*
+* @example
+* ```typescript
+* // Basic — scopes every operation by organizationId from context
+* const repo = new Repository(Invoice, [
+*   multiTenantPlugin({ tenantField: 'organizationId' }),
+* ]);
+*
+* const invoices = await repo.getAll(
+*   { filters: { status: 'paid' } },
+*   { organizationId: 'org_123' }
+* );
+* // Actual query: { status: 'paid', organizationId: 'org_123' }
+*
+* // Super admin bypass — skip scoping based on context
+* const repo = new Repository(Invoice, [
+*   multiTenantPlugin({
+*     tenantField: 'organizationId',
+*     skipWhen: (context) => context.role === 'superadmin',
+*   }),
+* ]);
+*
+* // Admin sees all orgs
+* await repo.getAll({ page: 1, limit: 10 }, { role: 'superadmin' });
+*
+* // Automatic context — resolve tenant from AsyncLocalStorage
+* const repo = new Repository(Invoice, [
+*   multiTenantPlugin({
+*     tenantField: 'organizationId',
+*     resolveContext: () => asyncLocalStorage.getStore()?.tenantId,
+*   }),
+* ]);
+* ```
+*/
+function multiTenantPlugin(options = {}) {
+	const { tenantField = "organizationId", contextKey = "organizationId", required = true, skipOperations = [], skipWhen, resolveContext, fieldType = "string", allowDataInjection = false } = options;
+	const extraOps = [{
+		op: "getDeleted",
+		policyKey: "filters"
+	}];
+	return {
+		name: "multi-tenant",
+		apply(repo) {
+			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) => {
+					const perCallBypass = context.bypassTenant === true;
+					const callbackBypass = !perCallBypass && skipWhen?.(context, op) === true;
+					if (perCallBypass || callbackBypass) {
+						repo.emit("after:tenant-bypass", {
+							context,
+							operation: op,
+							reason: perCallBypass ? "option" : "callback"
+						});
+						return;
+					}
+					let tenantId = context[contextKey];
+					if (!tenantId && resolveContext) {
+						tenantId = resolveContext();
+						if (tenantId) 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}'. Pass it via options or set required: false. For deliberate cross-tenant access (admin / migration / support), pass \`bypassTenant: true\` in the options bag for this call, or wire \`skipWhen: adminBypass({...})\` at plugin construction.`);
+					if (!tenantId) return;
+					const castId = fieldType === "objectId" ? new mongoose.Types.ObjectId(tenantId) : tenantId;
+					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;
+							}
+							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 });
+			}
+		}
+	};
+}
+/**
+* Build the canonical `skipWhen` callback for role-based tenant
+* bypass — replaces the hand-rolled
+* `(ctx) => ctx.role === 'superadmin'` callback that ~6 packages
+* across the classytic codebase carry as boilerplate. Eliminates the
+* "I forgot to include 'platform_admin'" drift class — the role
+* vocabulary lives in one place.
+*
+* **Composes with `bypassTenant: true` per-call**, doesn't replace
+* it. `bypassTenant` is the deliberate per-call form for migration
+* scripts and one-off admin queries; `adminBypass` is the
+* always-on role-based bypass for users whose JWT / session carries
+* a privileged role.
+*
+* **NOT a substitute for authentication or RBAC.** This factory only
+* answers "should the tenant scope hook fire for this call?" — it
+* does NOT validate that the caller is authenticated, that their
+* role claim is genuine, or that the requested operation is
+* permitted. Always run auth + RBAC before the call reaches the
+* repository layer; this is the LAST gate, not the only one.
+*
+* @example Single role
+* ```ts
+* import { adminBypass, multiTenantPlugin } from '@classytic/mongokit';
+*
+* const repo = new Repository(InvoiceModel, [
+*   multiTenantPlugin({
+*     tenantField: 'organizationId',
+*     skipWhen: adminBypass({ adminRoles: ['superadmin'] }),
+*   }),
+* ]);
+*
+* await repo.getAll({}, { role: 'superadmin' }); // sees all orgs
+* await repo.getAll({}, { role: 'user', organizationId: 'org-1' }); // scoped
+* ```
+*
+* @example Multiple admin roles + custom field name
+* ```ts
+* skipWhen: adminBypass({
+*   roleField: 'principalRole',                  // ctx.principalRole, not ctx.role
+*   adminRoles: ['superadmin', 'platform_admin', 'support'],
+* }),
+* ```
+*
+* @example Composing with custom logic
+* ```ts
+* // adminBypass for the role check, then your own additional logic:
+* const adminCheck = adminBypass({ adminRoles: ['superadmin'] });
+* skipWhen: (ctx, op) => adminCheck(ctx, op) || ctx.internalSystemFlag === true,
+* ```
+*
+* @param options.roleField - Path on the context to read the role
+*   from. Defaults to `'role'`. Top-level keys only — for nested
+*   shapes (e.g. `ctx.user.role`), wrap your own `(ctx) => …` callback
+*   instead.
+* @param options.adminRoles - Role values that grant the bypass. The
+*   factory does an exact-match `includes` check — case-sensitive,
+*   no fuzzy matching. Lowercase your role vocabulary upstream.
+* @returns A `skipWhen`-compatible callback `(ctx, op) → boolean`.
+*/
+function adminBypass$1(options) {
+	return adminBypass(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/soft-delete.plugin.ts
+/**
+* Build filter condition based on filter mode
+*/
+function buildDeletedFilter(deletedField, filterMode, includeDeleted) {
+	if (includeDeleted) return {};
+	if (filterMode === "exists") return { [deletedField]: { $exists: false } };
+	return { [deletedField]: null };
+}
+/**
+* Build filter condition for finding deleted documents
+*/
+function buildGetDeletedFilter(deletedField, filterMode) {
+	if (filterMode === "exists") return { [deletedField]: {
+		$exists: true,
+		$ne: null
+	} };
+	return { [deletedField]: { $ne: null } };
+}
+/**
+* Soft delete plugin
+*
+* @example Basic usage
+* ```typescript
+* const repo = new Repository(Model, [
+*   softDeletePlugin({ deletedField: 'deletedAt' })
+* ]);
+*
+* // Delete (soft)
+* await repo.delete(id);
+*
+* // Restore
+* await repo.restore(id);
+*
+* // Get deleted documents
+* await repo.getDeleted({ page: 1, limit: 20 });
+* ```
+*
+* @example With null filter mode (for schemas with default: null)
+* ```typescript
+* // Schema: { deletedAt: { type: Date, default: null } }
+* const repo = new Repository(Model, [
+*   softDeletePlugin({
+*     deletedField: 'deletedAt',
+*     filterMode: 'null', // default - works with default: null
+*   })
+* ]);
+* ```
+*
+* @example With TTL for auto-cleanup
+* ```typescript
+* const repo = new Repository(Model, [
+*   softDeletePlugin({
+*     deletedField: 'deletedAt',
+*     ttlDays: 30, // Auto-delete after 30 days
+*   })
+* ]);
+* ```
+*/
+function softDeletePlugin(options = {}) {
+	const deletedField = options.deletedField || "deletedAt";
+	const deletedByField = options.deletedByField || "deletedBy";
+	const filterMode = options.filterMode || "null";
+	const addRestoreMethod = options.addRestoreMethod !== false;
+	const addGetDeletedMethod = options.addGetDeletedMethod !== false;
+	const ttlDays = options.ttlDays;
+	return {
+		name: "softDelete",
+		apply(repo) {
+			try {
+				const schemaPaths = repo.Model.schema.paths;
+				for (const [pathName, schemaType] of Object.entries(schemaPaths)) {
+					if (pathName === "_id" || pathName === deletedField) continue;
+					if (schemaType.options?.unique) warn(`[softDeletePlugin] Field '${pathName}' on model '${repo.Model.modelName}' has a unique index. With soft-delete enabled, deleted documents will block new documents with the same '${pathName}'. Fix: change to a compound partial index — { ${pathName}: 1 }, { unique: true, partialFilterExpression: { ${deletedField}: null } }`);
+				}
+			} catch (err) {
+				warn(`[softDeletePlugin] Schema introspection failed for ${repo.Model.modelName}: ${err instanceof Error ? err.message : String(err)}`);
+			}
+			if (ttlDays !== void 0 && ttlDays > 0) {
+				const ttlSeconds = ttlDays * 24 * 60 * 60;
+				repo.Model.collection.createIndex({ [deletedField]: 1 }, {
+					expireAfterSeconds: ttlSeconds,
+					partialFilterExpression: { [deletedField]: { $type: "date" } }
+				}).catch((err) => {
+					if (err.code !== 85 && err.code !== 86 && !err.message.includes("already exists")) warn(`[softDeletePlugin] Failed to create TTL index: ${err.message}`);
+				});
+			}
+			repo.on("before:delete", async (context) => {
+				if (context.deleteMode === "hard") return;
+				if (options.soft !== false) {
+					const updateData = { [deletedField]: /* @__PURE__ */ new Date() };
+					if (context.user) updateData[deletedByField] = context.user._id || context.user.id;
+					const deleteQuery = {
+						[repo.idField || "_id"]: context.id,
+						...context.query || {}
+					};
+					if (!await repo.Model.findOneAndUpdate(deleteQuery, updateData, { session: context.session })) {
+						const error = /* @__PURE__ */ new Error(`Document with id '${context.id}' not found`);
+						error.status = 404;
+						throw error;
+					}
+					context.softDeleted = true;
+				}
+			}, { priority: HOOK_PRIORITY.POLICY });
+			const injectDeleteFilterToFilters = (context) => {
+				if (options.soft !== false) {
+					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
+					if (Object.keys(deleteFilter).length > 0) context.filters = {
+						...context.filters || {},
+						...deleteFilter
+					};
+				}
+			};
+			const injectDeleteFilterToQuery = (context) => {
+				if (options.soft !== false) {
+					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
+					if (Object.keys(deleteFilter).length > 0) context.query = {
+						...context.query || {},
+						...deleteFilter
+					};
+				}
+			};
+			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);
+					if (Object.keys(deleteFilter).length > 0) context.query = {
+						...context.query || {},
+						...deleteFilter
+					};
+				}
+			}, { priority: HOOK_PRIORITY.POLICY });
+			repo.on("before:deleteMany", async (context) => {
+				if (context.deleteMode === "hard") return;
+				if (options.soft !== false) {
+					const deleteFilter = buildDeletedFilter(deletedField, filterMode, false);
+					const finalQuery = {
+						...context.query || {},
+						...deleteFilter
+					};
+					const updateRes = await repo.Model.updateMany(finalQuery, { $set: { [deletedField]: /* @__PURE__ */ new Date() } }, { session: context.session });
+					context.softDeleted = true;
+					context.softDeletedCount = updateRes?.modifiedCount ?? 0;
+				}
+			}, { priority: HOOK_PRIORITY.POLICY });
+			if (addRestoreMethod) {
+				const restoreMethod = async function(id, restoreOptions = {}) {
+					const context = await this._buildContext("restore", {
+						id,
+						...restoreOptions
+					});
+					const updateData = {
+						[deletedField]: null,
+						[deletedByField]: null
+					};
+					const restoreQuery = {
+						_id: id,
+						...context.query || {}
+					};
+					const result = await this.Model.findOneAndUpdate(restoreQuery, { $set: updateData }, {
+						returnDocument: "after",
+						session: restoreOptions.session
+					});
+					if (!result) {
+						const error = /* @__PURE__ */ new Error(`Document with id '${id}' not found`);
+						error.status = 404;
+						throw error;
+					}
+					await this.emitAsync("after:restore", {
+						context,
+						result
+					});
+					return result;
+				};
+				if (typeof repo.registerMethod === "function") repo.registerMethod("restore", restoreMethod);
+				else repo.restore = restoreMethod.bind(repo);
+			}
+			if (addGetDeletedMethod) {
+				const getDeletedMethod = async function(params = {}, getDeletedOptions = {}) {
+					const context = await this._buildContext("getDeleted", {
+						...params,
+						...getDeletedOptions
+					});
+					const deletedFilter = buildGetDeletedFilter(deletedField, filterMode);
+					const combinedFilters = {
+						...params.filters || {},
+						...deletedFilter,
+						...context.filters || {},
+						...context.query || {}
+					};
+					const page = params.page || 1;
+					const limit = params.limit || 20;
+					const skip = (page - 1) * limit;
+					let sortSpec = { [deletedField]: -1 };
+					if (params.sort) if (typeof params.sort === "string") {
+						const sortOrder = params.sort.startsWith("-") ? -1 : 1;
+						sortSpec = { [params.sort.startsWith("-") ? params.sort.substring(1) : params.sort]: sortOrder };
+					} else sortSpec = params.sort;
+					let query = this.Model.find(combinedFilters).sort(sortSpec).skip(skip).limit(limit);
+					if (getDeletedOptions.session) query = query.session(getDeletedOptions.session);
+					if (getDeletedOptions.select) {
+						const selectValue = Array.isArray(getDeletedOptions.select) ? getDeletedOptions.select.join(" ") : getDeletedOptions.select;
+						query = query.select(selectValue);
+					}
+					if (getDeletedOptions.populate) {
+						const populateSpec = getDeletedOptions.populate;
+						if (typeof populateSpec === "string") query = query.populate(populateSpec.split(",").map((p) => p.trim()));
+						else if (Array.isArray(populateSpec)) query = query.populate(populateSpec);
+						else query = query.populate(populateSpec);
+					}
+					if (getDeletedOptions.lean !== false) query = query.lean();
+					const [data, total] = await Promise.all([query.exec(), this.Model.countDocuments(combinedFilters)]);
+					const pages = Math.ceil(total / limit);
+					return {
+						method: "offset",
+						data,
+						page,
+						limit,
+						total,
+						pages,
+						hasNext: page < pages,
+						hasPrev: page > 1
+					};
+				};
+				if (typeof repo.registerMethod === "function") repo.registerMethod("getDeleted", getDeletedMethod);
+				else repo.getDeleted = getDeletedMethod.bind(repo);
+			}
+		}
+	};
+}
+//#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/timestamp.plugin.ts
+/**
+* Timestamp plugin that auto-injects timestamps
+*
+* @example
+* const repo = new Repository(Model, [timestampPlugin()]);
+*/
+function timestampPlugin() {
+	return {
+		name: "timestamp",
+		apply(repo) {
+			repo.on("before:create", (context) => {
+				if (!context.data) return;
+				const now = /* @__PURE__ */ new Date();
+				if (!context.data.createdAt) context.data.createdAt = now;
+				if (!context.data.updatedAt) context.data.updatedAt = now;
+			});
+			repo.on("before:update", (context) => {
+				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;
+			});
+		}
+	};
+}
+//#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 { aggregateHelpersPlugin as A, sequentialId as C, AuditTrailQuery as D, batchOperationsPlugin as E, auditTrailPlugin as O, prefixedId as S, cachePlugin as T, fieldFilterPlugin as _, uniqueField as a, dateSequentialId as b, createTenantContext as c, observabilityPlugin as d, adminBypass$1 as f, leasePlugin as g, methodRegistryPlugin as h, requireField as i, auditLogPlugin as k, subdocumentPlugin as l, mongoOperationsPlugin as m, blockIf as n, validationChainPlugin as o, multiTenantPlugin as p, immutableField as r, timestampPlugin as s, autoInject as t, softDeletePlugin as u, elasticSearchPlugin as v, cascadePlugin as w, getNextSequence as x, customIdPlugin as y };