@classytic/mongokit 3.3.2 → 3.4.0

package/dist/{custom-id.plugin-FInXDsUX.mjs → validation-chain.plugin-Ow6EUIoo.mjs}

@@ -1,98 +1,712 @@
-import { i as createError, n as debug, r as warn } from "./logger-D8ily-PP.mjs";
-import { _ as upsert, c as count, d as getByQuery, f as getOrCreate, h as createMany, i as deleteById, l as exists, m as create, n as distinct, o as update, r as LookupBuilder, u as getById } from "./aggregate-BClp040M.mjs";
-import { PaginationEngine } from "./pagination/PaginationEngine.mjs";
-import { a as modelPattern, i as listQueryKey, l as getFieldsForUser, n as byQueryKey, o as versionKey, t as byIdKey } from "./cache-keys-CzFwVnLy.mjs";
+import { a as warn, i as debug, n as parseDuplicateKeyError, t as createError } from "./error-Bpbi_NKo.mjs";
+import { _ as LookupBuilder, a as getById, d as create, f as createMany, g as distinct, i as exists, l as deleteById, m as upsert, o as getByQuery, r as count, s as getOrCreate, t as update } from "./update-DXwVh6M1.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-PLyDhrO7.mjs";
+import { a as byIdKey, c as listQueryKey, l as modelPattern, o as byQueryKey, r as getFieldsForUser, u as versionKey } from "./field-selection-CalOB7yM.mjs";
 import mongoose from "mongoose";
-
-//#region src/query/AggregationBuilder.ts
+//#region src/plugins/aggregate-helpers.plugin.ts
 /**
-* Normalize SortSpec to MongoDB's strict format (1 | -1)
-* Converts 'asc' -> 1, 'desc' -> -1
+* 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 normalizeSortSpec(sortSpec) {
-	const normalized = {};
-	for (const [field, order] of Object.entries(sortSpec)) if (order === "asc") normalized[field] = 1;
-	else if (order === "desc") normalized[field] = -1;
-	else normalized[field] = order;
-	return normalized;
+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/audit-log.plugin.ts
 /**
-* Fluent builder for MongoDB aggregation pipelines
-* Optimized for complex queries at scale
+* Audit log plugin that logs all repository operations
+*
+* @example
+* const repo = new Repository(Model, [auditLogPlugin(console)]);
 */
-var AggregationBuilder = class AggregationBuilder {
-	pipeline = [];
-	_diskUse = false;
-	/**
-	* Get the current pipeline
-	*/
-	get() {
-		return [...this.pipeline];
-	}
-	/**
-	* Build and return the final pipeline
-	*/
-	build() {
-		return this.get();
+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/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 });
 	}
-	/**
-	* Build pipeline with execution options (allowDiskUse, etc.)
-	*/
-	plan() {
-		return {
-			pipeline: this.get(),
-			allowDiskUse: this._diskUse
+	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
 		};
 	}
-	/**
-	* Build and execute the pipeline against a model
-	*
-	* @example
-	* ```typescript
-	* const results = await new AggregationBuilder()
-	*   .match({ status: 'active' })
-	*   .allowDiskUse()
-	*   .exec(MyModel);
-	* ```
-	*/
-	async exec(model, session) {
-		const agg = model.aggregate(this.build());
-		if (this._diskUse) agg.allowDiskUse(true);
-		if (session) agg.session(session);
-		return agg.exec();
+	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);
 	}
 	/**
-	* Reset the pipeline
+	* Get the underlying Mongoose model for custom queries
 	*/
-	reset() {
-		this.pipeline = [];
-		this._diskUse = false;
-		return this;
+	getModel() {
+		return this.model;
 	}
 	/**
-	* Add a raw pipeline stage
+	* Query audit entries with filters and pagination
 	*/
-	addStage(stage) {
-		this.pipeline.push(stage);
-		return this;
+	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
+		};
 	}
 	/**
-	* Add multiple raw pipeline stages
+	* Get audit trail for a specific document
 	*/
