@classytic/mongokit 3.2.1 → 3.2.3

package/dist/custom-id.plugin-m0VW6yYm.mjs

@@ -0,0 +1,2169 @@
+import { i as createError, n as debug, r as warn } from "./logger-D8ily-PP.mjs";
+import { i as upsert } from "./create-BuO6xt0v.mjs";
+import { a as modelPattern, i as listQueryKey, l as getFieldsForUser, n as byQueryKey, o as versionKey, t as byIdKey } from "./cache-keys-C8Z9B5sw.mjs";
+import mongoose from "mongoose";
+
+//#region src/plugins/field-filter.plugin.ts
+/**
+* Field Filter Plugin
+* Automatically filters response fields based on user roles
+*/
+/**
+* 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:getById", applyFieldFiltering);
+			repo.on("before:getByQuery", applyFieldFiltering);
+		}
+	};
+}
+
+//#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();
+			});
+		}
+	};
+}
+
+//#endregion
+//#region src/plugins/audit-log.plugin.ts
+/**
+* Audit log plugin that logs all repository operations
+* 
+* @example
+* const repo = new Repository(Model, [auditLogPlugin(console)]);
+*/
+function auditLogPlugin(logger) {
+	return {
+		name: "auditLog",
+		apply(repo) {
+			repo.on("after:create", ({ context, result }) => {
+				logger?.info?.("Document created", {
+					model: context.model || repo.model,
+					id: result?._id,
+					userId: context.user?._id || context.user?.id,
+					organizationId: context.organizationId
+				});
+			});
+			repo.on("after:update", ({ context, result }) => {
+				logger?.info?.("Document updated", {
+					model: context.model || repo.model,
+					id: context.id || result?._id,
+					userId: context.user?._id || context.user?.id,
+					organizationId: context.organizationId
+				});
+			});
+			repo.on("after:delete", ({ context }) => {
+				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 }) => {
+				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 }) => {
+				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 }) => {
+				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/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 {}
+			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.message.includes("already exists")) warn(`[softDeletePlugin] Failed to create TTL index: ${err.message}`);
+				});
+			}
+			repo.on("before:delete", async (context) => {
+				if (options.soft !== false) {
+					const updateData = { [deletedField]: /* @__PURE__ */ new Date() };
+					if (context.user) updateData[deletedByField] = context.user._id || context.user.id;
+					await repo.Model.findByIdAndUpdate(context.id, updateData, { session: context.session });
+					context.softDeleted = true;
+				}
+			});
+			repo.on("before:getAll", (context) => {
+				if (options.soft !== false) {
+					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
+					if (Object.keys(deleteFilter).length > 0) context.filters = {
+						...context.filters || {},
+						...deleteFilter
+					};
+				}
+			});
+			repo.on("before:getById", (context) => {
+				if (options.soft !== false) {
+					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
+					if (Object.keys(deleteFilter).length > 0) context.query = {
+						...context.query || {},
+						...deleteFilter
+					};
+				}
+			});
+			repo.on("before:getByQuery", (context) => {
+				if (options.soft !== false) {
+					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
+					if (Object.keys(deleteFilter).length > 0) context.query = {
+						...context.query || {},
+						...deleteFilter
+					};
+				}
+			});
+			if (addRestoreMethod) {
+				const restoreMethod = async function(id, restoreOptions = {}) {
+					const updateData = {
+						[deletedField]: null,
+						[deletedByField]: null
+					};
+					const result = await this.Model.findByIdAndUpdate(id, { $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", {
+						id,
+						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 deletedFilter = buildGetDeletedFilter(deletedField, filterMode);
+					const combinedFilters = {
+						...params.filters || {},
+						...deletedFilter
+					};
+					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 [docs, total] = await Promise.all([query.exec(), this.Model.countDocuments(combinedFilters)]);
+					const pages = Math.ceil(total / limit);
+					return {
+						method: "offset",
+						docs,
+						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/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 = function(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 = function(name) {
+				return typeof repo[name] === "function";
+			};
+			/**
+			* Get list of all dynamically registered methods
+			*/
+			repo.getRegisteredMethods = function() {
+				return [...registeredMethods];
+			};
+		}
+	};
+}
+
+//#endregion
+//#region src/plugins/validation-chain.plugin.ts
+/**
+* Validation Chain Plugin
+* 
+* Composable validation for repository operations with customizable rules.
+*/
+/**
+* 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: [],
+		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: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 || !context.data[field] || !repo) return;
+			const query = { [field]: context.data[field] };
+			const getByQuery = repo.getByQuery;
+			if (typeof getByQuery !== "function") return;
+			const existing = await getByQuery.call(repo, query, {
+				select: "_id",
+				lean: true,
+				throwOnNotFound: false
+			});
+			if (existing && String(existing._id) !== String(context.id)) throw createError(409, errorMessage || `${field} already exists`);
+		}
+	};
+}
+
+//#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);
+			});
+		}
+	};
+}
+
+//#endregion
+//#region src/plugins/batch-operations.plugin.ts
+/**
+* Batch operations plugin
+* 
+* @example
+* const repo = new Repository(Model, [
+*   methodRegistryPlugin(),
+*   batchOperationsPlugin(),
+* ]);
+* 
+* await repo.updateMany({ status: 'pending' }, { status: 'active' });
+* await repo.deleteMany({ status: 'deleted' });
+*/
+function batchOperationsPlugin() {
+	return {
+		name: "batch-operations",
+		apply(repo) {
+			if (!repo.registerMethod) throw new Error("batchOperationsPlugin requires methodRegistryPlugin");
+			/**
+			* Update multiple documents
+			*/
+			repo.registerMethod("updateMany", async function(query, data, options = {}) {
+				const context = await this._buildContext.call(this, "updateMany", {
+					query,
+					data,
+					options
+				});
+				try {
+					await this.emitAsync("before:updateMany", context);
+					if (Array.isArray(data) && options.updatePipeline !== true) throw createError(400, "Update pipelines (array updates) are disabled by default; pass `{ updatePipeline: true }` to explicitly allow pipeline-style updates.");
+					const result = await this.Model.updateMany(query, data, {
+						runValidators: true,
+						session: options.session,
+						...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
+					}).exec();
+					await this.emitAsync("after:updateMany", {
+						context,
+						result
+					});
+					return result;
+				} catch (error) {
+					this.emit("error:updateMany", {
+						context,
+						error
+					});
+					throw this._handleError.call(this, error);
+				}
+			});
+			/**
+			* Delete multiple documents
+			*/
+			repo.registerMethod("deleteMany", async function(query, options = {}) {
+				const context = await this._buildContext.call(this, "deleteMany", {
+					query,
+					options
+				});
+				try {
+					await this.emitAsync("before:deleteMany", context);
+					const result = await this.Model.deleteMany(query, { session: options.session }).exec();
+					await this.emitAsync("after:deleteMany", {
+						context,
+						result
+					});
+					return result;
+				} catch (error) {
+					this.emit("error:deleteMany", {
+						context,
+						error
+					});
+					throw this._handleError.call(this, error);
+				}
+			});
+		}
+	};
+}
+
+//#endregion
+//#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.aggregate.call(this, pipeline, options);
+			});
+			const aggregateOperation = async function(field, operator, resultKey, query = {}, options = {}) {
+				const pipeline = [{ $match: query }, { $group: {
+					_id: null,
+					[resultKey]: { [operator]: `$${field}` }
+				} }];
+				return (await this.aggregate.call(this, 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/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.call(this, parentId, { $push: { [arrayPath]: subData } }, options);
+			});
+			/**
+			* Get subdocument from array
+			*/
+			repo.registerMethod("getSubdocument", async function(parentId, arrayPath, subId, options = {}) {
+				return this._executeQuery.call(this, 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.call(this, 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.call(this, parentId, { $pull: { [arrayPath]: { _id: subId } } }, options);
+			});
+		}
+	};
+}
+
+//#endregion
+//#region src/plugins/cache.plugin.ts
+/**
+* Cache plugin factory
+*
+* @param options - Cache configuration
+* @returns Plugin instance
+*/
+function cachePlugin(options) {
+	const config = {
+		adapter: options.adapter,
+		ttl: options.ttl ?? 60,
+		byIdTtl: options.byIdTtl ?? options.ttl ?? 60,
+		queryTtl: options.queryTtl ?? options.ttl ?? 60,
+		prefix: options.prefix ?? "mk",
+		debug: options.debug ?? false,
+		skipIfLargeLimit: options.skipIf?.largeLimit ?? 100
+	};
+	const stats = {
+		hits: 0,
+		misses: 0,
+		sets: 0,
+		invalidations: 0
+	};
+	const log = (msg, data) => {
+		if (config.debug) debug(`[mongokit:cache] ${msg}`, data ?? "");
+	};
+	return {
+		name: "cache",
+		apply(repo) {
+			const model = repo.model;
+			async function getVersion() {
+				try {
+					return await config.adapter.get(versionKey(config.prefix, model)) ?? 0;
+				} catch {
+					return 0;
+				}
+			}
+			/**
+			* Bump collection version in the adapter (invalidates all list caches).
+			* Uses Date.now() so version always moves forward — safe after eviction or deploy.
+			*/
+			async function bumpVersion() {
+				const newVersion = Date.now();
+				try {
+					await config.adapter.set(versionKey(config.prefix, model), newVersion, config.ttl * 10);
+					stats.invalidations++;
+					log(`Bumped version for ${model} to:`, newVersion);
+				} catch (e) {
+					log(`Failed to bump version for ${model}:`, e);
+				}
+			}
+			/**
+			* Invalidate a specific document by ID
+			*/
+			async function invalidateById(id) {
+				const key = byIdKey(config.prefix, model, id);
+				try {
+					await config.adapter.del(key);
+					stats.invalidations++;
+					log(`Invalidated byId cache:`, key);
+				} catch (e) {
+					log(`Failed to invalidate byId cache:`, e);
+				}
+			}
+			/**
+			* before:getById - Check cache for document
+			*/
+			repo.on("before:getById", async (context) => {
+				if (context.skipCache) {
+					log(`Skipping cache for getById: ${context.id}`);
+					return;
+				}
+				const id = String(context.id);
+				const key = byIdKey(config.prefix, model, id);
+				try {
+					const cached = await config.adapter.get(key);
+					if (cached !== null) {
+						stats.hits++;
+						log(`Cache HIT for getById:`, key);
+						context._cacheHit = true;
+						context._cachedResult = cached;
+					} else {
+						stats.misses++;
+						log(`Cache MISS for getById:`, key);
+					}
+				} catch (e) {
+					log(`Cache error for getById:`, e);
+					stats.misses++;
+				}
+			});
+			/**
+			* before:getByQuery - Check cache for single-doc query
+			*/
+			repo.on("before:getByQuery", async (context) => {
+				if (context.skipCache) {
+					log(`Skipping cache for getByQuery`);
+					return;
+				}
+				const query = context.query || {};
+				const key = byQueryKey(config.prefix, model, query, {
+					select: context.select,
+					populate: context.populate
+				});
+				try {
+					const cached = await config.adapter.get(key);
+					if (cached !== null) {
+						stats.hits++;
+						log(`Cache HIT for getByQuery:`, key);
+						context._cacheHit = true;
+						context._cachedResult = cached;
+					} else {
+						stats.misses++;
+						log(`Cache MISS for getByQuery:`, key);
+					}
+				} catch (e) {
+					log(`Cache error for getByQuery:`, e);
+					stats.misses++;
+				}
+			});
+			/**
+			* before:getAll - Check cache for list query
+			*/
+			repo.on("before:getAll", async (context) => {
+				if (context.skipCache) {
+					log(`Skipping cache for getAll`);
+					return;
+				}
+				const limit = context.limit;
+				if (limit && limit > config.skipIfLargeLimit) {
+					log(`Skipping cache for large query (limit: ${limit})`);
+					return;
+				}
+				const collectionVersion = await getVersion();
+				const params = {
+					filters: context.filters,
+					sort: context.sort,
+					page: context.page,
+					limit,
+					after: context.after,
+					select: context.select,
+					populate: context.populate,
+					search: context.search
+				};
+				const key = listQueryKey(config.prefix, model, collectionVersion, params);
+				try {
+					const cached = await config.adapter.get(key);
+					if (cached !== null) {
+						stats.hits++;
+						log(`Cache HIT for getAll:`, key);
+						context._cacheHit = true;
+						context._cachedResult = cached;
+					} else {
+						stats.misses++;
+						log(`Cache MISS for getAll:`, key);
+					}
+				} catch (e) {
+					log(`Cache error for getAll:`, e);
+					stats.misses++;
+				}
+			});
+			/**
+			* after:getById - Cache the result
+			*/
+			repo.on("after:getById", async (payload) => {
+				const { context, result } = payload;
+				if (context._cacheHit) return;
+				if (context.skipCache) return;
+				if (result === null) return;
+				const id = String(context.id);
+				const key = byIdKey(config.prefix, model, id);
+				const ttl = context.cacheTtl ?? config.byIdTtl;
+				try {
+					await config.adapter.set(key, result, ttl);
+					stats.sets++;
+					log(`Cached getById result:`, key);
+				} catch (e) {
+					log(`Failed to cache getById:`, e);
+				}
+			});
+			/**
+			* after:getByQuery - Cache the result
+			*/
+			repo.on("after:getByQuery", async (payload) => {
+				const { context, result } = payload;
+				if (context._cacheHit) return;
+				if (context.skipCache) return;
+				if (result === null) return;
+				const query = context.query || {};
+				const key = byQueryKey(config.prefix, model, query, {
+					select: context.select,
+					populate: context.populate
+				});
+				const ttl = context.cacheTtl ?? config.queryTtl;
+				try {
+					await config.adapter.set(key, result, ttl);
+					stats.sets++;
+					log(`Cached getByQuery result:`, key);
+				} catch (e) {
+					log(`Failed to cache getByQuery:`, e);
+				}
+			});
+			/**
+			* after:getAll - Cache the result
+			*/
+			repo.on("after:getAll", async (payload) => {
+				const { context, result } = payload;
+				if (context._cacheHit) return;
+				if (context.skipCache) return;
+				const limit = context.limit;
+				if (limit && limit > config.skipIfLargeLimit) return;
+				const collectionVersion = await getVersion();
+				const params = {
+					filters: context.filters,
+					sort: context.sort,
+					page: context.page,
+					limit,
+					after: context.after,
+					select: context.select,
+					populate: context.populate,
+					search: context.search
+				};
+				const key = listQueryKey(config.prefix, model, collectionVersion, params);
+				const ttl = context.cacheTtl ?? config.queryTtl;
+				try {
+					await config.adapter.set(key, result, ttl);
+					stats.sets++;
+					log(`Cached getAll result:`, key);
+				} catch (e) {
+					log(`Failed to cache getAll:`, e);
+				}
+			});
+			/**
+			* after:create - Bump version to invalidate list caches
+			*/
+			repo.on("after:create", async () => {
+				await bumpVersion();
+			});
+			/**
+			* after:createMany - Bump version to invalidate list caches
+			*/
+			repo.on("after:createMany", async () => {
+				await bumpVersion();
+			});
+			/**
+			* after:update - Invalidate by ID and bump version
+			*/
+			repo.on("after:update", async (payload) => {
+				const { context } = payload;
+				const id = String(context.id);
+				await Promise.all([invalidateById(id), bumpVersion()]);
+			});
+			/**
+			* after:updateMany - Bump version (can't track individual IDs efficiently)
+			*/
+			repo.on("after:updateMany", async () => {
+				await bumpVersion();
+			});
+			/**
+			* after:delete - Invalidate by ID and bump version
+			*/
+			repo.on("after:delete", async (payload) => {
+				const { context } = payload;
+				const id = String(context.id);
+				await Promise.all([invalidateById(id), bumpVersion()]);
+			});
+			/**
+			* after:deleteMany - Bump version
+			*/
+			repo.on("after:deleteMany", async () => {
+				await bumpVersion();
+			});
+			/**
+			* Invalidate cache for a specific document
+			* Use when document was updated outside this service
+			*
+			* @example
+			* await userRepo.invalidateCache('507f1f77bcf86cd799439011');
+			*/
+			repo.invalidateCache = async (id) => {
+				await invalidateById(id);
+				log(`Manual invalidation for ID:`, id);
+			};
+			/**
+			* Invalidate all list caches for this model
+			* Use when bulk changes happened outside this service
+			*
+			* @example
+			* await userRepo.invalidateListCache();
+			*/
+			repo.invalidateListCache = async () => {
+				await bumpVersion();
+				log(`Manual list cache invalidation for ${model}`);
+			};
+			/**
+			* Invalidate ALL cache entries for this model
+			* Nuclear option - use sparingly
+			*
+			* @example
+			* await userRepo.invalidateAllCache();
+			*/
+			repo.invalidateAllCache = async () => {
+				if (config.adapter.clear) try {
+					await config.adapter.clear(modelPattern(config.prefix, model));
+					stats.invalidations++;
+					log(`Full cache invalidation for ${model}`);
+				} catch (e) {
+					log(`Failed full cache invalidation for ${model}:`, e);
+				}
+				else {
+					await bumpVersion();
+					log(`Partial cache invalidation for ${model} (adapter.clear not available)`);
+				}
+			};
+			/**
+			* Get cache statistics for monitoring
+			*
+			* @example
+			* const stats = userRepo.getCacheStats();
+			* console.log(`Hit rate: ${stats.hits / (stats.hits + stats.misses) * 100}%`);
+			*/
+			repo.getCacheStats = () => ({ ...stats });
+			/**
+			* Reset cache statistics
+			*/
+			repo.resetCacheStats = () => {
+				stats.hits = 0;
+				stats.misses = 0;
+				stats.sets = 0;
+				stats.invalidations = 0;
+			};
+		}
+	};
+}
+
+//#endregion
+//#region src/plugins/cascade.plugin.ts
+/**
+* Cascade Delete Plugin
+* Automatically deletes related documents when a parent document is deleted
+*
+* @example
+* ```typescript
+* import mongoose from 'mongoose';
+* import { Repository, cascadePlugin, methodRegistryPlugin } from '@classytic/mongokit';
+*
+* const productRepo = new Repository(Product, [
+*   methodRegistryPlugin(),
+*   cascadePlugin({
+*     relations: [
+*       { model: 'StockEntry', foreignKey: 'product' },
+*       { model: 'StockMovement', foreignKey: 'product' },
+*     ]
+*   })
+* ]);
+*
+* // When a product is deleted, all related StockEntry and StockMovement docs are also deleted
+* await productRepo.delete(productId);
+* ```
+*/
+/**
+* Cascade delete plugin
+*
+* Deletes related documents after the parent document is deleted.
+* Works with both hard delete and soft delete scenarios.
+*
+* @param options - Cascade configuration
+* @returns Plugin
+*/
+function cascadePlugin(options) {
+	const { relations, parallel = true, logger } = options;
+	if (!relations || relations.length === 0) throw new Error("cascadePlugin requires at least one relation");
+	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 isSoftDelete = context.softDeleted === true;
+				const cascadeDelete = async (relation) => {
+					const RelatedModel = mongoose.models[relation.model];
+					if (!RelatedModel) {
+						logger?.warn?.(`Cascade delete skipped: model '${relation.model}' not found`, {
+							parentModel: context.model,
+							parentId: String(deletedId)
+						});
+						return;
+					}
+					const query = { [relation.foreignKey]: deletedId };
+					try {
+						if (relation.softDelete ?? isSoftDelete) {
+							const updateResult = await RelatedModel.updateMany(query, {
+								deletedAt: /* @__PURE__ */ new Date(),
+								...context.user ? { deletedBy: context.user._id || context.user.id } : {}
+							}, { session: context.session });
+							logger?.info?.(`Cascade soft-deleted ${updateResult.modifiedCount} documents`, {
+								parentModel: context.model,
+								parentId: String(deletedId),
+								relatedModel: relation.model,
+								foreignKey: relation.foreignKey,
+								count: updateResult.modifiedCount
+							});
+						} else {
+							const deleteResult = await RelatedModel.deleteMany(query, { session: context.session });
+							logger?.info?.(`Cascade deleted ${deleteResult.deletedCount} documents`, {
+								parentModel: context.model,
+								parentId: String(deletedId),
+								relatedModel: relation.model,
+								foreignKey: relation.foreignKey,
+								count: deleteResult.deletedCount
+							});
+						}
+					} catch (error) {
+						logger?.error?.(`Cascade delete failed for model '${relation.model}'`, {
+							parentModel: context.model,
+							parentId: String(deletedId),
+							relatedModel: relation.model,
+							foreignKey: relation.foreignKey,
+							error: error.message
+						});
+						throw error;
+					}
+				};
+				if (parallel) {
+					const failures = (await Promise.allSettled(relations.map(cascadeDelete))).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 cascadeDelete(relation);
+			});
+			repo.on("after:deleteMany", async (payload) => {
+				const { context, result } = payload;
+				const query = context.query;
+				if (!query || Object.keys(query).length === 0) {
+					logger?.warn?.("Cascade deleteMany skipped: empty query", { model: context.model });
+					return;
+				}
+				logger?.warn?.("Cascade deleteMany: use before:deleteMany hook for complete cascade support", { model: context.model });
+			});
+			repo.on("before:deleteMany", async (context) => {
+				const query = context.query;
+				if (!query || Object.keys(query).length === 0) return;
+				context._cascadeIds = (await repo.Model.find(query, { _id: 1 }).lean().session(context.session ?? null)).map((doc) => doc._id);
+			});
+			const originalAfterDeleteMany = repo._hooks.get("after:deleteMany") || [];
+			repo._hooks.set("after:deleteMany", [...originalAfterDeleteMany, async (payload) => {
+				const { context } = payload;
+				const ids = context._cascadeIds;
+				if (!ids || ids.length === 0) return;
+				const isSoftDelete = context.softDeleted === true;
+				const cascadeDeleteMany = async (relation) => {
+					const RelatedModel = mongoose.models[relation.model];
+					if (!RelatedModel) {
+						logger?.warn?.(`Cascade deleteMany skipped: model '${relation.model}' not found`, { parentModel: context.model });
+						return;
+					}
+					const query = { [relation.foreignKey]: { $in: ids } };
+					const shouldSoftDelete = relation.softDelete ?? isSoftDelete;
+					try {
+						if (shouldSoftDelete) {
+							const updateResult = await RelatedModel.updateMany(query, {
+								deletedAt: /* @__PURE__ */ new Date(),
+								...context.user ? { deletedBy: context.user._id || context.user.id } : {}
+							}, { session: context.session });
+							logger?.info?.(`Cascade soft-deleted ${updateResult.modifiedCount} documents (bulk)`, {
+								parentModel: context.model,
+								parentCount: ids.length,
+								relatedModel: relation.model,
+								foreignKey: relation.foreignKey,
+								count: updateResult.modifiedCount
+							});
+						} else {
+							const deleteResult = await RelatedModel.deleteMany(query, { session: context.session });
+							logger?.info?.(`Cascade deleted ${deleteResult.deletedCount} documents (bulk)`, {
+								parentModel: context.model,
+								parentCount: ids.length,
+								relatedModel: relation.model,
+								foreignKey: relation.foreignKey,
+								count: deleteResult.deletedCount
+							});
+						}
+					} catch (error) {
+						logger?.error?.(`Cascade deleteMany failed for model '${relation.model}'`, {
+							parentModel: context.model,
+							relatedModel: relation.model,
+							foreignKey: relation.foreignKey,
+							error: error.message
+						});
+						throw error;
+					}
+				};
+				if (parallel) {
+					const failures = (await Promise.allSettled(relations.map(cascadeDeleteMany))).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 cascadeDeleteMany(relation);
+			}]);
+		}
+	};
+}
+
+//#endregion
+//#region src/plugins/multi-tenant.plugin.ts
+function multiTenantPlugin(options = {}) {
+	const { tenantField = "organizationId", contextKey = "organizationId", required = true, skipOperations = [], skipWhen, resolveContext } = options;
+	const readOps = [
+		"getById",
+		"getByQuery",
+		"getAll",
+		"aggregatePaginate",
+		"lookupPopulate"
+	];
+	const writeOps = [
+		"create",
+		"createMany",
+		"update",
+		"delete"
+	];
+	const allOps = [...readOps, ...writeOps];
+	return {
+		name: "multi-tenant",
+		apply(repo) {
+			for (const op of allOps) {
+				if (skipOperations.includes(op)) continue;
+				repo.on(`before:${op}`, (context) => {
+					if (skipWhen?.(context, op)) return;
+					let tenantId = context[contextKey];
+					if (!tenantId && resolveContext) {
+						tenantId = resolveContext();
+						if (tenantId) context[contextKey] = tenantId;
+					}
+					if (!tenantId && required) throw new Error(`[mongokit] Multi-tenant: Missing '${contextKey}' in context for '${op}'. Pass it via options or set required: false.`);
+					if (!tenantId) return;
+					if (readOps.includes(op)) if (op === "getAll" || op === "aggregatePaginate" || op === "lookupPopulate") context.filters = {
+						...context.filters,
+						[tenantField]: tenantId
+					};
+					else context.query = {
+						...context.query,
+						[tenantField]: tenantId
+					};
+					if (op === "create" && context.data) context.data[tenantField] = tenantId;
+					if (op === "createMany" && context.dataArray) for (const doc of context.dataArray) doc[tenantField] = tenantId;
+					if (op === "update" || op === "delete") context.query = {
+						...context.query,
+						[tenantField]: tenantId
+					};
+				});
+			}
+		}
+	};
+}
+
+//#endregion
+//#region src/plugins/observability.plugin.ts
+const DEFAULT_OPS = [
+	"create",
+	"createMany",
+	"update",
+	"delete",
+	"getById",
+	"getByQuery",
+	"getAll",
+	"aggregatePaginate",
+	"lookupPopulate"
+];
+const timers = /* @__PURE__ */ new WeakMap();
+function observabilityPlugin(options) {
+	const { onMetric, slowThresholdMs } = options;
+	const ops = options.operations ?? DEFAULT_OPS;
+	return {
+		name: "observability",
+		apply(repo) {
+			for (const op of ops) {
+				repo.on(`before:${op}`, (context) => {
+					timers.set(context, performance.now());
+				});
+				repo.on(`after:${op}`, ({ context }) => {
+					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 }) => {
+					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/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",
+				"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: write audit entry, never throw */
+function writeAudit(AuditModel, entry) {
+	Promise.resolve().then(() => {
+		AuditModel.create({
+			...entry,
+			timestamp: /* @__PURE__ */ new Date()
+		}).catch((err) => {
+			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 = [] } = options;
+	const opsSet = new Set(operations);
+	return {
+		name: "auditTrail",
+		apply(repo) {
+			const AuditModel = getAuditModel(collectionName, ttlDays);
+			if (opsSet.has("create")) repo.on("after:create", ({ context, result }) => {
+				const doc = toPlainObject(result);
+				writeAudit(AuditModel, {
+					model: context.model || repo.model,
+					operation: "create",
+					documentId: doc?._id,
+					userId: getUserId(context),
+					orgId: context.organizationId,
+					document: trackDocument ? sanitizeDoc(doc, excludeFields) : void 0,
+					metadata: metadata?.(context)
+				});
+			});
+			if (opsSet.has("update")) {
+				if (trackChanges) repo.on("before:update", async (context) => {
+					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 }) => {
+					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?._id,
+						userId: getUserId(context),
+						orgId: context.organizationId,
+						changes,
+						metadata: metadata?.(context)
+					});
+				});
+			}
+			if (opsSet.has("delete")) repo.on("after:delete", ({ context }) => {
+				writeAudit(AuditModel, {
+					model: context.model || repo.model,
+					operation: "delete",
+					documentId: context.id,
+					userId: getUserId(context),
+					orgId: context.organizationId,
+					metadata: metadata?.(context)
+				});
+			});
+			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 [docs, total] = await Promise.all([AuditModel.find(filter).sort({ timestamp: -1 }).skip(skip).limit(limit).lean(), AuditModel.countDocuments(filter)]);
+				return {
+					docs,
+					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 [docs, 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 {
+			docs,
+			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/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 {
+					docs: [],
+					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 {
+					docs: [],
+					total,
+					limit,
+					from
+				};
+				const mongoQuery = this.Model.find({ _id: { $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 {
+					docs: (await mongoQuery.exec()).sort((a, b) => {
+						const aId = String(a._id);
+						const bId = String(b._id);
+						return (docsOrder.get(aId) ?? Number.MAX_SAFE_INTEGER) - (docsOrder.get(bId) ?? Number.MAX_SAFE_INTEGER);
+					}).map((doc) => {
+						const strId = String(doc._id);
+						if (searchOptions.mongoOptions?.lean !== false) return {
+							...doc,
+							_score: scores.get(strId)
+						};
+						return doc;
+					}),
+					total,
+					limit,
+					from
+				};
+			});
+		}
+	};
+}
+
+//#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.
+* Lazy-init to avoid model registration errors if mongoose isn't connected yet.
+*/
+function getCounterModel() {
+	if (mongoose.models._MongoKitCounter) return mongoose.models._MongoKitCounter;
+	return mongoose.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)
+* @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)
+*/
+async function getNextSequence(counterKey, increment = 1) {
+	return (await getCounterModel().findOneAndUpdate({ _id: counterKey }, { $inc: { seq: increment } }, {
+		upsert: true,
+		returnDocument: "after"
+	})).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);
+		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);
+		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) {
+			repo.on("before:create", async (context) => {
+				if (!context.data) return;
+				if (generateOnlyIfEmpty && context.data[fieldName]) return;
+				context.data[fieldName] = await options.generator(context);
+			});
+			repo.on("before:createMany", async (context) => {
+				if (!context.dataArray) return;
+				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
+export { methodRegistryPlugin as C, fieldFilterPlugin as D, timestampPlugin as E, validationChainPlugin as S, auditLogPlugin as T, autoInject as _, sequentialId as a, requireField as b, auditTrailPlugin as c, cascadePlugin as d, cachePlugin as f, mongoOperationsPlugin as g, batchOperationsPlugin as h, prefixedId as i, observabilityPlugin as l, aggregateHelpersPlugin as m, dateSequentialId as n, elasticSearchPlugin as o, subdocumentPlugin as p, getNextSequence as r, AuditTrailQuery as s, customIdPlugin as t, multiTenantPlugin as u, blockIf as v, softDeletePlugin as w, uniqueField as x, immutableField as y };