@classytic/mongokit 3.5.3 → 3.5.5

package/README.md

@@ -192,6 +192,45 @@ const repo = new Repository(UserModel, plugins, {
 });
 ```
 
+### Search configuration
+
+`Repository.getAll({ search })` has three layers, ordered from simplest to most
+flexible. Pick the lowest one that solves your problem.
+
+| Layer                       | When to use                                                                                                              | Where it lives                              |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
+| **`searchMode: 'text'`**    | You have a MongoDB text index and want `$text`-ranked results.                                                           | Repository option (default)                 |
+| **`searchMode: 'regex'`**   | Small/medium collection, no text index, simple substring matching across known fields. Works behind any HTTP framework.  | Repository option                           |
+| **Search-resolver plugin**  | External engine (Elasticsearch, Meilisearch, Typesense, pgvector, hybrid BM25+vector). Composes with cache, multi-tenant. | `before:getAll` plugin — see Plugins below  |
+
+```javascript
+// Built-in regex mode — no MongoDB text index required
+const repo = new Repository(
+  MemoModel,
+  [],
+  {},
+  {
+    // 'text'  → default, requires text index
+    // 'regex' → case-insensitive $or of $regex across searchFields, no index needed
+    // 'auto'  → text if a text index exists, otherwise regex
+    searchMode: "regex",
+    searchFields: ["title", "scope", "body"],
+  },
+);
+
+await repo.getAll({ search: "alpha", filters: { scope: "public" } });
+```
+
+User input is regex-escaped (literal substring match), and any pre-existing
+`$or` filter is preserved by promoting both clauses to `$and`.
+
+> **QueryParser ↔ Repository:** `QueryParser` also exposes `searchMode`/`searchFields`
+> for the HTTP boundary (`?search=foo` URL → parsed query). The two layers are
+> independent: configure the parser if you want URL-time consumption (Arc does
+> this), configure the Repository if you want data-layer consumption
+> (Express/Nest/raw handlers), or both for defense in depth — they will not
+> conflict because the parser clears `parsed.search` before it reaches the repo.
+
 ## Plugins
 
 ### Using Plugins
@@ -754,6 +793,62 @@ const results = await repo.searchSimilar({ query: [0.1, 0.2, ...], limit: 5 });
 const vector = await repo.embed('some text');
 ```
 