-	addStages(stages) {
-		this.pipeline.push(...stages);
-		return this;
+	async getDocumentTrail(model, documentId, options = {}) {
+		return this.query({
+			model,
+			documentId,
+			...options
+		});
 	}
 	/**
-	* $match - Filter documents
-	* IMPORTANT: Place $match as early as possible for performance
+	* Get all audits for a user
 	*/
-	match(query) {
-		this.pipeline.push({ $match: query });
-		return this;
+	async getUserTrail(userId, options = {}) {
+		return this.query({
+			userId,
+			...options
+		});
 	}
 	/**
-	* $project - Include/exclude fields or compute new fields
+	* 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(),
+* ]);
+*
+* 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 {
+					const finalQuery = context.query || query;
+					if (!finalQuery || Object.keys(finalQuery).length === 0) throw createError(400, "updateMany requires a non-empty query filter. Pass an explicit filter to prevent accidental mass updates.");
+					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 finalData = context.data || data;
+					const result = await this.Model.updateMany(finalQuery, finalData, {
+						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);
+				}
+			});
+			/**
+			* 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.call(this, "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.call(this, error);
+				}
+			});
+			/**
+			* Delete multiple documents
+			*/
+			repo.registerMethod("deleteMany", async function(query, options = {}) {
+				const context = await this._buildContext.call(this, "deleteMany", {
+					query,
+					...options
+				});
+				try {
+					if (context.softDeleted) {
+						const result = {
+							acknowledged: true,
+							deletedCount: 0
+						};
+						await this.emitAsync("after:deleteMany", {
+							context,
+							result
+						});
+						return result;
+					}
+					const finalQuery = context.query || query;
+					if (!finalQuery || Object.keys(finalQuery).length === 0) throw createError(400, "deleteMany requires a non-empty query filter. Pass an explicit filter to prevent accidental mass deletes.");
+					const result = await this.Model.deleteMany(finalQuery, { 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/query/AggregationBuilder.ts
+/**
+* Normalize SortSpec to MongoDB's strict format (1 | -1)
+* Converts 'asc' -> 1, 'desc' -> -1
+*/
+function normalizeSortSpec(sortSpec) {
+	const normalized = {};
+	for (const [field, order] of Object.entries(sortSpec)) if (order === "asc") normalized[field] = 1;
+	else if (order === "desc") normalized[field] = -1;
+	else normalized[field] = order;
+	return normalized;
+}
+/**
+* Fluent builder for MongoDB aggregation pipelines
+* Optimized for complex queries at scale
+*/
+var AggregationBuilder = class AggregationBuilder {
+	pipeline = [];
+	_diskUse = false;
+	/**
+	* Get the current pipeline
+	*/
+	get() {
+		return [...this.pipeline];
+	}
+	/**
+	* Build and return the final pipeline
+	*/
+	build() {
+		return this.get();
+	}
+	/**
+	* Build pipeline with execution options (allowDiskUse, etc.)
+	*/
+	plan() {
+		return {
+			pipeline: this.get(),
+			allowDiskUse: this._diskUse
+		};
+	}
+	/**
+	* Build and execute the pipeline against a model
+	*
+	* @example
+	* ```typescript
+	* const results = await new AggregationBuilder()
+	*   .match({ status: 'active' })
+	*   .allowDiskUse()
+	*   .exec(MyModel);
+	* ```
+	*/
+	async exec(model, session) {
+		const agg = model.aggregate(this.build());
+		if (this._diskUse) agg.allowDiskUse(true);
+		if (session) agg.session(session);
+		return agg.exec();
+	}
+	/**
+	* Reset the pipeline
+	*/
+	reset() {
+		this.pipeline = [];
+		this._diskUse = false;
+		return this;
+	}
+	/**
+	* Add a raw pipeline stage
+	*/
+	addStage(stage) {
+		this.pipeline.push(stage);
+		return this;
+	}
+	/**
+	* Add multiple raw pipeline stages
+	*/
+	addStages(stages) {
+		this.pipeline.push(...stages);
+		return this;
+	}
+	/**
+	* $match - Filter documents
+	* IMPORTANT: Place $match as early as possible for performance
+	*/
+	match(query) {
+		this.pipeline.push({ $match: query });
+		return this;
+	}
+	/**
+	* $project - Include/exclude fields or compute new fields
 	*/
 	project(projection) {
 		this.pipeline.push({ $project: projection });
@@ -489,36 +1103,9 @@ var AggregationBuilder = class AggregationBuilder {
 		return new AggregationBuilder().match(query);
 	}
 };
-
 //#endregion
 //#region src/Repository.ts
 /**
-* Repository Pattern - Data Access Layer
-*
-* Event-driven, plugin-based abstraction for MongoDB operations
-* Inspired by Meta & Stripe's repository patterns
-*
-* @example
-* ```typescript
-* const userRepo = new Repository(UserModel, [
-*   timestampPlugin(),
-*   softDeletePlugin(),
-* ]);
-*
-* // Create
-* const user = await userRepo.create({ name: 'John', email: 'john@example.com' });
-*
-* // Read with pagination
-* const users = await userRepo.getAll({ page: 1, limit: 20, filters: { status: 'active' } });
-*
-* // Update
-* const updated = await userRepo.update(user._id, { name: 'John Doe' });
-*
-* // Delete
-* await userRepo.delete(user._id);
-* ```
-*/
-/**
 * Plugin phase priorities (lower = runs first)
 * Policy hooks (multi-tenant, soft-delete, validation) MUST run before cache
 * to ensure filters are injected before cache keys are computed.
@@ -546,7 +1133,9 @@ var Repository = class {
 		this._hooks = /* @__PURE__ */ new Map();
 		this._pagination = new PaginationEngine(Model, paginationConfig);
 		this._hookMode = options.hooks ?? "async";
-		plugins.forEach((plugin) => this.use(plugin));
+		plugins.forEach((plugin) => {
+			this.use(plugin);
+		});
 	}
 	/**
 	* Register a plugin
@@ -807,7 +1396,7 @@ var Repository = class {
 		let useKeyset = false;
 		if (mode) useKeyset = mode === "keyset";
 		else useKeyset = !page && !!(after || sort !== "-createdAt" && (context.sort ?? params.sort));
-		let query = { ...filters };
+		const query = { ...filters };
 		if (search) {
 			if (this._hasTextIndex === null) this._hasTextIndex = this.Model.schema.indexes().some((idx) => idx[0] && Object.values(idx[0]).includes("text"));
 			if (this._hasTextIndex) query.$text = { $search: search };
@@ -826,18 +1415,30 @@ var Repository = class {
 			maxTimeMS: context.maxTimeMS ?? params.maxTimeMS,
 			readPreference: context.readPreference ?? options.readPreference ?? params.readPreference
 		};
-		try {
-			let result;
-			if (useKeyset) result = await this._pagination.stream({
-				...paginationOptions,
+		const lookups = params.lookups;
+		if (lookups && lookups.length > 0) try {
+			const lookupResult = await this.lookupPopulate({
+				filters: query,
+				lookups,
 				sort: paginationOptions.sort,
-				after
-			});
-			else result = await this._pagination.paginate({
-				...paginationOptions,
 				page: page || 1,
-				countStrategy: context.countStrategy ?? params.countStrategy
-			});
+				limit,
+				select: paginationOptions.select,
+				session: options.session,
+				readPreference: paginationOptions.readPreference
+			});
+			const totalPages = Math.ceil((lookupResult.total ?? 0) / (lookupResult.limit ?? limit));
+			const currentPage = lookupResult.page ?? 1;
+			const result = {
+				method: "offset",
+				docs: lookupResult.data,
+				page: currentPage,
+				limit: lookupResult.limit ?? limit,
+				total: lookupResult.total ?? 0,
+				pages: totalPages,
+				hasNext: currentPage < totalPages,
+				hasPrev: currentPage > 1
+			};
 			await this._emitHook("after:getAll", {
 				context,
 				result
@@ -850,9 +1451,33 @@ var Repository = class {
 			});
 			throw this._handleError(error);
 		}
-	}
-	/**
-	* Get or create document
+		try {
+			let result;
+			if (useKeyset) result = await this._pagination.stream({
+				...paginationOptions,
+				sort: paginationOptions.sort,
+				after
+			});
+			else result = await this._pagination.paginate({
+				...paginationOptions,
+				page: page || 1,
+				countStrategy: context.countStrategy ?? params.countStrategy
+			});
+			await this._emitHook("after:getAll", {
+				context,
+				result
+			});
+			return result;
+		} catch (error) {
+			await this._emitErrorHook("error:getAll", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
+	* Get or create document
 	* Routes through hook system for policy enforcement (multi-tenant, soft-delete)
 	*/
 	async getOrCreate(query, createData, options = {}) {
@@ -1340,1614 +1965,1205 @@ var Repository = class {
 	_handleError(error) {
 		if (error instanceof mongoose.Error.ValidationError) return createError(400, `Validation Error: ${Object.values(error.errors).map((err) => err.message).join(", ")}`);
 		if (error instanceof mongoose.Error.CastError) return createError(400, `Invalid ${error.path}: ${error.value}`);
+		const duplicateErr = parseDuplicateKeyError(error);
+		if (duplicateErr) return duplicateErr;
 		if (error.status && error.message) return error;
 		return createError(500, error.message || "Internal Server Error");
 	}
 };
-
-//#endregion
-//#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 } };
-}
+//#region src/plugins/cache.plugin.ts
 /**
-* Soft delete plugin
+* Cache Plugin
 *
-* @example Basic usage
-* ```typescript
-* const repo = new Repository(Model, [
-*   softDeletePlugin({ deletedField: 'deletedAt' })
-* ]);
+* Optional caching layer for MongoKit with automatic invalidation.
+* Bring-your-own cache adapter (Redis, Memcached, in-memory, etc.)
 *
-* // Delete (soft)
-* await repo.delete(id);
+* Features:
+* - Cache-aside (read-through) pattern with configurable TTLs
+* - Automatic invalidation on create/update/delete
+* - Collection version tags for efficient list cache invalidation
+* - Manual invalidation methods for microservice scenarios
+* - Skip cache per-operation with `skipCache: true`
 *
-* // Restore
-* await repo.restore(id);
+* @example
+* ```typescript
+* import { Repository, cachePlugin } from '@classytic/mongokit';
+* import Redis from 'ioredis';
 *
-* // Get deleted documents
-* await repo.getDeleted({ page: 1, limit: 20 });
-* ```
+* const redis = new Redis();
 *
-* @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
+* const userRepo = new Repository(UserModel, [
+*   cachePlugin({
+*     adapter: {
+*       async get(key) { return JSON.parse(await redis.get(key) || 'null'); },
+*       async set(key, value, ttl) { await redis.setex(key, ttl, JSON.stringify(value)); },
+*       async del(key) { await redis.del(key); },
+*       async clear(pattern) {
+*         const keys = await redis.keys(pattern || '*');
+*         if (keys.length) await redis.del(...keys);
+*       }
+*     },
+*     ttl: 60, // 1 minute default
 *   })
 * ]);
-* ```
 *
-* @example With TTL for auto-cleanup
-* ```typescript
-* const repo = new Repository(Model, [
-*   softDeletePlugin({
-*     deletedField: 'deletedAt',
-*     ttlDays: 30, // Auto-delete after 30 days
-*   })
-* ]);
+* // Reads check cache first
+* const user = await userRepo.getById(id); // cached
+*
+* // Skip cache for fresh data
+* const fresh = await userRepo.getById(id, { skipCache: true });
+*
+* // Mutations auto-invalidate
+* await userRepo.update(id, { name: 'New Name' }); // invalidates cache
+*
+* // Manual invalidation for microservice sync
+* await userRepo.invalidateCache(id); // invalidate single doc
+* await userRepo.invalidateAllCache(); // invalidate all for this model
 * ```
 */
-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;
+/**
+* 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,
+		errors: 0
+	};
+	const log = (msg, data) => {
+		if (config.debug) debug(`[mongokit:cache] ${msg}`, data ?? "");
+	};
 	return {
-		name: "softDelete",
+		name: "cache",
 		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 } }`);
+			const model = repo.model;
+			const byIdKeyRegistry = /* @__PURE__ */ new Map();
+			function trackByIdKey(docId, cacheKey) {
+				let keys = byIdKeyRegistry.get(docId);
+				if (!keys) {
+					keys = /* @__PURE__ */ new Set();
+					byIdKeyRegistry.set(docId, keys);
 				}
-			} catch (err) {
-				warn(`[softDeletePlugin] Schema introspection failed for ${repo.Model.modelName}: ${err instanceof Error ? err.message : String(err)}`);
+				keys.add(cacheKey);
 			}
-			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}`);
-				});
+			async function getVersion() {
+				try {
+					return await config.adapter.get(versionKey(config.prefix, model)) ?? 0;
+				} catch (e) {
+					log(`Cache error in getVersion for ${model}:`, e);
+					return 0;
+				}
 			}
-			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;
-					const deleteQuery = {
-						_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;
+			/**
+			* 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);
 				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			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
-					};
+			}
+			/**
+			* Invalidate a specific document by ID (all shape variants).
+			* Deletes every tracked shape-variant key individually via del(),
+			* so adapters without pattern-based clear() still get full invalidation.
+			*/
+			async function invalidateById(id) {
+				try {
+					const baseKey = byIdKey(config.prefix, model, id);
+					await config.adapter.del(baseKey);
+					const trackedKeys = byIdKeyRegistry.get(id);
+					if (trackedKeys) {
+						for (const key of trackedKeys) if (key !== baseKey) await config.adapter.del(key);
+						byIdKeyRegistry.delete(id);
+					}
+					stats.invalidations++;
+					log(`Invalidated byId cache for:`, id);
+				} catch (e) {
+					log(`Failed to invalidate byId cache:`, e);
 				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			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
-					};
+			}
+			/**
+			* before:getById - Check cache for document
+			* Runs at CACHE priority (200) — after policy hooks inject filters
+			*/
+			repo.on("before:getById", async (context) => {
+				if (context.skipCache) {
+					log(`Skipping cache for getById: ${context.id}`);
+					return;
 				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			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
-					};
+				const id = String(context.id);
+				const key = byIdKey(config.prefix, model, id, {
+					select: context.select,
+					populate: context.populate,
+					lean: context.lean
+				});
+				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.errors++;
 				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:count", (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.CACHE });
+			/**
+			* before:getByQuery - Check cache for single-doc query
+			* Runs at CACHE priority (200) — after policy hooks inject filters
+			*/
+			repo.on("before:getByQuery", async (context) => {
+				if (context.skipCache) {
+					log(`Skipping cache for getByQuery`);
+					return;
 				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:exists", (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.query = {
-						...context.query || {},
-						...deleteFilter
-					};
+				const collectionVersion = await getVersion();
+				const query = context.query || {};
+				const key = byQueryKey(config.prefix, model, collectionVersion, 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.errors++;
 				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:getOrCreate", (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.CACHE });
+			/**
+			* before:getAll - Check cache for list query
+			* Runs at CACHE priority (200) — after policy hooks inject filters
+			*/
+			repo.on("before:getAll", async (context) => {
+				if (context.skipCache) {
+					log(`Skipping cache for getAll`);
+					return;
 				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:distinct", (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.query = {
-						...context.query || {},
-						...deleteFilter
-					};
+				const limit = context.limit;
+				if (limit && limit > config.skipIfLargeLimit) {
+					log(`Skipping cache for large query (limit: ${limit})`);
+					return;
 				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:aggregate", (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.query = {
-						...context.query || {},
-						...deleteFilter
-					};
+				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,
+					mode: context.mode,
+					lean: context.lean,
+					readPreference: context.readPreference,
+					hint: context.hint,
+					maxTimeMS: context.maxTimeMS,
+					countStrategy: context.countStrategy
+				};
+				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.errors++;
 				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:aggregatePaginate", (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.filters = {
-						...context.filters || {},
-						...deleteFilter
-					};
+			}, { priority: HOOK_PRIORITY.CACHE });
+			/**
+			* 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, {
+					select: context.select,
+					populate: context.populate,
+					lean: context.lean
+				});
+				const ttl = context.cacheTtl ?? config.byIdTtl;
+				try {
+					await config.adapter.set(key, result, ttl);
+					trackByIdKey(id, key);
+					stats.sets++;
+					log(`Cached getById result:`, key);
+				} catch (e) {
+					log(`Failed to cache getById:`, e);
 				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			if (addRestoreMethod) {
-				const restoreMethod = async function(id, restoreOptions = {}) {
-					const context = await this._buildContext.call(this, "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", {
-						id,
-						result,
-						context
-					});
-					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.call(this, "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 [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
+			* after:getByQuery - Cache the result
 			*/
-			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
+			repo.on("after:getByQuery", async (payload) => {
+				const { context, result } = payload;
+				if (context._cacheHit) return;
+				if (context.skipCache) return;
+				if (result === null) return;
+				const collectionVersion = await getVersion();
+				const query = context.query || {};
+				const key = byQueryKey(config.prefix, model, collectionVersion, 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,
+					mode: context.mode,
+					lean: context.lean,
+					readPreference: context.readPreference,
+					hint: context.hint,
+					maxTimeMS: context.maxTimeMS,
+					countStrategy: context.countStrategy
+				};
+				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();
+			});
+			/**
+			* after:bulkWrite - Bump version (bulk ops may insert/update/delete)
+			*/
+			repo.on("after:bulkWrite", 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);
 			};
 			/**
-			* Check if a method is registered
+			* Invalidate all list caches for this model
+			* Use when bulk changes happened outside this service
+			*
+			* @example
+			* await userRepo.invalidateListCache();
 			*/
-			repo.hasMethod = function(name) {
-				return typeof repo[name] === "function";
+			repo.invalidateListCache = async () => {
+				await bumpVersion();
+				log(`Manual list cache invalidation for ${model}`);
 			};
 			/**
-			* Get list of all dynamically registered methods
+			* Invalidate ALL cache entries for this model
+			* Nuclear option - use sparingly
+			*
+			* @example
+			* await userRepo.invalidateAllCache();
 			*/
-			repo.getRegisteredMethods = function() {
-				return [...registeredMethods];
+			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)`);
+				}
 			};
-		}
-	};
-}
-
-//#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;
-				}
+			/**
+			* 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;
+				stats.errors = 0;
 			};
-			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]) 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 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.
-*/
+//#region src/plugins/cascade.plugin.ts
 /**
-* 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
+* Cascade Delete Plugin
+* Automatically deletes related documents when a parent document is deleted
 *
-* @example Basic usage (no TypeScript autocomplete)
+* @example
 * ```typescript
-* const repo = new Repository(ProductModel, [
+* import mongoose from 'mongoose';
+* import { Repository, cascadePlugin, methodRegistryPlugin } from '@classytic/mongokit';
+*
+* const productRepo = new Repository(Product, [
 *   methodRegistryPlugin(),
-*   mongoOperationsPlugin(),
+*   cascadePlugin({
+*     relations: [
+*       { model: 'StockEntry', foreignKey: 'product' },
+*       { model: 'StockMovement', foreignKey: 'product' },
+*     ]
+*   })
 * ]);
 *
-* // 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');
+* // When a product is deleted, all related StockEntry and StockMovement docs are also deleted
+* await productRepo.delete(productId);
 * ```
+*/
+/**
+* Cascade delete plugin
 *
-* @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;
+* Deletes related documents after the parent document is deleted.
+* Works with both hard delete and soft delete scenarios.
 *
-* // 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');
-* ```
+* @param options - Cascade configuration
+* @returns Plugin
 */
