@classytic/mongokit 3.5.3 → 3.5.5

package/dist/index.mjs

@@ -1,11 +1,13 @@
 import { a as warn, n as parseDuplicateKeyError, r as configureLogger, t as createError } from "./error-Bpbi_NKo.mjs";
 import { y as LookupBuilder } from "./update-AVfKWNGt.mjs";
 import { t as actions_exports } from "./actions/index.mjs";
-import { t as PaginationEngine } from "./PaginationEngine-DCs-zKwZ.mjs";
-import { A as aggregateHelpersPlugin, C as HOOK_PRIORITY, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as cachePlugin, T as AggregationBuilder, _ as dateSequentialId, a as uniqueField, b as sequentialId, c as subdocumentPlugin, d as multiTenantPlugin, f as mongoOperationsPlugin, g as customIdPlugin, h as elasticSearchPlugin, i as requireField, k as auditLogPlugin, l as softDeletePlugin, m as fieldFilterPlugin, n as blockIf, o as validationChainPlugin, p as methodRegistryPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as observabilityPlugin, v as getNextSequence, w as Repository, x as cascadePlugin, y as prefixedId } from "./validation-chain.plugin-KjPV_6_N.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-CpsQl471.mjs";
+import { A as aggregateHelpersPlugin, C as HOOK_PRIORITY, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as cachePlugin, T as AggregationBuilder, _ as dateSequentialId, a as uniqueField, b as sequentialId, c as subdocumentPlugin, d as multiTenantPlugin, f as mongoOperationsPlugin, g as customIdPlugin, h as elasticSearchPlugin, i as requireField, k as auditLogPlugin, l as softDeletePlugin, m as fieldFilterPlugin, n as blockIf, o as validationChainPlugin, p as methodRegistryPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as observabilityPlugin, v as getNextSequence, w as Repository, x as cascadePlugin, y as prefixedId } from "./validation-chain.plugin-BCPh2UZG.mjs";
+import { isGeoOperator, parseGeoFilter } from "./query/primitives/geo.mjs";
 import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "./field-selection-reyDRzXf.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-B6Qyl8BK.mjs";
