@classytic/mongokit 3.2.4 → 3.3.0

package/dist/{custom-id.plugin-m0VW6yYm.mjs → custom-id.plugin-FInXDsUX.mjs}

@@ -1,8 +1,1351 @@
 import { i as createError, n as debug, r as warn } from "./logger-D8ily-PP.mjs";
-import { i as upsert } from "./create-BuO6xt0v.mjs";
-import { a as modelPattern, i as listQueryKey, l as getFieldsForUser, n as byQueryKey, o as versionKey, t as byIdKey } from "./cache-keys-C8Z9B5sw.mjs";
+import { _ 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 mongoose from "mongoose";
 
+//#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 });
+		return this;
+	}
+	/**
+	* $group - Group documents and compute aggregations
+	*
+	* @example
+	* ```typescript
+	* .group({
+	*   _id: '$department',
+	*   count: { $sum: 1 },
+	*   avgSalary: { $avg: '$salary' }
+	* })
+	* ```
+	*/
+	group(groupSpec) {
+		this.pipeline.push({ $group: groupSpec });
+		return this;
+	}
+	/**
+	* $sort - Sort documents
+	*/
+	sort(sortSpec) {
+		if (typeof sortSpec === "string") {
+			const order = sortSpec.startsWith("-") ? -1 : 1;
+			const field = sortSpec.startsWith("-") ? sortSpec.substring(1) : sortSpec;
+			this.pipeline.push({ $sort: { [field]: order } });
+		} else this.pipeline.push({ $sort: normalizeSortSpec(sortSpec) });
+		return this;
+	}
+	/**
+	* $limit - Limit number of documents
+	*/
+	limit(count) {
+		this.pipeline.push({ $limit: count });
+		return this;
+	}
+	/**
+	* $skip - Skip documents
+	*/
+	skip(count) {
+		this.pipeline.push({ $skip: count });
+		return this;
+	}
+	/**
+	* $unwind - Deconstruct array field
+	*/
+	unwind(path, preserveNullAndEmptyArrays = false) {
+		this.pipeline.push({ $unwind: {
+			path: path.startsWith("$") ? path : `$${path}`,
+			preserveNullAndEmptyArrays
+		} });
+		return this;
+	}
+	/**
+	* $addFields - Add new fields or replace existing fields
+	*/
+	addFields(fields) {
+		this.pipeline.push({ $addFields: fields });
+		return this;
+	}
+	/**
+	* $set - Alias for $addFields
+	*/
+	set(fields) {
+		return this.addFields(fields);
+	}
+	/**
+	* $unset - Remove fields
+	*/
+	unset(fields) {
+		this.pipeline.push({ $unset: fields });
+		return this;
+	}
+	/**
+	* $replaceRoot - Replace the root document
+	*/
+	replaceRoot(newRoot) {
+		this.pipeline.push({ $replaceRoot: { newRoot: typeof newRoot === "string" ? `$${newRoot}` : newRoot } });
+		return this;
+	}
+	/**
+	* $lookup - Join with another collection (simple form)
+	*
+	* @param from - Collection to join with
+	* @param localField - Field from source collection
+	* @param foreignField - Field from target collection
+	* @param as - Output field name
+	* @param single - Unwrap array to single object
+	*
+	* @example
+	* ```typescript
+	* // Join employees with departments by slug
+	* .lookup('departments', 'deptSlug', 'slug', 'department', true)
+	* ```
+	*/
+	lookup(from, localField, foreignField, as, single) {
+		const stages = new LookupBuilder(from).localField(localField).foreignField(foreignField).as(as || from).single(single || false).build();
+		this.pipeline.push(...stages);
+		return this;
+	}
+	/**
+	* $lookup - Join with another collection (advanced form with pipeline)
+	*
+	* @example
+	* ```typescript
+	* .lookupWithPipeline({
+	*   from: 'products',
+	*   localField: 'productIds',
+	*   foreignField: 'sku',
+	*   as: 'products',
+	*   pipeline: [
+	*     { $match: { status: 'active' } },
+	*     { $project: { name: 1, price: 1 } }
+	*   ]
+	* })
+	* ```
+	*/
+	lookupWithPipeline(options) {
+		const builder = new LookupBuilder(options.from).localField(options.localField).foreignField(options.foreignField);
+		if (options.as) builder.as(options.as);
+		if (options.single) builder.single(options.single);
+		if (options.pipeline) builder.pipeline(options.pipeline);
+		if (options.let) builder.let(options.let);
+		this.pipeline.push(...builder.build());
+		return this;
+	}
+	/**
+	* Multiple lookups at once
+	*
+	* @example
+	* ```typescript
+	* .multiLookup([
+	*   { from: 'departments', localField: 'deptSlug', foreignField: 'slug', single: true },
+	*   { from: 'managers', localField: 'managerId', foreignField: '_id', single: true }
+	* ])
+	* ```
+	*/
+	multiLookup(lookups) {
+		const stages = LookupBuilder.multiple(lookups);
+		this.pipeline.push(...stages);
+		return this;
+	}
+	/**
+	* $facet - Process multiple aggregation pipelines in a single stage
+	* Useful for computing multiple aggregations in parallel
+	*
+	* @example
+	* ```typescript
+	* .facet({
+	*   totalCount: [{ $count: 'count' }],
+	*   avgPrice: [{ $group: { _id: null, avg: { $avg: '$price' } } }],
+	*   topProducts: [{ $sort: { sales: -1 } }, { $limit: 10 }]
+	* })
+	* ```
+	*/
+	facet(facets) {
+		this.pipeline.push({ $facet: facets });
+		return this;
+	}
+	/**
+	* $bucket - Categorize documents into buckets
+	*
+	* @example
+	* ```typescript
+	* .bucket({
+	*   groupBy: '$price',
+	*   boundaries: [0, 50, 100, 200],
+	*   default: 'Other',
+	*   output: {
+	*     count: { $sum: 1 },
+	*     products: { $push: '$name' }
+	*   }
+	* })
+	* ```
+	*/
+	bucket(options) {
+		this.pipeline.push({ $bucket: options });
+		return this;
+	}
+	/**
+	* $bucketAuto - Automatically determine bucket boundaries
+	*/
+	bucketAuto(options) {
+		this.pipeline.push({ $bucketAuto: options });
+		return this;
+	}
+	/**
+	* $setWindowFields - Perform window functions (MongoDB 5.0+)
+	* Useful for rankings, running totals, moving averages
+	*
+	* @example
+	* ```typescript
+	* .setWindowFields({
+	*   partitionBy: '$department',
+	*   sortBy: { salary: -1 },
+	*   output: {
+	*     rank: { $rank: {} },
+	*     runningTotal: { $sum: '$salary', window: { documents: ['unbounded', 'current'] } }
+	*   }
+	* })
+	* ```
+	*/
+	setWindowFields(options) {
+		const normalizedOptions = {
+			...options,
+			sortBy: options.sortBy ? normalizeSortSpec(options.sortBy) : void 0
+		};
+		this.pipeline.push({ $setWindowFields: normalizedOptions });
+		return this;
+	}
+	/**
+	* $unionWith - Combine results from multiple collections (MongoDB 4.4+)
+	*
+	* @example
+	* ```typescript
+	* .unionWith({
+	*   coll: 'archivedOrders',
+	*   pipeline: [{ $match: { year: 2024 } }]
+	* })
+	* ```
+	*/
+	unionWith(options) {
+		this.pipeline.push({ $unionWith: options });
+		return this;
+	}
+	/**
+	* $densify - Fill gaps in data (MongoDB 5.1+)
+	* Useful for time series data with missing points
+	*/
+	densify(options) {
+		this.pipeline.push({ $densify: options });
+		return this;
+	}
+	/**
+	* $fill - Fill null or missing field values (MongoDB 5.3+)
+	*/
+	fill(options) {
+		const normalizedOptions = {
+			...options,
+			sortBy: options.sortBy ? normalizeSortSpec(options.sortBy) : void 0
+		};
+		this.pipeline.push({ $fill: normalizedOptions });
+		return this;
+	}
+	/**
+	* Enable allowDiskUse for large aggregations that exceed 100MB memory limit
+	*
+	* @example
+	* ```typescript
+	* const results = await new AggregationBuilder()
+	*   .match({ status: 'active' })
+	*   .group({ _id: '$category', total: { $sum: '$amount' } })
+	*   .allowDiskUse()
+	*   .exec(Model);
+	* ```
+	*/
+	allowDiskUse(enable = true) {
+		this._diskUse = enable;
+		return this;
+	}
+	/**
+	* Paginate - Add skip and limit for offset-based pagination
+	*/
+	paginate(page, limit) {
+		const skip = (page - 1) * limit;
+		return this.skip(skip).limit(limit);
+	}
+	/**
+	* Count total documents (useful with $facet for pagination metadata)
+	*/
+	count(outputField = "count") {
+		this.pipeline.push({ $count: outputField });
+		return this;
+	}
+	/**
+	* Sample - Randomly select N documents
+	*/
+	sample(size) {
+		this.pipeline.push({ $sample: { size } });
+		return this;
+	}
+	/**
+	* Out - Write results to a collection
+	*/
+	out(collection) {
+		this.pipeline.push({ $out: collection });
+		return this;
+	}
+	/**
+	* Merge - Merge results into a collection
+	*/
+	merge(options) {
+		this.pipeline.push({ $merge: typeof options === "string" ? { into: options } : options });
+		return this;
+	}
+	/**
+	* GeoNear - Perform geospatial queries
+	*/
+	geoNear(options) {
+		this.pipeline.push({ $geoNear: options });
+		return this;
+	}
+	/**
+	* GraphLookup - Perform recursive search (graph traversal)
+	*/
+	graphLookup(options) {
+		this.pipeline.push({ $graphLookup: options });
+		return this;
+	}
+	/**
+	* $search - Atlas Search full-text search (Atlas only)
+	*
+	* @example
+	* ```typescript
+	* .search({
+	*   index: 'default',
+	*   text: {
+	*     query: 'laptop computer',
+	*     path: ['title', 'description'],
+	*     fuzzy: { maxEdits: 2 }
+	*   }
+	* })
+	* ```
+	*/
+	search(options) {
+		this.pipeline.push({ $search: options });
+		return this;
+	}
+	/**
+	* $searchMeta - Get Atlas Search metadata (Atlas only)
+	*/
+	searchMeta(options) {
+		this.pipeline.push({ $searchMeta: options });
+		return this;
+	}
+	/**
+	* $vectorSearch - Semantic similarity search using vector embeddings (Atlas only)
+	*
+	* Requires an Atlas Vector Search index on the target field.
+	* Must be the first stage in the pipeline.
+	*
+	* @example
+	* ```typescript
+	* const results = await new AggregationBuilder()
+	*   .vectorSearch({
+	*     index: 'vector_index',
+	*     path: 'embedding',
+	*     queryVector: await getEmbedding('running shoes'),
+	*     limit: 10,
+	*     numCandidates: 100,
+	*     filter: { category: 'footwear' }
+	*   })
+	*   .project({ embedding: 0, score: { $meta: 'vectorSearchScore' } })
+	*   .exec(ProductModel);
+	* ```
+	*/
+	vectorSearch(options) {
+		if (this.pipeline.length > 0) throw new Error("[mongokit] $vectorSearch must be the first stage in the pipeline");
+		const rawCandidates = options.numCandidates ?? Math.max(options.limit * 10, 100);
+		const numCandidates = Math.min(Math.max(rawCandidates, options.limit), 1e4);
+		this.pipeline.push({ $vectorSearch: {
+			index: options.index,
+			path: options.path,
+			queryVector: options.queryVector,
+			numCandidates,
+			limit: options.limit,
+			...options.filter && { filter: options.filter },
+			...options.exact && { exact: options.exact }
+		} });
+		return this;
+	}
+	/**
+	* Add vectorSearchScore as a field after $vectorSearch
+	* Convenience for `.addFields({ score: { $meta: 'vectorSearchScore' } })`
+	*/
+	withVectorScore(fieldName = "score") {
+		return this.addFields({ [fieldName]: { $meta: "vectorSearchScore" } });
+	}
+	/**
+	* Create a builder from an existing pipeline
+	*/
+	static from(pipeline) {
+		const builder = new AggregationBuilder();
+		builder.pipeline = [...pipeline];
+		return builder;
+	}
+	/**
+	* Create a builder with initial match stage
+	*/
+	static startWith(query) {
+		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.
+*/
+const HOOK_PRIORITY = {
+	POLICY: 100,
+	CACHE: 200,
+	OBSERVABILITY: 300,
+	DEFAULT: 500
+};
+/**
+* Production-grade repository for MongoDB
+* Event-driven, plugin-based, with smart pagination
+*/
+var Repository = class {
+	Model;
+	model;
+	_hooks;
+	_pagination;
+	_hookMode;
+	_hasTextIndex = null;
+	constructor(Model, plugins = [], paginationConfig = {}, options = {}) {
+		this.Model = Model;
+		this.model = Model.modelName;
+		this._hooks = /* @__PURE__ */ new Map();
+		this._pagination = new PaginationEngine(Model, paginationConfig);
+		this._hookMode = options.hooks ?? "async";
+		plugins.forEach((plugin) => this.use(plugin));
+	}
+	/**
+	* Register a plugin
+	*/
+	use(plugin) {
+		if (typeof plugin === "function") plugin(this);
+		else if (plugin && typeof plugin.apply === "function") plugin.apply(this);
+		return this;
+	}
+	/**
+	* Register event listener with optional priority for phase ordering.
+	*
+	* @param event - Event name (e.g. 'before:getAll')
+	* @param listener - Hook function
+	* @param options - Optional { priority } — use HOOK_PRIORITY constants.
+	*                  Lower priority numbers run first.
+	*                  Default: HOOK_PRIORITY.DEFAULT (500)
+	*/
+	on(event, listener, options) {
+		if (!this._hooks.has(event)) this._hooks.set(event, []);
+		const hooks = this._hooks.get(event);
+		const priority = options?.priority ?? HOOK_PRIORITY.DEFAULT;
+		hooks.push({
+			listener,
+			priority
+		});
+		hooks.sort((a, b) => a.priority - b.priority);
+		return this;
+	}
+	/**
+	* Remove a specific event listener
+	*/
+	off(event, listener) {
+		const hooks = this._hooks.get(event);
+		if (hooks) {
+			const idx = hooks.findIndex((h) => h.listener === listener);
+			if (idx !== -1) hooks.splice(idx, 1);
+		}
+		return this;
+	}
+	/**
+	* Remove all listeners for an event, or all listeners entirely
+	*/
+	removeAllListeners(event) {
+		if (event) this._hooks.delete(event);
+		else this._hooks.clear();
+		return this;
+	}
+	/**
+	* Emit event (sync - for backwards compatibility)
+	*/
+	emit(event, data) {
+		const hooks = this._hooks.get(event) || [];
+		for (const { listener } of hooks) try {
+			const result = listener(data);
+			if (result && typeof result.then === "function") result.catch((error) => {
+				if (event === "error:hook") return;
+				const err = error instanceof Error ? error : new Error(String(error));
+				this.emit("error:hook", {
+					event,
+					error: err
+				});
+			});
+		} catch (error) {
+			if (event === "error:hook") continue;
+			const err = error instanceof Error ? error : new Error(String(error));
+			this.emit("error:hook", {
+				event,
+				error: err
+			});
+		}
+	}
+	/**
+	* Emit event and await all async handlers (sorted by priority)
+	*/
+	async emitAsync(event, data) {
+		const hooks = this._hooks.get(event) || [];
+		for (const { listener } of hooks) await listener(data);
+	}
+	async _emitHook(event, data) {
+		if (this._hookMode === "async") {
+			await this.emitAsync(event, data);
+			return;
+		}
+		this.emit(event, data);
+	}
+	async _emitErrorHook(event, data) {
+		try {
+			await this._emitHook(event, data);
+		} catch (hookError) {
+			warn(`[${this.model}] Error hook '${event}' threw: ${hookError instanceof Error ? hookError.message : String(hookError)}`);
+		}
+	}
+	/**
+	* Create single document
+	*/
+	async create(data, options = {}) {
+		const context = await this._buildContext("create", {
+			data,
+			...options
+		});
+		try {
+			const result = await create(this.Model, context.data || data, options);
+			await this._emitHook("after:create", {
+				context,
+				result
+			});
+			return result;
+		} catch (error) {
+			await this._emitErrorHook("error:create", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
+	* Create multiple documents
+	*/
+	async createMany(dataArray, options = {}) {
+		const context = await this._buildContext("createMany", {
+			dataArray,
+			...options
+		});
+		try {
+			const result = await createMany(this.Model, context.dataArray || dataArray, options);
+			await this._emitHook("after:createMany", {
+				context,
+				result
+			});
+			return result;
+		} catch (error) {
+			await this._emitErrorHook("error:createMany", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
+	* Get document by ID
+	*/
+	async getById(id, options = {}) {
+		const populateSpec = options.populateOptions || options.populate;
+		const context = await this._buildContext("getById", {
+			id,
+			...options,
+			populate: populateSpec
+		});
+		if (context._cacheHit) {
+			const cachedResult = context._cachedResult;
+			await this._emitHook("after:getById", {
+				context,
+				result: cachedResult,
+				fromCache: true
+			});
+			return cachedResult;
+		}
+		try {
+			const result = await getById(this.Model, id, context);
+			await this._emitHook("after:getById", {
+				context,
+				result
+			});
+			return result;
+		} catch (error) {
+			await this._emitErrorHook("error:getById", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
+	* Get single document by query
+	*/
+	async getByQuery(query, options = {}) {
+		const populateSpec = options.populateOptions || options.populate;
+		const context = await this._buildContext("getByQuery", {
+			query,
+			...options,
+			populate: populateSpec
+		});
+		if (context._cacheHit) {
+			const cachedResult = context._cachedResult;
+			await this._emitHook("after:getByQuery", {
+				context,
+				result: cachedResult,
+				fromCache: true
+			});
+			return cachedResult;
+		}
+		const finalQuery = context.query || query;
+		try {
+			const result = await getByQuery(this.Model, finalQuery, context);
+			await this._emitHook("after:getByQuery", {
+				context,
+				result
+			});
+			return result;
+		} catch (error) {
+			await this._emitErrorHook("error:getByQuery", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
+	* Unified pagination - auto-detects offset vs keyset based on params
+	*
+	* Auto-detection logic:
+	* - If params has 'cursor' or 'after' → uses keyset pagination (stream)
+	* - If params has 'pagination' or 'page' → uses offset pagination (paginate)
+	* - Else → defaults to offset pagination with page=1
+	*
+	* @example
+	* // Offset pagination (page-based)
+	* await repo.getAll({ page: 1, limit: 50, filters: { status: 'active' } });
+	* await repo.getAll({ pagination: { page: 2, limit: 20 } });
+	*
+	* // Keyset pagination (cursor-based)
+	* await repo.getAll({ cursor: 'eyJ2Ij...', limit: 50 });
+	* await repo.getAll({ after: 'eyJ2Ij...', sort: { createdAt: -1 } });
+	*
+	* // Simple query (defaults to page 1)
+	* await repo.getAll({ filters: { status: 'active' } });
+	*
+	* // Skip cache for fresh data
+	* await repo.getAll({ filters: { status: 'active' } }, { skipCache: true });
+	*/
+	async getAll(params = {}, options = {}) {
+		const normalizedParams = {
+			...params,
+			page: params.page ?? params.pagination?.page,
+			limit: params.limit ?? params.pagination?.limit
+		};
+		const context = await this._buildContext("getAll", {
+			...normalizedParams,
+			...options
+		});
+		if (context._cacheHit) {
+			const cachedResult = context._cachedResult;
+			await this._emitHook("after:getAll", {
+				context,
+				result: cachedResult,
+				fromCache: true
+			});
+			return cachedResult;
+		}
+		const filters = context.filters ?? params.filters ?? {};
+		const search = context.search ?? params.search;
+		const sort = context.sort ?? params.sort ?? "-createdAt";
+		const limit = context.limit ?? params.limit ?? params.pagination?.limit ?? this._pagination.config.defaultLimit;
+		const page = context.page ?? params.pagination?.page ?? params.page;
+		const after = context.after ?? params.cursor ?? params.after;
+		const mode = context.mode ?? params.mode;
+		let useKeyset = false;
+		if (mode) useKeyset = mode === "keyset";
+		else useKeyset = !page && !!(after || sort !== "-createdAt" && (context.sort ?? params.sort));
+		let 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 };
+			else throw createError(400, `No text index found for ${this.model}. Cannot perform text search.`);
+		}
+		const populateSpec = options.populateOptions || params.populateOptions || context.populate || options.populate;
+		const paginationOptions = {
+			filters: query,
+			sort: this._parseSort(sort),
+			limit,
+			populate: this._parsePopulate(populateSpec),
+			select: context.select || options.select,
+			lean: context.lean ?? options.lean ?? true,
+			session: options.session,
+			hint: context.hint ?? params.hint,
+			maxTimeMS: context.maxTimeMS ?? params.maxTimeMS,
+			readPreference: context.readPreference ?? options.readPreference ?? params.readPreference
+		};
+		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 = {}) {
+		const context = await this._buildContext("getOrCreate", {
+			query,
+			data: createData,
+			...options
+		});
+		try {
+			const finalQuery = context.query || query;
+			const finalData = context.data || createData;
+			const result = await getOrCreate(this.Model, finalQuery, finalData, options);
+			await this._emitHook("after:getOrCreate", {
+				context,
+				result
+			});
+			return result;
+		} catch (error) {
+			await this._emitErrorHook("error:getOrCreate", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
+	* Count documents
+	* Routes through hook system for policy enforcement (multi-tenant, soft-delete)
+	*/
+	async count(query = {}, options = {}) {
+		const context = await this._buildContext("count", {
+			query,
+			...options
+		});
+		try {
+			const finalQuery = context.query || query;
+			const result = await count(this.Model, finalQuery, options);
+			await this._emitHook("after:count", {
+				context,
+				result
+			});
+			return result;
+		} catch (error) {
+			await this._emitErrorHook("error:count", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
+	* Check if document exists
+	* Routes through hook system for policy enforcement (multi-tenant, soft-delete)
+	*/
+	async exists(query, options = {}) {
+		const context = await this._buildContext("exists", {
+			query,
+			...options
+		});
+		try {
+			const finalQuery = context.query || query;
+			const result = await exists(this.Model, finalQuery, options);
+			await this._emitHook("after:exists", {
+				context,
+				result
+			});
+			return result;
+		} catch (error) {
+			await this._emitErrorHook("error:exists", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
+	* Update document by ID
+	*/
+	async update(id, data, options = {}) {
+		const context = await this._buildContext("update", {
+			id,
+			data,
+			...options
+		});
+		try {
+			const result = await update(this.Model, id, context.data || data, context);
+			await this._emitHook("after:update", {
+				context,
+				result
+			});
+			return result;
+		} catch (error) {
+			await this._emitErrorHook("error:update", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
+	* Delete document by ID
+	*/
+	async delete(id, options = {}) {
+		const context = await this._buildContext("delete", {
+			id,
+			...options
+		});
+		try {
+			if (context.softDeleted) {
+				const result = {
+					success: true,
+					message: "Soft deleted successfully",
+					id: String(id),
+					soft: true
+				};
+				await this._emitHook("after:delete", {
+					context,
+					result
+				});
+				return result;
+			}
+			const result = await deleteById(this.Model, id, {
+				session: options.session,
+				query: context.query
+			});
+			await this._emitHook("after:delete", {
+				context,
+				result
+			});
+			return result;
+		} catch (error) {
+			await this._emitErrorHook("error:delete", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
+	* Execute aggregation pipeline
+	* Routes through hook system for policy enforcement (multi-tenant, soft-delete)
+	*
+	* @param pipeline - Aggregation pipeline stages
+	* @param options - Aggregation options including governance controls
+	*/
+	async aggregate(pipeline, options = {}) {
+		const context = await this._buildContext("aggregate", {
+			pipeline,
+			...options
+		});
+		const maxStages = options.maxPipelineStages;
+		if (maxStages && pipeline.length > maxStages) throw createError(400, `Aggregation pipeline exceeds maximum allowed stages (${pipeline.length} > ${maxStages})`);
+		try {
+			const finalPipeline = [...pipeline];
+			if (context.query && Object.keys(context.query).length > 0) finalPipeline.unshift({ $match: context.query });
+			const aggregation = this.Model.aggregate(finalPipeline);
+			if (options.session) aggregation.session(options.session);
+			if (options.allowDiskUse) aggregation.allowDiskUse(true);
+			if (options.readPreference) aggregation.read(options.readPreference);
+			if (options.maxTimeMS) aggregation.option({ maxTimeMS: options.maxTimeMS });
+			if (options.comment) aggregation.option({ comment: options.comment });
+			if (options.readConcern) aggregation.option({ readConcern: options.readConcern });
+			if (options.collation) aggregation.collation(options.collation);
+			const result = await aggregation.exec();
+			await this._emitHook("after:aggregate", {
+				context,
+				result
+			});
+			return result;
+		} catch (error) {
+			await this._emitErrorHook("error:aggregate", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
+	* Aggregate pipeline with pagination
+	* Best for: Complex queries, grouping, joins
+	*
+	* Policy hooks (multi-tenant, soft-delete) inject context.filters which are
+	* prepended as a $match stage to the pipeline, ensuring tenant isolation.
+	*/
+	async aggregatePaginate(options = {}) {
+		const context = await this._buildContext("aggregatePaginate", options);
+		const finalPipeline = [...context.pipeline || options.pipeline || []];
+		if (context.filters && Object.keys(context.filters).length > 0) finalPipeline.unshift({ $match: context.filters });
+		const aggOptions = {
+			...context,
+			pipeline: finalPipeline
+		};
+		try {
+			const result = await this._pagination.aggregatePaginate(aggOptions);
+			await this._emitHook("after:aggregatePaginate", {
+				context,
+				result
+			});
+			return result;
+		} catch (error) {
+			await this._emitErrorHook("error:aggregatePaginate", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
+	* Get distinct values
+	* Routes through hook system for policy enforcement (multi-tenant, soft-delete)
+	*/
+	async distinct(field, query = {}, options = {}) {
+		const context = await this._buildContext("distinct", {
+			query,
+			...options
+		});
+		try {
+			const finalQuery = context.query || query;
+			const readPreference = context.readPreference ?? options.readPreference;
+			const result = await distinct(this.Model, field, finalQuery, {
+				session: options.session,
+				readPreference
+			});
+			await this._emitHook("after:distinct", {
+				context,
+				result
+			});
+			return result;
+		} catch (error) {
+			await this._emitErrorHook("error:distinct", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
+	* Query with custom field lookups ($lookup)
+	* Best for: Joins on slugs, SKUs, codes, or other indexed custom fields
+	*
+	* @example
+	* ```typescript
+	* // Join employees with departments using slug instead of ObjectId
+	* const employees = await employeeRepo.lookupPopulate({
+	*   filters: { status: 'active' },
+	*   lookups: [
+	*     {
+	*       from: 'departments',
+	*       localField: 'departmentSlug',
+	*       foreignField: 'slug',
+	*       as: 'department',
+	*       single: true
+	*     }
+	*   ],
+	*   sort: '-createdAt',
+	*   page: 1,
+	*   limit: 50
+	* });
+	* ```
+	*/
+	async lookupPopulate(options) {
+		const context = await this._buildContext("lookupPopulate", options);
+		try {
+			const builder = new AggregationBuilder();
+			const filters = context.filters ?? options.filters;
+			if (filters && Object.keys(filters).length > 0) builder.match(filters);
+			builder.multiLookup(options.lookups);
+			const sort = context.sort ?? options.sort;
+			if (sort) builder.sort(this._parseSort(sort));
+			const page = context.page ?? options.page ?? 1;
+			const limit = context.limit ?? options.limit ?? this._pagination.config.defaultLimit ?? 20;
+			const skip = (page - 1) * limit;
+			const SAFE_LIMIT = 1e3;
+			const SAFE_MAX_OFFSET = 1e4;
+			if (limit > SAFE_LIMIT) warn(`[mongokit] Large limit (${limit}) in lookupPopulate. $facet results must be <16MB. Consider using smaller limits or stream-based pagination for large datasets.`);
+			if (skip > SAFE_MAX_OFFSET) warn(`[mongokit] Large offset (${skip}) in lookupPopulate. $facet with high offsets can exceed 16MB. For deep pagination, consider using keyset/cursor-based pagination instead.`);
+			const dataStages = [{ $skip: skip }, { $limit: limit }];
+			const selectSpec = context.select ?? options.select;
+			if (selectSpec) {
+				let projection;
+				if (typeof selectSpec === "string") {
+					projection = {};
+					const fields = selectSpec.split(",").map((f) => f.trim());
+					for (const field of fields) if (field.startsWith("-")) projection[field.substring(1)] = 0;
+					else projection[field] = 1;
+				} else if (Array.isArray(selectSpec)) {
+					projection = {};
+					for (const field of selectSpec) if (field.startsWith("-")) projection[field.substring(1)] = 0;
+					else projection[field] = 1;
+				} else projection = selectSpec;
+				dataStages.push({ $project: projection });
+			}
+			builder.facet({
+				metadata: [{ $count: "total" }],
+				data: dataStages
+			});
+			const pipeline = builder.build();
+			const aggregation = this.Model.aggregate(pipeline).session(options.session || null);
+			const readPref = context.readPreference ?? options.readPreference;
+			if (readPref) aggregation.read(readPref);
+			const result = (await aggregation)[0] || {
+				metadata: [],
+				data: []
+			};
+			const total = result.metadata[0]?.total || 0;
+			const data = result.data || [];
+			await this._emitHook("after:lookupPopulate", {
+				context,
+				result: data
+			});
+			return {
+				data,
+				total,
+				page,
+				limit
+			};
+		} catch (error) {
+			await this._emitErrorHook("error:lookupPopulate", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
+	* Create an aggregation builder for this model
+	* Useful for building complex custom aggregations
+	*
+	* @example
+	* ```typescript
+	* const pipeline = repo.buildAggregation()
+	*   .match({ status: 'active' })
+	*   .lookup('departments', 'deptSlug', 'slug', 'department', true)
+	*   .group({ _id: '$department', count: { $sum: 1 } })
+	*   .sort({ count: -1 })
+	*   .build();
+	*
+	* const results = await repo.Model.aggregate(pipeline);
+	* ```
+	*/
+	buildAggregation() {
+		return new AggregationBuilder();
+	}
+	/**
+	* Create a lookup builder
+	* Useful for building $lookup stages independently
+	*
+	* @example
+	* ```typescript
+	* const lookupStages = repo.buildLookup('departments')
+	*   .localField('deptSlug')
+	*   .foreignField('slug')
+	*   .as('department')
+	*   .single()
+	*   .build();
+	*
+	* const pipeline = [
+	*   { $match: { status: 'active' } },
+	*   ...lookupStages
+	* ];
+	* ```
+	*/
+	buildLookup(from) {
+		return new LookupBuilder(from);
+	}
+	/**
+	* Execute callback within a transaction with automatic retry on transient failures.
+	*
+	* Uses the MongoDB driver's `session.withTransaction()` which automatically retries
+	* on `TransientTransactionError` and `UnknownTransactionCommitResult`.
+	*
+	* The callback always receives a `ClientSession`. When `allowFallback` is true
+	* and the MongoDB deployment doesn't support transactions (e.g., standalone),
+	* the callback runs without a transaction on the same session.
+	*
+	* @param callback - Receives a `ClientSession` to pass to repository operations
+	* @param options.allowFallback - Run without transaction on standalone MongoDB (default: false)
+	* @param options.onFallback - Called when falling back to non-transactional execution
+	* @param options.transactionOptions - MongoDB driver transaction options (readConcern, writeConcern, etc.)
+	*
+	* @example
+	* ```typescript
+	* const result = await repo.withTransaction(async (session) => {
+	*   const order = await repo.create({ total: 100 }, { session });
+	*   await paymentRepo.create({ orderId: order._id }, { session });
+	*   return order;
+	* });
+	*
+	* // With fallback for standalone/dev environments
+	* await repo.withTransaction(callback, {
+	*   allowFallback: true,
+	*   onFallback: (err) => logger.warn('Running without transaction', err),
+	* });
+	* ```
+	*/
+	async withTransaction(callback, options = {}) {
+		const session = await this.Model.db.startSession();
+		try {
+			return await session.withTransaction(() => callback(session), options.transactionOptions);
+		} catch (error) {
+			const err = error;
+			if (options.allowFallback && this._isTransactionUnsupported(err)) {
+				options.onFallback?.(err);
+				return await callback(session);
+			}
+			throw err;
+		} finally {
+			await session.endSession();
+		}
+	}
+	_isTransactionUnsupported(error) {
+		const code = error.code;
+		if (code === 263 || code === 20) return true;
+		const message = (error.message || "").toLowerCase();
+		return message.includes("transaction numbers are only allowed on a replica set member") || message.includes("transaction is not supported");
+	}
+	/**
+	* Execute custom query with event emission
+	*/
+	async _executeQuery(buildQuery) {
+		const operation = buildQuery.name || "custom";
+		const context = await this._buildContext(operation, {});
+		try {
+			const result = await buildQuery(this.Model);
+			await this._emitHook(`after:${operation}`, {
+				context,
+				result
+			});
+			return result;
+		} catch (error) {
+			await this._emitErrorHook(`error:${operation}`, {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
+	* Build operation context and run before hooks (sorted by priority).
+	*
+	* Hook execution order is deterministic:
+	* 1. POLICY (100) — tenant isolation, soft-delete filtering, validation
+	* 2. CACHE  (200) — cache lookup (after policy filters are injected)
+	* 3. OBSERVABILITY (300) — audit logging, metrics
+	* 4. DEFAULT (500) — user-registered hooks
+	*/
+	async _buildContext(operation, options) {
+		const context = {
+			operation,
+			model: this.model,
+			...options
+		};
+		const event = `before:${operation}`;
+		const hooks = this._hooks.get(event) || [];
+		for (const { listener } of hooks) await listener(context);
+		return context;
+	}
+	/**
+	* Parse sort string or object
+	*/
+	_parseSort(sort) {
+		if (!sort) return { createdAt: -1 };
+		if (typeof sort === "object") {
+			if (Object.keys(sort).length === 0) return { createdAt: -1 };
+			return sort;
+		}
+		const sortObj = {};
+		const fields = sort.split(",").map((s) => s.trim());
+		for (const field of fields) if (field.startsWith("-")) sortObj[field.substring(1)] = -1;
+		else sortObj[field] = 1;
+		return sortObj;
+	}
+	/**
+	* Parse populate specification
+	*/
+	_parsePopulate(populate) {
+		if (!populate) return [];
+		if (typeof populate === "string") return populate.split(",").map((p) => p.trim());
+		if (Array.isArray(populate)) return populate.map((p) => typeof p === "string" ? p.trim() : p);
+		return [populate];
+	}
+	/**
+	* Handle errors with proper HTTP status codes
+	*/
+	_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}`);
+		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
@@ -202,24 +1545,34 @@ function softDeletePlugin(options = {}) {
 					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 {}
+			} 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.message.includes("already exists")) warn(`[softDeletePlugin] Failed to create TTL index: ${err.message}`);
+					if (err.code !== 85 && err.code !== 86 && !err.message.includes("already exists")) warn(`[softDeletePlugin] Failed to create TTL index: ${err.message}`);
 				});
 			}
 			repo.on("before:delete", async (context) => {
 				if (options.soft !== false) {
 					const updateData = { [deletedField]: /* @__PURE__ */ new Date() };
 					if (context.user) updateData[deletedByField] = context.user._id || context.user.id;
-					await repo.Model.findByIdAndUpdate(context.id, updateData, { session: context.session });
+					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;
 				}
-			});
+			}, { priority: HOOK_PRIORITY.POLICY });
 			repo.on("before:getAll", (context) => {
 				if (options.soft !== false) {
 					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
@@ -228,7 +1581,7 @@ function softDeletePlugin(options = {}) {
 						...deleteFilter
 					};
 				}
-			});
+			}, { priority: HOOK_PRIORITY.POLICY });
 			repo.on("before:getById", (context) => {
 				if (options.soft !== false) {
 					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
@@ -237,7 +1590,7 @@ function softDeletePlugin(options = {}) {
 						...deleteFilter
 					};
 				}
-			});
+			}, { priority: HOOK_PRIORITY.POLICY });
 			repo.on("before:getByQuery", (context) => {
 				if (options.soft !== false) {
 					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
@@ -246,14 +1599,76 @@ function softDeletePlugin(options = {}) {
 						...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: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 result = await this.Model.findByIdAndUpdate(id, { $set: updateData }, {
+					const restoreQuery = {
+						_id: id,
+						...context.query || {}
+					};
+					const result = await this.Model.findOneAndUpdate(restoreQuery, { $set: updateData }, {
 						returnDocument: "after",
 						session: restoreOptions.session
 					});
@@ -264,7 +1679,8 @@ function softDeletePlugin(options = {}) {
 					}
 					await this.emitAsync("after:restore", {
 						id,
-						result
+						result,
+						context
 					});
 					return result;
 				};
@@ -273,10 +1689,16 @@ function softDeletePlugin(options = {}) {
 			}
 			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
+						...deletedFilter,
+						...context.filters || {},
+						...context.query || {}
 					};
 					const page = params.page || 1;
 					const limit = params.limit || 20;
@@ -491,10 +1913,17 @@ function uniqueField(field, errorMessage) {
 		name: `unique-${field}`,
 		operations: ["create", "update"],
 		validate: async (context, repo) => {
-			if (!context.data || !context.data[field] || !repo) return;
+			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") return;
+			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,
@@ -647,6 +2076,59 @@ function mongoOperationsPlugin() {
 			repo.registerMethod("setMax", async function(id, field, value, options = {}) {
 				return applyOperator.call(this, id, field, value, "$max", options);
 			});
+			/**
+			* 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);
+			});
 		}
 	};
 }
@@ -677,12 +2159,13 @@ function batchOperationsPlugin() {
 				const context = await this._buildContext.call(this, "updateMany", {
 					query,
 					data,
-					options
+					...options
 				});
 				try {
-					await this.emitAsync("before:updateMany", context);
+					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(query, data, {
+					const result = await this.Model.updateMany(finalQuery, data, {
 						runValidators: true,
 						session: options.session,
 						...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
@@ -701,16 +2184,66 @@ function batchOperationsPlugin() {
 				}
 			});
 			/**
+			* 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
+					...options
 				});
 				try {
-					await this.emitAsync("before:deleteMany", context);
-					const result = await this.Model.deleteMany(query, { session: options.session }).exec();
+					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
@@ -886,7 +2419,8 @@ function cachePlugin(options) {
 		hits: 0,
 		misses: 0,
 		sets: 0,
-		invalidations: 0
+		invalidations: 0,
+		errors: 0
 	};
 	const log = (msg, data) => {
 		if (config.debug) debug(`[mongokit:cache] ${msg}`, data ?? "");
@@ -895,10 +2429,20 @@ function cachePlugin(options) {
 		name: "cache",
 		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 {
+				} catch (e) {
+					log(`Cache error in getVersion for ${model}:`, e);
 					return 0;
 				}
 			}
@@ -917,20 +2461,28 @@ function cachePlugin(options) {
 				}
 			}
 			/**
-			* Invalidate a specific document by ID
+			* 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) {
-				const key = byIdKey(config.prefix, model, id);
 				try {
-					await config.adapter.del(key);
+					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:`, key);
+					log(`Invalidated byId cache for:`, id);
 				} catch (e) {
 					log(`Failed to invalidate byId cache:`, e);
 				}
 			}
 			/**
 			* 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) {
@@ -938,7 +2490,11 @@ function cachePlugin(options) {
 					return;
 				}
 				const id = String(context.id);
-				const key = byIdKey(config.prefix, model, 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) {
@@ -952,19 +2508,21 @@ function cachePlugin(options) {
 					}
 				} catch (e) {
 					log(`Cache error for getById:`, e);
-					stats.misses++;
+					stats.errors++;
 				}
-			});
+			}, { 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;
 				}
+				const collectionVersion = await getVersion();
 				const query = context.query || {};
-				const key = byQueryKey(config.prefix, model, query, {
+				const key = byQueryKey(config.prefix, model, collectionVersion, query, {
 					select: context.select,
 					populate: context.populate
 				});
@@ -981,11 +2539,12 @@ function cachePlugin(options) {
 					}
 				} catch (e) {
 					log(`Cache error for getByQuery:`, e);
-					stats.misses++;
+					stats.errors++;
 				}
-			});
+			}, { 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) {
@@ -1006,7 +2565,13 @@ function cachePlugin(options) {
 					after: context.after,
 					select: context.select,
 					populate: context.populate,
-					search: context.search
+					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 {
@@ -1022,9 +2587,9 @@ function cachePlugin(options) {
 					}
 				} catch (e) {
 					log(`Cache error for getAll:`, e);
-					stats.misses++;
+					stats.errors++;
 				}
-			});
+			}, { priority: HOOK_PRIORITY.CACHE });
 			/**
 			* after:getById - Cache the result
 			*/
@@ -1034,10 +2599,15 @@ function cachePlugin(options) {
 				if (context.skipCache) return;
 				if (result === null) return;
 				const id = String(context.id);
-				const key = byIdKey(config.prefix, model, 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) {
@@ -1052,8 +2622,9 @@ function cachePlugin(options) {
 				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, query, {
+				const key = byQueryKey(config.prefix, model, collectionVersion, query, {
 					select: context.select,
 					populate: context.populate
 				});
@@ -1084,7 +2655,13 @@ function cachePlugin(options) {
 					after: context.after,
 					select: context.select,
 					populate: context.populate,
-					search: context.search
+					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;
@@ -1137,6 +2714,12 @@ function cachePlugin(options) {
 				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
 			*
@@ -1194,6 +2777,7 @@ function cachePlugin(options) {
 				stats.misses = 0;
 				stats.sets = 0;
 				stats.invalidations = 0;
+				stats.errors = 0;
 			};
 		}
 	};
@@ -1300,22 +2884,12 @@ function cascadePlugin(options) {
 					}
 				} else for (const relation of relations) await cascadeDelete(relation);
 			});
-			repo.on("after:deleteMany", async (payload) => {
-				const { context, result } = payload;
-				const query = context.query;
-				if (!query || Object.keys(query).length === 0) {
-					logger?.warn?.("Cascade deleteMany skipped: empty query", { model: context.model });
-					return;
-				}
-				logger?.warn?.("Cascade deleteMany: use before:deleteMany hook for complete cascade support", { model: context.model });
-			});
 			repo.on("before:deleteMany", async (context) => {
 				const query = context.query;
 				if (!query || Object.keys(query).length === 0) return;
 				context._cascadeIds = (await repo.Model.find(query, { _id: 1 }).lean().session(context.session ?? null)).map((doc) => doc._id);
 			});
-			const originalAfterDeleteMany = repo._hooks.get("after:deleteMany") || [];
-			repo._hooks.set("after:deleteMany", [...originalAfterDeleteMany, async (payload) => {
+			repo.on("after:deleteMany", async (payload) => {
 				const { context } = payload;
 				const ids = context._cascadeIds;
 				if (!ids || ids.length === 0) return;
@@ -1369,29 +2943,90 @@ function cascadePlugin(options) {
 						throw err;
 					}
 				} else for (const relation of relations) await cascadeDeleteMany(relation);
-			}]);
+			});
 		}
 	};
 }
 
 //#endregion
 //#region src/plugins/multi-tenant.plugin.ts
+/**
+* Multi-Tenant Plugin
+*
+* Automatically injects tenant isolation filters into all queries.
+* Ensures data isolation by adding organizationId (or custom tenant field)
+* to every read and write operation.
+*
+* Uses HOOK_PRIORITY.POLICY (100) to ensure tenant filters are injected
+* BEFORE cache keys are computed (HOOK_PRIORITY.CACHE = 200).
+*
+* @example
+* ```typescript
+* // Basic — scopes every operation by organizationId from context
+* const repo = new Repository(Invoice, [
+*   multiTenantPlugin({ tenantField: 'organizationId' }),
+* ]);
+*
+* const invoices = await repo.getAll(
+*   { filters: { status: 'paid' } },
+*   { organizationId: 'org_123' }
+* );
+* // Actual query: { status: 'paid', organizationId: 'org_123' }
+*
+* // Super admin bypass — skip scoping based on context
+* const repo = new Repository(Invoice, [
+*   multiTenantPlugin({
+*     tenantField: 'organizationId',
+*     skipWhen: (context) => context.role === 'superadmin',
+*   }),
+* ]);
+*
+* // Admin sees all orgs
+* await repo.getAll({ page: 1, limit: 10 }, { role: 'superadmin' });
+*
+* // Automatic context — resolve tenant from AsyncLocalStorage
+* const repo = new Repository(Invoice, [
+*   multiTenantPlugin({
+*     tenantField: 'organizationId',
+*     resolveContext: () => asyncLocalStorage.getStore()?.tenantId,
+*   }),
+* ]);
+* ```
+*/
 function multiTenantPlugin(options = {}) {
 	const { tenantField = "organizationId", contextKey = "organizationId", required = true, skipOperations = [], skipWhen, resolveContext } = options;
-	const readOps = [
-		"getById",
-		"getByQuery",
+	const filterOps = [
 		"getAll",
 		"aggregatePaginate",
 		"lookupPopulate"
 	];
-	const writeOps = [
-		"create",
-		"createMany",
+	const queryReadOps = [
+		"getById",
+		"getByQuery",
+		"count",
+		"exists",
+		"getOrCreate",
+		"distinct",
+		"aggregate"
+	];
+	const constrainedWriteOps = [
 		"update",
-		"delete"
+		"delete",
+		"restore"
+	];
+	const filterReadOps = ["getDeleted"];
+	const createOps = ["create", "createMany"];
+	const batchQueryOps = ["updateMany", "deleteMany"];
+	const bulkOps = ["bulkWrite"];
+	const allOps = [
+		...filterOps,
+		...filterReadOps,
+		...queryReadOps,
+		...constrainedWriteOps,
+		...createOps,
+		...batchQueryOps,
+		...bulkOps
 	];
-	const allOps = [...readOps, ...writeOps];
 	return {
 		name: "multi-tenant",
 		apply(repo) {
@@ -1406,21 +3041,47 @@ function multiTenantPlugin(options = {}) {
 					}
 					if (!tenantId && required) throw new Error(`[mongokit] Multi-tenant: Missing '${contextKey}' in context for '${op}'. Pass it via options or set required: false.`);
 					if (!tenantId) return;
-					if (readOps.includes(op)) if (op === "getAll" || op === "aggregatePaginate" || op === "lookupPopulate") context.filters = {
+					if (filterOps.includes(op) || filterReadOps.includes(op)) context.filters = {
 						...context.filters,
 						[tenantField]: tenantId
 					};
-					else context.query = {
+					if (queryReadOps.includes(op)) context.query = {
 						...context.query,
 						[tenantField]: tenantId
 					};
 					if (op === "create" && context.data) context.data[tenantField] = tenantId;
-					if (op === "createMany" && context.dataArray) for (const doc of context.dataArray) doc[tenantField] = tenantId;
-					if (op === "update" || op === "delete") context.query = {
+					if (op === "createMany" && context.dataArray) {
+						for (const doc of context.dataArray) if (doc && typeof doc === "object") doc[tenantField] = tenantId;
+					}
+					if (constrainedWriteOps.includes(op)) context.query = {
 						...context.query,
 						[tenantField]: tenantId
 					};
-				});
+					if (batchQueryOps.includes(op)) context.query = {
+						...context.query,
+						[tenantField]: tenantId
+					};
+					if (op === "bulkWrite" && context.operations) {
+						const ops = context.operations;
+						for (const subOp of ops) {
+							for (const key of [
+								"updateOne",
+								"updateMany",
+								"deleteOne",
+								"deleteMany",
+								"replaceOne"
+							]) {
+								const opBody = subOp[key];
+								if (opBody?.filter) opBody.filter = {
+									...opBody.filter,
+									[tenantField]: tenantId
+								};
+							}
+							const insertBody = subOp.insertOne;
+							if (insertBody?.document) insertBody.document[tenantField] = tenantId;
+						}
+					}
+				}, { priority: HOOK_PRIORITY.POLICY });
 			}
 		}
 	};
@@ -1449,7 +3110,7 @@ function observabilityPlugin(options) {
 			for (const op of ops) {
 				repo.on(`before:${op}`, (context) => {
 					timers.set(context, performance.now());
-				});
+				}, { priority: 300 });
 				repo.on(`after:${op}`, ({ context }) => {
 					const start = timers.get(context);
 					if (start == null) return;
@@ -1986,12 +3647,14 @@ const counterSchema = new mongoose.Schema({
 	versionKey: false
 });
 /**
-* Get or create the Counter model.
+* 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() {
-	if (mongoose.models._MongoKitCounter) return mongoose.models._MongoKitCounter;
-	return mongoose.model("_MongoKitCounter", counterSchema);
+function getCounterModel(connection) {
+	const conn = connection ?? mongoose.connection;
+	if (conn.models._MongoKitCounter) return conn.models._MongoKitCounter;
+	return conn.model("_MongoKitCounter", counterSchema);
 }
 /**
 * Atomically increment and return the next sequence value for a given key.
@@ -2010,11 +3673,13 @@ function getCounterModel() {
 * const startSeq = await getNextSequence('invoices', 5);
 * // If current was 10, returns 15 (you use 11, 12, 13, 14, 15)
 */
-async function getNextSequence(counterKey, increment = 1) {
-	return (await getCounterModel().findOneAndUpdate({ _id: counterKey }, { $inc: { seq: increment } }, {
+async function getNextSequence(counterKey, increment = 1, connection) {
+	const result = await getCounterModel(connection).findOneAndUpdate({ _id: counterKey }, { $inc: { seq: increment } }, {
 		upsert: true,
 		returnDocument: "after"
-	})).seq;
+	});
+	if (!result) throw new Error(`Failed to increment counter '${counterKey}'`);
+	return result.seq;
 }
 /**
 * Generator: Simple sequential counter.
@@ -2033,8 +3698,8 @@ async function getNextSequence(counterKey, increment = 1) {
 function sequentialId(options) {
 	const { prefix, model, padding = 4, separator = "-", counterKey } = options;
 	const key = counterKey || model.modelName;
-	return async (_context) => {
-		const seq = await getNextSequence(key);
+	return async (context) => {
+		const seq = await getNextSequence(key, 1, context._counterConnection);
 		return `${prefix}${separator}${String(seq).padStart(padding, "0")}`;
 	};
 }
@@ -2061,7 +3726,7 @@ function sequentialId(options) {
 */
 function dateSequentialId(options) {
 	const { prefix, model, partition = "monthly", padding = 4, separator = "-" } = options;
-	return async (_context) => {
+	return async (context) => {
 		const now = /* @__PURE__ */ new Date();
 		const year = String(now.getFullYear());
 		const month = String(now.getMonth() + 1).padStart(2, "0");
@@ -2082,7 +3747,7 @@ function dateSequentialId(options) {
 				counterKey = `${model.modelName}:${year}-${month}`;
 				break;
 		}
-		const seq = await getNextSequence(counterKey);
+		const seq = await getNextSequence(counterKey, 1, context._counterConnection);
 		return `${prefix}${separator}${datePart}${separator}${String(seq).padStart(padding, "0")}`;
 	};
 }
@@ -2143,13 +3808,16 @@ function customIdPlugin(options) {
 	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;
@@ -2166,4 +3834,4 @@ function customIdPlugin(options) {
 }
 
 //#endregion
-export { methodRegistryPlugin as C, fieldFilterPlugin as D, timestampPlugin as E, validationChainPlugin as S, auditLogPlugin as T, autoInject as _, sequentialId as a, requireField as b, auditTrailPlugin as c, cascadePlugin as d, cachePlugin as f, mongoOperationsPlugin as g, batchOperationsPlugin as h, prefixedId as i, observabilityPlugin as l, aggregateHelpersPlugin as m, dateSequentialId as n, elasticSearchPlugin as o, subdocumentPlugin as p, getNextSequence as r, AuditTrailQuery as s, customIdPlugin as t, multiTenantPlugin as u, blockIf as v, softDeletePlugin as w, uniqueField as x, immutableField as y };
+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 };