-function mongoOperationsPlugin() {
+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: "mongo-operations",
+		name: "cascade",
 		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);
+			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);
 			});
-			/**
-			* 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);
+			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);
 			});
-			/**
-			* 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);
+			repo.on("after:deleteMany", 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/batch-operations.plugin.ts
+//#region src/plugins/custom-id.plugin.ts
 /**
-* Batch operations plugin
-* 
-* @example
-* const repo = new Repository(Model, [
-*   methodRegistryPlugin(),
-*   batchOperationsPlugin(),
+* 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,
+*     }),
+*   }),
 * ]);
-* 
-* 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 {
-					const finalQuery = context.query || query;
-					if (!finalQuery || Object.keys(finalQuery).length === 0) throw createError(400, "updateMany requires a non-empty query filter. Pass an explicit filter to prevent accidental mass updates.");
-					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(finalQuery, 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);
-				}
-			});
-			/**
-			* 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.call(this, "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.call(this, error);
-				}
-			});
-			/**
-			* Delete multiple documents
-			*/
-			repo.registerMethod("deleteMany", async function(query, options = {}) {
-				const context = await this._buildContext.call(this, "deleteMany", {
-					query,
-					...options
-				});
-				try {
-					const finalQuery = context.query || query;
-					if (!finalQuery || Object.keys(finalQuery).length === 0) throw createError(400, "deleteMany requires a non-empty query filter. Pass an explicit filter to prevent accidental mass deletes.");
-					const result = await this.Model.deleteMany(finalQuery, { 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);
-				}
-			});
-		}
-	};
+*
+* 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);
 }