+### Custom Search Backends (search-resolver plugin contract)
+
+The built-in `searchMode: 'text' | 'regex'` is sugar over a more general
+**plugin contract** for any search backend — Elasticsearch, Meilisearch,
+Typesense, Algolia, pgvector, Pinecone, hybrid BM25+vector. The contract
+keeps mongokit core free of backend-specific dependencies, and the same
+plugin works behind any HTTP framework (Arc, Express, Nest, raw handlers)
+without further wiring.
+
+**The contract** (4 lines):
+
+1. Hook `before:getAll`.
+2. If `ctx.search` is set, resolve it against your backend (returns IDs).
+3. Mutate `ctx.filters` to constrain the Mongo query: `_id: { $in: ids }`.
+4. Set `ctx.search = undefined` so Repository's text-index check is bypassed.
+
+```javascript
+function meilisearchPlugin({ client, index }) {
+  return (repo) => {
+    repo.on("before:getAll", async (ctx) => {
+      if (!ctx.search) return;
+      const hits = await client.index(index).search(ctx.search, {
+        limit: ctx.limit ?? 20,
+      });
+      const ids = hits.hits.map((h) => h.id);
+      ctx.filters = { ...(ctx.filters ?? {}), _id: { $in: ids } };
+      ctx.search = undefined; // bypass text-index check
+      ctx._meiliRanking = ids; // stash for after:getAll re-sort
+    });
+    repo.on("after:getAll", (ctx) => {
+      if (!ctx._meiliRanking) return;
+      const order = new Map(ctx._meiliRanking.map((id, i) => [String(id), i]));
+      ctx.result.docs.sort(
+        (a, b) => order.get(String(a._id)) - order.get(String(b._id)),
+      );
+    });
+  };
+}
+
+// Wire at Repository construction — works in Arc, Express, Nest, anywhere
+const repo = new Repository(ProductModel, [
+  meilisearchPlugin({ client: meili, index: "products" }),
+  cachePlugin({ adapter: createMemoryCache(), ttl: 60 }), // composes cleanly
+]);
+```
+
+**Why this contract works:**
+
+- `before:getAll` runs inside `_buildContext`, _before_ Repository reads `search` or hits the text-index check. A plugin that clears `ctx.search` short-circuits the built-in search path entirely.
+- `Repository.getAll` reads `search` only from the post-hook context (no fallback to original params) — this is the framework-level guarantee that makes `ctx.search = undefined` a real clear, not a silently overridden no-op.
+- The caller's existing filters are preserved by spreading: `ctx.filters = { ...(ctx.filters ?? {}), _id: ... }`. Multi-tenant scoping (which also runs in `before:getAll`), soft-delete filters, and the search plugin compose without ordering concerns — they all mutate `ctx.filters` independently and all survive.
+- Cache plugin composes too: it sees the post-hook context (filters with the resolved ID list), so cache keys are accurate. ES/Meili results get cached just like Mongo results.
+- The same plugin shape works for every backend; only the resolver call changes.
+
+The bundled `elasticSearchPlugin` (next section) is the canonical reference implementation, and `tests/repository-search-mode.test.ts` exercises this contract end-to-end with multi-tenant + soft-delete + cache composition.
+
 ### Elasticsearch / OpenSearch Plugin
 
 Delegates heavy text and semantic search to an external search engine while fetching full documents from MongoDB. Keeps your OLTP (transactional) MongoDB operations fast by separating search I/O.
@@ -1044,12 +1139,13 @@ Converts HTTP query strings to MongoDB queries with built-in security:
 import { QueryParser } from "@classytic/mongokit";
 
 const parser = new QueryParser({
+  schema: ProductModel.schema, // Schema-aware coercion (recommended)
   maxLimit: 100, // Prevent excessive queries
   maxFilterDepth: 5, // Prevent nested injection
   maxRegexLength: 100, // ReDoS protection
-  allowedFilterFields: ['status', 'name', 'email'], // Whitelist filter fields
-  allowedSortFields: ['createdAt', 'name'], // Whitelist sort fields
-  allowedOperators: ['eq', 'ne', 'in', 'gt', 'lt'], // Whitelist operators
+  allowedFilterFields: ["status", "name", "email"], // Whitelist filter fields
+  allowedSortFields: ["createdAt", "name"], // Whitelist sort fields
+  allowedOperators: ["eq", "ne", "in", "gt", "lt"], // Whitelist operators
 });
 
 // Parse request query
@@ -1061,6 +1157,35 @@ parser.allowedSortFields; // ['createdAt', 'name'] or undefined
 parser.allowedOperators; // ['eq', 'ne', 'in', 'gt', 'lt'] or undefined
 ```
 
+**Schema-aware value coercion (recommended):** Pass `schema: Model.schema` and
+the parser coerces filter values exactly to each field's declared type. With
+schema configured, `?stock=50` against a `Number` field becomes `50` (number),
+`?name=12345` against a `String` field stays `'12345'`, `?releasedAt=2026-04-07`
+against a `Date` field becomes a `Date` instance, `?address.zip=01234` against
+a nested `String` field preserves the leading zero. Direct equality and
+operator syntax (`stock[gte]=50`) coerce identically — no more "why does
+operator work but direct equality doesn't" surprises. Unknown fields fall
+through to a safe heuristic so ad-hoc filters still work.
+
+For DB-agnostic setups (raw MongoDB, Prisma, computed fields, models you
+don't own), use `fieldTypes` instead of `schema`. The two can be combined —
+`fieldTypes` overrides `schema` per path:
+
+```typescript
+const parser = new QueryParser({
+  schema: ProductModel.schema,
+  fieldTypes: {
+    "address.zip": "string", // override a Mongoose path
+    legacyCount: "number", // declare a non-schema field
+  },
+});
+```
+
+Without either option, the parser falls back to a string-shape heuristic
+(numeric strings without leading zeros and ≤15 chars become numbers; ObjectId
+hex stays a string; `'true'`/`'false'` become booleans). The heuristic is
+safe but inherently lossy — schema-aware mode is strictly better.
+
 **Supported query patterns:**
 
 ```bash
