@classytic/mongokit 3.5.4 → 3.5.6

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-DCYjnPau.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-B19MD38s.mjs";
+export { FieldType, SchemaPathsLike, buildFieldTypeMap, coerceFieldValue, coerceHeuristic, coerceToType, normalizeMongooseType };

package/dist/query/primitives/coercion.mjs

@@ -0,0 +1,148 @@
+import { n as isObjectIdInstance } from "../../id-resolution-LZ-cCwR5.mjs";
+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 "Mixed": return "mixed";
+		default:
+			if (isObjectIdInstance(raw)) return "objectid";
+			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 };

package/dist/query/primitives/geo.mjs

@@ -0,0 +1,211 @@
+//#region src/query/primitives/geo.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 */
+const GEO_OPERATORS = [
+	"near",
+	"nearSphere",
+	"geoWithin",
+	"withinRadius"
+];
+/** Earth radius in meters — used to convert meters → radians for $centerSphere */
+const EARTH_RADIUS_METERS = 6378137;
+/**
+* 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.
+*/
+function isGeoOperator(operator) {
+	return GEO_OPERATORS.includes(operator);
+}
+/**
+* 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).
+*/
+function parseCoordinateList(raw) {
+	if (typeof raw !== "string" && !Array.isArray(raw)) return null;
+	const parts = Array.isArray(raw) ? raw : raw.split(",").map((s) => s.trim());
+	const nums = [];
+	for (const part of parts) {
+		const n = Number(String(part));
+		if (!Number.isFinite(n)) return null;
+		nums.push(n);
+	}
+	return nums;
+}
+/**
+* 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.
+*/
+function isValidLngLat(lng, lat) {
+	return lng >= -180 && lng <= 180 && lat >= -90 && lat <= 90;
+}
+/**
+* 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).
+*/
+function buildNearFilter(variant, coords) {
+	if (coords.length < 2 || coords.length > 3) return null;
+	const [lng, lat, maxDistance] = coords;
+	if (!isValidLngLat(lng, lat)) return null;
+	const operator = variant === "near" ? "$near" : "$nearSphere";
+	const inner = { $geometry: {
+		type: "Point",
+		coordinates: [lng, lat]
+	} };
+	if (maxDistance !== void 0) {
+		if (!Number.isFinite(maxDistance) || maxDistance < 0) return null;
+		inner.$maxDistance = maxDistance;
+	}
+	return { [operator]: inner };
+}
+/**
+* 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.
+*/
+function buildWithinRadiusFilter(coords) {
+	if (coords.length !== 3) return null;
+	const [lng, lat, radiusMeters] = coords;
+	if (!isValidLngLat(lng, lat)) return null;
+	if (!Number.isFinite(radiusMeters) || radiusMeters < 0) return null;
+	const radiusRadians = radiusMeters / EARTH_RADIUS_METERS;
+	return { $geoWithin: { $centerSphere: [[lng, lat], radiusRadians] } };
+}
+/**
+* Build a `$geoWithin: $box` filter from a 4-element coordinate list:
+*   [minLng, minLat, maxLng, maxLat]
+*
+* Returns null on any validation failure (drop the filter).
+*/
+function buildGeoWithinBoxFilter(coords) {
+	if (coords.length !== 4) return null;
+	const [minLng, minLat, maxLng, maxLat] = coords;
+	if (!isValidLngLat(minLng, minLat) || !isValidLngLat(maxLng, maxLat)) return null;
+	if (minLng > maxLng || minLat > maxLat) return null;
+	return { $geoWithin: { $box: [[minLng, minLat], [maxLng, maxLat]] } };
+}
+/**
+* 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'`)
+*/
+function rewriteNearForCount(filters) {
+	if (!filters || typeof filters !== "object" || Array.isArray(filters)) return null;
+	const src = filters;
+	const rewritten = {};
+	let anyRewritten = false;
+	for (const [key, value] of Object.entries(src)) {
+		if (!value || typeof value !== "object" || Array.isArray(value)) {
+			rewritten[key] = value;
+			continue;
+		}
+		const inner = value;
+		const nearOp = "$near" in inner ? "$near" : "$nearSphere" in inner ? "$nearSphere" : null;
+		if (!nearOp) {
+			rewritten[key] = value;
+			continue;
+		}
+		const nearVal = inner[nearOp];
+		const geometry = nearVal?.$geometry;
+		const maxDistance = nearVal?.$maxDistance;
+		if (!geometry?.coordinates || geometry.coordinates.length < 2 || typeof maxDistance !== "number" || !Number.isFinite(maxDistance) || maxDistance < 0) return null;
+		const [lng, lat] = geometry.coordinates;
+		if (!isValidLngLat(lng, lat)) return null;
+		const radiusRadians = maxDistance / EARTH_RADIUS_METERS;
+		rewritten[key] = { $geoWithin: { $centerSphere: [[lng, lat], radiusRadians] } };
+		anyRewritten = true;
+	}
+	return anyRewritten ? rewritten : 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.
+*/
+function hasNearOperator(filters) {
+	if (!filters || typeof filters !== "object" || Array.isArray(filters)) return false;
+	for (const value of Object.values(filters)) {
+		if (!value || typeof value !== "object") continue;
+		if (Array.isArray(value)) {
+			for (const branch of value) if (hasNearOperator(branch)) return true;
+			continue;
+		}
+		const inner = value;
+		if ("$near" in inner || "$nearSphere" in inner) return true;
+	}
+	return false;
+}
+/**
+* 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).
+*/
+function parseGeoFilter(operator, raw) {
+	if (!isGeoOperator(operator)) return null;
+	const coords = parseCoordinateList(raw);
+	if (!coords) return null;
+	if (operator === "near") return buildNearFilter("near", coords);
+	if (operator === "nearSphere") return buildNearFilter("nearSphere", coords);
+	if (operator === "geoWithin") return buildGeoWithinBoxFilter(coords);
+	if (operator === "withinRadius") return buildWithinRadiusFilter(coords);
+	return null;
+}
+//#endregion
+export { GEO_OPERATORS, buildGeoWithinBoxFilter, buildNearFilter, buildWithinRadiusFilter, hasNearOperator, isGeoOperator, isValidLngLat, parseCoordinateList, parseGeoFilter, rewriteNearForCount };

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

@@ -0,0 +1,2 @@
+import { n as SchemaIndexes, r as extractSchemaIndexes, t as IndexableSchema } from "../../indexes-qIBCZ3mY.mjs";
+export { IndexableSchema, SchemaIndexes, extractSchemaIndexes };

package/dist/query/primitives/indexes.mjs

@@ -0,0 +1,46 @@
+//#region src/query/primitives/indexes.ts
+const EMPTY = {
+	geoFields: [],
+	textFields: [],
+	other: []
+};
+/**
+* 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.
+*/
+function extractSchemaIndexes(schema) {
+	if (!schema || typeof schema.indexes !== "function") return EMPTY;
+	const geoFields = [];
+	const textFields = [];
+	const other = [];
+	let raw;
+	try {
+		raw = schema.indexes();
+	} catch {
+		return EMPTY;
+	}
+	for (const entry of raw) {
+		const [spec, options] = entry;
+		if (!spec || typeof spec !== "object") continue;
+		let classified = false;
+		for (const [field, value] of Object.entries(spec)) if (value === "2dsphere" || value === "2d") {
+			geoFields.push(field);
+			classified = true;
+		} else if (value === "text") {
+			textFields.push(field);
+			classified = true;
+		}
+		if (!classified) other.push({
+			spec,
+			options
+		});
+	}
+	return {
+		geoFields,
+		textFields,
+		other
+	};
+}
+//#endregion
+export { extractSchemaIndexes };

package/dist/{types-CkE3mOaW.d.mts → types-BwO4u3JN.d.mts}

@@ -546,6 +546,8 @@ type CreateInput<TDoc> = Omit<TDoc, '_id' | 'createdAt' | 'updatedAt' | '__v'>;
 type UpdateInput<TDoc> = Partial<Omit<TDoc, '_id' | 'createdAt' | '__v'>>;
 /** Hook execution mode */
 type HookMode = 'sync' | 'async';
+/** Search strategy used by Repository.getAll when `search` is provided */
+type RepositorySearchMode = 'text' | 'regex' | 'auto';
 /** Repository options */
 interface RepositoryOptions {
   /** Whether repository event hooks are awaited */
@@ -553,6 +555,21 @@ interface RepositoryOptions {
   /** Custom ID field used by getById/update/delete (default: '_id').
    * Set to 'slug', 'code', 'chatId', etc. for non-ObjectId lookups. */
   idField?: string;
+  /**
+   * How Repository.getAll handles the `search` parameter.
+   * - 'text' (default): uses MongoDB $text; requires a text index.
+   * - 'regex': builds case-insensitive $or of $regex across `searchFields`. No index required.
+   * - 'auto': uses 'text' if a text index exists, otherwise falls back to 'regex' when `searchFields` is set.
+   *
+   * Works standalone (Express/Nest/etc.) or alongside QueryParser — when the parser
+   * already consumed `search` into filters, Repository does nothing extra.
+   */
+  searchMode?: RepositorySearchMode;
+  /**
+   * Fields used when searchMode is 'regex' (or 'auto' falling back to regex).
+   * Required for regex mode to take effect.
+   */
+  searchFields?: string[];
 }
 /** Pagination configuration */
 interface PaginationConfig {
@@ -613,6 +630,14 @@ interface OffsetPaginationOptions extends BasePaginationOptions {
   page?: number;
   /** Count strategy for filtered queries (default: 'exact') */
   countStrategy?: 'exact' | 'estimated' | 'none';
+  /**
+   * Optional alternate filter used for the count query only. The primary
+   * `filters` is still used for `.find()`. Lets callers (Repository) run a
+   * sort-only query like `$near` for results while counting with a
+   * count-compatible rewrite (e.g. `$geoWithin: $centerSphere`) that
+   * returns the same document set but works with `countDocuments`.
+   */
+  countFilters?: FilterQuery<AnyDocument>;
 }
 /** Keyset (cursor) pagination options */
 interface KeysetPaginationOptions extends BasePaginationOptions {

package/dist/utils/index.d.mts

@@ -1,5 +1,5 @@
-import { Z as PopulateSpec, pt as SortSpec, st as SelectSpec } from "../types-CkE3mOaW.mjs";
-import { a as isFieldUpdateAllowed, c as configureLogger, d as getFieldsForUser, f as getMongooseProjection, i as getSystemManagedFields, l as createFieldPreset, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, p as createError, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel, u as filterResponseData } from "../mongooseToJsonSchema-Dsx3YAAx.mjs";
+import { Z as PopulateSpec, pt as SortSpec, st as SelectSpec } from "../types-BwO4u3JN.mjs";
+import { a as isFieldUpdateAllowed, c as configureLogger, d as getFieldsForUser, f as getMongooseProjection, i as getSystemManagedFields, l as createFieldPreset, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, p as createError, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel, u as filterResponseData } from "../mongooseToJsonSchema-DQMU0Dlv.mjs";
 
 //#region src/utils/cache-keys.d.ts
 /**
@@ -89,4 +89,61 @@ declare function modelPattern(prefix: string, model: string): string;
  */
 declare function listPattern(prefix: string, model: string): string;
 //#endregion
-export { buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, byIdKey, byQueryKey, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getSystemManagedFields, isFieldUpdateAllowed, listPattern, listQueryKey, modelPattern, validateUpdateBody, versionKey };
+//#region src/utils/id-resolution.d.ts
+/**
+ * ID Resolution Primitive
+ *
+ * Pure functions for detecting a Mongoose schema's _id type and validating
+ * id values against it. Used by Repository.getById to decide whether to
+ * run ObjectId validation (for ObjectId schemas) or skip it (for String /
+ * Number / UUID schemas).
+ *
+ * Also usable standalone — Arc controllers, custom repositories, migration
+ * scripts, or test harnesses can import these directly to make the same
+ * decision without depending on Repository.
+ *
+ * Design: no `this`, no Model, no DB calls. Only reads `schema.paths._id.instance`.
+ */
+/** Normalized _id type — covers the common Mongoose _id declarations */
+type IdType = 'objectid' | 'string' | 'number' | 'uuid' | 'unknown';
+/**
+ * Check if a Mongoose SchemaType `instance` string is an ObjectId variant.
+ * Mongoose 9.x uses `'ObjectId'`, older versions use `'ObjectID'`. This
+ * is the single source of truth — use it instead of inline
+ * `instance === 'ObjectId' || instance === 'ObjectID'` checks.
+ */
+declare function isObjectIdInstance(instance: string | undefined): boolean;
+/** Minimal structural type for schema introspection (decoupled from Mongoose version) */
+interface SchemaLike {
+  paths?: Record<string, {
+    instance?: string;
+  }>;
+}
+/**
+ * Detect the _id path type from a Mongoose schema.
+ *
+ * Returns 'objectid' as the safe default when:
+ *   - No schema is provided (mock models, test harnesses)
+ *   - The schema has no `paths._id` (auto-generated ObjectId)
+ *   - The instance string is unrecognized
+ *
+ * This safe-default means existing callers that don't set _id explicitly
+ * get the same ObjectId validation they always had — the behavioral change
+ * is strictly opt-in via schema declaration.
+ */
+declare function getSchemaIdType(schema?: SchemaLike | null): IdType;
+/**
+ * Validate an id value against a known _id type — WITHOUT hitting the DB.
+ *
+ * Returns `true` when the value is structurally valid for the given type.
+ * Returns `false` when it's definitely invalid (Repository should return
+ * 404 / null immediately rather than wasting a round-trip).
+ *
+ * For `'string'` and `'unknown'` types, validation is intentionally
+ * permissive: any truthy, non-empty value is accepted. The DB is the
+ * authority for whether the document exists — we only reject values that
+ * are structurally impossible (null, undefined, empty string).
+ */
+declare function isValidIdForType(id: unknown, idType: IdType): boolean;
+//#endregion
+export { type IdType, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, byIdKey, byQueryKey, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getSchemaIdType, getSystemManagedFields, isFieldUpdateAllowed, isObjectIdInstance, isValidIdForType, listPattern, listQueryKey, modelPattern, validateUpdateBody, versionKey };

package/dist/utils/index.mjs

@@ -1,4 +1,5 @@
 import { r as configureLogger, t as createError } from "../error-Bpbi_NKo.mjs";
-import { a as byIdKey, c as listQueryKey, i as getMongooseProjection, l as modelPattern, n as filterResponseData, o as byQueryKey, r as getFieldsForUser, s as listPattern, t as createFieldPreset, u as versionKey } 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-DpjhFfaO.mjs";
-export { buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, byIdKey, byQueryKey, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getSystemManagedFields, isFieldUpdateAllowed, listPattern, listQueryKey, modelPattern, validateUpdateBody, versionKey };
+import { n as isObjectIdInstance, r as isValidIdForType, t as getSchemaIdType } from "../id-resolution-LZ-cCwR5.mjs";
+import { a as byIdKey, c as listQueryKey, i as getMongooseProjection, l as modelPattern, n as filterResponseData, o as byQueryKey, r as getFieldsForUser, s as listPattern, t as createFieldPreset, u as versionKey } from "../field-selection-C5o7jyyA.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-8Cyu3NFJ.mjs";
+export { buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, byIdKey, byQueryKey, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getSchemaIdType, getSystemManagedFields, isFieldUpdateAllowed, isObjectIdInstance, isValidIdForType, listPattern, listQueryKey, modelPattern, validateUpdateBody, versionKey };