-
-//#endregion
-//#region src/plugins/aggregate-helpers.plugin.ts
 /**
-* Aggregate helpers plugin
-* 
+* 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 repo = new Repository(Model, [
-*   methodRegistryPlugin(),
-*   aggregateHelpersPlugin(),
-* ]);
-* 
-* const groups = await repo.groupBy('category');
-* const total = await repo.sum('amount', { status: 'completed' });
+* 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)
 */
-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);
-			});
-		}
-	};
+async function getNextSequence(counterKey, increment = 1, connection) {
+	const result = await getCounterModel(connection).findOneAndUpdate({ _id: counterKey }, { $inc: { seq: increment } }, {
+		upsert: true,
+		returnDocument: "after"
+	});
+	if (!result) throw new Error(`Failed to increment counter '${counterKey}'`);
+	return result.seq;
 }
-
-//#endregion
-//#region src/plugins/subdocument.plugin.ts
 /**
-* Subdocument plugin for managing nested arrays
-* 
+* Generator: Simple sequential counter.
+* Produces IDs like `INV-0001`, `INV-0002`, etc.
+*
+* Uses atomic MongoDB counters — safe under concurrency.
+*
 * @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",
+* ```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);
+		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);
+		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) {
-			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);
+			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);
 			});
-			/**
-			* 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;
+			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
 				});
 			});
-			/**
-			* 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;
+		}
+	};
+}
+//#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
+					}
 				});
-			});
-			/**
-			* Delete subdocument from array
-			*/
-			repo.registerMethod("deleteSubdocument", async function(parentId, arrayPath, subId, options = {}) {
-				return this.update.call(this, parentId, { $pull: { [arrayPath]: { _id: subId } } }, options);
+				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/cache.plugin.ts
+//#region src/plugins/field-filter.plugin.ts
 /**
-* Cache plugin factory
+* Field filter plugin that restricts fields based on user context
 *
-* @param options - Cache configuration
-* @returns Plugin instance
+* @example
+* const fieldPreset = {
+*   public: ['id', 'name'],
+*   authenticated: ['email'],
+*   admin: ['createdAt', 'internalNotes']
+* };
+*
+* const repo = new Repository(Model, [fieldFilterPlugin(fieldPreset)]);
 */
-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,
-		errors: 0
-	};
-	const log = (msg, data) => {
-		if (config.debug) debug(`[mongokit:cache] ${msg}`, data ?? "");
+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/method-registry.plugin.ts
+/**
+* Method registry plugin that enables dynamic method registration
+*/
+function methodRegistryPlugin() {
 	return {
-		name: "cache",
+		name: "method-registry",
 		apply(repo) {
-			const model = repo.model;
-			const byIdKeyRegistry = /* @__PURE__ */ new Map();
-			function trackByIdKey(docId, cacheKey) {
-				let keys = byIdKeyRegistry.get(docId);
-				if (!keys) {
-					keys = /* @__PURE__ */ new Set();
-					byIdKeyRegistry.set(docId, keys);
-				}
-				keys.add(cacheKey);
-			}
-			async function getVersion() {
-				try {
-					return await config.adapter.get(versionKey(config.prefix, model)) ?? 0;
-				} catch (e) {
-					log(`Cache error in getVersion for ${model}:`, e);
-					return 0;
-				}
-			}
+			const registeredMethods = [];
 			/**
-			* Bump collection version in the adapter (invalidates all list caches).
-			* Uses Date.now() so version always moves forward — safe after eviction or deploy.
+			* Register a new method on the repository instance
 			*/
-			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);
-				}
-			}
+			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
+				});
+			};
 			/**
-			* Invalidate a specific document by ID (all shape variants).
-			* Deletes every tracked shape-variant key individually via del(),
-			* so adapters without pattern-based clear() still get full invalidation.
+			* Check if a method is registered
 			*/
