@classytic/mongokit 3.2.0 → 3.2.2

package/dist/index.mjs

@@ -0,0 +1,1906 @@
+import { i as createError, r as warn, t as configureLogger } from "./logger-D8ily-PP.mjs";
+import { n as createMany, t as create } from "./create-BuO6xt0v.mjs";
+import { a as deleteById, d as getById, f as getByQuery, i as LookupBuilder, l as count, p as getOrCreate, r as distinct, s as update, t as aggregate, u as exists } from "./aggregate-BAi4Do-X.mjs";
+import { PaginationEngine } from "./pagination/PaginationEngine.mjs";
+import { c as filterResponseData, l as getFieldsForUser, s as createFieldPreset, u as getMongooseProjection } from "./cache-keys-C8Z9B5sw.mjs";
+import { C as auditLogPlugin, S as softDeletePlugin, T as fieldFilterPlugin, _ as immutableField, a as sequentialId, b as validationChainPlugin, c as multiTenantPlugin, d as subdocumentPlugin, f as aggregateHelpersPlugin, g as blockIf, h as autoInject, i as prefixedId, l as cascadePlugin, m as mongoOperationsPlugin, n as dateSequentialId, o as elasticSearchPlugin, p as batchOperationsPlugin, r as getNextSequence, s as observabilityPlugin, t as customIdPlugin, u as cachePlugin, v as requireField, w as timestampPlugin, x as methodRegistryPlugin, y as uniqueField } from "./custom-id.plugin-B_zIs6gE.mjs";
+import { a as isFieldUpdateAllowed, i as getSystemManagedFields, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-COdDEkIJ.mjs";
+import { t as actions_exports } from "./actions/index.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);
+* ```
+*/
+/**
+* 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
+	*/
+	on(event, listener) {
+		if (!this._hooks.has(event)) this._hooks.set(event, []);
+		this._hooks.get(event).push(listener);
+		return this;
+	}
+	/**
+	* Remove a specific event listener
+	*/
+	off(event, listener) {
+		const listeners = this._hooks.get(event);
+		if (listeners) {
+			const idx = listeners.indexOf(listener);
+			if (idx !== -1) listeners.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 listeners = this._hooks.get(event) || [];
+		for (const listener of listeners) 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
+	*/
+	async emitAsync(event, data) {
+		const listeners = this._hooks.get(event) || [];
+		for (const listener of listeners) 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) return context._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) return context._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 context = await this._buildContext("getAll", {
+			...params,
+			...options
+		});
+		if (context._cacheHit) return context._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
+	*/
+	async getOrCreate(query, createData, options = {}) {
+		return getOrCreate(this.Model, query, createData, options);
+	}
+	/**
+	* Count documents
+	*/
+	async count(query = {}, options = {}) {
+		return count(this.Model, query, options);
+	}
+	/**
+	* Check if document exists
+	*/
+	async exists(query, options = {}) {
+		return exists(this.Model, query, options);
+	}
+	/**
+	* 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"
+				};
+				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
+	*/
+	async aggregate(pipeline, options = {}) {
+		return aggregate(this.Model, pipeline, options);
+	}
+	/**
+	* Aggregate pipeline with pagination
+	* Best for: Complex queries, grouping, joins
+	*/
+	async aggregatePaginate(options = {}) {
+		const context = await this._buildContext("aggregatePaginate", options);
+		return this._pagination.aggregatePaginate(context);
+	}
+	/**
+	* Get distinct values
+	*/
+	async distinct(field, query = {}, options = {}) {
+		return distinct(this.Model, field, query, options);
+	}
+	/**
+	* 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);
+			if (options.sort) builder.sort(this._parseSort(options.sort));
+			const page = options.page || 1;
+			const 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 }];
+			if (options.select) {
+				let projection;
+				if (typeof options.select === "string") {
+					projection = {};
+					const fields = options.select.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(options.select)) {
+					projection = {};
+					for (const field of options.select) if (field.startsWith("-")) projection[field.substring(1)] = 0;
+					else projection[field] = 1;
+				} else projection = options.select;
+				dataStages.push({ $project: projection });
+			}
+			builder.facet({
+				metadata: [{ $count: "total" }],
+				data: dataStages
+			});
+			const pipeline = builder.build();
+			const result = (await this.Model.aggregate(pipeline).session(options.session || null))[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 mongoose.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 message = (error.message || "").toLowerCase();
+		return message.includes("transaction numbers are only allowed on a replica set member") || message.includes("replica set") || message.includes("mongos");
+	}
+	/**
+	* 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
+	*/
+	async _buildContext(operation, options) {
+		const context = {
+			operation,
+			model: this.model,
+			...options
+		};
+		const event = `before:${operation}`;
+		const hooks = this._hooks.get(event) || [];
+		for (const hook of hooks) await hook(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/query/QueryParser.ts
+/**
+* Modern Query Parser - URL to MongoDB Query Transpiler
+*
+* Next-generation query parser that converts URL parameters to MongoDB aggregation pipelines.
+* Smarter than Prisma/tRPC for MongoDB with support for:
+* - Custom field lookups ($lookup)
+* - Complex filtering with operators
+* - Full-text search
+* - Aggregations via URL
+* - Security hardening
+*
+* @example
+* ```typescript
+* // Simple usage
+* const parser = new QueryParser();
+* const query = parser.parse(req.query);
+*
+* // URL: ?status=active&lookup[department]=slug&sort=-createdAt&page=1&limit=20
+* // Result: Complete MongoDB query with $lookup, filters, sort, pagination
+* ```
+*
+* ## SECURITY CONSIDERATIONS FOR PRODUCTION
+*
+* ### Aggregation Security (enableAggregations option)
+*
+* **IMPORTANT:** The `enableAggregations` option exposes powerful MongoDB aggregation
+* pipeline capabilities via URL parameters. While this feature includes sanitization
+* (blocks $where, $function, $accumulator), it should be used with caution:
+*
+* **Recommended security practices:**
+* 1. **Disable by default for public endpoints:**
+*    ```typescript
+*    const parser = new QueryParser({
+*      enableAggregations: false  // Default: disabled
+*    });
+*    ```
+*
+* 2. **Use per-route allowlists for trusted clients:**
+*    ```typescript
+*    // Admin/internal routes only
+*    if (req.user?.role === 'admin') {
+*      const allowedStages = ['$match', '$project', '$sort', '$limit'];
+*      // Validate aggregate parameter against allowlist
+*    }
+*    ```
+*
+* 3. **Validate stage structure:** Even with sanitization, complex pipelines can
+*    cause performance issues. Consider limiting:
+*    - Number of pipeline stages (e.g., max 5)
+*    - Specific allowed operators per stage
+*    - Allowed fields in $project/$match
+*
+* 4. **Monitor resource usage:** Aggregation pipelines can be expensive.
+*    Use MongoDB profiling to track slow operations.
+*
+* ### Lookup Security
+*
+* Lookup pipelines are sanitized by default:
+* - Dangerous stages blocked ($out, $merge, $unionWith, $collStats, $currentOp, $listSessions)
+* - Dangerous operators blocked inside $match/$addFields/$set ($where, $function, $accumulator, $expr)
+* - Optional collection whitelist via `allowedLookupCollections`
+* For maximum security, use per-collection field allowlists in your controller layer.
+*
+* ### Filter Security
+*
+* All filters are sanitized:
+* - Dangerous operators blocked ($where, $function, $accumulator, $expr)
+* - Regex patterns validated (ReDoS protection)
+* - Max filter depth enforced (prevents filter bombs)
+* - Max limit enforced (prevents resource exhaustion)
+*
+* @see {@link https://github.com/classytic/mongokit/blob/main/docs/SECURITY.md}
+*/
+/**
+* Modern Query Parser
+* Converts URL parameters to MongoDB queries with $lookup support
+*/
+var QueryParser = class {
+	options;
+	operators = {
+		eq: "$eq",
+		ne: "$ne",
+		gt: "$gt",
+		gte: "$gte",
+		lt: "$lt",
+		lte: "$lte",
+		in: "$in",
+		nin: "$nin",
+		like: "$regex",
+		contains: "$regex",
+		regex: "$regex",
+		exists: "$exists",
+		size: "$size",
+		type: "$type"
+	};
+	dangerousOperators;
+	/**
+	* Regex patterns that can cause catastrophic backtracking (ReDoS attacks)
+	* Detects:
+	* - Quantifiers: {n,m}
+	* - Possessive quantifiers: *+, ++, ?+
+	* - Nested quantifiers: (a+)+, (a*)*
+	* - Backreferences: \1, \2, etc.
+	* - Complex character classes: [...]...[...]
+	*/
+	dangerousRegexPatterns = /(\{[0-9,]+\}|\*\+|\+\+|\?\+|(\(.+\))\+|\(\?\:|\\[0-9]|(\[.+\]).+(\[.+\]))/;
+	constructor(options = {}) {
+		this.options = {
+			maxRegexLength: options.maxRegexLength ?? 500,
+			maxSearchLength: options.maxSearchLength ?? 200,
+			maxFilterDepth: options.maxFilterDepth ?? 10,
+			maxLimit: options.maxLimit ?? 1e3,
+			additionalDangerousOperators: options.additionalDangerousOperators ?? [],
+			enableLookups: options.enableLookups ?? true,
+			enableAggregations: options.enableAggregations ?? false,
+			searchMode: options.searchMode ?? "text",
+			searchFields: options.searchFields,
+			allowedLookupCollections: options.allowedLookupCollections,
+			allowedFilterFields: options.allowedFilterFields,
+			allowedSortFields: options.allowedSortFields
+		};
+		if (this.options.searchMode === "regex" && (!this.options.searchFields || this.options.searchFields.length === 0)) {
+			warn("[mongokit] searchMode \"regex\" requires searchFields to be specified. Falling back to \"text\" mode.");
+			this.options.searchMode = "text";
+		}
+		this.dangerousOperators = [
+			"$where",
+			"$function",
+			"$accumulator",
+			"$expr",
+			...this.options.additionalDangerousOperators
+		];
+	}
+	/**
+	* Parse URL query parameters into MongoDB query format
+	*
+	* @example
+	* ```typescript
+	* // URL: ?status=active&lookup[department][foreignField]=slug&sort=-createdAt&page=1
+	* const query = parser.parse(req.query);
+	* // Returns: { filters: {...}, lookups: [...], sort: {...}, page: 1 }
+	* ```
+	*/
+	parse(query) {
+		const { page, limit = 20, sort = "-createdAt", populate, search, after, cursor, select, lookup, aggregate, ...filters } = query || {};
+		let parsedLimit = parseInt(String(limit), 10);
+		if (isNaN(parsedLimit) || parsedLimit < 1) parsedLimit = 20;
+		if (parsedLimit > this.options.maxLimit) {
+			warn(`[mongokit] Limit ${parsedLimit} exceeds maximum ${this.options.maxLimit}, capping to max`);
+			parsedLimit = this.options.maxLimit;
+		}
+		const sanitizedSearch = this._sanitizeSearch(search);
+		const { simplePopulate, populateOptions } = this._parsePopulate(populate);
+		const parsed = {
+			filters: this._parseFilters(filters),
+			limit: parsedLimit,
+			sort: this._parseSort(sort),
+			populate: simplePopulate,
+			populateOptions,
+			search: sanitizedSearch
+		};
+		if (sanitizedSearch && this.options.searchMode === "regex" && this.options.searchFields) {
+			const regexSearchFilters = this._buildRegexSearch(sanitizedSearch);
+			if (regexSearchFilters) {
+				if (parsed.filters.$or) {
+					parsed.filters = {
+						...parsed.filters,
+						$and: [{ $or: parsed.filters.$or }, { $or: regexSearchFilters }]
+					};
+					delete parsed.filters.$or;
+				} else parsed.filters.$or = regexSearchFilters;
+				parsed.search = void 0;
+			}
+		}
+		if (select) parsed.select = this._parseSelect(select);
+		if (this.options.enableLookups && lookup) parsed.lookups = this._parseLookups(lookup);
+		if (this.options.enableAggregations && aggregate) parsed.aggregation = this._parseAggregation(aggregate);
+		if (after || cursor) parsed.after = String(after || cursor);
+		if (page !== void 0) parsed.page = parseInt(String(page), 10);
+		const orGroup = this._parseOr(query);
+		if (orGroup) if (parsed.filters.$or) {
+			const existingOr = parsed.filters.$or;
+			delete parsed.filters.$or;
+			parsed.filters.$and = [{ $or: existingOr }, { $or: orGroup }];
+		} else parsed.filters.$or = orGroup;
+		parsed.filters = this._enhanceWithBetween(parsed.filters);
+		return parsed;
+	}
+	/**
+	* Parse lookup configurations from URL parameters
+	*
+	* Supported formats:
+	* 1. Simple: ?lookup[department]=slug
+	*    → Join with 'departments' collection on slug field
+	*
+	* 2. Detailed: ?lookup[department][localField]=deptSlug&lookup[department][foreignField]=slug
+	*    → Full control over join configuration
+	*
+	* 3. Multiple: ?lookup[department]=slug&lookup[category]=categorySlug
+	*    → Multiple lookups
+	*
+	* @example
+	* ```typescript
+	* // URL: ?lookup[department][localField]=deptSlug&lookup[department][foreignField]=slug&lookup[department][single]=true
+	* const lookups = parser._parseLookups({
+	*   department: { localField: 'deptSlug', foreignField: 'slug', single: 'true' }
+	* });
+	* // Returns: [{ from: 'departments', localField: 'deptSlug', foreignField: 'slug', single: true }]
+	* ```
+	*/
+	_parseLookups(lookup) {
+		if (!lookup || typeof lookup !== "object") return [];
+		const lookups = [];
+		const lookupObj = lookup;
+		for (const [collectionName, config] of Object.entries(lookupObj)) try {
+			const lookupConfig = this._parseSingleLookup(collectionName, config);
+			if (lookupConfig) lookups.push(lookupConfig);
+		} catch (error) {
+			warn(`[mongokit] Invalid lookup config for ${collectionName}:`, error);
+		}
+		return lookups;
+	}
+	/**
+	* Parse a single lookup configuration
+	*/
+	_parseSingleLookup(collectionName, config) {
+		if (!config) return null;
+		if (typeof config === "string") {
+			const from = this._pluralize(collectionName);
+			if (this.options.allowedLookupCollections && !this.options.allowedLookupCollections.includes(from)) {
+				warn(`[mongokit] Blocked lookup to disallowed collection: ${from}`);
+				return null;
+			}
+			return {
+				from,
+				localField: `${collectionName}${this._capitalize(config)}`,
+				foreignField: config,
+				as: collectionName,
+				single: true
+			};
+		}
+		if (typeof config === "object" && config !== null) {
+			const opts = config;
+			const from = opts.from || this._pluralize(collectionName);
+			const localField = opts.localField;
+			const foreignField = opts.foreignField;
+			if (this.options.allowedLookupCollections && !this.options.allowedLookupCollections.includes(from)) {
+				warn(`[mongokit] Blocked lookup to disallowed collection: ${from}`);
+				return null;
+			}
+			if (!localField || !foreignField) {
+				warn(`[mongokit] Lookup requires localField and foreignField for ${collectionName}`);
+				return null;
+			}
+			return {
+				from,
+				localField,
+				foreignField,
+				as: opts.as || collectionName,
+				single: opts.single === true || opts.single === "true",
+				...opts.pipeline && Array.isArray(opts.pipeline) ? { pipeline: this._sanitizePipeline(opts.pipeline) } : {}
+			};
+		}
+		return null;
+	}
+	/**
+	* Parse aggregation pipeline from URL (advanced feature)
+	*
+	* @example
+	* ```typescript
+	* // URL: ?aggregate[group][_id]=$status&aggregate[group][count]=$sum:1
+	* const pipeline = parser._parseAggregation({
+	*   group: { _id: '$status', count: '$sum:1' }
+	* });
+	* ```
+	*/
+	_parseAggregation(aggregate) {
+		if (!aggregate || typeof aggregate !== "object") return void 0;
+		const pipeline = [];
+		const aggObj = aggregate;
+		for (const [stage, config] of Object.entries(aggObj)) try {
+			if (stage === "group" && typeof config === "object") pipeline.push({ $group: config });
+			else if (stage === "match" && typeof config === "object") {
+				const sanitizedMatch = this._sanitizeMatchConfig(config);
+				if (Object.keys(sanitizedMatch).length > 0) pipeline.push({ $match: sanitizedMatch });
+			} else if (stage === "sort" && typeof config === "object") pipeline.push({ $sort: config });
+			else if (stage === "project" && typeof config === "object") pipeline.push({ $project: config });
+		} catch (error) {
+			warn(`[mongokit] Invalid aggregation stage ${stage}:`, error);
+		}
+		return pipeline.length > 0 ? pipeline : void 0;
+	}
+	/**
+	* Parse select/project fields
+	*
+	* @example
+	* ```typescript
+	* // URL: ?select=name,email,-password
+	* // Returns: { name: 1, email: 1, password: 0 }
+	* ```
+	*/
+	_parseSelect(select) {
+		if (!select) return void 0;
+		if (typeof select === "string") {
+			const projection = {};
+			const fields = select.split(",").map((f) => f.trim());
+			for (const field of fields) if (field.startsWith("-")) projection[field.substring(1)] = 0;
+			else projection[field] = 1;
+			return projection;
+		}
+		if (typeof select === "object" && select !== null) return select;
+	}
+	/**
+	* Parse populate parameter - handles both simple string and advanced object format
+	*
+	* @example
+	* ```typescript
+	* // Simple: ?populate=author,category
+	* // Returns: { simplePopulate: 'author,category', populateOptions: undefined }
+	*
+	* // Advanced: ?populate[author][select]=name,email
+	* // Returns: { simplePopulate: undefined, populateOptions: [{ path: 'author', select: 'name email' }] }
+	* ```
+	*/
+	_parsePopulate(populate) {
+		if (!populate) return {};
+		if (typeof populate === "string") return { simplePopulate: populate };
+		if (typeof populate === "object" && populate !== null) {
+			const populateObj = populate;
+			if (Object.keys(populateObj).length === 0) return {};
+			const populateOptions = [];
+			for (const [path, config] of Object.entries(populateObj)) {
+				if (path.startsWith("$") || this.dangerousOperators.includes(path)) {
+					warn(`[mongokit] Blocked dangerous populate path: ${path}`);
+					continue;
+				}
+				const option = this._parseSinglePopulate(path, config);
+				if (option) populateOptions.push(option);
+			}
+			return populateOptions.length > 0 ? { populateOptions } : {};
+		}
+		return {};
+	}
+	/**
+	* Parse a single populate configuration
+	*/
+	_parseSinglePopulate(path, config, depth = 0) {
+		if (depth > 5) {
+			warn(`[mongokit] Populate depth exceeds maximum (5), truncating at path: ${path}`);
+			return { path };
+		}
+		if (typeof config === "string") {
+			if (config === "true" || config === "1") return { path };
+			return {
+				path,
+				select: config.split(",").join(" ")
+			};
+		}
+		if (typeof config === "object" && config !== null) {
+			const opts = config;
+			const option = { path };
+			if (opts.select && typeof opts.select === "string") option.select = opts.select.split(",").map((s) => s.trim()).join(" ");
+			if (opts.match && typeof opts.match === "object") option.match = this._convertPopulateMatch(opts.match);
+			if (opts.limit !== void 0) {
+				const limit = parseInt(String(opts.limit), 10);
+				if (!isNaN(limit) && limit > 0) {
+					option.options = option.options || {};
+					option.options.limit = limit;
+				}
+			}
+			if (opts.sort && typeof opts.sort === "string") {
+				const sortSpec = this._parseSort(opts.sort);
+				if (sortSpec) {
+					option.options = option.options || {};
+					option.options.sort = sortSpec;
+				}
+			}
+			if (opts.skip !== void 0) {
+				const skip = parseInt(String(opts.skip), 10);
+				if (!isNaN(skip) && skip >= 0) {
+					option.options = option.options || {};
+					option.options.skip = skip;
+				}
+			}
+			if (opts.populate && typeof opts.populate === "object") {
+				const nestedPopulate = opts.populate;
+				const nestedEntries = Object.entries(nestedPopulate);
+				if (nestedEntries.length > 0) {
+					const [nestedPath, nestedConfig] = nestedEntries[0];
+					const nestedOption = this._parseSinglePopulate(nestedPath, nestedConfig, depth + 1);
+					if (nestedOption) option.populate = nestedOption;
+				}
+			}
+			return option;
+		}
+		return null;
+	}
+	/**
+	* Convert populate match values (handles boolean strings, etc.)
+	*/
+	_convertPopulateMatch(match) {
+		const converted = {};
+		for (const [key, value] of Object.entries(match)) converted[key] = this._convertValue(value);
+		return converted;
+	}
+	/**
+	* Parse filter parameters
+	*/
+	_parseFilters(filters, depth = 0) {
+		if (depth > this.options.maxFilterDepth) {
+			warn(`[mongokit] Filter depth ${depth} exceeds maximum ${this.options.maxFilterDepth}, truncating`);
+			return {};
+		}
+		const parsedFilters = {};
+		const regexFields = {};
+		for (const [key, value] of Object.entries(filters)) {
+			if (this.dangerousOperators.includes(key) || key.startsWith("$") && !["$or", "$and"].includes(key)) {
+				warn(`[mongokit] Blocked dangerous operator: ${key}`);
+				continue;
+			}
+			if ([
+				"page",
+				"limit",
+				"sort",
+				"populate",
+				"search",
+				"select",
+				"lean",
+				"includeDeleted",
+				"lookup",
+				"aggregate",
+				"or",
+				"OR",
+				"$or"
+			].includes(key)) continue;
+			const operatorMatch = key.match(/^(.+)\[(.+)\]$/);
+			const baseField = operatorMatch ? operatorMatch[1] : key;
+			if (this.options.allowedFilterFields && !this.options.allowedFilterFields.includes(baseField)) {
+				warn(`[mongokit] Blocked filter field not in allowlist: ${baseField}`);
+				continue;
+			}
+			if (operatorMatch) {
+				const [, , operator] = operatorMatch;
+				if (this.dangerousOperators.includes("$" + operator)) {
+					warn(`[mongokit] Blocked dangerous operator: ${operator}`);
+					continue;
+				}
+				this._handleOperatorSyntax(parsedFilters, regexFields, operatorMatch, value);
+				continue;
+			}
+			if (typeof value === "object" && value !== null && !Array.isArray(value)) this._handleBracketSyntax(key, value, parsedFilters, depth + 1);
+			else parsedFilters[key] = this._convertValue(value);
+		}
+		return parsedFilters;
+	}
+	/**
+	* Handle operator syntax: field[operator]=value
+	*/
+	_handleOperatorSyntax(filters, regexFields, operatorMatch, value) {
+		const [, field, operator] = operatorMatch;
+		if (value === "" || value === null || value === void 0) return;
+		if (operator.toLowerCase() === "options" && regexFields[field]) {
+			const fieldValue = filters[field];
+			if (typeof fieldValue === "object" && fieldValue !== null && "$regex" in fieldValue) if (typeof value === "string" && /^[imsx]+$/.test(value)) fieldValue.$options = value;
+			else warn(`[mongokit] Blocked invalid regex $options value: ${String(value)}. Allowed flags: i, m, s, x`);
+			return;
+		}
+		if (operator.toLowerCase() === "contains" || operator.toLowerCase() === "like") {
+			const safeRegex = this._createSafeRegex(value);
+			if (safeRegex) {
+				filters[field] = { $regex: safeRegex };
+				regexFields[field] = true;
+			}
+			return;
+		}
+		const mongoOperator = this._toMongoOperator(operator);
+		if (this.dangerousOperators.includes(mongoOperator)) {
+			warn(`[mongokit] Blocked dangerous operator: ${mongoOperator}`);
+			return;
+		}
+		if (mongoOperator === "$eq") filters[field] = value;
+		else if (mongoOperator === "$regex") {
+			const safeRegex = this._createSafeRegex(value);
+			if (safeRegex) {
+				filters[field] = { $regex: safeRegex };
+				regexFields[field] = true;
+			}
+		} else {
+			let processedValue;
+			const op = operator.toLowerCase();
+			if ([
+				"gt",
+				"gte",
+				"lt",
+				"lte",
+				"size"
+			].includes(op)) {
+				processedValue = parseFloat(String(value));
+				if (isNaN(processedValue)) return;
+			} else if (op === "in" || op === "nin") processedValue = Array.isArray(value) ? value : String(value).split(",").map((v) => v.trim());
+			else processedValue = this._convertValue(value);
+			if (typeof filters[field] !== "object" || filters[field] === null || Array.isArray(filters[field])) filters[field] = {};
+			filters[field][mongoOperator] = processedValue;
+		}
+	}
+	/**
+	* Handle bracket syntax with object value
+	*/
+	_handleBracketSyntax(field, operators, parsedFilters, depth = 0) {
+		if (depth > this.options.maxFilterDepth) {
+			warn(`[mongokit] Nested filter depth exceeds maximum, skipping field: ${field}`);
+			return;
+		}
+		if (!parsedFilters[field]) parsedFilters[field] = {};
+		for (const [operator, value] of Object.entries(operators)) {
+			if (value === "" || value === null || value === void 0) continue;
+			if (operator === "between") {
+				parsedFilters[field].between = value;
+				continue;
+			}
+			if (this.operators[operator]) {
+				const mongoOperator = this.operators[operator];
+				let processedValue;
+				if ([
+					"gt",
+					"gte",
+					"lt",
+					"lte",
+					"size"
+				].includes(operator)) {
+					processedValue = parseFloat(String(value));
+					if (isNaN(processedValue)) continue;
+				} else if (operator === "in" || operator === "nin") processedValue = Array.isArray(value) ? value : String(value).split(",").map((v) => v.trim());
+				else if (operator === "like" || operator === "contains" || operator === "regex") {
+					const safeRegex = this._createSafeRegex(value);
+					if (!safeRegex) continue;
+					processedValue = safeRegex;
+				} else processedValue = this._convertValue(value);
+				parsedFilters[field][mongoOperator] = processedValue;
+			}
+		}
+		if (typeof parsedFilters[field] === "object" && Object.keys(parsedFilters[field]).length === 0) delete parsedFilters[field];
+	}
+	_parseSort(sort) {
+		if (!sort) return void 0;
+		if (typeof sort === "object") {
+			const sortObj = {};
+			for (const [key, value] of Object.entries(sort)) {
+				if (this.options.allowedSortFields && !this.options.allowedSortFields.includes(key)) {
+					warn(`[mongokit] Blocked sort field not in allowlist: ${key}`);
+					continue;
+				}
+				const strVal = String(value).toLowerCase();
+				sortObj[key] = strVal === "desc" || strVal === "-1" || value === -1 ? -1 : 1;
+			}
+			return Object.keys(sortObj).length > 0 ? sortObj : void 0;
+		}
+		const sortObj = {};
+		const fields = sort.split(",").map((s) => s.trim());
+		for (const field of fields) {
+			if (!field) continue;
+			const cleanField = field.startsWith("-") ? field.substring(1) : field;
+			if (this.options.allowedSortFields && !this.options.allowedSortFields.includes(cleanField)) {
+				warn(`[mongokit] Blocked sort field not in allowlist: ${cleanField}`);
+				continue;
+			}
+			if (field.startsWith("-")) sortObj[field.substring(1)] = -1;
+			else sortObj[field] = 1;
+		}
+		return Object.keys(sortObj).length > 0 ? sortObj : void 0;
+	}
+	_toMongoOperator(operator) {
+		const op = operator.toLowerCase();
+		return op.startsWith("$") ? op : "$" + op;
+	}
+	_createSafeRegex(pattern, flags = "i") {
+		if (pattern === null || pattern === void 0) return null;
+		const patternStr = String(pattern);
+		if (patternStr.length > this.options.maxRegexLength) {
+			warn(`[mongokit] Regex pattern too long, truncating`);
+			return new RegExp(this._escapeRegex(patternStr.substring(0, this.options.maxRegexLength)), flags);
+		}
+		if (this.dangerousRegexPatterns.test(patternStr)) {
+			warn("[mongokit] Potentially dangerous regex pattern, escaping");
+			return new RegExp(this._escapeRegex(patternStr), flags);
+		}
+		try {
+			return new RegExp(patternStr, flags);
+		} catch {
+			return new RegExp(this._escapeRegex(patternStr), flags);
+		}
+	}
+	_escapeRegex(str) {
+		return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	}
+	/**
+	* Sanitize $match configuration to prevent dangerous operators
+	* Recursively filters out operators like $where, $function, $accumulator
+	*/
+	_sanitizeMatchConfig(config) {
+		const sanitized = {};
+		for (const [key, value] of Object.entries(config)) {
+			if (this.dangerousOperators.includes(key)) {
+				warn(`[mongokit] Blocked dangerous operator in aggregation: ${key}`);
+				continue;
+			}
+			if (value && typeof value === "object" && !Array.isArray(value)) sanitized[key] = this._sanitizeMatchConfig(value);
+			else if (Array.isArray(value)) sanitized[key] = value.map((item) => {
+				if (item && typeof item === "object" && !Array.isArray(item)) return this._sanitizeMatchConfig(item);
+				return item;
+			});
+			else sanitized[key] = value;
+		}
+		return sanitized;
+	}
+	/**
+	* Sanitize pipeline stages for use in $lookup.
+	* Blocks dangerous stages ($out, $merge, etc.) and recursively sanitizes
+	* operator expressions within $match, $addFields, and $set stages.
+	*/
+	_sanitizePipeline(stages) {
+		const blockedStages = [
+			"$out",
+			"$merge",
+			"$unionWith",
+			"$collStats",
+			"$currentOp",
+			"$listSessions"
+		];
+		const sanitized = [];
+		for (const stage of stages) {
+			if (!stage || typeof stage !== "object") continue;
+			const entries = Object.entries(stage);
+			if (entries.length !== 1) continue;
+			const [op, config] = entries[0];
+			if (blockedStages.includes(op)) {
+				warn(`[mongokit] Blocked dangerous pipeline stage in lookup: ${op}`);
+				continue;
+			}
+			if (op === "$match" && typeof config === "object" && config !== null) sanitized.push({ $match: this._sanitizeMatchConfig(config) });
+			else if ((op === "$addFields" || op === "$set") && typeof config === "object" && config !== null) sanitized.push({ [op]: this._sanitizeExpressions(config) });
+			else sanitized.push(stage);
+		}
+		return sanitized;
+	}
+	/**
+	* Recursively sanitize expression objects, blocking dangerous operators
+	* like $where, $function, $accumulator inside $addFields/$set stages.
+	*/
+	_sanitizeExpressions(config) {
+		const sanitized = {};
+		for (const [key, value] of Object.entries(config)) {
+			if (this.dangerousOperators.includes(key)) {
+				warn(`[mongokit] Blocked dangerous operator in pipeline expression: ${key}`);
+				continue;
+			}
+			if (value && typeof value === "object" && !Array.isArray(value)) sanitized[key] = this._sanitizeExpressions(value);
+			else if (Array.isArray(value)) sanitized[key] = value.map((item) => {
+				if (item && typeof item === "object" && !Array.isArray(item)) return this._sanitizeExpressions(item);
+				return item;
+			});
+			else sanitized[key] = value;
+		}
+		return sanitized;
+	}
+	_sanitizeSearch(search) {
+		if (search === null || search === void 0 || search === "") return void 0;
+		let searchStr = String(search).trim();
+		if (!searchStr) return void 0;
+		if (searchStr.length > this.options.maxSearchLength) {
+			warn(`[mongokit] Search query too long, truncating`);
+			searchStr = searchStr.substring(0, this.options.maxSearchLength);
+		}
+		return searchStr;
+	}
+	/**
+	* Build regex-based multi-field search filters
+	* Creates an $or query with case-insensitive regex across all searchFields
+	*
+	* @example
+	* // searchFields: ['name', 'description', 'sku']
+	* // search: 'azure'
+	* // Returns: [
+	* //   { name: { $regex: /azure/i } },
+	* //   { description: { $regex: /azure/i } },
+	* //   { sku: { $regex: /azure/i } }
+	* // ]
+	*/
+	_buildRegexSearch(searchTerm) {
+		if (!this.options.searchFields || this.options.searchFields.length === 0) return null;
+		const safeRegex = this._createSafeRegex(searchTerm, "i");
+		if (!safeRegex) return null;
+		const orConditions = [];
+		for (const field of this.options.searchFields) orConditions.push({ [field]: { $regex: safeRegex } });
+		return orConditions.length > 0 ? orConditions : null;
+	}
+	_convertValue(value) {
+		if (value === null || value === void 0) return value;
+		if (Array.isArray(value)) return value.map((v) => this._convertValue(v));
+		if (typeof value === "object") return value;
+		const stringValue = String(value);
+		if (stringValue === "true") return true;
+		if (stringValue === "false") return false;
+		if (mongoose.Types.ObjectId.isValid(stringValue) && stringValue.length === 24) return stringValue;
+		return stringValue;
+	}
+	_parseOr(query) {
+		const orArray = [];
+		const raw = query?.or || query?.OR || query?.$or;
+		if (!raw) return void 0;
+		const items = Array.isArray(raw) ? raw : typeof raw === "object" ? Object.values(raw) : [];
+		for (const item of items) if (typeof item === "object" && item) orArray.push(this._parseFilters(item, 1));
+		return orArray.length ? orArray : void 0;
+	}
+	_enhanceWithBetween(filters) {
+		const output = { ...filters };
+		for (const [key, value] of Object.entries(filters || {})) if (value && typeof value === "object" && "between" in value) {
+			const between = value.between;
+			const [from, to] = String(between).split(",").map((s) => s.trim());
+			const fromDate = from ? new Date(from) : void 0;
+			const toDate = to ? new Date(to) : void 0;
+			const range = {};
+			if (fromDate && !isNaN(fromDate.getTime())) range.$gte = fromDate;
+			if (toDate && !isNaN(toDate.getTime())) range.$lte = toDate;
+			output[key] = range;
+		}
+		return output;
+	}
+	_pluralize(str) {
+		if (str.endsWith("y")) return str.slice(0, -1) + "ies";
+		if (str.endsWith("s")) return str;
+		return str + "s";
+	}
+	_capitalize(str) {
+		return str.charAt(0).toUpperCase() + str.slice(1);
+	}
+};
+
+//#endregion
+//#region src/index.ts
+/**
+* Factory function to create a repository instance
+*
+* @param Model - Mongoose model
+* @param plugins - Array of plugins to apply
+* @returns Repository instance
+*
+* @example
+* const userRepo = createRepository(UserModel, [timestampPlugin()]);
+*/
+function createRepository(Model, plugins = [], paginationConfig = {}, options = {}) {
+	return new Repository(Model, plugins, paginationConfig, options);
+}
+var src_default = Repository;
+
+//#endregion
+export { AggregationBuilder, LookupBuilder, PaginationEngine, QueryParser, Repository, actions_exports as actions, aggregateHelpersPlugin, auditLogPlugin, autoInject, batchOperationsPlugin, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, configureLogger, createError, createFieldPreset, createMemoryCache, createRepository, customIdPlugin, dateSequentialId, src_default as default, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getNextSequence, getSystemManagedFields, immutableField, isFieldUpdateAllowed, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validateUpdateBody, validationChainPlugin };