@classytic/mongokit 3.5.4 → 3.5.5

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-CiIT-Zli.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-CWUL0yiw.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-CWUL0yiw.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-BlDfbg_0.mjs";
 
 //#region src/utils/cache-keys.d.ts
 /**

package/dist/{validation-chain.plugin-KjPV_6_N.mjs → validation-chain.plugin-BCPh2UZG.mjs}

@@ -1,6 +1,7 @@
 import { a as warn, i as debug, n as parseDuplicateKeyError, t as createError } from "./error-Bpbi_NKo.mjs";
 import { a as exists, c as getOrCreate, d as deleteByQuery, g as upsert, i as count, m as createMany, n as updateByQuery, o as getById, p as create, s as getByQuery, t as update, u as deleteById, v as distinct, y as LookupBuilder } from "./update-AVfKWNGt.mjs";
-import { t as PaginationEngine } from "./PaginationEngine-DCs-zKwZ.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-CpsQl471.mjs";
+import { hasNearOperator, rewriteNearForCount } from "./query/primitives/geo.mjs";
 import { a as byIdKey, c as listQueryKey, l as modelPattern, o as byQueryKey, r as getFieldsForUser, u as versionKey } from "./field-selection-reyDRzXf.mjs";
 import mongoose from "mongoose";
 //#region src/plugins/aggregate-helpers.plugin.ts
@@ -1182,6 +1183,8 @@ var Repository = class {
 	_pagination;
 	_hookMode;
 	idField;
+	searchMode;
+	searchFields;
 	_hasTextIndex = null;
 	constructor(Model, plugins = [], paginationConfig = {}, options = {}) {
 		this.Model = Model;
@@ -1190,6 +1193,9 @@ var Repository = class {
 		this._pagination = new PaginationEngine(Model, paginationConfig);
 		this._hookMode = options.hooks ?? "async";
 		this.idField = options.idField ?? "_id";
+		this.searchMode = options.searchMode ?? "text";
+		this.searchFields = options.searchFields;
+		if (this.searchMode === "regex" && (!this.searchFields || this.searchFields.length === 0)) warn(`[mongokit] Repository "${this.model}" configured with searchMode: 'regex' but no searchFields provided. getAll({ search }) will throw until searchFields is set.`);
 		plugins.forEach((plugin) => {
 			this.use(plugin);
 		});
@@ -1542,8 +1548,11 @@ var Repository = class {
 			sort: context.sort ?? params.sort
 		});
 		const filters = context.filters ?? params.filters ?? {};
-		const search = context.search ?? params.search;
-		const sort = context.sort ?? params.sort ?? "-createdAt";
+		const search = context.search;
+		const isNearQuery = hasNearOperator(context.filters ?? params.filters ?? {});
+		const explicitSort = context.sort ?? params.sort;
+		if (isNearQuery && explicitSort !== void 0) warn(`[mongokit] Repository "${this.model}" dropping explicit sort (${JSON.stringify(explicitSort)}) because the filter contains $near / $nearSphere. MongoDB forbids explicit sort with $near. Use [withinRadius] instead of [near] if you need a custom sort.`);
+		const sort = isNearQuery ? void 0 : explicitSort ?? "-createdAt";
 		const limit = context.limit ?? params.limit ?? params.pagination?.limit ?? this._pagination.config.defaultLimit;
 		const page = context.page ?? params.pagination?.page ?? params.page;
 		const after = context.after ?? params.cursor ?? params.after;
@@ -1554,13 +1563,31 @@ var Repository = class {
 		const query = { ...filters };
 		if (search) {
 			if (this._hasTextIndex === null) this._hasTextIndex = this.Model.schema.indexes().some((idx) => idx[0] && Object.values(idx[0]).includes("text"));
-			if (this._hasTextIndex) query.$text = { $search: search };
-			else throw createError(400, `No text index found for ${this.model}. Cannot perform text search.`);
+			let effectiveMode = this.searchMode === "regex" ? "regex" : "text";
+			if (this.searchMode === "auto") effectiveMode = this._hasTextIndex ? "text" : "regex";
+			if (effectiveMode === "regex") {
+				if (!this.searchFields || this.searchFields.length === 0) throw createError(400, `Repository "${this.model}" configured with searchMode: '${this.searchMode}' but no searchFields provided.`);
+				const escaped = String(search).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+				const orConds = this.searchFields.map((field) => ({ [field]: {
+					$regex: escaped,
+					$options: "i"
+				} }));
+				if (Array.isArray(query.$or)) {
+					const existingOr = query.$or;
+					delete query.$or;
+					query.$and = [
+						...Array.isArray(query.$and) ? query.$and : [],
+						{ $or: existingOr },
+						{ $or: orConds }
+					];
+				} else query.$or = orConds;
+			} else if (this._hasTextIndex) query.$text = { $search: search };
+			else throw createError(400, `No text index found for ${this.model}. Cannot perform text search. Configure Repository with searchMode: 'regex' (and searchFields) or 'auto' to enable index-free search.`);
 		}
 		const populateSpec = options.populateOptions || params.populateOptions || context.populate || options.populate;
 		const paginationOptions = {
 			filters: query,
-			sort: this._parseSort(sort),
+			sort: isNearQuery ? void 0 : this._parseSort(sort),
 			limit,
 			populate: this._parsePopulate(populateSpec),
 			select: context.select || options.select,
@@ -1630,11 +1657,21 @@ var Repository = class {
 				sort: paginationOptions.sort,
 				after
 			});
-			else result = await this._pagination.paginate({
-				...paginationOptions,
-				page: page || 1,
-				countStrategy: context.countStrategy ?? params.countStrategy
-			});
+			else {
+				let countFilters;
+				let forcedCountStrategy;
+				if (isNearQuery) {
+					const rewritten = rewriteNearForCount(query);
+					if (rewritten) countFilters = rewritten;
+					else forcedCountStrategy = "none";
+				}
+				result = await this._pagination.paginate({
+					...paginationOptions,
+					page: page || 1,
+					countFilters,
+					countStrategy: context.countStrategy ?? params.countStrategy ?? forcedCountStrategy
+				});
+			}
 			await this._emitHook("after:getAll", {
 				context,
 				result

package/dist/{validation-chain.plugin-BYMZB8dN.d.mts → validation-chain.plugin-Dn41aAbK.d.mts}

@@ -1,4 +1,4 @@
-import { I as Logger, J as Plugin, St as ValidatorDefinition, T as FieldPreset, U as OffsetPaginationResult, V as ObjectId, Z as PopulateSpec, bt as ValidationChainOptions, et as RepositoryContext, f as CascadeOptions, l as CacheOptions, nt as RepositoryInstance, pt as SortSpec, st as SelectSpec, u as CacheStats, ut as SoftDeleteOptions } from "./types-CkE3mOaW.mjs";
+import { I as Logger, J as Plugin, St as ValidatorDefinition, T as FieldPreset, U as OffsetPaginationResult, V as ObjectId, Z as PopulateSpec, bt as ValidationChainOptions, et as RepositoryContext, f as CascadeOptions, l as CacheOptions, nt as RepositoryInstance, pt as SortSpec, st as SelectSpec, u as CacheStats, ut as SoftDeleteOptions } from "./types-CWUL0yiw.mjs";
 import mongoose, { ClientSession } from "mongoose";
 
 //#region src/plugins/aggregate-helpers.plugin.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/mongokit",
-  "version": "3.5.4",
+  "version": "3.5.5",
   "description": "Production-grade MongoDB repositories with zero dependencies - smart pagination, events, and plugins",
   "type": "module",
   "sideEffects": false,
@@ -31,6 +31,18 @@
     "./ai": {
       "types": "./dist/ai/index.d.mts",
       "default": "./dist/ai/index.mjs"
+    },
+    "./query/primitives/geo": {
+      "types": "./dist/query/primitives/geo.d.mts",
+      "default": "./dist/query/primitives/geo.mjs"
+    },
+    "./query/primitives/coercion": {
+      "types": "./dist/query/primitives/coercion.d.mts",
+      "default": "./dist/query/primitives/coercion.mjs"
+    },
+    "./query/primitives/indexes": {
+      "types": "./dist/query/primitives/indexes.d.mts",
+      "default": "./dist/query/primitives/indexes.mjs"
     }
   },
   "files": [
@@ -81,7 +93,7 @@
   },
   "homepage": "https://github.com/classytic/mongokit#readme",
   "peerDependencies": {
-    "mongoose": "^9.0.0"
+    "mongoose": "^9.4.1"
   },
   "engines": {
     "node": ">=22"
@@ -111,7 +123,7 @@
     "@vitest/coverage-v8": "^3.2.4",
     "knip": "^6.3.0",
     "mongodb-memory-server": "^10.4.3",
-    "mongoose": "^9.1.3",
+    "mongoose": "^9.4.1",
     "tsdown": "^0.21.7",
     "typescript": "^5.7.0",
     "vitest": "^3.2.4"