-			async function invalidateById(id) {
-				try {
-					const baseKey = byIdKey(config.prefix, model, id);
-					await config.adapter.del(baseKey);
-					const trackedKeys = byIdKeyRegistry.get(id);
-					if (trackedKeys) {
-						for (const key of trackedKeys) if (key !== baseKey) await config.adapter.del(key);
-						byIdKeyRegistry.delete(id);
-					}
-					stats.invalidations++;
-					log(`Invalidated byId cache for:`, id);
-				} catch (e) {
-					log(`Failed to invalidate byId cache:`, e);
-				}
-			}
+			repo.hasMethod = (name) => typeof repo[name] === "function";
 			/**
-			* before:getById - Check cache for document
-			* Runs at CACHE priority (200) — after policy hooks inject filters
+			* Get list of all dynamically registered methods
 			*/
-			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, {
-					select: context.select,
-					populate: context.populate,
-					lean: context.lean
-				});
-				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.errors++;
-				}
-			}, { priority: HOOK_PRIORITY.CACHE });
+			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.");
 			/**
-			* before:getByQuery - Check cache for single-doc query
-			* Runs at CACHE priority (200) — after policy hooks inject filters
+			* Update existing document or insert new one
 			*/
-			repo.on("before:getByQuery", async (context) => {
-				if (context.skipCache) {
-					log(`Skipping cache for getByQuery`);
-					return;
-				}
-				const collectionVersion = await getVersion();
-				const query = context.query || {};
-				const key = byQueryKey(config.prefix, model, collectionVersion, 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.errors++;
-				}
-			}, { priority: HOOK_PRIORITY.CACHE });
+			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);
+			};
 			/**
-			* before:getAll - Check cache for list query
-			* Runs at CACHE priority (200) — after policy hooks inject filters
+			* Atomically increment numeric field
 			*/
