@classytic/mongokit 3.23.0 → 3.25.0

package/dist/index.mjs

@@ -1,19 +1,19 @@
-import { n as idVariants } from "./id-resolution-P2OzcyRl.mjs";
-import { a as withTransaction, c as MUTATING_OPERATIONS, d as operationsByPolicyKey, f as MONGOKIT_CAPABILITIES, i as isTransactionUnsupported, l as OP_REGISTRY, n as Repository, o as AggregationBuilder, p as createMongoPurgePort, r as batchTransaction, s as ALL_OPERATIONS, t as HOOK_PRIORITY, u as READ_OPERATIONS } from "./Repository-CLQA3sEz.mjs";
+import { n as idVariants } from "./id-resolution-BqDrk0S2.mjs";
+import { a as withTransaction, c as MUTATING_OPERATIONS, d as operationsByPolicyKey, f as MONGOKIT_CAPABILITIES, i as isTransactionUnsupported, l as OP_REGISTRY, n as Repository, o as AggregationBuilder, p as createMongoPurgePort, r as batchTransaction, s as ALL_OPERATIONS, t as HOOK_PRIORITY, u as READ_OPERATIONS } from "./Repository-KKR8jxfD.mjs";
 import { b as LookupBuilder, x as compileFilterToMongo } from "./update-1Lq9OMD2.mjs";
 import { n as warn, t as configureLogger } from "./logger-K7dPmu2U.mjs";
 import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-BuByZwKU.mjs";
 import { t as actions_exports } from "./actions/index.mjs";
-import { a as methodRegistryPlugin, c as getNextSequence, d as cachePlugin, f as batchOperationsPlugin, h as auditLogPlugin, i as multiTenantPlugin, l as prefixedId, m as auditTrailPlugin, n as softDeletePlugin, o as customIdPlugin, p as AuditTrailQuery, r as adminBypass, s as dateSequentialId, t as timestampPlugin, u as sequentialId } from "./timestamp.plugin-BnuuIDqJ.mjs";
-import { t as PaginationEngine } from "./PaginationEngine-BT1ywu9k.mjs";
+import { a as methodRegistryPlugin, c as getNextSequence, d as cachePlugin, f as batchOperationsPlugin, g as auditLogPlugin, h as ensureAuditTrailReady, i as multiTenantPlugin, l as prefixedId, m as auditTrailPlugin, n as softDeletePlugin, o as customIdPlugin, p as AuditTrailQuery, r as adminBypass, s as dateSequentialId, t as timestampPlugin, u as sequentialId } from "./timestamp.plugin-B8252GuQ.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-CczbvCAq.mjs";
 import { isGeoOperator, parseGeoFilter } from "./query/primitives/geo.mjs";
-import { t as createRepository } from "./create-repository-Bx1PpcdF.mjs";
-import { _ as appendOnlyPlugin, a as uniqueField, c as subdocumentPlugin, d as mongoOperationsPlugin, f as leasePlugin, g as cascadePlugin, h as elasticSearchPlugin, i as requireField, l as observabilityPlugin, m as fieldFilterPlugin, n as blockIf, o as validationChainPlugin, p as immutableStatesPlugin, r as immutableField, s as createTenantContext, t as autoInject, u as MONGOKIT_PLUGIN_NAMES, v as aggregateHelpersPlugin } from "./validation-chain.plugin-ZFDHxXLn.mjs";
+import { t as createRepository } from "./create-repository-DA5VJh-3.mjs";
+import { _ as appendOnlyPlugin, a as uniqueField, c as subdocumentPlugin, d as mongoOperationsPlugin, f as leasePlugin, g as cascadePlugin, h as elasticSearchPlugin, i as requireField, l as observabilityPlugin, m as fieldFilterPlugin, n as blockIf, o as validationChainPlugin, p as immutableStatesPlugin, r as immutableField, s as createTenantContext, t as autoInject, u as MONGOKIT_PLUGIN_NAMES, v as aggregateHelpersPlugin } from "./validation-chain.plugin-C3Vwp-Rk.mjs";
 import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "./field-selection-FSQFLpsU.mjs";
 import { buildFieldTypeMap, coerceFieldValue, coerceHeuristic } from "./query/primitives/coercion.mjs";
 import { extractSchemaIndexes } from "./query/primitives/indexes.mjs";
 import { n as createMemoryCache, t as toPlain } from "./to-plain-vksRrLtc.mjs";