-import mongoose from "mongoose";
+import { buildFieldTypeMap, coerceFieldValue, coerceHeuristic } from "./query/primitives/coercion.mjs";
+import { extractSchemaIndexes } from "./query/primitives/indexes.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-DpjhFfaO.mjs";
 //#region src/query/QueryParser.ts
 /**
 * Modern Query Parser
@@ -31,6 +33,21 @@ var QueryParser = class {
 	};
 	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.
+	*/
+	_fieldTypes;
+	/**
+	* 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).
+	*/
+	_schemaIndexes;
+	/**
 	* Regex patterns that can cause catastrophic backtracking (ReDoS attacks)
 	* Detects:
 	* - Quantifiers: {n,m}
@@ -67,6 +84,20 @@ var QueryParser = class {
 			"$expr",
 			...this.options.additionalDangerousOperators
 		];
+		this._fieldTypes = buildFieldTypeMap(options.schema, options.fieldTypes);
+		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.
+	*/
+	get schemaIndexes() {
+		return this._schemaIndexes;
 	}
 	/**
 	* Get the configured allowed filter fields.
@@ -520,7 +551,7 @@ var QueryParser = class {
 	*/
 	_convertPopulateMatch(match) {
 		const converted = {};
-		for (const [key, value] of Object.entries(match)) converted[key] = this._convertValue(value);
+		for (const [key, value] of Object.entries(match)) converted[key] = coerceHeuristic(value);
 		return converted;
 	}
 	/**
@@ -569,7 +600,7 @@ var QueryParser = class {
 				continue;
 			}
 			if (typeof value === "object" && value !== null && !Array.isArray(value)) this._handleBracketSyntax(key, value, parsedFilters, depth + 1);
-			else parsedFilters[key] = this._convertValue(value);
+			else parsedFilters[key] = coerceFieldValue(key, value, this._fieldTypes);
 		}
 		return parsedFilters;
 	}
@@ -597,12 +628,18 @@ var QueryParser = class {
 			}
 			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] = value;
+		if (mongoOperator === "$eq") filters[field] = coerceFieldValue(field, value, this._fieldTypes);
 		else if (mongoOperator === "$regex") {
 			const safeRegex = this._createSafeRegex(value);
 			if (safeRegex) {
@@ -612,17 +649,23 @@ var QueryParser = class {
 		} else {
 			let processedValue;
 			const op = operator.toLowerCase();
-			if ([
+			if (op === "size") {
+				processedValue = parseFloat(String(value));
+				if (Number.isNaN(processedValue)) return;
+			} else if ([
 				"gt",
 				"gte",
 				"lt",
-				"lte",
-				"size"
-			].includes(op)) {
+				"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());
-			else processedValue = this._convertValue(value);
+			}
+			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;
 		}
@@ -642,6 +685,15 @@ var QueryParser = class {
 				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;
@@ -649,21 +701,27 @@ var QueryParser = class {
 			if (this.operators[operator]) {
 				const mongoOperator = this.operators[operator];
 				let processedValue;
-				if ([
+				if (operator === "size") {
+					processedValue = parseFloat(String(value));
+					if (Number.isNaN(processedValue)) continue;
+				} else if ([
 					"gt",
 					"gte",
 					"lt",
-					"lte",
-					"size"
-				].includes(operator)) {
+					"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());
+				}
+				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 = this._convertValue(value);
+				} else processedValue = coerceFieldValue(field, value, this._fieldTypes);
 				parsedFilters[field][mongoOperator] = processedValue;
 			}
 		}
@@ -727,17 +785,31 @@ var QueryParser = class {
 	*/
 	_sanitizeMatchConfig(config) {
 		const sanitized = {};
+		const logicalArrayOps = 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);
-			else if (Array.isArray(value)) sanitized[key] = value.map((item) => {
-				if (item && typeof item === "object" && !Array.isArray(item)) return this._sanitizeMatchConfig(item);
-				return item;
-			});
-			else sanitized[key] = value;
+			else if (Array.isArray(value)) {
+				const sanitizedArray = value.map((item) => {
+					if (item && typeof item === "object" && !Array.isArray(item)) return this._sanitizeMatchConfig(item);
+					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;
 	}
@@ -822,22 +894,15 @@ var QueryParser = class {
 		for (const field of this.options.searchFields) orConditions.push({ [field]: { $regex: safeRegex } });
 		return orConditions.length > 0 ? orConditions : null;
 	}
-	_convertValue(value) {
-		if (value === null || value === void 0) return value;
-		if (Array.isArray(value)) return value.map((v) => this._convertValue(v));
-		if (typeof value === "object") return value;
-		const stringValue = String(value);
-		if (stringValue === "true") return true;
-		if (stringValue === "false") return false;
-		if (mongoose.Types.ObjectId.isValid(stringValue) && stringValue.length === 24) return stringValue;
-		return stringValue;
-	}
 	_parseOr(query) {
 		const orArray = [];
 		const raw = query?.or || query?.OR || query?.$or;
 		if (!raw) return void 0;
 		const items = Array.isArray(raw) ? raw : typeof raw === "object" ? Object.values(raw) : [];
-		for (const item of items) if (typeof item === "object" && item) orArray.push(this._parseFilters(item, 1));
+		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) {

package/dist/indexes-CiIT-Zli.d.mts

@@ -0,0 +1,41 @@
+//#region src/query/primitives/indexes.d.ts
+/**
+ * Schema index introspection
+ *
+ * Pure functions that read a Mongoose-like schema's `.indexes()` output and
+ * extract structured information about which fields are indexed how. Used by
+ * QueryParser to:
+ *
+ *   - Detect 2dsphere/2d-indexed fields → enable geo operator routing.
+ *   - Detect text-indexed fields → expose to repositories that need it.
+ *   - Surface compound index hints → useful for query planners and Arc MCP
+ *     auto-generation.
+ *
+ * Stays decoupled from a specific Mongoose major version: only depends on
+ * `.indexes()` returning a list of `[indexSpec, options?]` tuples, which has
+ * been stable since Mongoose 4.x.
+ */
+/** Minimal structural type for a Mongoose-like schema. */
+interface IndexableSchema {
+  indexes(): Array<[Record<string, unknown>, Record<string, unknown>?]>;
+}
+/** Structured view of a schema's indexes, indexed by purpose. */
+interface SchemaIndexes {
+  /** Field paths with a 2dsphere or 2d index — eligible for geo operators */
+  geoFields: string[];
+  /** Field paths with a text index — eligible for $text queries */
+  textFields: string[];
+  /** All other indexes as raw spec/options pairs (for hints, plan analysis) */
+  other: Array<{
+    spec: Record<string, unknown>;
+    options?: Record<string, unknown>;
+  }>;
+}
+/**
+ * Extract structured index information from a Mongoose schema. Returns an
+ * empty `SchemaIndexes` shape (not null) when no schema is provided so callers
+ * can read `.geoFields`/`.textFields` unconditionally without null checks.
+ */
+declare function extractSchemaIndexes(schema?: IndexableSchema | null): SchemaIndexes;
+//#endregion
+export { SchemaIndexes as n, extractSchemaIndexes as r, IndexableSchema as t };

package/dist/{mongooseToJsonSchema-BivI9LWt.d.mts → mongooseToJsonSchema-BlDfbg_0.d.mts}

@@ -1,4 +1,4 @@
-import { T as FieldPreset, _ as CrudSchemas, k as HttpError, ot as SchemaBuilderOptions, s as CacheAdapter, xt as ValidationResult, yt as UserContext } from "./types-wCkH8jE3.mjs";
+import { T as FieldPreset, _ as CrudSchemas, k as HttpError, ot as SchemaBuilderOptions, s as CacheAdapter, xt as ValidationResult, yt as UserContext } from "./types-CWUL0yiw.mjs";
 import mongoose, { Schema } from "mongoose";
 
 //#region src/utils/error.d.ts

package/dist/{mongooseToJsonSchema-B6Qyl8BK.mjs → mongooseToJsonSchema-DpjhFfaO.mjs}

@@ -154,6 +154,11 @@ function buildJsonSchemaFromPaths(mongooseSchema, options) {
 	const properties = {};
 	const required = [];
 	const paths = mongooseSchema.paths;
+	const softRequiredSet = new Set(options?.softRequiredFields ?? []);
+	const isSoftRequired = (name, schemaType) => {
+		if (softRequiredSet.has(name)) return true;
+		return schemaType?.options?.softRequired === true;
+	};
 	const rootFields = /* @__PURE__ */ new Map();
 	for (const [path, schemaType] of Object.entries(paths)) {
 		if (path === "_id" || path === "__v") continue;
@@ -167,7 +172,7 @@ function buildJsonSchemaFromPaths(mongooseSchema, options) {
 	for (const [rootField, fieldPaths] of rootFields.entries()) if (fieldPaths.length === 1 && fieldPaths[0].path === rootField) {
 		const schemaType = fieldPaths[0].schemaType;
 		properties[rootField] = schemaTypeToJsonSchema(schemaType);
-		if (schemaType.isRequired) required.push(rootField);
+		if (schemaType.isRequired && !isSoftRequired(rootField, schemaType)) required.push(rootField);
 	} else {
 		const nestedSchema = buildNestedJsonSchema(fieldPaths, rootField);
 		properties[rootField] = nestedSchema.schema;

package/dist/pagination/PaginationEngine.d.mts

@@ -1,4 +1,4 @@
-import { F as KeysetPaginationResult, G as PaginationConfig, H as OffsetPaginationOptions, P as KeysetPaginationOptions, U as OffsetPaginationResult, a as AnyDocument, n as AggregatePaginationOptions, r as AggregatePaginationResult } from "../types-wCkH8jE3.mjs";
+import { F as KeysetPaginationResult, G as PaginationConfig, H as OffsetPaginationOptions, P as KeysetPaginationOptions, U as OffsetPaginationResult, a as AnyDocument, n as AggregatePaginationOptions, r as AggregatePaginationResult } from "../types-CWUL0yiw.mjs";
 import { Model } from "mongoose";
 
 //#region src/pagination/PaginationEngine.d.ts

package/dist/pagination/PaginationEngine.mjs

@@ -1,2 +1,2 @@
-import { t as PaginationEngine } from "../PaginationEngine-DCs-zKwZ.mjs";
+import { t as PaginationEngine } from "../PaginationEngine-CpsQl471.mjs";
 export { PaginationEngine };

package/dist/plugins/index.d.mts

@@ -1,2 +1,2 @@
-import { A as dateSequentialId, B as AuditEntry, C as elasticSearchPlugin, D as PrefixedIdOptions, E as IdGenerator, F as CacheMethods, G as AuditTrailOptions, H as AuditQueryOptions, I as cachePlugin, J as auditLogPlugin, K as AuditTrailQuery, L as BatchOperationsMethods, M as prefixedId, N as sequentialId, O as SequentialIdOptions, P as cascadePlugin, S as ElasticSearchOptions, T as DateSequentialIdOptions, U as AuditQueryResult, V as AuditOperation, W as AuditTrailMethods, X as aggregateHelpersPlugin, Y as AggregateHelpersMethods, _ as MongoOperationsMethods, a as uniqueField, b as methodRegistryPlugin, c as SubdocumentMethods, d as softDeletePlugin, f as ObservabilityOptions, g as multiTenantPlugin, h as MultiTenantOptions, i as requireField, j as getNextSequence, k as customIdPlugin, l as subdocumentPlugin, m as observabilityPlugin, n as blockIf, o as validationChainPlugin, p as OperationMetric, q as auditTrailPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as SoftDeleteMethods, v as mongoOperationsPlugin, w as CustomIdOptions, x as fieldFilterPlugin, y as MethodRegistryRepository, z as batchOperationsPlugin } from "../validation-chain.plugin-CGE_mKQr.mjs";
+import { A as dateSequentialId, B as AuditEntry, C as elasticSearchPlugin, D as PrefixedIdOptions, E as IdGenerator, F as CacheMethods, G as AuditTrailOptions, H as AuditQueryOptions, I as cachePlugin, J as auditLogPlugin, K as AuditTrailQuery, L as BatchOperationsMethods, M as prefixedId, N as sequentialId, O as SequentialIdOptions, P as cascadePlugin, S as ElasticSearchOptions, T as DateSequentialIdOptions, U as AuditQueryResult, V as AuditOperation, W as AuditTrailMethods, X as aggregateHelpersPlugin, Y as AggregateHelpersMethods, _ as MongoOperationsMethods, a as uniqueField, b as methodRegistryPlugin, c as SubdocumentMethods, d as softDeletePlugin, f as ObservabilityOptions, g as multiTenantPlugin, h as MultiTenantOptions, i as requireField, j as getNextSequence, k as customIdPlugin, l as subdocumentPlugin, m as observabilityPlugin, n as blockIf, o as validationChainPlugin, p as OperationMetric, q as auditTrailPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as SoftDeleteMethods, v as mongoOperationsPlugin, w as CustomIdOptions, x as fieldFilterPlugin, y as MethodRegistryRepository, z as batchOperationsPlugin } from "../validation-chain.plugin-Dn41aAbK.mjs";
 export { type AggregateHelpersMethods, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BatchOperationsMethods, type CacheMethods, type CustomIdOptions, type DateSequentialIdOptions, type ElasticSearchOptions, type IdGenerator, type MethodRegistryRepository, type MongoOperationsMethods, type MultiTenantOptions, type ObservabilityOptions, type OperationMetric, type PrefixedIdOptions, type SequentialIdOptions, type SoftDeleteMethods, type SubdocumentMethods, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, getNextSequence, immutableField, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin };

package/dist/plugins/index.mjs

@@ -1,2 +1,2 @@
-import { A as aggregateHelpersPlugin, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as cachePlugin, _ as dateSequentialId, a as uniqueField, b as sequentialId, c as subdocumentPlugin, d as multiTenantPlugin, f as mongoOperationsPlugin, g as customIdPlugin, h as elasticSearchPlugin, i as requireField, k as auditLogPlugin, l as softDeletePlugin, m as fieldFilterPlugin, n as blockIf, o as validationChainPlugin, p as methodRegistryPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as observabilityPlugin, v as getNextSequence, x as cascadePlugin, y as prefixedId } from "../validation-chain.plugin-KjPV_6_N.mjs";
+import { A as aggregateHelpersPlugin, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as cachePlugin, _ as dateSequentialId, a as uniqueField, b as sequentialId, c as subdocumentPlugin, d as multiTenantPlugin, f as mongoOperationsPlugin, g as customIdPlugin, h as elasticSearchPlugin, i as requireField, k as auditLogPlugin, l as softDeletePlugin, m as fieldFilterPlugin, n as blockIf, o as validationChainPlugin, p as methodRegistryPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as observabilityPlugin, v as getNextSequence, x as cascadePlugin, y as prefixedId } from "../validation-chain.plugin-BCPh2UZG.mjs";
 export { AuditTrailQuery, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, getNextSequence, immutableField, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin };

package/dist/query/primitives/coercion.d.mts

@@ -0,0 +1,2 @@
+import { a as coerceHeuristic, i as coerceFieldValue, n as SchemaPathsLike, o as coerceToType, r as buildFieldTypeMap, s as normalizeMongooseType, t as FieldType } from "../../coercion-01tEHsKF.mjs";
+export { FieldType, SchemaPathsLike, buildFieldTypeMap, coerceFieldValue, coerceHeuristic, coerceToType, normalizeMongooseType };

package/dist/query/primitives/coercion.mjs

@@ -0,0 +1,147 @@
+import mongoose from "mongoose";
+//#region src/query/primitives/coercion.ts
+/**
+* Value coercion primitives
+*
+* Pure functions that convert raw URL-decoded values into typed values
+* suitable for MongoDB queries. Two layers:
+*
+*   1. `coerceHeuristic(value)` — string-shape based, used when no schema
+*      is configured. Safe defaults: rejects leading zeros, scientific
+*      notation, and strings >15 chars to preserve zip codes, phone codes,
+*      and long numeric IDs that exceed JS safe-integer precision.
+*
+*   2. `coerceToType(value, type)` — type-directed, used when a Mongoose
+*      schema or `fieldTypes` map declares the field's type. Strictly
+*      better than the heuristic when type information is available.
+*
+* QueryParser composes these via `coerceFieldValue(field, value, types)`
+* which prefers the type-directed path and falls back to the heuristic.
+*
+* Field-type extraction from a Mongoose schema is also here so the
+* normalization logic lives next to the coercion that consumes it.
+*/
+/**
+* Map a Mongoose `SchemaType.instance` string to our normalized FieldType.
+* For arrays (`type: [Number]` or `type: [{ type: Number }]`), Mongoose
+* stores the element type on `embeddedSchemaType.instance` (Mongoose 8+) or
+* `caster.instance` (older). We probe both — element-level coercion is what
+* `[in]`/`[nin]` operators need against typed arrays.
+*
+* Returns null for paths we cannot classify (embedded documents handled by
+* their own nested paths).
+*/
+function normalizeMongooseType(schemaType) {
+	const raw = schemaType.embeddedSchemaType?.instance ?? schemaType.caster?.instance ?? schemaType.instance;
+	if (!raw) return null;
+	switch (raw) {
+		case "String": return "string";
+		case "Number": return "number";
+		case "Boolean": return "boolean";
+		case "Date": return "date";
+		case "ObjectID":
+		case "ObjectId": return "objectid";
+		case "Mixed": return "mixed";
+		default: return null;
+	}
+}
+/**
+* Build a normalized field-type map from a Mongoose schema and an optional
+* override map. The override wins on a per-path basis. Paths with unmappable
+* types are silently skipped — `coerceFieldValue` will fall back to the
+* heuristic for them.
+*/
+function buildFieldTypeMap(schema, overrides) {
+	const map = /* @__PURE__ */ new Map();
+	if (schema?.paths) for (const [path, schemaType] of Object.entries(schema.paths)) {
+		const normalized = normalizeMongooseType(schemaType);
+		if (normalized) map.set(path, normalized);
+	}
+	if (overrides) for (const [path, type] of Object.entries(overrides)) map.set(path, type);
+	return map;
+}
+/**
+* String-shape heuristic — used when no field type is known.
+*
+* Rules (deliberately conservative — silent miscoercion is worse than
+* leaving a string):
+*   - `null`/`undefined` pass through
+*   - Already-typed primitives (number, boolean) pass through
+*   - Arrays recurse element-wise
+*   - Objects pass through (filter operator objects, etc.)
+*   - `'true'`/`'false'` → boolean
+*   - 24-char hex → kept as string (ObjectId)
+*   - Strings 1–15 chars matching `^-?(0|[1-9]\d*)(\.\d+)?$` → number
+*     (rejects leading zeros, scientific notation, hex/octal, NaN, Infinity)
+*   - Everything else stays a string
+*/
+function coerceHeuristic(value) {
+	if (value === null || value === void 0) return value;
+	if (Array.isArray(value)) return value.map((v) => coerceHeuristic(v));
+	if (typeof value === "object") return value;
+	if (typeof value === "number" || typeof value === "boolean") return value;
+	const s = String(value);
+	if (s === "true") return true;
+	if (s === "false") return false;
+	if (mongoose.Types.ObjectId.isValid(s) && s.length === 24) return s;
+	if (s.length > 0 && s.length <= 15 && /^-?(?:0|[1-9]\d*)(?:\.\d+)?$/.test(s)) {
+		const n = Number(s);
+		if (Number.isFinite(n)) return n;
+	}
+	return s;
+}
+/**
+* Type-directed coercion — used when a field's declared type is known.
+*
+* Returns the original value unchanged when coercion is impossible
+* (invalid date, non-numeric string for a Number field) — better to surface
+* a no-match than to silently produce `Invalid Date` or `NaN` which MongoDB
+* treats as legitimate query values.
+*/
+function coerceToType(value, type) {
+	if (value === null || value === void 0) return value;
+	if (Array.isArray(value)) return value.map((v) => coerceToType(v, type));
+	if (typeof value === "object") return value;
+	switch (type) {
+		case "number": {
+			if (typeof value === "number") return value;
+			const num = Number(String(value));
+			return Number.isFinite(num) ? num : value;
+		}
+		case "boolean": {
+			if (typeof value === "boolean") return value;
+			const s = String(value).toLowerCase();
+			if (s === "true" || s === "1") return true;
+			if (s === "false" || s === "0") return false;
+			return value;
+		}
+		case "date": {
+			if (value instanceof Date) return value;
+			const d = new Date(String(value));
+			return Number.isNaN(d.getTime()) ? value : d;
+		}
+		case "objectid": {
+			const sv = String(value);
+			if (mongoose.Types.ObjectId.isValid(sv) && sv.length === 24) return sv;
+			return value;
+		}
+		case "string": return String(value);
+		case "mixed": return coerceHeuristic(value);
+	}
+}
+/**
+* Field-aware coercion. Looks up `field` in `types` and uses
+* `coerceToType` when found, otherwise falls back to `coerceHeuristic`.
+*
+* This is the single choke point QueryParser uses for typed coercion of
+* direct equality, `[eq]`, `[in]`, `[nin]`, `[gt]`/`[gte]`/`[lt]`/`[lte]`
+* (the last only when a type is declared — see QueryParser for the
+* preserves-pre-3.5.5-behavior fallback).
+*/
+function coerceFieldValue(field, value, types) {
+	const type = types.get(field);
+	if (!type) return coerceHeuristic(value);
+	return coerceToType(value, type);
+}
+//#endregion
+export { buildFieldTypeMap, coerceFieldValue, coerceHeuristic, coerceToType, normalizeMongooseType };

package/dist/query/primitives/geo.d.mts

@@ -0,0 +1,116 @@
+//#region src/query/primitives/geo.d.ts
+/**
+ * Geo query primitives
+ *
+ * Pure functions that translate ergonomic URL syntax into the canonical
+ * GeoJSON-shaped MongoDB query operators ($near, $nearSphere, $geoWithin).
+ *
+ * Coordinate convention: ALWAYS lng,lat (matches GeoJSON, opposite of Google
+ * Maps' lat,lng). The parser is responsible for documenting this so users
+ * don't pass coordinates in the wrong order.
+ *
+ * These functions are pure (no `this`, no I/O) and unit-testable in isolation.
+ * QueryParser orchestrates by calling them when it sees a `[near]`,
+ * `[nearSphere]`, or `[geoWithin]` operator on a field.
+ */
+/** Geo operators recognized by the parser */
+declare const GEO_OPERATORS: readonly ["near", "nearSphere", "geoWithin", "withinRadius"];
+type GeoOperator = (typeof GEO_OPERATORS)[number];
+/**
+ * True iff `operator` is one of the geo operators we handle.
+ * Used by the operator router in QueryParser to short-circuit before the
+ * generic numeric/string operator handling kicks in.
+ */
+declare function isGeoOperator(operator: string): operator is GeoOperator;
+/**
+ * Parse a comma-separated coordinate list into numbers, validating each value
+ * is a finite number. Returns null on any parse failure — callers must treat
+ * null as "drop this filter entirely" rather than substituting defaults
+ * (which would silently widen the query).
+ */
+declare function parseCoordinateList(raw: unknown): number[] | null;
+/**
+ * Validate a [lng, lat] pair against MongoDB's accepted ranges.
+ * Longitude: [-180, 180]. Latitude: [-90, 90]. Out-of-range coordinates
+ * return false so the parser can drop the filter — emitting a $near query
+ * with `coordinates: [999, 40]` would either error inside Mongo or worse,
+ * silently behave unexpectedly.
+ */
+declare function isValidLngLat(lng: number, lat: number): boolean;
+/**
+ * Build a `$near` or `$nearSphere` filter for a single field from a coordinate
+ * list. Accepts:
+ *   [lng, lat]                — proximity sort, no distance bound
+ *   [lng, lat, maxDistance]   — proximity sort within `maxDistance` meters
+ *
+ * Returns null on any validation failure (drop the filter).
+ */
+declare function buildNearFilter(variant: 'near' | 'nearSphere', coords: number[]): Record<string, unknown> | null;
+/**
+ * Build a `$geoWithin: $centerSphere` filter from [lng, lat, radiusMeters].
+ *
+ * IMPORTANT: this is the count-compatible alternative to `$near`. MongoDB
+ * forbids `$near` / `$nearSphere` in any context that requires sorting (which
+ * `countDocuments`, `$lookup`, `$facet`, and several others do), because they
+ * are themselves sort operators. `$geoWithin: $centerSphere` is a *filter*
+ * operator, returns the same set of documents within a radius, and works
+ * everywhere `$near` does not — including paginated `Repository.getAll`.
+ *
+ * Use `[near]` when you want results sorted by distance and don't need a
+ * total count. Use `[withinRadius]` for pagination, counts, and joins.
+ *
+ * `$centerSphere` takes the radius in radians, so we convert from the
+ * caller-friendly meters using Earth's equatorial radius.
+ */
+declare function buildWithinRadiusFilter(coords: number[]): Record<string, unknown> | null;
+/**
+ * Build a `$geoWithin: $box` filter from a 4-element coordinate list:
+ *   [minLng, minLat, maxLng, maxLat]
+ *
+ * Returns null on any validation failure (drop the filter).
+ */
+declare function buildGeoWithinBoxFilter(coords: number[]): Record<string, unknown> | null;
+/**
+ * Rewrite a filter object that contains `$near` / `$nearSphere` into an
+ * equivalent count-compatible filter using `$geoWithin: $centerSphere`.
+ *
+ * Background: MongoDB refuses `countDocuments` on any query that uses a
+ * sort-operator like `$near` (they consume the query plan slot that count
+ * would use). The equivalent `$geoWithin: $centerSphere` is NOT a sort
+ * operator and counts/composes freely — and since both are evaluated
+ * against the same 2dsphere index, they return the same document set.
+ *
+ * This lets Repository run `find().sort(...)` with `$near` for the page
+ * results AND `countDocuments()` with the rewritten filter for the total,
+ * without ever breaking the parser → repo contract.
+ *
+ * Returns null when:
+ *   - `filters` is not an object
+ *   - No `$near` / `$nearSphere` is present (caller can use filters as-is)
+ *   - A `$near` operator lacks `$maxDistance` (unbounded — cannot be
+ *     rewritten to a bounded `$centerSphere`; caller should fall back to
+ *     `countStrategy: 'none'`)
+ */
+declare function rewriteNearForCount(filters: unknown): Record<string, unknown> | null;
+/**
+ * Detect whether a Mongo filter object contains a `$near` or `$nearSphere`
+ * operator on any field at the top level. These are SORT operators in
+ * MongoDB — they cannot coexist with an explicit `.sort()` clause and they
+ * cannot be used with `countDocuments`. Repositories must check this before
+ * injecting their default sort or running a count.
+ *
+ * Walks the top level only. Geo operators nested inside `$or` / `$and` are
+ * also forbidden by MongoDB so we check those one level down too.
+ *
+ * Returns false for falsy / non-object inputs.
+ */
+declare function hasNearOperator(filters: unknown): boolean;
+/**
+ * High-level entry point: given an operator name and the raw value from the
+ * URL, return the MongoDB filter for that field — or null if the operator is
+ * not a geo operator (caller should fall through to normal handling) or the
+ * value is invalid (caller should drop the filter).
+ */
+declare function parseGeoFilter(operator: string, raw: unknown): Record<string, unknown> | null;
+//#endregion
+export { GEO_OPERATORS, GeoOperator, buildGeoWithinBoxFilter, buildNearFilter, buildWithinRadiusFilter, hasNearOperator, isGeoOperator, isValidLngLat, parseCoordinateList, parseGeoFilter, rewriteNearForCount };