-			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,
-					mode: context.mode,
-					lean: context.lean,
-					readPreference: context.readPreference,
-					hint: context.hint,
-					maxTimeMS: context.maxTimeMS,
-					countStrategy: context.countStrategy
-				};
-				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.errors++;
-				}
-			}, { priority: HOOK_PRIORITY.CACHE });
+			repo.registerMethod("increment", async function(id, field, value = 1, options = {}) {
+				return validateAndUpdateNumeric.call(this, id, field, value, "$inc", "Increment", options);
+			});
 			/**
-			* after:getById - Cache the result
+			* Atomically decrement numeric field
 			*/
-			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, {
-					select: context.select,
-					populate: context.populate,
-					lean: context.lean
-				});
-				const ttl = context.cacheTtl ?? config.byIdTtl;
-				try {
-					await config.adapter.set(key, result, ttl);
-					trackByIdKey(id, key);
-					stats.sets++;
-					log(`Cached getById result:`, key);
-				} catch (e) {
-					log(`Failed to cache getById:`, e);
-				}
+			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);
+			};
 			/**
-			* after:getByQuery - Cache the result
+			* Push value to array field
 			*/
-			repo.on("after:getByQuery", async (payload) => {
-				const { context, result } = payload;
-				if (context._cacheHit) return;
-				if (context.skipCache) return;
-				if (result === null) return;
-				const collectionVersion = await getVersion();
-				const query = context.query || {};
-				const key = byQueryKey(config.prefix, model, collectionVersion, 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);
-				}
+			repo.registerMethod("pushToArray", async function(id, field, value, options = {}) {
+				return applyOperator.call(this, id, field, value, "$push", options);
 			});
 			/**
-			* after:getAll - Cache the result
+			* Remove value from array field
 			*/
-			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,
-					mode: context.mode,
-					lean: context.lean,
-					readPreference: context.readPreference,
-					hint: context.hint,
-					maxTimeMS: context.maxTimeMS,
-					countStrategy: context.countStrategy
-				};
-				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);
-				}
+			repo.registerMethod("pullFromArray", async function(id, field, value, options = {}) {
+				return applyOperator.call(this, id, field, value, "$pull", options);
 			});
 			/**
-			* after:create - Bump version to invalidate list caches
+			* Add value to array only if not already present (unique)
 			*/