@@ -1078,7 +1203,7 @@ GET /users?after=eyJfaWQiOi...&limit=20  # Cursor-based
 # Sorting
 GET /users?sort=-createdAt,name
 
-# Search (requires text index)
+# Search (default: text index; or configure searchMode: 'regex' / 'auto')
 GET /users?search=john
 
 # Simple populate
@@ -1172,6 +1297,40 @@ const { crudSchemas } = buildCrudSchemasFromModel(UserModel, {
 // crudSchemas.listQuery   - GET query validation
 ```
 
+#### Soft-required fields (draft-friendly bodies)
+
+Some resources have fields that must be non-null in the DB but should be
+**optional in the HTTP body** — draft journal entries, multi-step wizards,
+or any state-machine resource that's filled out progressively. Marking a
+path `softRequired: true` keeps the Mongoose `required: true` invariant
+(null on save is still rejected) while excluding the field from the
+generated `createBody.required[]` array.
+
+```typescript
+// 1. Per-path flag (when you own the Mongoose schema)
+const JournalEntrySchema = new Schema({
+  label: { type: String, required: true },            // hard required
+  journalType: {
+    type: String,
+    required: true,       // DB invariant — null rejected on save
+    softRequired: true,   // HTTP body — optional in create/update
+    enum: ['sale', 'purchase', 'adjustment'],
+  },
+  date: { type: Date, required: true, softRequired: true },
+});
+
+// 2. Per-build override (when the Mongoose model lives in an upstream package)
+const { createBody } = buildCrudSchemasFromModel(UpstreamModel, {
+  softRequiredFields: ['journalType', 'date'],
+});
+// createBody.required   →  ['label']   (journalType + date excluded)
+// createBody.properties →  still includes journalType + date (validated when present)
+```
+
+The DB-level `required: true` is unaffected — `repo.create()` with `null`
+for a soft-required field still throws a Mongoose ValidationError. The
+flag only changes what HTTP clients must send.
+
 ### Complete Controller Example
 
 ```typescript

package/dist/{PaginationEngine-DCs-zKwZ.mjs → PaginationEngine-CpsQl471.mjs}

@@ -129,7 +129,7 @@ var PaginationEngine = class {
 	* console.log(result.docs, result.total, result.hasNext);
 	*/
 	async paginate(options = {}) {
-		const { filters = {}, sort = { _id: -1 }, page = 1, limit = this.config.defaultLimit, select, populate = [], lean = true, session, hint, maxTimeMS, countStrategy = "exact", readPreference, collation } = options;
+		const { filters = {}, sort, countFilters, page = 1, limit = this.config.defaultLimit, select, populate = [], lean = true, session, hint, maxTimeMS, countStrategy = "exact", readPreference, collation } = options;
 		const sanitizedPage = validatePage(page, this.config);
 		const sanitizedLimit = validateLimit(limit, this.config);
 		const skip = calculateSkip(sanitizedPage, sanitizedLimit);
@@ -137,7 +137,8 @@ var PaginationEngine = class {
 		let query = this.Model.find(filters);
 		if (select) query = query.select(select);
 		if (populate && (Array.isArray(populate) ? populate.length : populate)) query = query.populate(populate);
-		query = query.sort(sort).skip(skip).limit(fetchLimit).lean(lean);
+		if (sort) query = query.sort(sort);
+		query = query.skip(skip).limit(fetchLimit).lean(lean);
 		if (collation) query = query.collation(collation);
 		if (session) query = query.session(session);
 		if (hint) query = query.hint(hint);
@@ -149,7 +150,8 @@ var PaginationEngine = class {
 		if ((countStrategy === "estimated" || useEstimated) && !hasFilters) countPromise = this.Model.estimatedDocumentCount();
 		else if (countStrategy === "none") countPromise = Promise.resolve(0);
 		else {
-			const countQuery = this.Model.countDocuments(filters).session(session ?? null);
+			const countTarget = countFilters ?? filters;
+			const countQuery = this.Model.countDocuments(countTarget).session(session ?? null);
 			if (hint) countQuery.hint(hint);
 			if (maxTimeMS) countQuery.maxTimeMS(maxTimeMS);
 			if (readPreference) countQuery.read(readPreference);

package/dist/actions/index.d.mts

@@ -1,2 +1,2 @@
-import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-D3ydSXYC.mjs";
+import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-Buj7P006.mjs";
 export { aggregate_d_exports as aggregate, create_d_exports as create, delete_d_exports as deleteActions, read_d_exports as read, update_d_exports as update };

package/dist/ai/index.d.mts

@@ -1,4 +1,4 @@
-import { J as Plugin } from "../types-wCkH8jE3.mjs";
+import { J as Plugin } from "../types-CWUL0yiw.mjs";
 import { ClientSession, PipelineStage } from "mongoose";
 
 //#region src/ai/types.d.ts

package/dist/coercion-01tEHsKF.d.mts

@@ -0,0 +1,106 @@
+//#region src/query/primitives/coercion.d.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.
+ */
+/** Normalized field type used for schema-aware coercion */
+type FieldType = 'string' | 'number' | 'boolean' | 'date' | 'objectid' | 'mixed';
+/**
+ * Minimal structural type for a Mongoose schema (read-only `.paths`).
+ * Mongoose stores array element types in two different shadow properties
+ * depending on version and declaration style:
+ *   - `caster.instance`     — older / some array forms
+ *   - `embeddedSchemaType.instance` — Mongoose 8+, both `[Type]` and `[{ type: Type }]`
+ * We read both and prefer whichever is populated.
+ */
+interface SchemaPathsLike {
+  paths: Record<string, {
+    instance?: string;
+    caster?: {
+      instance?: string;
+    };
+    embeddedSchemaType?: {
+      instance?: string;
+    };
+  }>;
+}
+/**
+ * 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).
+ */
+declare function normalizeMongooseType(schemaType: {
+  instance?: string;
+  caster?: {
+    instance?: string;
+  };
+  embeddedSchemaType?: {
+    instance?: string;
+  };
+}): FieldType | 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.
+ */
+declare function buildFieldTypeMap(schema?: SchemaPathsLike | null, overrides?: Record<string, FieldType>): Map<string, FieldType>;
+/**
+ * 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
+ */
+declare function coerceHeuristic(value: unknown): unknown;
+/**
+ * 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.
+ */
+declare function coerceToType(value: unknown, type: FieldType): unknown;
+/**
+ * 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).
+ */
+declare function coerceFieldValue(field: string, value: unknown, types: Map<string, FieldType>): unknown;
+//#endregion
+export { coerceHeuristic as a, coerceFieldValue as i, SchemaPathsLike as n, coerceToType as o, buildFieldTypeMap as r, normalizeMongooseType as s, FieldType as t };

package/dist/{index-D3ydSXYC.d.mts → index-Buj7P006.d.mts}

@@ -1,4 +1,4 @@
-import { $ as ReadPreferenceType, At as LookupOptions, D as GroupResult, V as ObjectId, W as OperationOptions, Z as PopulateSpec, _t as UpdateOptions, a as AnyDocument, b as DeleteResult, g as CreateOptions, gt as UpdateManyResult, pt as SortSpec, st as SelectSpec, vt as UpdateWithValidationResult, z as MinMaxResult } from "./types-wCkH8jE3.mjs";
+import { $ as ReadPreferenceType, At as LookupOptions, D as GroupResult, V as ObjectId, W as OperationOptions, Z as PopulateSpec, _t as UpdateOptions, a as AnyDocument, b as DeleteResult, g as CreateOptions, gt as UpdateManyResult, pt as SortSpec, st as SelectSpec, vt as UpdateWithValidationResult, z as MinMaxResult } from "./types-CWUL0yiw.mjs";
 import { ClientSession, Model, PipelineStage } from "mongoose";
 
 //#region src/actions/aggregate.d.ts

package/dist/index.d.mts

@@ -1,8 +1,10 @@
-import { $ as ReadPreferenceType, A as InferDocument, At as LookupOptions, B as NonNullableFields, C as EventPayload, Ct as WithPlugins, D as GroupResult, Dt as IRequestContext, E as FieldRules, Et as IControllerResponse, F as KeysetPaginationResult, G as PaginationConfig, H as OffsetPaginationOptions, I as Logger, J as Plugin, K as PaginationResult, L as LookupPopulateOptions, M as JsonSchema, N as KeysOfType, O as HookMode, Ot as IResponseFormatter, P as KeysetPaginationOptions, Q as ReadOptions, R as LookupPopulateResult, S as EventHandlers, St as ValidatorDefinition, T as FieldPreset, Tt as IController, U as OffsetPaginationResult, V as ObjectId, W as OperationOptions, X as PluginType, Y as PluginFunction, Z as PopulateSpec, _ as CrudSchemas, _t as UpdateOptions, a as AnyDocument, at as RequiredBy, b as DeleteResult, bt as ValidationChainOptions, c as CacheOperationOptions, ct as SessionOptions, d as CacheableOptions, dt as SoftDeleteRepository, et as RepositoryContext, f as CascadeOptions, ft as SortDirection, g as CreateOptions, gt as UpdateManyResult, h as CreateInput, ht as UpdateInput, i as AllPluginMethods, it as RepositoryOptions, j as InferRawDoc, k as HttpError, kt as LookupBuilder, l as CacheOptions, lt as SoftDeleteFilterMode, m as CollationOptions, mt as Strict, n as AggregatePaginationOptions, nt as RepositoryInstance, o as AnyModel, ot as SchemaBuilderOptions, p as CascadeRelation, pt as SortSpec, q as PartialBy, r as AggregatePaginationResult, rt as RepositoryOperation, s as CacheAdapter, st as SelectSpec, t as AggregateOptions, tt as RepositoryEvent, u as CacheStats, ut as SoftDeleteOptions, v as DecodedCursor, vt as UpdateWithValidationResult, w as EventPhase, wt as WithTransactionOptions, x as DocField, xt as ValidationResult, y as DeepPartial, yt as UserContext, z as MinMaxResult } from "./types-wCkH8jE3.mjs";
-import { t as index_d_exports } from "./index-D3ydSXYC.mjs";
+import { $ as ReadPreferenceType, A as InferDocument, At as LookupOptions, B as NonNullableFields, C as EventPayload, Ct as WithPlugins, D as GroupResult, Dt as IRequestContext, E as FieldRules, Et as IControllerResponse, F as KeysetPaginationResult, G as PaginationConfig, H as OffsetPaginationOptions, I as Logger, J as Plugin, K as PaginationResult, L as LookupPopulateOptions, M as JsonSchema, N as KeysOfType, O as HookMode, Ot as IResponseFormatter, P as KeysetPaginationOptions, Q as ReadOptions, R as LookupPopulateResult, S as EventHandlers, St as ValidatorDefinition, T as FieldPreset, Tt as IController, U as OffsetPaginationResult, V as ObjectId, W as OperationOptions, X as PluginType, Y as PluginFunction, Z as PopulateSpec, _ as CrudSchemas, _t as UpdateOptions, a as AnyDocument, at as RequiredBy, b as DeleteResult, bt as ValidationChainOptions, c as CacheOperationOptions, ct as SessionOptions, d as CacheableOptions, dt as SoftDeleteRepository, et as RepositoryContext, f as CascadeOptions, ft as SortDirection, g as CreateOptions, gt as UpdateManyResult, h as CreateInput, ht as UpdateInput, i as AllPluginMethods, it as RepositoryOptions, j as InferRawDoc, k as HttpError, kt as LookupBuilder, l as CacheOptions, lt as SoftDeleteFilterMode, m as CollationOptions, mt as Strict, n as AggregatePaginationOptions, nt as RepositoryInstance, o as AnyModel, ot as SchemaBuilderOptions, p as CascadeRelation, pt as SortSpec, q as PartialBy, r as AggregatePaginationResult, rt as RepositoryOperation, s as CacheAdapter, st as SelectSpec, t as AggregateOptions, tt as RepositoryEvent, u as CacheStats, ut as SoftDeleteOptions, v as DecodedCursor, vt as UpdateWithValidationResult, w as EventPhase, wt as WithTransactionOptions, x as DocField, xt as ValidationResult, y as DeepPartial, yt as UserContext, z as MinMaxResult } from "./types-CWUL0yiw.mjs";
+import { t as index_d_exports } from "./index-Buj7P006.mjs";
 import { PaginationEngine } from "./pagination/PaginationEngine.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, R as BulkWriteResult, 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, z as batchOperationsPlugin } from "./validation-chain.plugin-CGE_mKQr.mjs";
-import { a as isFieldUpdateAllowed, c as configureLogger, d as getFieldsForUser, f as getMongooseProjection, i as getSystemManagedFields, l as createFieldPreset, m as parseDuplicateKeyError, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, p as createError, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel, u as filterResponseData } from "./mongooseToJsonSchema-BivI9LWt.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, R as BulkWriteResult, 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, z as batchOperationsPlugin } from "./validation-chain.plugin-Dn41aAbK.mjs";
+import { n as SchemaPathsLike, t as FieldType$1 } from "./coercion-01tEHsKF.mjs";
+import { n as SchemaIndexes } from "./indexes-CiIT-Zli.mjs";
+import { a as isFieldUpdateAllowed, c as configureLogger, d as getFieldsForUser, f as getMongooseProjection, i as getSystemManagedFields, l as createFieldPreset, m as parseDuplicateKeyError, 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";
 import * as _$mongoose from "mongoose";
 import { ClientSession, Expression, Model, PipelineStage, PopulateOptions } from "mongoose";
 
@@ -487,6 +489,22 @@ interface ParsedQuery {
 }
 /** Search mode for query parser */
 type SearchMode = 'text' | 'regex';
+/**
+ * Normalized field type used for schema-aware value coercion. Re-exported
+ * from `primitives/coercion` so the public QueryParser API stays unchanged
+ * while the actual logic lives in a single, unit-tested primitive module.
+ */
+type FieldType = FieldType$1;
+/**
+ * Minimal structural type for a Mongoose schema. We only read `.paths` and
+ * (optionally) `.indexes()`, so the parser stays decoupled from a specific
+ * Mongoose major version and is easy to mock in tests. Re-exported from the
+ * primitives module — the canonical definition lives there.
+ */
+interface SchemaLike extends SchemaPathsLike {
+  /** Optional — when present, schema indexes are introspected for geo/text fields */
+  indexes?: () => Array<[Record<string, unknown>, Record<string, unknown>?]>;
+}
 interface QueryParserOptions {
   /** Maximum allowed regex pattern length (default: 500) */
   maxRegexLength?: number;
@@ -534,6 +552,25 @@ interface QueryParserOptions {
    * @example ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in']
    */
   allowedOperators?: string[];
+  /**
+   * Mongoose schema (or schema-like object exposing `.paths`) used for
+   * authoritative, schema-aware value coercion. When provided, filter values
+   * are coerced to the declared field type instead of guessed from the
+   * string shape — `?stock=50` becomes a number against a `Number` field but
+   * `?name=12345` stays a string against a `String` field. Nested paths like
+   * `address.zip` are looked up via dot-notation, matching Mongoose's
+   * `schema.paths` reflection. Unknown fields fall through to the heuristic.
+   */
+  schema?: SchemaLike;
+  /**
+   * Plain field-type map used for authoritative coercion when no Mongoose
+   * schema is available (raw MongoDB, Prisma, computed fields, upstream
+   * models you don't own). Takes precedence over `schema` for paths declared
+   * in both — useful for runtime overrides. Use dot-notation for nested
+   * paths (`'address.zip': 'string'`).
+   * @example { stock: 'number', active: 'boolean', releasedAt: 'date' }
+   */
+  fieldTypes?: Record<string, FieldType>;
 }
 /**
  * Modern Query Parser
@@ -543,6 +580,21 @@ declare class QueryParser {
   private readonly options;
   private readonly operators;
   private readonly 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.
+   */
+  private readonly _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).
+   */
+  private readonly _schemaIndexes;
   /**
    * Regex patterns that can cause catastrophic backtracking (ReDoS attacks)
    * Detects:
@@ -554,6 +606,16 @@ declare class QueryParser {
    */
   private readonly dangerousRegexPatterns;
   constructor(options?: QueryParserOptions);
+  /**
+   * 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(): SchemaIndexes;
   /**
    * Get the configured allowed filter fields.
    * Returns `undefined` if no whitelist is set (all fields allowed).
@@ -738,7 +800,6 @@ declare class QueryParser {
    * // ]
    */
   private _buildRegexSearch;
-  private _convertValue;
   private _parseOr;
   private _enhanceWithBetween;
   private _pluralize;
@@ -774,6 +835,8 @@ declare class Repository<TDoc = unknown> {
   readonly _pagination: PaginationEngine<TDoc>;
   private readonly _hookMode;
   readonly idField: string;
+  readonly searchMode: 'text' | 'regex' | 'auto';
+  readonly searchFields: string[] | undefined;
   [key: string]: unknown;
   private _hasTextIndex;
   constructor(Model: Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions);
@@ -1075,4 +1138,4 @@ declare class Repository<TDoc = unknown> {
  */
 declare function createRepository<TDoc>(Model: _$mongoose.Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions): Repository<TDoc>;
 //#endregion
-export { type AggregateHelpersMethods, type AggregateOptions, type AggregatePaginationOptions, type AggregatePaginationResult, AggregationBuilder, type AllPluginMethods, type AnyDocument, type AnyModel, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BatchOperationsMethods, type BulkWriteResult, type CacheAdapter, type CacheMethods, type CacheOperationOptions, type CacheOptions, type CacheStats, type CacheableOptions, type CascadeOptions, type CascadeRelation, type CollationOptions, type CreateInput, type CreateOptions, type CrudSchemas, type CustomIdOptions, type DateSequentialIdOptions, type DecodedCursor, type DeepPartial, type DeleteResult, type DocField, type ElasticSearchOptions, type EventHandlers, type EventPayload, type EventPhase, type FieldPreset, type FieldRules, type FilterQuery, type GroupResult, HOOK_PRIORITY, type HookMode, type HttpError, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, type IdGenerator, type InferDocument, type InferRawDoc, type JsonSchema, type KeysOfType, type KeysetPaginationOptions, type KeysetPaginationResult, type Logger, LookupBuilder, type LookupOptions, type LookupPopulateOptions, type LookupPopulateResult, type MinMaxResult, type MongoOperationsMethods, type MultiTenantOptions, type NonNullableFields, type ObjectId, type ObservabilityOptions, type OffsetPaginationOptions, type OffsetPaginationResult, type OperationMetric, type OperationOptions, type PaginationConfig, PaginationEngine, type PaginationResult, type ParsedQuery, type PartialBy, type Plugin, type PluginFunction, type PluginType, type PopulateOption, type PopulateSpec, type PrefixedIdOptions, QueryParser, type QueryParserOptions, type ReadOptions, type ReadPreferenceType, Repository, Repository as default, type RepositoryContext, type RepositoryEvent, type RepositoryInstance, type RepositoryOperation, type RepositoryOptions, type RequiredBy, type SchemaBuilderOptions, type SearchMode, type SelectSpec, type SequentialIdOptions, type SessionOptions, type SoftDeleteFilterMode, type SoftDeleteMethods, type SoftDeleteOptions, type SoftDeleteRepository, type SortDirection, type SortSpec, type Strict, type SubdocumentMethods, type UpdateInput, type UpdateManyResult, type UpdateOptions, type UpdateWithValidationResult, type UserContext, type ValidationChainOptions, type ValidationResult, type ValidatorDefinition, type WithPlugins, type WithTransactionOptions, index_d_exports as actions, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, configureLogger, createError, createFieldPreset, createMemoryCache, createRepository, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getNextSequence, getSystemManagedFields, immutableField, isFieldUpdateAllowed, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, parseDuplicateKeyError, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validateUpdateBody, validationChainPlugin };
+export { type AggregateHelpersMethods, type AggregateOptions, type AggregatePaginationOptions, type AggregatePaginationResult, AggregationBuilder, type AllPluginMethods, type AnyDocument, type AnyModel, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BatchOperationsMethods, type BulkWriteResult, type CacheAdapter, type CacheMethods, type CacheOperationOptions, type CacheOptions, type CacheStats, type CacheableOptions, type CascadeOptions, type CascadeRelation, type CollationOptions, type CreateInput, type CreateOptions, type CrudSchemas, type CustomIdOptions, type DateSequentialIdOptions, type DecodedCursor, type DeepPartial, type DeleteResult, type DocField, type ElasticSearchOptions, type EventHandlers, type EventPayload, type EventPhase, type FieldPreset, type FieldRules, type FieldType, type FilterQuery, type GroupResult, HOOK_PRIORITY, type HookMode, type HttpError, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, type IdGenerator, type InferDocument, type InferRawDoc, type JsonSchema, type KeysOfType, type KeysetPaginationOptions, type KeysetPaginationResult, type Logger, LookupBuilder, type LookupOptions, type LookupPopulateOptions, type LookupPopulateResult, type MinMaxResult, type MongoOperationsMethods, type MultiTenantOptions, type NonNullableFields, type ObjectId, type ObservabilityOptions, type OffsetPaginationOptions, type OffsetPaginationResult, type OperationMetric, type OperationOptions, type PaginationConfig, PaginationEngine, type PaginationResult, type ParsedQuery, type PartialBy, type Plugin, type PluginFunction, type PluginType, type PopulateOption, type PopulateSpec, type PrefixedIdOptions, QueryParser, type QueryParserOptions, type ReadOptions, type ReadPreferenceType, Repository, Repository as default, type RepositoryContext, type RepositoryEvent, type RepositoryInstance, type RepositoryOperation, type RepositoryOptions, type RequiredBy, type SchemaBuilderOptions, type SchemaLike, type SearchMode, type SelectSpec, type SequentialIdOptions, type SessionOptions, type SoftDeleteFilterMode, type SoftDeleteMethods, type SoftDeleteOptions, type SoftDeleteRepository, type SortDirection, type SortSpec, type Strict, type SubdocumentMethods, type UpdateInput, type UpdateManyResult, type UpdateOptions, type UpdateWithValidationResult, type UserContext, type ValidationChainOptions, type ValidationResult, type ValidatorDefinition, type WithPlugins, type WithTransactionOptions, index_d_exports as actions, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, configureLogger, createError, createFieldPreset, createMemoryCache, createRepository, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getNextSequence, getSystemManagedFields, immutableField, isFieldUpdateAllowed, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, parseDuplicateKeyError, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validateUpdateBody, validationChainPlugin };