-import { n as buildCrudSchemasFromMongooseSchema, t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-CVnrKFDq.mjs";
+import { n as buildCrudSchemasFromMongooseSchema, t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-CByt1VhQ.mjs";
 import { runChunkedPurge } from "@classytic/repo-core/repository";
 import { isControlParam } from "@classytic/repo-core/query-parser";
 //#region src/actions/cascade-references.ts
@@ -145,87 +145,255 @@ async function cascadePurgeReferences(options) {
 	return out;
 }
 //#endregion
-//#region src/query/QueryParser.ts
+//#region src/query/parser/pipeline-sanitizer.ts
 /**
-* Modern Query Parser - URL to MongoDB Query Transpiler
+* Sanitize $match configuration to prevent dangerous operators.
+* Recursively filters out operators like $where, $function, $accumulator.
+*/
+function sanitizeMatchConfig(rt, config, depth = 0) {
+	if (depth > rt.options.maxFilterDepth) {
+		rt.reject(`$match sanitize depth ${depth} exceeds maximum ${rt.options.maxFilterDepth}, truncating branch`, {
+			depth,
+			maxFilterDepth: rt.options.maxFilterDepth
+		});
+		return {};
+	}
+	const sanitized = {};
+	const logicalArrayOps = /* @__PURE__ */ new Set([
+		"$or",
+		"$and",
+		"$nor"
+	]);
+	for (const [key, value] of Object.entries(config)) {
+		if (rt.dangerousOperators.includes(key)) {
+			rt.reject(`Blocked dangerous operator in aggregation: ${key}`, { key });
+			continue;
+		}
+		if (value && typeof value === "object" && !Array.isArray(value)) sanitized[key] = sanitizeMatchConfig(rt, value, depth + 1);
+		else if (Array.isArray(value)) {
+			const sanitizedArray = value.map((item) => {
+				if (item && typeof item === "object" && !Array.isArray(item)) return sanitizeMatchConfig(rt, item, depth + 1);
+				return item;
+			});
+			if (logicalArrayOps.has(key)) {
+				const filtered = sanitizedArray.filter((item) => !(item && typeof item === "object" && !Array.isArray(item) && Object.keys(item).length === 0));
+				if (filtered.length === 0) {
+					rt.reject(`All branches of ${key} were blocked by sanitization; dropping the operator`, { key });
+					continue;
+				}
+				sanitized[key] = filtered;
+			} else sanitized[key] = sanitizedArray;
+		} 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.
+*/
+function sanitizePipeline(rt, stages) {
+	const blockedStages = [
+		"$out",
+		"$merge",
+		"$unionWith",
+		"$collStats",
+		"$currentOp",
+		"$listSessions"
+	];
+	const sanitized = [];
+	for (const stage of stages) {
+		if (!stage || typeof stage !== "object") {
+			rt.reject(`Malformed pipeline stage in lookup (not an object): ${String(stage)}`);
+			continue;
+		}
+		const entries = Object.entries(stage);
+		if (entries.length !== 1) {
+			rt.reject(`Malformed pipeline stage in lookup (expected exactly one operator, got ${entries.length})`);
+			continue;
+		}
+		const [op, config] = entries[0];
+		if (blockedStages.includes(op)) {
+			rt.reject(`Blocked dangerous pipeline stage in lookup: ${op}`, { stage: op });
+			continue;
+		}
+		if (op === "$match" && typeof config === "object" && config !== null) sanitized.push({ $match: sanitizeMatchConfig(rt, config) });
+		else if ((op === "$addFields" || op === "$set") && typeof config === "object" && config !== null) sanitized.push({ [op]: sanitizeExpressions(rt, config) });
+		else sanitized.push(stage);
+	}
+	return sanitized;
+}
+/**
+* Recursively sanitize expression objects, blocking dangerous operators
+* like $where, $function, $accumulator inside $addFields/$set stages.
 *
-* 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
+* Depth-guarded — same protection `sanitizeMatchConfig` ships, since
+* a hostile `$cond`/`$switch` chain can recurse arbitrarily deep and
+* exhaust JS stack.
+*/
+function sanitizeExpressions(rt, config, depth = 0) {
+	if (depth > rt.options.maxFilterDepth) {
+		rt.reject(`pipeline expression sanitize depth ${depth} exceeds maximum ${rt.options.maxFilterDepth}, truncating branch`, {
+			depth,
+			maxFilterDepth: rt.options.maxFilterDepth
+		});
+		return {};
+	}
+	const sanitized = {};
+	for (const [key, value] of Object.entries(config)) {
+		if (rt.dangerousOperators.includes(key)) {
+			rt.reject(`Blocked dangerous operator in pipeline expression: ${key}`, { key });
+			continue;
+		}
+		if (value && typeof value === "object" && !Array.isArray(value)) sanitized[key] = sanitizeExpressions(rt, value, depth + 1);
+		else if (Array.isArray(value)) sanitized[key] = value.map((item) => {
+			if (item && typeof item === "object" && !Array.isArray(item)) return sanitizeExpressions(rt, item, depth + 1);
+			return item;
+		});
+		else sanitized[key] = value;
+	}
+	return sanitized;
+}
+//#endregion
+//#region src/query/parser/aggregation.ts
+/**
+* Parse aggregation pipeline from URL (advanced feature).
 *
 * @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
+* // URL: ?aggregate[group][_id]=$status&aggregate[group][count]=$sum:1
+* parseAggregation(rt, { group: { _id: '$status', count: '$sum:1' } });
 * ```
+*/
+function parseAggregation(rt, 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 = sanitizeMatchConfig(rt, 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 });
+		else rt.reject(`Unsupported aggregation stage: ${stage}`, { stage });
+	} catch (error) {
+		if (error.code === "INVALID_QUERY_INPUT") throw error;
+		rt.reject(`Invalid aggregation stage ${stage}: ${error instanceof Error ? error.message : String(error)}`, { stage });
+	}
+	return pipeline.length > 0 ? pipeline : void 0;
+}
+//#endregion
+//#region src/query/parser/regex-safety.ts
+/**
+* Regex safety — ReDoS protection for user-supplied patterns.
 *
-* ## 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
+* Two independent detectors feed the decision:
+*  1. A heuristic pattern for classic catastrophic-backtracking shapes
+*     (nested quantifiers, possessive quantifiers, backreferences, …).
+*  2. A deterministic static complexity budget, so patterns that evade the
+*     heuristic still fail over when their unbounded-quantifier density is
+*     pathological.
 *
-* 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.
+* Unsafe input is never executed as a regex: depending on the caller's
+* intent it is either escaped to a literal match or rejected through the
+* `invalidInput` policy.
+*/
+/**
+* Regex patterns that can cause catastrophic backtracking (ReDoS attacks).
+* Detects common footguns:
+* - Quantifiers: {n,m}
+* - Possessive quantifiers: *+, ++, ?+
+* - Nested quantifiers: (a+)+, (a*)*
+* - Backreferences: \1, \2, etc.
+* - Complex character classes: [...]...[...]
+*/
+const DANGEROUS_REGEX_PATTERNS = /(\{[0-9,]+\}|\*\+|\+\+|\?\+|(\(.+\))\+|\(\?:|\\[0-9]|(\[.+\]).+(\[.+\]))/;
+/**
+* Static complexity budget for user-supplied regex patterns.
+* Returns `true` if the pattern crosses a budget that empirically correlates
+* with ReDoS risk — independent of the heuristic regex detector.
 *
-* ### Filter Security
+* Budget components (any single threshold crossed → over budget):
+*   - unbounded quantifiers (`*`, `+`, `?`) — hard cap 20
+*   - nested groups `(` — hard cap 8
+*   - alternations `|` — hard cap 10
+*   - combined: (quantifiers * groups) — hard cap 40
+*/
+function regexComplexityExceedsBudget(patternStr) {
+	const stripped = patternStr.replace(/\\[^\\]/g, "");
+	const unboundedQuantifiers = (stripped.match(/[*+?]/g) ?? []).length;
+	const groups = (stripped.match(/\(/g) ?? []).length;
+	const alternations = (stripped.match(/\|/g) ?? []).length;
+	if (unboundedQuantifiers > 20) return true;
+	if (groups > 8) return true;
+	if (alternations > 10) return true;
+	if (unboundedQuantifiers * groups > 40) return true;
+	return false;
+}
+/** Escape special regex characters (backslash first, then other metas). */
+function escapeRegex(str) {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Build a safe RegExp from user input.
 *
-* 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)
+* `onUnsafe` selects what happens when the pattern is over-long,
+* pathological, or syntactically invalid:
+* - `'reject'`: route through the `invalidInput` policy — HTTP 400 in
+*   `'throw'` mode, warn + escape-to-literal in `'drop'` mode. Used for
+*   the explicit `regex` operator, where the caller claims to be sending
+*   a real regex.
+* - `'escape'`: always warn + escape-to-literal, never throw. Used for
+*   `search` terms and the `like`/`contains` operators, whose documented
+*   semantic is a literal substring match — `?search=c++` must not 400.
+*/
+function createSafeRegex(rt, pattern, flags = "i", onUnsafe = "reject") {
+	if (pattern === null || pattern === void 0) return null;
+	const flag = (message, meta) => {
+		if (onUnsafe === "reject") rt.reject(message, meta);
+		else warn(`[mongokit] ${message}`);
+	};
+	const patternStr = String(pattern);
+	if (patternStr.length > rt.options.maxRegexLength) {
+		flag(`Regex pattern too long, truncating`, {
+			length: patternStr.length,
+			maxRegexLength: rt.options.maxRegexLength
+		});
+		return new RegExp(escapeRegex(patternStr.substring(0, rt.options.maxRegexLength)), flags);
+	}
+	if (DANGEROUS_REGEX_PATTERNS.test(patternStr)) {
+		flag("Potentially dangerous regex pattern, escaping");
+		return new RegExp(escapeRegex(patternStr), flags);
+	}
+	if (regexComplexityExceedsBudget(patternStr)) {
+		flag("Regex complexity budget exceeded, escaping");
+		return new RegExp(escapeRegex(patternStr), flags);
+	}
+	try {
+		return new RegExp(patternStr, flags);
+	} catch {
+		flag("Invalid regex pattern syntax, escaping to literal match");
+		return new RegExp(escapeRegex(patternStr), flags);
+	}
+}
+//#endregion
+//#region src/query/parser/filter-compiler.ts
+/**
+* Filter compiler — URL filter parameters → MongoDB filter query.
 *
-* @see {@link https://github.com/classytic/mongokit/blob/main/docs/SECURITY.md}
+* Owns the three entry shapes (flat `field=value`, flat operator syntax
+* `field[gte]=10`, nested bracket objects from qs), the `$or` group router,
+* and the `between` range expander. Every invalid or disallowed fragment
+* routes through the runtime's `invalidInput` policy.
 */
 /**
 * Top-level query parameters that mongokit handles outside the filter
-* pipeline. Used by `_handleBracketSyntax` to detect a common typo where a
+* pipeline. Used by `handleBracketSyntax` to detect a common typo where a
 * caller wrote `?filters[limit]=5` instead of `?limit=5` and the qs parser
 * nested the key under a filter object — the value is silently dropped
 * without this guard. Kept as a Set for O(1) lookup; values mirror the
-* reserved-key list at the top of `_parseFilters`.
+* reserved-key list at the top of `parseFilters`.
 */
 const RESERVED_PAGINATION_KEYS = /* @__PURE__ */ new Set([
 	"page",
@@ -233,88 +401,817 @@ const RESERVED_PAGINATION_KEYS = /* @__PURE__ */ new Set([
 	"sort",
 	"select"
 ]);
+function toMongoOperator(operator) {
+	const op = operator.toLowerCase();
+	return op.startsWith("$") ? op : `$${op}`;
+}
+/** Parse filter parameters into a MongoDB filter query. */
+function parseFilters(rt, filters, depth = 0) {
+	if (depth > rt.options.maxFilterDepth) {
+		rt.reject(`Filter depth ${depth} exceeds maximum ${rt.options.maxFilterDepth}, truncating`, {
+			depth,
+			maxFilterDepth: rt.options.maxFilterDepth
+		});
+		return {};
+	}
+	const parsedFilters = {};
+	const regexFields = {};
+	for (const [key, value] of Object.entries(filters)) {
+		if (rt.dangerousOperators.includes(key) || key.startsWith("$") && !["$or", "$and"].includes(key)) {
+			rt.reject(`Blocked dangerous operator: ${key}`, { key });
+			continue;
+		}
+		if (isControlParam(key) || [
+			"lean",
+			"includeDeleted",
+			"lookup",
+			"aggregate",
+			"or",
+			"OR",
+			"$or"
+		].includes(key)) continue;
+		const operatorMatch = key.match(/^(.+)\[(.+)\]$/);
+		const baseField = operatorMatch ? operatorMatch[1] : key;
+		if (rt.options.allowedFilterFields && !rt.options.allowedFilterFields.includes(baseField)) {
+			rt.reject(`Blocked filter field not in allowlist: ${baseField}`, { field: baseField });
+			continue;
+		}
+		if (operatorMatch) {
+			const [, , operator] = operatorMatch;
+			if (rt.dangerousOperators.includes(`$${operator}`)) {
+				rt.reject(`Blocked dangerous operator: ${operator}`, { operator });
+				continue;
+			}
+			handleOperatorSyntax(rt, parsedFilters, regexFields, operatorMatch, value);
+			continue;
+		}
+		if (typeof value === "object" && value !== null && !Array.isArray(value)) handleBracketSyntax(rt, key, value, parsedFilters, depth + 1);
+		else parsedFilters[key] = coerceFieldValue(key, value, rt.fieldTypes);
+	}
+	return parsedFilters;
+}
+/** Handle flat operator syntax: field[operator]=value */
+function handleOperatorSyntax(rt, filters, regexFields, operatorMatch, value) {
+	const [, field, operator] = operatorMatch;
+	if (value === "" || value === null || value === void 0) return;
+	if (rt.options.allowedOperators && !rt.options.allowedOperators.includes(operator.toLowerCase())) {
+		rt.reject(`Operator not in allowlist: ${operator}`, {
+			field,
+			operator
+		});
+		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 rt.reject(`Blocked invalid regex $options value: ${String(value)}. Allowed flags: i, m, s, x`, {
+			field,
+			value: String(value)
+		});
+		return;
+	}
+	if (operator.toLowerCase() === "between") {
+		if (typeof filters[field] !== "object" || filters[field] === null || Array.isArray(filters[field])) filters[field] = {};
+		filters[field].between = value;
+		return;
+	}
+	if (operator.toLowerCase() === "contains" || operator.toLowerCase() === "like") {
+		const safeRegex = createSafeRegex(rt, value, "i", "escape");
+		if (safeRegex) {
+			filters[field] = { $regex: safeRegex };
+			regexFields[field] = true;
+		}
+		return;
+	}
+	if (isGeoOperator(operator)) {
+		const geoFilter = parseGeoFilter(operator, value);
+		if (geoFilter) filters[field] = geoFilter;
+		else rt.reject(`Invalid geo operator value for ${field}[${operator}]; dropping filter`, {
+			field,
+			operator
+		});
+		return;
+	}
+	const mongoOperator = toMongoOperator(operator);
+	if (rt.dangerousOperators.includes(mongoOperator)) {
+		rt.reject(`Blocked dangerous operator: ${mongoOperator}`, { operator: mongoOperator });
+		return;
+	}
+	if (mongoOperator === "$eq") filters[field] = coerceFieldValue(field, value, rt.fieldTypes);
+	else if (mongoOperator === "$regex") {
+		const safeRegex = createSafeRegex(rt, value);
+		if (safeRegex) {
+			filters[field] = { $regex: safeRegex };
+			regexFields[field] = true;
+		}
+	} else {
+		let processedValue;
+		const op = operator.toLowerCase();
+		if (op === "size") {
+			processedValue = parseFloat(String(value));
+			if (Number.isNaN(processedValue)) {
+				rt.reject(`Non-numeric value for ${field}[${op}]: ${String(value)}`, {
+					field,
+					op
+				});
+				return;
+			}
+		} else if ([
+			"gt",
+			"gte",
+			"lt",
+			"lte"
+		].includes(op)) if (rt.fieldTypes.has(field)) {
+			processedValue = coerceFieldValue(field, value, rt.fieldTypes);
+			if (typeof processedValue === "number" && Number.isNaN(processedValue)) {
+				rt.reject(`Invalid value for ${field}[${op}]: ${String(value)}`, {
+					field,
+					op
+				});
+				return;
+			}
+		} else {
+			processedValue = parseFloat(String(value));
+			if (Number.isNaN(processedValue)) {
+				rt.reject(`Non-numeric value for ${field}[${op}]: ${String(value)}`, {
+					field,
+					op
+				});
+				return;
+			}
+		}
+		else if (op === "in" || op === "nin") processedValue = (Array.isArray(value) ? value : String(value).split(",").map((v) => v.trim())).map((elem) => coerceFieldValue(field, elem, rt.fieldTypes));
+		else processedValue = coerceFieldValue(field, value, rt.fieldTypes);
+		if (typeof filters[field] !== "object" || filters[field] === null || Array.isArray(filters[field])) filters[field] = {};
+		filters[field][mongoOperator] = processedValue;
+	}
+}
+/** Handle bracket syntax with object value (qs-parsed nested operators). */
+function handleBracketSyntax(rt, field, operators, parsedFilters, depth = 0) {
+	if (depth > rt.options.maxFilterDepth) {
+		rt.reject(`Nested filter depth exceeds maximum, skipping field: ${field}`, {
+			field,
+			maxFilterDepth: rt.options.maxFilterDepth
+		});
+		return;
+	}
+	for (const op of Object.keys(operators)) if (RESERVED_PAGINATION_KEYS.has(op)) warn(`[mongokit] Nested filter contains reserved key '${op}' at '${field}.${op}' — did you mean ?${op}=... at the top level? The nested value is ignored.`);
+	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 (isGeoOperator(operator)) {
+			const geoFilter = parseGeoFilter(operator, value);
+			if (geoFilter) parsedFilters[field] = geoFilter;
+			else {
+				rt.reject(`Invalid geo operator value for ${field}[${operator}]; dropping filter`, {
+					field,
+					operator
+				});
+				delete parsedFilters[field];
+			}
+			continue;
+		}
+		if (rt.options.allowedOperators && !rt.options.allowedOperators.includes(operator)) {
+			rt.reject(`Operator not in allowlist: ${operator}`, {
+				field,
+				operator
+			});
+			continue;
+		}
+		if (rt.operators[operator]) {
+			const mongoOperator = rt.operators[operator];
+			let processedValue;
+			if (operator === "size") {
+				processedValue = parseFloat(String(value));
+				if (Number.isNaN(processedValue)) {
+					rt.reject(`Non-numeric value for ${field}[${operator}]: ${String(value)}`, {
+						field,
+						operator
+					});
+					continue;
+				}
+			} else if ([
+				"gt",
+				"gte",
+				"lt",
+				"lte"
+			].includes(operator)) if (rt.fieldTypes.has(field)) {
+				processedValue = coerceFieldValue(field, value, rt.fieldTypes);
+				if (typeof processedValue === "number" && Number.isNaN(processedValue)) {
+					rt.reject(`Invalid value for ${field}[${operator}]: ${String(value)}`, {
+						field,
+						operator
+					});
+					continue;
+				}
+			} else {
+				processedValue = parseFloat(String(value));
+				if (Number.isNaN(processedValue)) {
+					rt.reject(`Non-numeric value for ${field}[${operator}]: ${String(value)}`, {
+						field,
+						operator
+					});
+					continue;
+				}
+			}
+			else if (operator === "in" || operator === "nin") processedValue = (Array.isArray(value) ? value : String(value).split(",").map((v) => v.trim())).map((elem) => coerceFieldValue(field, elem, rt.fieldTypes));
+			else if (operator === "like" || operator === "contains" || operator === "regex") {
+				const safeRegex = createSafeRegex(rt, value, "i", operator === "regex" ? "reject" : "escape");
+				if (!safeRegex) continue;
+				processedValue = safeRegex;
+			} else processedValue = coerceFieldValue(field, value, rt.fieldTypes);
+			parsedFilters[field][mongoOperator] = processedValue;
+		}
+	}
+	if (typeof parsedFilters[field] === "object" && Object.keys(parsedFilters[field]).length === 0) delete parsedFilters[field];
+}
+/** Parse `?or=[...]` / `?OR=[...]` / `?$or=[...]` groups into an $or array. */
+function parseOr(rt, 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) {
+		const parsedBranch = parseFilters(rt, item, 1);
+		if (Object.keys(parsedBranch).length > 0) orArray.push(parsedBranch);
+	}
+	return orArray.length ? orArray : void 0;
+}
+/** Expand `{ field: { between: 'a,b' } }` markers into `$gte`/`$lte` date ranges. */
+function enhanceWithBetween(rt, 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 && !Number.isNaN(fromDate.getTime())) range.$gte = fromDate;
+		if (toDate && !Number.isNaN(toDate.getTime())) range.$lte = toDate;
+		if (Object.keys(range).length === 0) {
+			rt.reject(`Invalid 'between' value for ${key}: ${String(between)}`, {
+				field: key,
+				value: String(between)
+			});
+			delete output[key];
+		} else output[key] = range;
+	}
+	return output;
+}
+//#endregion
+//#region src/query/parser/lookup.ts
+function pluralize(str) {
+	if (str.endsWith("y")) return `${str.slice(0, -1)}ies`;
+	if (str.endsWith("s")) return str;
+	return `${str}s`;
+}
+function capitalize(str) {
+	return str.charAt(0).toUpperCase() + str.slice(1);
+}
+/**
+* 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
+*/
+function parseLookups(rt, lookup) {
+	if (!lookup || typeof lookup !== "object") return [];
+	const lookups = [];
+	const lookupObj = lookup;
+	for (const [collectionName, config] of Object.entries(lookupObj)) try {
+		const lookupConfig = parseSingleLookup(rt, collectionName, config);
+		if (lookupConfig) lookups.push(lookupConfig);
+	} catch (error) {
+		if (error.code === "INVALID_QUERY_INPUT") throw error;
+		rt.reject(`Invalid lookup config for ${collectionName}: ${error instanceof Error ? error.message : String(error)}`, { collection: collectionName });
+	}
+	return lookups;
+}
+/** Parse a single lookup configuration. */
+function parseSingleLookup(rt, collectionName, config) {
+	if (!config) return null;
+	if (typeof config === "string") {
+		const from = pluralize(collectionName);
+		if (rt.options.allowedLookupCollections && !rt.options.allowedLookupCollections.includes(from)) {
+			rt.reject(`Blocked lookup to disallowed collection: ${from}`, { collection: from });
+			return null;
+		}
+		return {
+			from,
+			localField: `${collectionName}${capitalize(config)}`,
+			foreignField: config,
+			as: collectionName,
+			single: true
+		};
+	}
+	if (typeof config === "object" && config !== null) {
+		const opts = config;
+		const from = opts.from || pluralize(collectionName);
+		const localField = opts.localField;
+		const foreignField = opts.foreignField;
+		if (rt.options.allowedLookupCollections && !rt.options.allowedLookupCollections.includes(from)) {
+			rt.reject(`Blocked lookup to disallowed collection: ${from}`, { collection: from });
+			return null;
+		}
+		if (!localField || !foreignField) {
+			rt.reject(`Lookup requires localField and foreignField for ${collectionName}`, { collection: collectionName });
+			return null;
+		}
+		return {
+			from,
+			localField,
+			foreignField,
+			as: opts.as || collectionName,
+			single: opts.single === true || opts.single === "true",
+			...opts.select ? { select: String(opts.select) } : {},
+			...opts.pipeline && Array.isArray(opts.pipeline) ? { pipeline: sanitizePipeline(rt, opts.pipeline) } : {}
+		};
+	}
+	return null;
+}
+//#endregion
+//#region src/query/parser/pagination-input.ts
+/**
+* Parse a pagination input to a positive integer, or `undefined` when the
+* value is absent, empty, or rejected under `'drop'` mode. Rejects (per
+* policy) on non-integers, negatives, zero, decimals, and trailing garbage.
+*/
+function parsePositiveInt(rt, raw, label) {
+	if (raw === void 0 || raw === null || raw === "") return void 0;
+	let n;
+	if (typeof raw === "number") n = raw;
+	else {
+		const s = String(raw).trim();
+		if (!/^\d+$/.test(s)) {
+			rt.reject(`Invalid ${label} value: ${String(raw)} (expected a positive integer)`, { [label]: String(raw) });
+			return;
+		}
+		n = Number(s);
+	}
+	if (!Number.isInteger(n) || n < 1) {
+		rt.reject(`Invalid ${label} value: ${String(raw)} (expected a positive integer)`, { [label]: String(raw) });
+		return;
+	}
+	return n;
+}
+//#endregion
+//#region src/query/parser/sort-select.ts
+/** Parse a sort spec (string or object form), honoring `allowedSortFields`. */
+function parseSort(rt, sort) {
+	if (!sort) return void 0;
+	if (typeof sort === "object") {
+		const sortObj = {};
+		for (const [key, value] of Object.entries(sort)) {
+			if (rt.options.allowedSortFields && !rt.options.allowedSortFields.includes(key)) {
+				rt.reject(`Blocked sort field not in allowlist: ${key}`, { field: 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 (rt.options.allowedSortFields && !rt.options.allowedSortFields.includes(cleanField)) {
+			rt.reject(`Blocked sort field not in allowlist: ${cleanField}`, { field: cleanField });
+			continue;
+		}
+		if (field.startsWith("-")) sortObj[field.substring(1)] = -1;
+		else sortObj[field] = 1;
+	}
+	return Object.keys(sortObj).length > 0 ? sortObj : void 0;
+}
+/**
+* Parse select/project fields.
+*
+* @example
+* ```typescript
+* // URL: ?select=name,email,-password
+* // Returns: { name: 1, email: 1, password: 0 }
+* ```
+*/
+function 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;
+}
+//#endregion
+//#region src/query/parser/populate.ts
+/**
+* Populate parsing — simple string form (`?populate=author,category`) and
+* qs-nested advanced form (`?populate[author][select]=name,email`), with
+* nested populate, match conditions, and per-path options.
+*/
+/**
+* Parse populate parameter - handles both simple string and advanced object format
+*
+* @example
+* ```typescript
+* // Simple: ?populate=author,category
+* // Returns: { simplePopulate: 'author,category', populateOptions: [{path:'author'},{path:'category'}] }
+*
+* // Advanced: ?populate[author][select]=name,email
+* // Returns: { simplePopulate: undefined, populateOptions: [{ path: 'author', select: 'name email' }] }
+* ```
+*/
+function parsePopulate(rt, populate) {
+	if (!populate) return {};
+	if (typeof populate === "string") {
+		const paths = populate.split(",").map((p) => p.trim()).filter(Boolean);
+		if (paths.length > 0) return {
+			simplePopulate: populate,
+			populateOptions: paths.map((path) => ({ path }))
+		};
+		return {};
+	}
+	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("$") || rt.dangerousOperators.includes(path)) {
+				rt.reject(`Blocked dangerous populate path: ${path}`, { path });
+				continue;
+			}
+			const option = parseSinglePopulate(rt, path, config);
+			if (option) populateOptions.push(option);
+		}
+		return populateOptions.length > 0 ? { populateOptions } : {};
+	}
+	return {};
+}
+/** Parse a single populate configuration (recursive for nested populate). */
+function parseSinglePopulate(rt, path, config, depth = 0) {
+	if (depth > 5) {
+		rt.reject(`Populate depth exceeds maximum (5), truncating at path: ${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 = convertPopulateMatch(opts.match);
+		if (opts.limit !== void 0) {
+			const limit = parseInt(String(opts.limit), 10);
+			if (!Number.isNaN(limit) && limit > 0) {
+				option.options = option.options || {};
+				option.options.limit = limit;
+			}
+		}
+		if (opts.sort && typeof opts.sort === "string") {
+			const sortSpec = parseSort(rt, 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 (!Number.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 = parseSinglePopulate(rt, nestedPath, nestedConfig, depth + 1);
+				if (nestedOption) option.populate = nestedOption;
+			}
+		}
+		return option;
+	}
+	return null;
+}
+/** Convert populate match values (handles boolean strings, etc.) */
+function convertPopulateMatch(match) {
+	const converted = {};
+	for (const [key, value] of Object.entries(match)) converted[key] = coerceHeuristic(value);
+	return converted;
+}
+//#endregion
+//#region src/query/parser/runtime.ts
+/**
+* Parser runtime — the shared context every parser module receives.
+*
+* The `QueryParser` facade resolves options once at construction and builds a
+* single `ParserRuntime`; the extracted modules (filter compiler, sanitizers,
+* populate/lookup/sort parsers, …) are pure functions over it. This keeps the
+* modules independently testable and the facade thin, without threading six
+* separate arguments through every call.
+*/
+/** URL operator key → MongoDB operator. */
+const OPERATOR_MAP = {
+	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"
+};
+/** Always-blocked MongoDB operators (extended via `additionalDangerousOperators`). */
+const BASE_DANGEROUS_OPERATORS = [
+	"$where",
+	"$function",
+	"$accumulator",
+	"$expr"
+];
+function createReject(mode) {
+	return (message, meta) => {
+		if (mode === "throw") throw createError(400, `[mongokit] ${message}`, {
+			code: "INVALID_QUERY_INPUT",
+			meta
+		});
+		warn(`[mongokit] ${message}`);
+	};
+}
+//#endregion
+//#region src/query/parser/schema-docs.ts
+function availableOperators(rt) {
+	return rt.options.allowedOperators ? Object.entries(rt.operators).filter(([key]) => rt.options.allowedOperators?.includes(key)) : Object.entries(rt.operators);
+}
+/** Get the JSON Schema type for a filter operator. */
+function operatorSchemaType(op) {
+	if ([
+		"gt",
+		"gte",
+		"lt",
+		"lte",
+		"size"
+	].includes(op)) return "number";
+	if (["exists"].includes(op)) return "boolean";
+	return "string";
+}
+/** Get a human-readable description for a filter operator. */
+function operatorDescription(op, field, mongoOp) {
+	return {
+		ne: `${field} not equal to value (${mongoOp})`,
+		gt: `${field} greater than value (${mongoOp})`,
+		gte: `${field} greater than or equal to value (${mongoOp})`,
+		lt: `${field} less than value (${mongoOp})`,
+		lte: `${field} less than or equal to value (${mongoOp})`,
+		in: `${field} in comma-separated list (${mongoOp}). Example: value1,value2`,
+		nin: `${field} not in comma-separated list (${mongoOp})`,
+		like: `${field} matches pattern (case-insensitive regex)`,
+		contains: `${field} contains substring (case-insensitive regex)`,
+		regex: `${field} matches regex pattern (${mongoOp})`,
+		exists: `Field ${field} exists (true/false)`,
+		size: `Array field ${field} has exactly N elements (${mongoOp})`,
+		type: `Field ${field} is of BSON type (${mongoOp})`
+	}[op] || `Filter ${field} with ${mongoOp}`;
+}
+/** Build a summary description of all available filter operators. */
+function buildOperatorSummary(operators) {
+	const lines = ["Available filter operators (use as field[operator]=value):"];
+	const desc = {
+		eq: "Equal (default when no operator specified)",
+		ne: "Not equal",
+		gt: "Greater than",
+		gte: "Greater than or equal",
+		lt: "Less than",
+		lte: "Less than or equal",
+		in: "In list (comma-separated values)",
+		nin: "Not in list",
+		like: "Pattern match (case-insensitive)",
+		contains: "Contains substring (case-insensitive)",
+		regex: "Regex pattern",
+		exists: "Field exists (true/false)",
+		size: "Array size equals",
+		type: "BSON type check"
+	};
+	for (const [op, mongoOp] of operators) lines.push(`  ${op} → ${mongoOp}: ${desc[op] || op}`);
+	return lines.join("\n");
+}
+/**
+* Generate OpenAPI-compatible JSON Schema for query parameters.
+*
+* The schema respects parser configuration:
+* - `allowedOperators`: only documents allowed operators
+* - `allowedFilterFields`: generates explicit field[op] entries
+* - `enableLookups` / `enableAggregations`: includes/excludes lookup/aggregate params
+* - `maxLimit` / `maxSearchLength`: reflected in schema constraints
+*/
+function buildQuerySchema(rt) {
+	const properties = {
+		page: {
+			type: "integer",
+			description: "Page number for offset pagination",
+			default: 1,
+			minimum: 1
+		},
+		limit: {
+			type: "integer",
+			description: "Number of items per page",
+			default: 20,
+			minimum: 1,
+			maximum: rt.options.maxLimit
+		},
+		sort: {
+			type: "string",
+			description: "Sort fields (comma-separated). Prefix with - for descending. Example: -createdAt,name"
+		},
+		search: {
+			type: "string",
+			description: rt.options.searchMode === "regex" ? `Search across fields${rt.options.searchFields ? ` (${rt.options.searchFields.join(", ")})` : ""} using case-insensitive regex` : "Full-text search query (requires text index)",
+			maxLength: rt.options.maxSearchLength
+		},
+		select: {
+			type: "string",
+			description: "Fields to include/exclude (comma-separated). Prefix with - to exclude. Example: name,email,-password"
+		},
+		populate: {
+			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",
+			description: "Cursor value for keyset pagination"
+		}
+	};
+	if (rt.options.enableLookups) properties.lookup = {
+		type: "object",
+		description: "Custom field lookups ($lookup). Example: lookup[department]=slug or lookup[department][localField]=deptId&lookup[department][foreignField]=_id"
+	};
+	if (rt.options.enableAggregations) properties.aggregate = {
+		type: "object",
+		description: "Aggregation pipeline stages. Supports: group, match, sort, project. Example: aggregate[group][_id]=$status"
+	};
+	const operators = availableOperators(rt);
+	if (rt.options.allowedFilterFields && rt.options.allowedFilterFields.length > 0) for (const field of rt.options.allowedFilterFields) {
+		properties[field] = {
+			type: "string",
+			description: `Filter by ${field} (exact match)`
+		};
+		for (const [op, mongoOp] of operators) {
+			if (op === "eq") continue;
+			properties[`${field}[${op}]`] = {
+				type: operatorSchemaType(op),
+				description: operatorDescription(op, field, mongoOp)
+			};
+		}
+	}
+	return {
+		type: "object",
+		properties
+	};
+}
+/**
+* Query schema with OpenAPI extensions — adds a documentary
+* `_filterOperators` property (marked `x-internal`) describing available
+* filter operators. For validation-only schemas use `buildQuerySchema`.
+*/
+function buildOpenAPIQuerySchema(rt) {
+	const schema = buildQuerySchema(rt);
+	schema.properties._filterOperators = {
+		type: "string",
+		description: buildOperatorSummary(availableOperators(rt)),
+		"x-internal": true
+	};
+	return schema;
+}
+//#endregion
+//#region src/query/parser/search.ts
+/**
+* Search-term handling — length-capped sanitization plus the regex-mode
+* multi-field `$or` builder. Search terms are literal text, never regex
+* patterns: special characters are escaped, not rejected.
+*/
+/** Trim + length-cap the raw search term (reject over-long input per policy). */
+function sanitizeSearch(rt, search) {
+	if (search === null || search === void 0 || search === "") return void 0;
+	let searchStr = String(search).trim();
+	if (!searchStr) return void 0;
+	if (searchStr.length > rt.options.maxSearchLength) {
+		rt.reject(`Search query too long, truncating`, {
+			length: searchStr.length,
+			maxSearchLength: rt.options.maxSearchLength
+		});
+		searchStr = searchStr.substring(0, rt.options.maxSearchLength);
+	}
+	return searchStr;
+}
+/**
+* Build regex-based multi-field search filters: an $or with case-insensitive
+* regex across all searchFields.
+*
+* @example
+* // searchFields: ['name', 'description', 'sku'], search: 'azure'
+* // Returns: [{ name: {$regex:/azure/i} }, { description: {...} }, { sku: {...} }]
+*/
+function buildRegexSearch(rt, searchTerm) {
+	if (!rt.options.searchFields || rt.options.searchFields.length === 0) return null;
+	const safeRegex = createSafeRegex(rt, searchTerm, "i", "escape");
+	if (!safeRegex) return null;
+	const orConditions = [];
+	for (const field of rt.options.searchFields) orConditions.push({ [field]: { $regex: safeRegex } });
+	return orConditions.length > 0 ? orConditions : null;
+}
+//#endregion
+//#region src/query/QueryParser.ts
+/**
+* Modern Query Parser - URL to MongoDB Query Transpiler
+*
+* Converts URL parameters to MongoDB queries with support for custom field
+* lookups ($lookup), operator filtering, full-text search, URL aggregations,
+* and security hardening.
+*
+* This file is the public facade: options resolution, the `parse()`
+* orchestration, and the OpenAPI schema surface. The implementation lives in
+* focused modules under `./parser/`:
+*
+* - `parser/filter-compiler`    — filters, operator syntax, $or, between
+* - `parser/regex-safety`       — ReDoS protection (escape/reject)
+* - `parser/pipeline-sanitizer` — $match / $lookup-pipeline / expression sanitizing
+* - `parser/lookup`             — ?lookup[...] parsing + collection allowlist
+* - `parser/aggregation`        — ?aggregate[...] parsing (opt-in)
+* - `parser/populate`           — ?populate parsing (simple + nested)
+* - `parser/sort-select`        — ?sort / ?select parsing
+* - `parser/search`             — search sanitization + regex-mode $or builder
+* - `parser/schema-docs`        — OpenAPI query-schema generation
+* - `parser/runtime`            — shared runtime + invalidInput policy
+*
+* @example
+* ```typescript
+* 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
+*
+* - `invalidInput` defaults to `'throw'` (fail-closed): invalid or blocked
+*   query input raises HTTP 400 (`code: 'INVALID_QUERY_INPUT'`) instead of
+*   being silently dropped (which broadens the result set). Opt into
+*   `'drop'` only for trusted compat tooling.
+* - Dangerous operators blocked everywhere ($where, $function, $accumulator, $expr).
+* - Regex patterns validated (ReDoS protection); search/like/contains are
+*   literal text (escaped, never rejected).
+* - Max filter depth + max limit enforced.
+* - Lookup pipelines sanitized; `enableAggregations` is opt-in — keep it off
+*   for public endpoints or pair with per-route allowlists.
+*
+* @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;
 	/**
-	* Normalized dot-notation field-type map. Built once at construction from
-	* `options.schema` (Mongoose) and `options.fieldTypes` (override map), with
-	* `fieldTypes` taking precedence. An empty map means schema-aware coercion
-	* is disabled and the heuristic in `_convertValue` runs unchanged — this
-	* preserves backwards compatibility for callers that don't opt in.
+	* Shared runtime handed to every parser module. `schema` and `fieldTypes`
+	* are consumed once at construction to build the coercion map and are not
+	* retained — the parser never holds a reference to the user's Mongoose
+	* schema.
 	*/
-	_fieldTypes;
+	rt;
 	/**
 	* Structured schema-index info (geo / text / other), built once from
-	* `options.schema?.indexes()`. Used by the operator router to validate
-	* geo operators against actual geo-indexed fields, and exposed publicly
-	* via `parser.schemaIndexes` for downstream tools (Arc MCP, query planners).
+	* `options.schema?.indexes()`. Exposed via `parser.schemaIndexes` for
+	* downstream tools (Arc MCP, query planners).
 	*/
 	_schemaIndexes;
-	/**
-	* Regex patterns that can cause catastrophic backtracking (ReDoS attacks).
-	* Detects common footguns:
-	* - Quantifiers: {n,m}
-	* - Possessive quantifiers: *+, ++, ?+
-	* - Nested quantifiers: (a+)+, (a*)*
-	* - Backreferences: \1, \2, etc.
-	* - Complex character classes: [...]...[...]
-	*
-	* This pattern detector is FAIL-SAFE (on match, the input is escaped), but
-	* it is not exhaustive. {@link _regexComplexityExceedsBudget} complements
-	* it with a deterministic static complexity budget so patterns that happen
-	* to evade the detector still fail over when their unbounded-quantifier
-	* density is pathological.
-	*/
-	dangerousRegexPatterns = /(\{[0-9,]+\}|\*\+|\+\+|\?\+|(\(.+\))\+|\(\?:|\\[0-9]|(\[.+\]).+(\[.+\]))/;
-	/**
-	* Static complexity budget for user-supplied regex patterns.
-	* Returns `true` if the pattern crosses a budget that empirically correlates
-	* with ReDoS risk — independent of the heuristic regex detector.
-	*
-	* Budget components (any single threshold crossed → over budget):
-	*   - unbounded quantifiers (`*`, `+`, `?`) — hard cap 20
-	*   - nested groups `(` — hard cap 8
-	*   - alternations `|` — hard cap 10
-	*   - combined: (quantifiers * groups) — hard cap 40
-	*
-	* These thresholds are intentionally permissive for legitimate queries and
-	* tight enough to refuse known-pathological patterns like `(a+)+b` with
-	* heavy repetition.
-	*/
-	_regexComplexityExceedsBudget(patternStr) {
-		const stripped = patternStr.replace(/\\[^\\]/g, "");
-		const unboundedQuantifiers = (stripped.match(/[*+?]/g) ?? []).length;
-		const groups = (stripped.match(/\(/g) ?? []).length;
-		const alternations = (stripped.match(/\|/g) ?? []).length;
-		if (unboundedQuantifiers > 20) return true;
-		if (groups > 8) return true;
-		if (alternations > 10) return true;
-		if (unboundedQuantifiers * groups > 40) return true;
-		return false;
-	}
 	constructor(options = {}) {
-		this.options = {
+		const resolved = {
+			invalidInput: options.invalidInput ?? "throw",
 			maxRegexLength: options.maxRegexLength ?? 500,
 			maxSearchLength: options.maxSearchLength ?? 200,
 			maxFilterDepth: options.maxFilterDepth ?? 10,
@@ -329,28 +1226,23 @@ var QueryParser = class {
 			allowedSortFields: options.allowedSortFields,
 			allowedOperators: options.allowedOperators
 		};
-		if (this.options.searchMode === "regex" && (!this.options.searchFields || this.options.searchFields.length === 0)) {
+		if (resolved.searchMode === "regex" && (!resolved.searchFields || resolved.searchFields.length === 0)) {
 			warn("[mongokit] searchMode \"regex\" requires searchFields to be specified. Falling back to \"text\" mode.");
-			this.options.searchMode = "text";
+			resolved.searchMode = "text";
 		}
-		this.dangerousOperators = [
-			"$where",
-			"$function",
-			"$accumulator",
-			"$expr",
-			...this.options.additionalDangerousOperators
-		];
-		this._fieldTypes = buildFieldTypeMap(options.schema, options.fieldTypes);
+		this.rt = {
+			options: resolved,
+			operators: OPERATOR_MAP,
+			dangerousOperators: [...BASE_DANGEROUS_OPERATORS, ...resolved.additionalDangerousOperators],
+			fieldTypes: buildFieldTypeMap(options.schema, options.fieldTypes),
+			reject: createReject(resolved.invalidInput)
+		};
 		this._schemaIndexes = extractSchemaIndexes(options.schema);
 	}
 	/**
 	* Structured view of the configured schema's indexes — geo fields, text
 	* fields, and other compound indexes. Empty arrays when no schema was
-	* provided. Stable across the parser's lifetime; mutating the returned
-	* object does not affect parser behavior.
-	*
-	* Useful for downstream tooling (Arc MCP, query planners, doc generators)
-	* that needs to know which fields support which query types.
+	* provided. Stable across the parser's lifetime.
 	*/
 	get schemaIndexes() {
 		return this._schemaIndexes;
@@ -363,21 +1255,21 @@ var QueryParser = class {
 	* from the QueryParser when `schemaOptions.filterableFields` is not set.
 	*/
 	get allowedFilterFields() {
-		return this.options.allowedFilterFields;
+		return this.rt.options.allowedFilterFields;
 	}
 	/**
 	* Get the configured allowed sort fields.
 	* Returns `undefined` if no whitelist is set (all fields allowed).
 	*/
 	get allowedSortFields() {
-		return this.options.allowedSortFields;
+		return this.rt.options.allowedSortFields;
 	}
 	/**
 	* Get the configured allowed operators.
 	* Returns `undefined` if no whitelist is set (all built-in operators allowed).
 	*/
 	get allowedOperators() {
-		return this.options.allowedOperators;
+		return this.rt.options.allowedOperators;
 	}
 	/**
 	* Parse URL query parameters into MongoDB query format
@@ -390,25 +1282,25 @@ var QueryParser = class {
 	* ```
 	*/
 	parse(query) {
+		const rt = this.rt;
 		const { page, limit = 20, sort = "-createdAt", populate, search, after, cursor, select, lookup, aggregate, ...filters } = query || {};
-		let parsedLimit = parseInt(String(limit), 10);
-		if (Number.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;
+		let parsedLimit = parsePositiveInt(rt, limit, "limit") ?? 20;
+		if (parsedLimit > rt.options.maxLimit) {
+			warn(`[mongokit] Limit ${parsedLimit} exceeds maximum ${rt.options.maxLimit}, capping to max`);
+			parsedLimit = rt.options.maxLimit;
 		}
-		const sanitizedSearch = this._sanitizeSearch(search);
-		const { simplePopulate, populateOptions } = this._parsePopulate(populate);
+		const sanitizedSearch = sanitizeSearch(rt, search);
+		const { simplePopulate, populateOptions } = parsePopulate(rt, populate);
 		const parsed = {
-			filters: this._parseFilters(filters),
+			filters: parseFilters(rt, filters),
 			limit: parsedLimit,
-			sort: this._parseSort(sort),
+			sort: parseSort(rt, sort),
 			populate: simplePopulate,
 			populateOptions,
 			search: sanitizedSearch
 		};
-		if (sanitizedSearch && this.options.searchMode === "regex" && this.options.searchFields) {
-			const regexSearchFilters = this._buildRegexSearch(sanitizedSearch);
+		if (sanitizedSearch && rt.options.searchMode === "regex" && rt.options.searchFields) {
+			const regexSearchFilters = buildRegexSearch(rt, sanitizedSearch);
 			if (regexSearchFilters) {
 				if (parsed.filters.$or) {
 					parsed.filters = {
@@ -420,97 +1312,28 @@ var QueryParser = class {
 				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 (select) parsed.select = parseSelect(select);
+		if (rt.options.enableLookups && lookup) parsed.lookups = parseLookups(rt, lookup);
+		if (rt.options.enableAggregations && aggregate) parsed.aggregation = parseAggregation(rt, aggregate);
 		if (after || cursor) parsed.after = String(after || cursor);
-		if (page !== void 0) parsed.page = parseInt(String(page), 10);
-		const orGroup = this._parseOr(query);
+		const parsedPage = parsePositiveInt(rt, page, "page");
+		if (parsedPage !== void 0) parsed.page = parsedPage;
+		const orGroup = parseOr(rt, 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);
+		parsed.filters = enhanceWithBetween(rt, parsed.filters);
 		return parsed;
 	}
 	/**
 	* Generate OpenAPI-compatible JSON Schema for query parameters.
 	* Arc's defineResource() auto-detects this method and uses it
 	* to document list endpoint query parameters in OpenAPI/Swagger.
-	*
-	* The schema respects parser configuration:
-	* - `allowedOperators`: only documents allowed operators
-	* - `allowedFilterFields`: generates explicit field[op] entries
-	* - `enableLookups` / `enableAggregations`: includes/excludes lookup/aggregate params
-	* - `maxLimit` / `maxSearchLength`: reflected in schema constraints
 	*/
 	getQuerySchema() {
-		const properties = {
-			page: {
-				type: "integer",
-				description: "Page number for offset pagination",
-				default: 1,
-				minimum: 1
-			},
-			limit: {
-				type: "integer",
-				description: "Number of items per page",
-				default: 20,
-				minimum: 1,
-				maximum: this.options.maxLimit
-			},
-			sort: {
-				type: "string",
-				description: "Sort fields (comma-separated). Prefix with - for descending. Example: -createdAt,name"
-			},
-			search: {
-				type: "string",
-				description: this.options.searchMode === "regex" ? `Search across fields${this.options.searchFields ? ` (${this.options.searchFields.join(", ")})` : ""} using case-insensitive regex` : "Full-text search query (requires text index)",
-				maxLength: this.options.maxSearchLength
-			},
-			select: {
-				type: "string",
-				description: "Fields to include/exclude (comma-separated). Prefix with - to exclude. Example: name,email,-password"
-			},
-			populate: {
-				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",
-				description: "Cursor value for keyset pagination"
-			}
-		};
-		if (this.options.enableLookups) properties.lookup = {
-			type: "object",
-			description: "Custom field lookups ($lookup). Example: lookup[department]=slug or lookup[department][localField]=deptId&lookup[department][foreignField]=_id"
-		};
-		if (this.options.enableAggregations) properties.aggregate = {
-			type: "object",
-			description: "Aggregation pipeline stages. Supports: group, match, sort, project. Example: aggregate[group][_id]=$status"
-		};
-		const availableOperators = this.options.allowedOperators ? Object.entries(this.operators).filter(([key]) => this.options.allowedOperators?.includes(key)) : Object.entries(this.operators);
-		if (this.options.allowedFilterFields && this.options.allowedFilterFields.length > 0) for (const field of this.options.allowedFilterFields) {
-			properties[field] = {
-				type: "string",
-				description: `Filter by ${field} (exact match)`
-			};
-			for (const [op, mongoOp] of availableOperators) {
-				if (op === "eq") continue;
-				properties[`${field}[${op}]`] = {
-					type: this._getOperatorSchemaType(op),
-					description: this._getOperatorDescription(op, field, mongoOp)
-				};
-			}
-		}
-		return {
-			type: "object",
-			properties
-		};
+		return buildQuerySchema(this.rt);
 	}
 	/**
 	* Get the query schema with OpenAPI extensions (x-internal metadata).
@@ -519,681 +1342,7 @@ var QueryParser = class {
 	* For validation-only schemas, use `getQuerySchema()` instead.
 	*/
 	getOpenAPIQuerySchema() {
-		const schema = this.getQuerySchema();
-		const availableOperators = this.options.allowedOperators ? Object.entries(this.operators).filter(([key]) => this.options.allowedOperators?.includes(key)) : Object.entries(this.operators);
-		schema.properties._filterOperators = {
-			type: "string",
-			description: this._buildOperatorDescription(availableOperators),
-			"x-internal": true
-		};
-		return schema;
-	}
-	/**
-	* Get the JSON Schema type for a filter operator
-	*/
-	_getOperatorSchemaType(op) {
-		if ([
-			"gt",
-			"gte",
-			"lt",
-			"lte",
-			"size"
-		].includes(op)) return "number";
-		if (["exists"].includes(op)) return "boolean";
-		return "string";
-	}
-	/**
-	* Get a human-readable description for a filter operator
-	*/
-	_getOperatorDescription(op, field, mongoOp) {
-		return {
-			ne: `${field} not equal to value (${mongoOp})`,
-			gt: `${field} greater than value (${mongoOp})`,
-			gte: `${field} greater than or equal to value (${mongoOp})`,
-			lt: `${field} less than value (${mongoOp})`,
-			lte: `${field} less than or equal to value (${mongoOp})`,
-			in: `${field} in comma-separated list (${mongoOp}). Example: value1,value2`,
-			nin: `${field} not in comma-separated list (${mongoOp})`,
-			like: `${field} matches pattern (case-insensitive regex)`,
-			contains: `${field} contains substring (case-insensitive regex)`,
-			regex: `${field} matches regex pattern (${mongoOp})`,
-			exists: `Field ${field} exists (true/false)`,
-			size: `Array field ${field} has exactly N elements (${mongoOp})`,
-			type: `Field ${field} is of BSON type (${mongoOp})`
-		}[op] || `Filter ${field} with ${mongoOp}`;
-	}
-	/**
-	* Build a summary description of all available filter operators
-	*/
-	_buildOperatorDescription(operators) {
-		const lines = ["Available filter operators (use as field[operator]=value):"];
-		for (const [op, mongoOp] of operators) lines.push(`  ${op} → ${mongoOp}: ${{
-			eq: "Equal (default when no operator specified)",
-			ne: "Not equal",
-			gt: "Greater than",
-			gte: "Greater than or equal",
-			lt: "Less than",
-			lte: "Less than or equal",
-			in: "In list (comma-separated values)",
-			nin: "Not in list",
-			like: "Pattern match (case-insensitive)",
-			contains: "Contains substring (case-insensitive)",
-			regex: "Regex pattern",
-			exists: "Field exists (true/false)",
-			size: "Array size equals",
-			type: "BSON type check"
-		}[op] || op}`);
-		return lines.join("\n");
-	}
-	/**
-	* 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.select ? { select: String(opts.select) } : {},
-				...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") {
-			const paths = populate.split(",").map((p) => p.trim()).filter(Boolean);
-			if (paths.length > 0) return {
-				simplePopulate: populate,
-				populateOptions: paths.map((path) => ({ path }))
-			};
-			return {};
-		}
-		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 (!Number.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 (!Number.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] = coerceHeuristic(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 (isControlParam(key) || [
-				"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] = coerceFieldValue(key, value, this._fieldTypes);
-		}
-		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 (this.options.allowedOperators && !this.options.allowedOperators.includes(operator.toLowerCase())) {
-			warn(`[mongokit] Operator not in allowlist: ${operator}`);
-			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;
-		}
-		if (isGeoOperator(operator)) {
-			const geoFilter = parseGeoFilter(operator, value);
-			if (geoFilter) filters[field] = geoFilter;
-			else warn(`[mongokit] Invalid geo operator value for ${field}[${operator}]; dropping filter`);
-			return;
-		}
-		const mongoOperator = this._toMongoOperator(operator);
-		if (this.dangerousOperators.includes(mongoOperator)) {
-			warn(`[mongokit] Blocked dangerous operator: ${mongoOperator}`);
-			return;
-		}
-		if (mongoOperator === "$eq") filters[field] = coerceFieldValue(field, value, this._fieldTypes);
-		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 (op === "size") {
-				processedValue = parseFloat(String(value));
-				if (Number.isNaN(processedValue)) return;
-			} else if ([
-				"gt",
-				"gte",
-				"lt",
-				"lte"
-			].includes(op)) if (this._fieldTypes.has(field)) {
-				processedValue = coerceFieldValue(field, value, this._fieldTypes);
-				if (typeof processedValue === "number" && Number.isNaN(processedValue)) return;
-			} else {
-				processedValue = parseFloat(String(value));
-				if (Number.isNaN(processedValue)) return;
-			}
-			else if (op === "in" || op === "nin") processedValue = (Array.isArray(value) ? value : String(value).split(",").map((v) => v.trim())).map((elem) => coerceFieldValue(field, elem, this._fieldTypes));
-			else processedValue = coerceFieldValue(field, value, this._fieldTypes);
-			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;
-		}
-		for (const op of Object.keys(operators)) if (RESERVED_PAGINATION_KEYS.has(op)) warn(`[mongokit] Nested filter contains reserved key '${op}' at '${field}.${op}' — did you mean ?${op}=... at the top level? The nested value is ignored.`);
-		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 (isGeoOperator(operator)) {
-				const geoFilter = parseGeoFilter(operator, value);
-				if (geoFilter) parsedFilters[field] = geoFilter;
-				else {
-					warn(`[mongokit] Invalid geo operator value for ${field}[${operator}]; dropping filter`);
-					delete parsedFilters[field];
-				}
-				continue;
-			}
-			if (this.options.allowedOperators && !this.options.allowedOperators.includes(operator)) {
-				warn(`[mongokit] Operator not in allowlist: ${operator}`);
-				continue;
-			}
-			if (this.operators[operator]) {
-				const mongoOperator = this.operators[operator];
-				let processedValue;
-				if (operator === "size") {
-					processedValue = parseFloat(String(value));
-					if (Number.isNaN(processedValue)) continue;
-				} else if ([
-					"gt",
-					"gte",
-					"lt",
-					"lte"
-				].includes(operator)) if (this._fieldTypes.has(field)) {
-					processedValue = coerceFieldValue(field, value, this._fieldTypes);
-					if (typeof processedValue === "number" && Number.isNaN(processedValue)) continue;
-				} else {
-					processedValue = parseFloat(String(value));
-					if (Number.isNaN(processedValue)) continue;
-				}
-				else if (operator === "in" || operator === "nin") processedValue = (Array.isArray(value) ? value : String(value).split(",").map((v) => v.trim())).map((elem) => coerceFieldValue(field, elem, this._fieldTypes));
-				else if (operator === "like" || operator === "contains" || operator === "regex") {
-					const safeRegex = this._createSafeRegex(value);
-					if (!safeRegex) continue;
-					processedValue = safeRegex;
-				} else processedValue = coerceFieldValue(field, value, this._fieldTypes);
-				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);
-		}
-		if (this._regexComplexityExceedsBudget(patternStr)) {
-			warn("[mongokit] Regex complexity budget exceeded, 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, depth = 0) {
-		if (depth > this.options.maxFilterDepth) {
-			warn(`[mongokit] $match sanitize depth ${depth} exceeds maximum ${this.options.maxFilterDepth}, truncating branch`);
-			return {};
-		}
-		const sanitized = {};
-		const logicalArrayOps = /* @__PURE__ */ new Set([
-			"$or",
-			"$and",
-			"$nor"
-		]);
-		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, depth + 1);
-			else if (Array.isArray(value)) {
-				const sanitizedArray = value.map((item) => {
-					if (item && typeof item === "object" && !Array.isArray(item)) return this._sanitizeMatchConfig(item, depth + 1);
-					return item;
-				});
-				if (logicalArrayOps.has(key)) {
-					const filtered = sanitizedArray.filter((item) => !(item && typeof item === "object" && !Array.isArray(item) && Object.keys(item).length === 0));
-					if (filtered.length === 0) {
-						warn(`[mongokit] All branches of ${key} were blocked by sanitization; dropping the operator`);
-						continue;
-					}
-					sanitized[key] = filtered;
-				} else sanitized[key] = sanitizedArray;
-			} 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.
-	*
-	* Depth-guarded — same protection `_sanitizeMatchConfig` ships, since
-	* a hostile `$cond`/`$switch` chain can recurse arbitrarily deep and
-	* exhaust JS stack. Without the guard, this is a one-liner DoS against
-	* any host that exposes pipeline parsing to untrusted callers.
-	*/
-	_sanitizeExpressions(config, depth = 0) {
-		if (depth > this.options.maxFilterDepth) {
-			warn(`[mongokit] pipeline expression sanitize depth ${depth} exceeds maximum ${this.options.maxFilterDepth}, truncating branch`);
-			return {};
-		}
-		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, depth + 1);
-			else if (Array.isArray(value)) sanitized[key] = value.map((item) => {
-				if (item && typeof item === "object" && !Array.isArray(item)) return this._sanitizeExpressions(item, depth + 1);
-				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;
-	}
-	_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) {
-			const parsedBranch = this._parseFilters(item, 1);
-			if (Object.keys(parsedBranch).length > 0) orArray.push(parsedBranch);
-		}
-		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 && !Number.isNaN(fromDate.getTime())) range.$gte = fromDate;
-			if (toDate && !Number.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);
+		return buildOpenAPIQuerySchema(this.rt);
 	}
 };
 //#endregion
@@ -1462,4 +1611,4 @@ function systemContext(extra) {
 */
 var src_default = Repository;
 //#endregion
-export { ALL_OPERATIONS, AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, MONGOKIT_CAPABILITIES, MONGOKIT_PLUGIN_NAMES, MUTATING_OPERATIONS, OP_REGISTRY, PaginationEngine, QueryParser, READ_OPERATIONS, Repository, actions_exports as actions, adminBypass, aggregateHelpersPlugin, appendOnlyPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, cascadePurgeReferences, compileFilterToMongo, configureLogger, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, src_default as default, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, idVariants, immutableField, immutableStatesPlugin, isDuplicateKeyError, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, repoOptionsFromCtx, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, systemContext, timestampPlugin, toPlain, uniqueField, validationChainPlugin, withTransaction };
+export { ALL_OPERATIONS, AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, MONGOKIT_CAPABILITIES, MONGOKIT_PLUGIN_NAMES, MUTATING_OPERATIONS, OP_REGISTRY, PaginationEngine, QueryParser, READ_OPERATIONS, Repository, actions_exports as actions, adminBypass, aggregateHelpersPlugin, appendOnlyPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, cascadePurgeReferences, compileFilterToMongo, configureLogger, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, src_default as default, elasticSearchPlugin, ensureAuditTrailReady, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, idVariants, immutableField, immutableStatesPlugin, isDuplicateKeyError, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, repoOptionsFromCtx, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, systemContext, timestampPlugin, toPlain, uniqueField, validationChainPlugin, withTransaction };