-			repo.on("after:create", async () => {
-				await bumpVersion();
+			repo.registerMethod("addToSet", async function(id, field, value, options = {}) {
+				return applyOperator.call(this, id, field, value, "$addToSet", options);
 			});
 			/**
-			* after:createMany - Bump version to invalidate list caches
+			* Set field value (alias for update with $set)
 			*/
-			repo.on("after:createMany", async () => {
-				await bumpVersion();
+			repo.registerMethod("setField", async function(id, field, value, options = {}) {
+				return applyOperator.call(this, id, field, value, "$set", options);
 			});
 			/**
-			* after:update - Invalidate by ID and bump version
+			* Unset (remove) field from document
 			*/
-			repo.on("after:update", async (payload) => {
-				const { context } = payload;
-				const id = String(context.id);
-				await Promise.all([invalidateById(id), bumpVersion()]);
+			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);
 			});
 			/**
-			* after:updateMany - Bump version (can't track individual IDs efficiently)
+			* Rename field in document
 			*/
-			repo.on("after:updateMany", async () => {
-				await bumpVersion();
+			repo.registerMethod("renameField", async function(id, oldName, newName, options = {}) {
+				return this.update(id, { $rename: { [oldName]: newName } }, options);
 			});
 			/**
-			* after:delete - Invalidate by ID and bump version
+			* Multiply numeric field by value
 			*/
-			repo.on("after:delete", async (payload) => {
-				const { context } = payload;
-				const id = String(context.id);
-				await Promise.all([invalidateById(id), bumpVersion()]);
+			repo.registerMethod("multiplyField", async function(id, field, multiplier, options = {}) {
+				return validateAndUpdateNumeric.call(this, id, field, multiplier, "$mul", "Multiplier", options);
 			});
 			/**
-			* after:deleteMany - Bump version
+			* Set field to minimum value (only if current value is greater)
 			*/
-			repo.on("after:deleteMany", async () => {
-				await bumpVersion();
+			repo.registerMethod("setMin", async function(id, field, value, options = {}) {
+				return applyOperator.call(this, id, field, value, "$min", options);
 			});
 			/**
-			* after:bulkWrite - Bump version (bulk ops may insert/update/delete)
+			* Set field to maximum value (only if current value is less)
 			*/
-			repo.on("after:bulkWrite", async () => {
-				await bumpVersion();
+			repo.registerMethod("setMax", async function(id, field, value, options = {}) {
+				return applyOperator.call(this, id, field, value, "$max", options);
 			});
 			/**
-			* Invalidate cache for a specific document
-			* Use when document was updated outside this service
+			* Atomic update with multiple MongoDB operators in a single call
 			*
-			* @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
+			* Combines $inc, $set, $push, $pull, $addToSet, $unset, $setOnInsert, $min, $max, $mul, $rename
+			* into one atomic database operation.
 			*
 			* @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
+			* // Combine $inc + $set in one atomic call
+			* await repo.atomicUpdate(id, {
+			*   $inc: { views: 1, commentCount: 1 },
+			*   $set: { lastActiveAt: new Date() }
+			* });
 			*
-			* @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
+			* // Multiple operators: $inc + $set + $push
+			* await repo.atomicUpdate(id, {
+			*   $inc: { 'metrics.total': 1 },
+			*   $set: { updatedAt: new Date() },
+			*   $push: { history: { action: 'update', at: new Date() } }
+			* });
 			*
-			* @example
-			* const stats = userRepo.getCacheStats();
-			* console.log(`Hit rate: ${stats.hits / (stats.hits + stats.misses) * 100}%`);
-			*/
-			repo.getCacheStats = () => ({ ...stats });
-			/**
-			* Reset cache statistics
+			* // $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.resetCacheStats = () => {
-				stats.hits = 0;
-				stats.misses = 0;
-				stats.sets = 0;
-				stats.invalidations = 0;
-				stats.errors = 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("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);
-			});
-			repo.on("after:deleteMany", 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);
+			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
 /**
@@ -3086,7 +3302,6 @@ function multiTenantPlugin(options = {}) {
 		}
 	};
 }
-
 //#endregion
 //#region src/plugins/observability.plugin.ts
 const DEFAULT_OPS = [
@@ -3147,691 +3362,538 @@ function observabilityPlugin(options) {
 		}
 	};
 }
-
 //#endregion
-//#region src/plugins/audit-trail.plugin.ts
+//#region src/plugins/soft-delete.plugin.ts
 /**
-* Audit Trail Plugin
+* 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
 *
-* Persists operation audit entries to a MongoDB collection.
-* Fire-and-forget: writes happen async and never block or fail the main operation.
+* @example Basic usage
+* ```typescript
+* const repo = new Repository(Model, [
+*   softDeletePlugin({ deletedField: 'deletedAt' })
+* ]);
 *
-* 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
+* // Delete (soft)
+* await repo.delete(id);
 *
-* @example
+* // 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
-* const repo = new Repository(Job, [
-*   auditTrailPlugin({
-*     operations: ['create', 'update', 'delete'],
-*     trackChanges: true,
-*     ttlDays: 90,
-*     metadata: (context) => ({
-*       ip: context.req?.ip,
-*     }),
-*   }),
+* // 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
+*   })
 * ]);
 * ```
 */
-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);
+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: "auditTrail",
+		name: "softDelete",
 		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)
+			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}`);
 				});
-			});
-			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("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;
+					const deleteQuery = {
+						_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;
 					}
-				});
-				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);
+					context.softDeleted = true;
+				}
+			}, { priority: HOOK_PRIORITY.POLICY });
+			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
+					};
+				}
+			}, { priority: HOOK_PRIORITY.POLICY });
+			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
+					};
+				}
+			}, { priority: HOOK_PRIORITY.POLICY });
+			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
+					};
+				}
+			}, { priority: HOOK_PRIORITY.POLICY });
+			repo.on("before:count", (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:exists", (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:getOrCreate", (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:distinct", (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: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 (options.soft !== false) {
+					const deleteFilter = buildDeletedFilter(deletedField, filterMode, false);
+					const finalQuery = {
+						...context.query || {},
+						...deleteFilter
+					};
+					await repo.Model.updateMany(finalQuery, { $set: { [deletedField]: /* @__PURE__ */ new Date() } }, { session: context.session });
+					context.softDeleted = true;
+				}
+			}, { priority: HOOK_PRIORITY.POLICY });
+			repo.on("before:aggregate", (context) => {
+				if (options.soft !== false) {
+					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
+					if (Object.keys(deleteFilter).length > 0) context.query = {
+						...context.query || {},
+						...deleteFilter
+					};
+				}
+			}, { priority: HOOK_PRIORITY.POLICY });
+			repo.on("before:aggregatePaginate", (context) => {
+				if (options.soft !== false) {
+					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
+					if (Object.keys(deleteFilter).length > 0) context.filters = {
+						...context.filters || {},
+						...deleteFilter
+					};
+				}
+			}, { priority: HOOK_PRIORITY.POLICY });
+			if (addRestoreMethod) {
+				const restoreMethod = async function(id, restoreOptions = {}) {
+					const context = await this._buildContext.call(this, "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;
 					}
-					writeAudit(AuditModel, {
-						model: context.model || repo.model,
-						operation: "update",
-						documentId: context.id || doc?._id,
-						userId: getUserId(context),
-						orgId: context.organizationId,
-						changes,
-						metadata: metadata?.(context)
+					await this.emitAsync("after:restore", {
+						id,
+						result,
+						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
+					return result;
 				};
-			});
-		}
-	};
-}
-/** 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
+				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.call(this, "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);
 					}
-				});
-				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 (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 (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
+					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/custom-id.plugin.ts
+//#region src/plugins/subdocument.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"
-* ```
+* Subdocument plugin for managing nested arrays
 *
-* @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,
-*     }),
-*   }),
+* @example
+* const repo = new Repository(Model, [
+*   methodRegistryPlugin(),
+*   subdocumentPlugin(),
 * ]);
 *
-* 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}`;
-*     },
-*   }),
-* ]);
-* ```
+* await repo.addSubdocument(parentId, 'items', { name: 'Item 1' });
+* await repo.updateSubdocument(parentId, 'items', itemId, { name: 'Updated Item' });
 */
-/** 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
-});
+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/timestamp.plugin.ts
 /**
-* 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.
+* Timestamp plugin that auto-injects timestamps
+*
+* @example
+* const repo = new Repository(Model, [timestampPlugin()]);
 */
-function getCounterModel(connection) {
-	const conn = connection ?? mongoose.connection;
-	if (conn.models._MongoKitCounter) return conn.models._MongoKitCounter;
-	return conn.model("_MongoKitCounter", counterSchema);
+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/validation-chain.plugin.ts
 /**
-* 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)
+* Validation chain plugin
 *
 * @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)
+* 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'),
+*   ])
+* ]);
 */
-async function getNextSequence(counterKey, increment = 1, connection) {
-	const result = await getCounterModel(connection).findOneAndUpdate({ _id: counterKey }, { $inc: { seq: increment } }, {
-		upsert: true,
-		returnDocument: "after"
+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`);
 	});
-	if (!result) throw new Error(`Failed to increment counter '${counterKey}'`);
-	return result.seq;
+	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));
+		}
+	};
 }
 /**
-* Generator: Simple sequential counter.
-* Produces IDs like `INV-0001`, `INV-0002`, etc.
-*
-* Uses atomic MongoDB counters — safe under concurrency.
+* Block operation if condition is true
 *
 * @example
-* ```typescript
-* customIdPlugin({
-*   field: 'invoiceNumber',
-*   generator: sequentialId({ prefix: 'INV', model: InvoiceModel }),
-* })
-* ```
+* blockIf('block-library', ['delete'], ctx => ctx.data?.managed, 'Cannot delete managed records')
 */
-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);
-		return `${prefix}${separator}${String(seq).padStart(padding, "0")}`;
+function blockIf(name, operations, condition, errorMessage) {
+	return {
+		name,
+		operations,
+		validate: (context) => {
+			if (condition(context)) throw createError(403, errorMessage);
+		}
 	};
 }
 /**
-* 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',
-*   }),
-* })
-* ```
+* Require a field to be present
 */
-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;
+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`);
 		}
-		const seq = await getNextSequence(counterKey, 1, context._counterConnection);
-		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 }),
-* })
-* ```
+* Auto-inject a value if not present
 */
-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}`;
+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;
+			}
+		}
 	};
 }
 /**
-* 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"
-* ```
+* Make a field immutable (cannot be updated)
 */
-function customIdPlugin(options) {
-	const fieldName = options.field || "customId";
-	const generateOnlyIfEmpty = options.generateOnlyIfEmpty !== false;
+function immutableField(field) {
 	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
-				});
+		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 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
-export { AggregationBuilder as A, methodRegistryPlugin as C, fieldFilterPlugin as D, timestampPlugin as E, HOOK_PRIORITY as O, 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, Repository as k, 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 };
+export { aggregateHelpersPlugin as A, HOOK_PRIORITY as C, AuditTrailQuery as D, batchOperationsPlugin as E, auditTrailPlugin as O, cachePlugin as S, AggregationBuilder as T, dateSequentialId as _, uniqueField as a, sequentialId as b, subdocumentPlugin as c, multiTenantPlugin as d, mongoOperationsPlugin as f, customIdPlugin as g, elasticSearchPlugin as h, requireField as i, auditLogPlugin as k, softDeletePlugin as l, fieldFilterPlugin as m, blockIf as n, validationChainPlugin as o, methodRegistryPlugin as p, immutableField as r, timestampPlugin as s, autoInject as t, observabilityPlugin as u, getNextSequence as v, Repository as w, cascadePlugin as x, prefixedId as y };