@classytic/mongokit 3.2.5 → 3.3.1

package/dist/index.mjs

@@ -1,1151 +1,12 @@
 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 { r as LookupBuilder } from "./aggregate-BClp040M.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 methodRegistryPlugin, D as fieldFilterPlugin, E as timestampPlugin, S as validationChainPlugin, T as auditLogPlugin, _ as autoInject, a as sequentialId, b as requireField, c as auditTrailPlugin, d as cascadePlugin, f as cachePlugin, g as mongoOperationsPlugin, h as batchOperationsPlugin, i as prefixedId, l as observabilityPlugin, m as aggregateHelpersPlugin, n as dateSequentialId, o as elasticSearchPlugin, p as subdocumentPlugin, r as getNextSequence, s as AuditTrailQuery, t as customIdPlugin, u as multiTenantPlugin, v as blockIf, w as softDeletePlugin, x as uniqueField, y as immutableField } from "./custom-id.plugin-m0VW6yYm.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 { A as AggregationBuilder, C as methodRegistryPlugin, D as fieldFilterPlugin, E as timestampPlugin, O as HOOK_PRIORITY, S as validationChainPlugin, T as auditLogPlugin, _ as autoInject, a as sequentialId, b as requireField, c as auditTrailPlugin, d as cascadePlugin, f as cachePlugin, g as mongoOperationsPlugin, h as batchOperationsPlugin, i as prefixedId, k as Repository, l as observabilityPlugin, m as aggregateHelpersPlugin, n as dateSequentialId, o as elasticSearchPlugin, p as subdocumentPlugin, r as getNextSequence, s as AuditTrailQuery, t as customIdPlugin, u as multiTenantPlugin, v as blockIf, w as softDeletePlugin, x as uniqueField, y as immutableField } from "./custom-id.plugin-FInXDsUX.mjs";
+import { c as filterResponseData, l as getFieldsForUser, s as createFieldPreset, u as getMongooseProjection } from "./cache-keys-CzFwVnLy.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-D_i2Am_O.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
@@ -1376,8 +237,11 @@ var QueryParser = class {
 				description: "Fields to include/exclude (comma-separated). Prefix with - to exclude. Example: name,email,-password"
 			},
 			populate: {
-				type: "string",
-				description: "Fields to populate/join (comma-separated). Example: author,category"
+				oneOf: [{ type: "string" }, {
+					type: "object",
+					additionalProperties: true
+				}],
+				description: "Fields to populate/join. Simple: comma-separated string (author,category). Advanced: bracket-notation object (populate[author][select]=name,email)"
 			},
 			after: {
 				type: "string",
@@ -2049,4 +913,4 @@ function createRepository(Model, plugins = [], paginationConfig = {}, options =
 var src_default = Repository;
 
 //#endregion
-export { AggregationBuilder, AuditTrailQuery, LookupBuilder, PaginationEngine, QueryParser, Repository, actions_exports as actions, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, 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 };
+export { AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, PaginationEngine, QueryParser, Repository, actions_exports as actions, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, 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 };