@classytic/mongokit 3.11.0 → 3.11.1

package/README.md

@@ -269,6 +269,16 @@ const result = await invoiceRepo.getAll({ filters, sort, page, limit, search });
 
 Supports URL operators: `_gt/_gte/_lt/_lte/_ne/_in/_nin/_regex`, geo (`[near]`, `[withinRadius]`, `[geoWithin]`), populate, and schema-aware coercion. ReDoS protection + allowlisted operators for hardening.
 
+**Nested subdocument filters.** Dotted paths pass through to MongoDB directly — Mongoose's strict-mode casting handles the nested-schema lookup, no special config required:
+
+```
+?contact.email[contains]=foo  → { 'contact.email': { $regex: /foo/i } }
+?name.given=sadman             → { 'name.given': 'sadman' }
+?name.given[in]=a,b            → { 'name.given': { $in: ['a', 'b'] } }
+```
+
+Dot-in-key semantics follow `qs` parsing: `?name.given=x` produces `{ 'name.given': 'x' }` (NOT nested into `{ name: { given: 'x' } }`). For the nested-object form use bracket notation: `?name[given]=x`.
+
 ---
 
 ## TypeScript

package/dist/{PaginationEngine-B93fLCcO.mjs → PaginationEngine-CvDFfVXT.mjs}

@@ -1,5 +1,5 @@
 import { r as warn } from "./logger-DJ7egMnd.mjs";
-import { t as createError } from "./error-CzYwrfUP.mjs";
+import { t as createError } from "./error-B00pI7dV.mjs";
 import { n as encodeCursor, r as resolveCursorFilter } from "./cursor-J84rR6wG.mjs";
 import { r as validateKeysetSort, t as getPrimaryField } from "./sort-CrZjTK25.mjs";
 //#region src/pagination/utils/index-hint.ts

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-C1MzVFsT.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-dNTmpgK8.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/actions/index.mjs

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "../chunk-CfYAbeIz.mjs";
-import { g as create_exports, i as update_exports, p as delete_exports, u as read_exports, v as aggregate_exports } from "../update-CWXfFC6O.mjs";
+import { g as create_exports, i as update_exports, p as delete_exports, u as read_exports, v as aggregate_exports } from "../update-DEJYcgfV.mjs";
 //#region src/actions/index.ts
 var actions_exports = /* @__PURE__ */ __exportAll({
 	aggregate: () => aggregate_exports,

package/dist/ai/index.d.mts

@@ -1,4 +1,4 @@
-import { q as Plugin } from "../types-xOyTec4n.mjs";
+import { q as Plugin } from "../types-Dc2aDVUi.mjs";
 import { PipelineStage } from "mongoose";
 
 //#region src/ai/types.d.ts

package/dist/{error-CzYwrfUP.mjs → error-B00pI7dV.mjs}

@@ -1,19 +1,26 @@
 //#region src/utils/error.ts
 /**
-* Creates an error with HTTP status code
+* Creates an error with HTTP status code, plus optional stable `code` /
+* `meta` so callers can `catch` on the code instead of regex-matching the
+* message string.
 *
 * @param status - HTTP status code
 * @param message - Error message
+* @param options - Optional `code` / `meta` for structured handling
 * @returns Error with status property
 *
 * @example
 * throw createError(404, 'Document not found');
-* throw createError(400, 'Invalid input');
-* throw createError(403, 'Access denied');
+* throw createError(400, 'Invalid input', {
+*   code: 'SEARCH_NOT_CONFIGURED',
+*   meta: { model: 'Customer', availableModes: ['text', 'regex', 'auto'] },
+* });
 */
-function createError(status, message) {
+function createError(status, message, options) {
 	const error = new Error(message);
 	error.status = status;
+	if (options?.code !== void 0) error.code = options.code;
+	if (options?.meta !== void 0) error.meta = options.meta;
 	return error;
 }
 /**

package/dist/{index-C1MzVFsT.d.mts → index-dNTmpgK8.d.mts}

@@ -1,4 +1,4 @@
-import { $ as ReadPreferenceType, B as ObjectId, D as GroupResult, E as FindOneAndUpdateOptions, R as MinMaxResult, U as OperationOptions, X as PopulateSpec, a as AnyDocument, b as DeleteResult, ft as SortSpec, g as CreateOptions, gt as UpdateOptions, ht as UpdateManyResult, kt as LookupOptions, ot as SelectSpec, vt as UpdateWithValidationResult } from "./types-xOyTec4n.mjs";
+import { $ as ReadPreferenceType, B as ObjectId, D as GroupResult, E as FindOneAndUpdateOptions, R as MinMaxResult, U as OperationOptions, X as PopulateSpec, a as AnyDocument, b as DeleteResult, ft as SortSpec, g as CreateOptions, gt as UpdateOptions, ht as UpdateManyResult, kt as LookupOptions, ot as SelectSpec, vt as UpdateWithValidationResult } from "./types-Dc2aDVUi.mjs";
 import { Model, PipelineStage } from "mongoose";
 
 //#region src/actions/aggregate.d.ts

package/dist/index.d.mts

@@ -1,10 +1,10 @@
-import { $ as ReadPreferenceType, A as InferDocument, B as ObjectId, C as EventPayload, Ct as WithTransactionOptions, D as GroupResult, Dt as IResponseFormatter, E as FindOneAndUpdateOptions, Et as IRequestContext, F as Logger, G as PaginationResult, H as OffsetPaginationResult, I as LookupPopulateOptions, J as PluginFunction, K as PartialBy, L as LookupPopulateResult, M as KeysOfType, N as KeysetPaginationOptions, O as HookMode, Ot as LookupBuilder, P as KeysetPaginationResult, Q as ReadOptions, R as MinMaxResult, S as EventHandlers, St as WithPlugins, T as FieldPreset, Tt as IControllerResponse, U as OperationOptions, V as OffsetPaginationOptions, W as PaginationConfig, X as PopulateSpec, Y as PluginType, Z as PrioritizedHook, _ as DecodedCursor, _t as UpdatePatch, a as AnyDocument, at as RequiredBy, b as DeleteResult, bt as ValidationChainOptions, c as CacheOperationOptions, ct as SoftDeleteFilterMode, d as CacheableOptions, dt as SortDirection, et as RepositoryContext, f as CascadeOptions, ft as SortSpec, g as CreateOptions, gt as UpdateOptions, h as CreateInput, ht as UpdateManyResult, i as AllPluginMethods, it as RepositoryOptions, j as InferRawDoc, k as HttpError, kt as LookupOptions, l as CacheOptions, lt as SoftDeleteOptions, m as CollationOptions, mt as UpdateInput, n as AggregatePaginationOptions, nt as RepositoryInstance, o as AnyModel, ot as SelectSpec, p as CascadeRelation, pt as Strict, q as Plugin, r as AggregatePaginationResult, rt as RepositoryOperation, s as CacheAdapter, st as SessionOptions, t as AggregateOptions, tt as RepositoryEvent, u as CacheStats, ut as SoftDeleteRepository, v as DeepPartial, vt as UpdateWithValidationResult, w as EventPhase, wt as IController, x as DocField, xt as ValidatorDefinition, y as DeleteManyResult, yt as UserContext, z as NonNullableFields } from "./types-xOyTec4n.mjs";
-import { t as index_d_exports } from "./index-C1MzVFsT.mjs";
+import { $ as ReadPreferenceType, A as InferDocument, B as ObjectId, C as EventPayload, Ct as WithTransactionOptions, D as GroupResult, Dt as IResponseFormatter, E as FindOneAndUpdateOptions, Et as IRequestContext, F as Logger, G as PaginationResult, H as OffsetPaginationResult, I as LookupPopulateOptions, J as PluginFunction, K as PartialBy, L as LookupPopulateResult, M as KeysOfType, N as KeysetPaginationOptions, O as HookMode, Ot as LookupBuilder, P as KeysetPaginationResult, Q as ReadOptions, R as MinMaxResult, S as EventHandlers, St as WithPlugins, T as FieldPreset, Tt as IControllerResponse, U as OperationOptions, V as OffsetPaginationOptions, W as PaginationConfig, X as PopulateSpec, Y as PluginType, Z as PrioritizedHook, _ as DecodedCursor, _t as UpdatePatch, a as AnyDocument, at as RequiredBy, b as DeleteResult, bt as ValidationChainOptions, c as CacheOperationOptions, ct as SoftDeleteFilterMode, d as CacheableOptions, dt as SortDirection, et as RepositoryContext, f as CascadeOptions, ft as SortSpec, g as CreateOptions, gt as UpdateOptions, h as CreateInput, ht as UpdateManyResult, i as AllPluginMethods, it as RepositoryOptions, j as InferRawDoc, k as HttpError, kt as LookupOptions, l as CacheOptions, lt as SoftDeleteOptions, m as CollationOptions, mt as UpdateInput, n as AggregatePaginationOptions, nt as RepositoryInstance, o as AnyModel, ot as SelectSpec, p as CascadeRelation, pt as Strict, q as Plugin, r as AggregatePaginationResult, rt as RepositoryOperation, s as CacheAdapter, st as SessionOptions, t as AggregateOptions, tt as RepositoryEvent, u as CacheStats, ut as SoftDeleteRepository, v as DeepPartial, vt as UpdateWithValidationResult, w as EventPhase, wt as IController, x as DocField, xt as ValidatorDefinition, y as DeleteManyResult, yt as UserContext, z as NonNullableFields } from "./types-Dc2aDVUi.mjs";
+import { t as index_d_exports } from "./index-dNTmpgK8.mjs";
 import { PaginationEngine } from "./pagination/PaginationEngine.mjs";
-import { $ as aggregateHelpersPlugin, A as PrefixedIdOptions, B as BatchOperationsMethods, C as methodRegistryPlugin, D as CustomIdOptions, E as elasticSearchPlugin, F as prefixedId, G as AuditQueryOptions, H as batchOperationsPlugin, I as sequentialId, J as AuditTrailOptions, K as AuditQueryResult, L as cascadePlugin, M as customIdPlugin, N as dateSequentialId, O as DateSequentialIdOptions, P as getNextSequence, Q as AggregateHelpersMethods, R as CacheMethods, T as ElasticSearchOptions, U as AuditEntry, V as BulkWriteResult, W as AuditOperation, X as auditTrailPlugin, Y as AuditTrailQuery, Z as auditLogPlugin, _ as observabilityPlugin, a as uniqueField, b as MongoOperationsMethods, c as TenantContext, d as SubdocumentMethods, f as subdocumentPlugin, g as OperationMetric, h as ObservabilityOptions, i as requireField, j as SequentialIdOptions, k as IdGenerator, l as TenantStore, m as softDeletePlugin, n as blockIf, o as validationChainPlugin, p as SoftDeleteMethods, q as AuditTrailMethods, r as immutableField, s as timestampPlugin, t as autoInject, u as createTenantContext, v as MultiTenantOptions, w as fieldFilterPlugin, x as mongoOperationsPlugin, y as multiTenantPlugin, z as cachePlugin } from "./validation-chain.plugin-BGdr5KRw.mjs";
+import { $ as aggregateHelpersPlugin, A as PrefixedIdOptions, B as BatchOperationsMethods, C as methodRegistryPlugin, D as CustomIdOptions, E as elasticSearchPlugin, F as prefixedId, G as AuditQueryOptions, H as batchOperationsPlugin, I as sequentialId, J as AuditTrailOptions, K as AuditQueryResult, L as cascadePlugin, M as customIdPlugin, N as dateSequentialId, O as DateSequentialIdOptions, P as getNextSequence, Q as AggregateHelpersMethods, R as CacheMethods, T as ElasticSearchOptions, U as AuditEntry, V as BulkWriteResult, W as AuditOperation, X as auditTrailPlugin, Y as AuditTrailQuery, Z as auditLogPlugin, _ as observabilityPlugin, a as uniqueField, b as MongoOperationsMethods, c as TenantContext, d as SubdocumentMethods, f as subdocumentPlugin, g as OperationMetric, h as ObservabilityOptions, i as requireField, j as SequentialIdOptions, k as IdGenerator, l as TenantStore, m as softDeletePlugin, n as blockIf, o as validationChainPlugin, p as SoftDeleteMethods, q as AuditTrailMethods, r as immutableField, s as timestampPlugin, t as autoInject, u as createTenantContext, v as MultiTenantOptions, w as fieldFilterPlugin, x as mongoOperationsPlugin, y as multiTenantPlugin, z as cachePlugin } from "./validation-chain.plugin-B0VSdcwa.mjs";
 import { n as SchemaPathsLike, t as FieldType$1 } from "./coercion-oM8G4b6m.mjs";
 import { n as SchemaIndexes } from "./indexes-C26GNZRU.mjs";
-import { a as createFieldPreset, c as getMongooseProjection, d as parseDuplicateKeyError, i as configureLogger, l as createError, n as buildCrudSchemasFromMongooseSchema, o as filterResponseData, r as createMemoryCache, s as getFieldsForUser, t as buildCrudSchemasFromModel, u as isDuplicateKeyError } from "./mongooseToJsonSchema-BH6OFec5.mjs";
+import { a as createFieldPreset, c as getMongooseProjection, d as parseDuplicateKeyError, i as configureLogger, l as createError, n as buildCrudSchemasFromMongooseSchema, o as filterResponseData, r as createMemoryCache, s as getFieldsForUser, t as buildCrudSchemasFromModel, u as isDuplicateKeyError } from "./mongooseToJsonSchema-DXxjFkLB.mjs";
 import * as _$mongoose from "mongoose";
 import { ClientSession, Expression, Model, PipelineStage, PopulateOptions } from "mongoose";
 import { AggPaginationRequest, AggRequest, AggResult, RepositoryBase } from "@classytic/repo-core/repository";

package/dist/index.mjs

@@ -1,9 +1,9 @@
 import { r as warn, t as configureLogger } from "./logger-DJ7egMnd.mjs";
-import { b as LookupBuilder } from "./update-CWXfFC6O.mjs";
-import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-CzYwrfUP.mjs";
+import { b as LookupBuilder } from "./update-DEJYcgfV.mjs";
+import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-B00pI7dV.mjs";
 import { t as actions_exports } from "./actions/index.mjs";
-import { A as AuditTrailQuery, C as cachePlugin, D as withTransaction, E as isTransactionUnsupported, F as MUTATING_OPERATIONS, I as OP_REGISTRY, L as READ_OPERATIONS, M as auditLogPlugin, N as aggregateHelpersPlugin, O as AggregationBuilder, P as ALL_OPERATIONS, R as operationsByPolicyKey, S as cascadePlugin, T as Repository, _ as customIdPlugin, a as uniqueField, b as prefixedId, c as createTenantContext, d as observabilityPlugin, f as multiTenantPlugin, g as elasticSearchPlugin, h as fieldFilterPlugin, i as requireField, j as auditTrailPlugin, k as batchOperationsPlugin, l as subdocumentPlugin, m as methodRegistryPlugin, n as blockIf, o as validationChainPlugin, p as mongoOperationsPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as softDeletePlugin, v as dateSequentialId, w as HOOK_PRIORITY, x as sequentialId, y as getNextSequence } from "./validation-chain.plugin-CLjEFr0c.mjs";
-import { t as PaginationEngine } from "./PaginationEngine-B93fLCcO.mjs";
+import { A as AuditTrailQuery, C as cachePlugin, D as withTransaction, E as isTransactionUnsupported, F as MUTATING_OPERATIONS, I as OP_REGISTRY, L as READ_OPERATIONS, M as auditLogPlugin, N as aggregateHelpersPlugin, O as AggregationBuilder, P as ALL_OPERATIONS, R as operationsByPolicyKey, S as cascadePlugin, T as Repository, _ as customIdPlugin, a as uniqueField, b as prefixedId, c as createTenantContext, d as observabilityPlugin, f as multiTenantPlugin, g as elasticSearchPlugin, h as fieldFilterPlugin, i as requireField, j as auditTrailPlugin, k as batchOperationsPlugin, l as subdocumentPlugin, m as methodRegistryPlugin, n as blockIf, o as validationChainPlugin, p as mongoOperationsPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as softDeletePlugin, v as dateSequentialId, w as HOOK_PRIORITY, x as sequentialId, y as getNextSequence } from "./validation-chain.plugin-Dllv-cml.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-CvDFfVXT.mjs";
 import { isGeoOperator, parseGeoFilter } from "./query/primitives/geo.mjs";
 import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "./field-selection-dI0m4RBs.mjs";
 import { buildFieldTypeMap, coerceFieldValue, coerceHeuristic } from "./query/primitives/coercion.mjs";
@@ -11,6 +11,20 @@ import { extractSchemaIndexes } from "./query/primitives/indexes.mjs";
 import { n as buildCrudSchemasFromMongooseSchema, r as createMemoryCache, t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-D1sdCOmj.mjs";
 //#region src/query/QueryParser.ts
 /**
+* Top-level query parameters that mongokit handles outside the filter
+* pipeline. Used by `_handleBracketSyntax` to detect a common typo where a
+* caller wrote `?filters[limit]=5` instead of `?limit=5` and the qs parser
+* nested the key under a filter object — the value is silently dropped
+* without this guard. Kept as a Set for O(1) lookup; values mirror the
+* reserved-key list at the top of `_parseFilters`.
+*/
+const RESERVED_PAGINATION_KEYS = new Set([
+	"page",
+	"limit",
+	"sort",
+	"select"
+]);
+/**
 * Modern Query Parser
 * Converts URL parameters to MongoDB queries with $lookup support
 */
@@ -711,6 +725,7 @@ var QueryParser = class {
 			warn(`[mongokit] Nested filter depth exceeds maximum, skipping field: ${field}`);
 			return;
 		}
+		for (const op of Object.keys(operators)) if (RESERVED_PAGINATION_KEYS.has(op)) warn(`[mongokit] Nested filter contains reserved key '${op}' at '${field}.${op}' — did you mean ?${op}=... at the top level? The nested value is ignored.`);
 		if (!parsedFilters[field]) parsedFilters[field] = {};
 		for (const [operator, value] of Object.entries(operators)) {
 			if (value === "" || value === null || value === void 0) continue;

package/dist/{mongooseToJsonSchema-BH6OFec5.d.mts → mongooseToJsonSchema-DXxjFkLB.d.mts}

@@ -1,21 +1,33 @@
-import { T as FieldPreset, k as HttpError, s as CacheAdapter, yt as UserContext } from "./types-xOyTec4n.mjs";
+import { T as FieldPreset, k as HttpError, s as CacheAdapter, yt as UserContext } from "./types-Dc2aDVUi.mjs";
 import mongoose, { Schema } from "mongoose";
 import { CrudSchemas, SchemaBuilderOptions } from "@classytic/repo-core/schema";
 
 //#region src/utils/error.d.ts
+/** Optional structured fields for createError. */
+interface CreateErrorOptions {
+  /** Stable machine-readable code (e.g. `SEARCH_NOT_CONFIGURED`). */
+  code?: string;
+  /** Diagnostic context — model name, configured modes, doc URL, etc. */
+  meta?: Record<string, unknown>;
+}
 /**
- * Creates an error with HTTP status code
+ * Creates an error with HTTP status code, plus optional stable `code` /
+ * `meta` so callers can `catch` on the code instead of regex-matching the
+ * message string.
  *
  * @param status - HTTP status code
  * @param message - Error message
+ * @param options - Optional `code` / `meta` for structured handling
  * @returns Error with status property
  *
  * @example
  * throw createError(404, 'Document not found');
- * throw createError(400, 'Invalid input');
- * throw createError(403, 'Access denied');
+ * throw createError(400, 'Invalid input', {
+ *   code: 'SEARCH_NOT_CONFIGURED',
+ *   meta: { model: 'Customer', availableModes: ['text', 'regex', 'auto'] },
+ * });
  */
-declare function createError(status: number, message: string): HttpError;
+declare function createError(status: number, message: string, options?: CreateErrorOptions): HttpError;
 /**
  * Boolean classifier: true when `err` is an authoritative MongoDB duplicate
  * key error — and ONLY then. Used by arc's outbox / idempotency adapters to
@@ -171,13 +183,30 @@ declare function configureLogger(config: Partial<LoggerConfig> | false): void;
 declare function createMemoryCache(maxEntries?: number): CacheAdapter;
 //#endregion
 //#region src/utils/mongooseToJsonSchema.d.ts
+/**
+ * Return shape for the schema builders. Structurally a `CrudSchemas` plus
+ * an `[key: string]: unknown` index signature so the function reference
+ * plugs directly into HTTP-framework adapter callbacks typed as
+ * `OpenApiSchemas | Record<string, unknown>` (e.g. arc's
+ * `MongooseAdapterOptions.schemaGenerator`).
+ *
+ * `CrudSchemas` itself is intentionally a closed 4-field shape in
+ * `@classytic/repo-core/schema` — widening at the kit boundary keeps that
+ * contract intact while removing the `as unknown as Record<string, unknown>`
+ * cast every arc + mongokit host previously needed at the wiring site.
+ *
+ * The intersection has zero runtime cost: every `CrudSchemas` value
+ * already satisfies `Record<string, unknown>` structurally; TypeScript
+ * just refuses the assignment without an explicit declaration.
+ */
+type CrudSchemasFramework = CrudSchemas & Record<string, unknown>;
 /**
  * Build CRUD schemas from Mongoose schema
  */
-declare function buildCrudSchemasFromMongooseSchema(mongooseSchema: Schema, options?: SchemaBuilderOptions): CrudSchemas;
+declare function buildCrudSchemasFromMongooseSchema(mongooseSchema: Schema, options?: SchemaBuilderOptions): CrudSchemasFramework;
 /**
  * Build CRUD schemas from Mongoose model
  */
-declare function buildCrudSchemasFromModel(mongooseModel: mongoose.Model<unknown>, options?: SchemaBuilderOptions): CrudSchemas;
+declare function buildCrudSchemasFromModel(mongooseModel: mongoose.Model<unknown>, options?: SchemaBuilderOptions): CrudSchemasFramework;
 //#endregion
 export { createFieldPreset as a, getMongooseProjection as c, parseDuplicateKeyError as d, configureLogger as i, createError as l, buildCrudSchemasFromMongooseSchema as n, filterResponseData as o, createMemoryCache as r, getFieldsForUser as s, buildCrudSchemasFromModel as t, isDuplicateKeyError as u };

package/dist/pagination/PaginationEngine.d.mts

@@ -1,4 +1,4 @@
-import { H as OffsetPaginationResult, N as KeysetPaginationOptions, P as KeysetPaginationResult, V as OffsetPaginationOptions, W as PaginationConfig, a as AnyDocument, n as AggregatePaginationOptions, r as AggregatePaginationResult } from "../types-xOyTec4n.mjs";
+import { H as OffsetPaginationResult, N as KeysetPaginationOptions, P as KeysetPaginationResult, V as OffsetPaginationOptions, W as PaginationConfig, a as AnyDocument, n as AggregatePaginationOptions, r as AggregatePaginationResult } from "../types-Dc2aDVUi.mjs";
 import { Model } from "mongoose";
 
 //#region src/pagination/PaginationEngine.d.ts

package/dist/pagination/PaginationEngine.mjs

@@ -1,2 +1,2 @@
-import { t as PaginationEngine } from "../PaginationEngine-B93fLCcO.mjs";
+import { t as PaginationEngine } from "../PaginationEngine-CvDFfVXT.mjs";
 export { PaginationEngine };

package/dist/plugins/index.d.mts

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

package/dist/plugins/index.mjs

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

package/dist/{types-xOyTec4n.d.mts → types-Dc2aDVUi.d.mts}

@@ -1352,6 +1352,19 @@ interface CascadeOptions {
 /** HTTP Error with status code */
 interface HttpError extends Error {
   status: number;
+  /**
+   * Stable machine-readable error code. Hosts can switch on this in catch
+   * blocks instead of grepping the message string. Currently emitted for:
+   * - `SEARCH_NOT_CONFIGURED` — search requested on a repo with no text
+   *   index AND no `searchMode: 'regex' | 'auto'` + `searchFields` config.
+   */
+  code?: string;
+  /**
+   * Free-form structured metadata for diagnostics. Pairs with `code` so
+   * hosts can render a clearer message in their own UI without parsing
+   * the human-readable `message` string. Safe for logs.
+   */
+  meta?: Record<string, unknown>;
   validationErrors?: Array<{
     validator: string;
     error: string;

package/dist/{update-CWXfFC6O.mjs → update-DEJYcgfV.mjs}

@@ -1,6 +1,6 @@
 import { t as __exportAll } from "./chunk-CfYAbeIz.mjs";
 import { r as warn } from "./logger-DJ7egMnd.mjs";
-import { t as createError } from "./error-CzYwrfUP.mjs";
+import { t as createError } from "./error-B00pI7dV.mjs";
 //#region src/query/LookupBuilder.ts
 /** Stages that are never valid inside a $lookup pipeline */
 const BLOCKED_PIPELINE_STAGES = [

package/dist/utils/index.d.mts

@@ -1,5 +1,5 @@
-import { X as PopulateSpec, ft as SortSpec, ot as SelectSpec } from "../types-xOyTec4n.mjs";
-import { a as createFieldPreset, c as getMongooseProjection, i as configureLogger, l as createError, n as buildCrudSchemasFromMongooseSchema, o as filterResponseData, r as createMemoryCache, s as getFieldsForUser, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-BH6OFec5.mjs";
+import { X as PopulateSpec, ft as SortSpec, ot as SelectSpec } from "../types-Dc2aDVUi.mjs";
+import { a as createFieldPreset, c as getMongooseProjection, i as configureLogger, l as createError, n as buildCrudSchemasFromMongooseSchema, o as filterResponseData, r as createMemoryCache, s as getFieldsForUser, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-DXxjFkLB.mjs";
 
 //#region src/utils/cache-keys.d.ts
 /**

package/dist/utils/index.mjs

@@ -1,5 +1,5 @@
 import { t as configureLogger } from "../logger-DJ7egMnd.mjs";
-import { t as createError } from "../error-CzYwrfUP.mjs";
+import { t as createError } from "../error-B00pI7dV.mjs";
 import { n as isObjectIdInstance, r as isValidIdForType, t as getSchemaIdType } from "../id-resolution-e4BT9zAV.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-dI0m4RBs.mjs";
 import { n as buildCrudSchemasFromMongooseSchema, r as createMemoryCache, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-D1sdCOmj.mjs";

package/dist/{validation-chain.plugin-BGdr5KRw.d.mts → validation-chain.plugin-B0VSdcwa.d.mts}

@@ -1,4 +1,4 @@
-import { B as ObjectId, F as Logger, H as OffsetPaginationResult, T as FieldPreset, X as PopulateSpec, bt as ValidationChainOptions, et as RepositoryContext, f as CascadeOptions, ft as SortSpec, l as CacheOptions, lt as SoftDeleteOptions, nt as RepositoryInstance, ot as SelectSpec, q as Plugin, u as CacheStats, xt as ValidatorDefinition } from "./types-xOyTec4n.mjs";
+import { B as ObjectId, F as Logger, H as OffsetPaginationResult, T as FieldPreset, X as PopulateSpec, bt as ValidationChainOptions, et as RepositoryContext, f as CascadeOptions, ft as SortSpec, l as CacheOptions, lt as SoftDeleteOptions, nt as RepositoryInstance, ot as SelectSpec, q as Plugin, u as CacheStats, xt as ValidatorDefinition } from "./types-Dc2aDVUi.mjs";
 import mongoose from "mongoose";
 import { BulkWriteResult } from "@classytic/repo-core/repository";
 import { AsyncLocalStorage } from "node:async_hooks";

package/dist/{validation-chain.plugin-CLjEFr0c.mjs → validation-chain.plugin-Dllv-cml.mjs}

@@ -1,7 +1,7 @@
 import { n as debug, r as warn } from "./logger-DJ7egMnd.mjs";
-import { _ as upsert, a as count, b as LookupBuilder, c as getByQuery, d as deleteById, f as deleteByQuery, h as createMany, l as getOrCreate, m as create, n as update, o as exists, r as updateByQuery, s as getById, t as findOneAndUpdate, y as distinct } from "./update-CWXfFC6O.mjs";
-import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-CzYwrfUP.mjs";
-import { t as PaginationEngine } from "./PaginationEngine-B93fLCcO.mjs";
+import { _ as upsert, a as count, b as LookupBuilder, c as getByQuery, d as deleteById, f as deleteByQuery, h as createMany, l as getOrCreate, m as create, n as update, o as exists, r as updateByQuery, s as getById, t as findOneAndUpdate, y as distinct } from "./update-DEJYcgfV.mjs";
+import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-B00pI7dV.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-CvDFfVXT.mjs";
 import { hasNearOperator, rewriteNearForCount } from "./query/primitives/geo.mjs";
 import { r as isValidIdForType, t as getSchemaIdType } from "./id-resolution-e4BT9zAV.mjs";
 import { a as byIdKey, c as listQueryKey, l as modelPattern, o as byQueryKey, r as getFieldsForUser, u as versionKey } from "./field-selection-dI0m4RBs.mjs";
@@ -2892,7 +2892,22 @@ var Repository = class extends RepositoryBase {
 				];
 			} 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.`);
+		else {
+			const modelName = String(this.model);
+			throw createError(400, `No text index found for ${modelName}. Cannot perform text search. Configure ${modelName}'s Repository with { searchMode: 'regex', searchFields: [...] } to enable index-free search, or create a text index on the collection for searchMode: 'text'. See https://github.com/classytic/mongokit/blob/main/docs/README.md#queryparser-url--filter`, {
+				code: "SEARCH_NOT_CONFIGURED",
+				meta: {
+					model: modelName,
+					configuredMode: this.searchMode,
+					availableModes: [
+						"text",
+						"regex",
+						"auto"
+					],
+					docs: "https://github.com/classytic/mongokit/blob/main/docs/README.md#queryparser-url--filter"
+				}
+			});
+		}
 		return query;
 	}
 	/**

package/package.json

@@ -1,143 +1,143 @@
-{
-  "name": "@classytic/mongokit",
-  "version": "3.11.0",
-  "description": "Production-grade MongoDB repositories - smart pagination, events, and plugins. Built on @classytic/repo-core.",
-  "type": "module",
-  "sideEffects": false,
-  "main": "./dist/index.mjs",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.mts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.mts",
-      "default": "./dist/index.mjs"
-    },
-    "./pagination": {
-      "types": "./dist/pagination/PaginationEngine.d.mts",
-      "default": "./dist/pagination/PaginationEngine.mjs"
-    },
-    "./plugins": {
-      "types": "./dist/plugins/index.d.mts",
-      "default": "./dist/plugins/index.mjs"
-    },
-    "./utils": {
-      "types": "./dist/utils/index.d.mts",
-      "default": "./dist/utils/index.mjs"
-    },
-    "./actions": {
-      "types": "./dist/actions/index.d.mts",
-      "default": "./dist/actions/index.mjs"
-    },
-    "./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": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "keywords": [
-    "mongodb",
-    "mongoose",
-    "repository",
-    "repository-pattern",
-    "data-access",
-    "pagination",
-    "cursor-pagination",
-    "infinite-scroll",
-    "offset-pagination",
-    "keyset-pagination",
-    "caching",
-    "redis",
-    "cache",
-    "multi-tenant",
-    "multi-tenancy",
-    "vector-search",
-    "embeddings",
-    "atlas-search",
-    "observability",
-    "event-driven",
-    "plugin-based",
-    "zero-dependencies",
-    "express",
-    "fastify",
-    "nestjs",
-    "nextjs",
-    "typescript"
-  ],
-  "author": "Classytic <classytic.dev@gmail.com> (https://github.com/classytic)",
-  "contributors": [
-    "Sadman Chowdhury (https://github.com/siam923)"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/classytic/mongokit.git"
-  },
-  "bugs": {
-    "url": "https://github.com/classytic/mongokit/issues"
-  },
-  "homepage": "https://github.com/classytic/mongokit#readme",
-  "peerDependencies": {
-    "mongoose": ">=9.4.1",
-    "@classytic/repo-core": ">=0.2.0"
-  },
-  "engines": {
-    "node": ">=22"
-  },
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "test": "vitest run --project unit --project integration",
-    "test:unit": "vitest run --project unit",
-    "test:integration": "vitest run --project integration",
-    "test:e2e": "vitest run --project e2e",
-    "test:all": "vitest run --project unit --project integration --project e2e",
-    "test:watch": "vitest --project unit --project integration",
-    "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit",
-    "typecheck:tests": "tsc --noEmit -p tsconfig.tests.json",
-    "lint": "biome check src/",
-    "lint:fix": "biome check src/ --write",
-    "format": "biome format src/ --write",
-    "check": "biome ci src/ --diagnostic-level=error",
-    "prepublishOnly": "npm run check && npm run build && npm run typecheck && npm run typecheck:tests && npm test",
-    "publish:dry": "npm publish --dry-run --access public",
-    "publish:npm": "npm publish --access public",
-    "release": "npm run check && npm run build && npm run typecheck && npm run typecheck:tests && npm test && npm publish --access public",
-    "release:patch": "npm version patch && npm run release",
-    "release:minor": "npm version minor && npm run release",
-    "release:major": "npm version major && npm run release"
-  },
-  "devDependencies": {
-    "@arethetypeswrong/cli": "^0.18.2",
-    "@biomejs/biome": "^2.4.10",
-    "@classytic/repo-core": ">=0.1.0",
-    "@types/node": "^22.0.0",
-    "@vitest/coverage-v8": "^3.2.4",
-    "ajv": "^8.18.0",
-    "ajv-formats": "^3.0.1",
-    "dotenv": "^17.4.2",
-    "knip": "^6.3.0",
-    "mongodb-memory-server": "^10.4.3",
-    "mongoose": "^9.4.1",
-    "publint": "^0.3.18",
-    "tsdown": "^0.21.8",
-    "typescript": "^5.7.0",
-    "vitest": "^3.2.4"
-  }
-}
+{
+  "name": "@classytic/mongokit",
+  "version": "3.11.1",
+  "description": "Production-grade MongoDB repositories - smart pagination, events, and plugins. Built on @classytic/repo-core.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./pagination": {
+      "types": "./dist/pagination/PaginationEngine.d.mts",
+      "default": "./dist/pagination/PaginationEngine.mjs"
+    },
+    "./plugins": {
+      "types": "./dist/plugins/index.d.mts",
+      "default": "./dist/plugins/index.mjs"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.mts",
+      "default": "./dist/utils/index.mjs"
+    },
+    "./actions": {
+      "types": "./dist/actions/index.d.mts",
+      "default": "./dist/actions/index.mjs"
+    },
+    "./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": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mongodb",
+    "mongoose",
+    "repository",
+    "repository-pattern",
+    "data-access",
+    "pagination",
+    "cursor-pagination",
+    "infinite-scroll",
+    "offset-pagination",
+    "keyset-pagination",
+    "caching",
+    "redis",
+    "cache",
+    "multi-tenant",
+    "multi-tenancy",
+    "vector-search",
+    "embeddings",
+    "atlas-search",
+    "observability",
+    "event-driven",
+    "plugin-based",
+    "zero-dependencies",
+    "express",
+    "fastify",
+    "nestjs",
+    "nextjs",
+    "typescript"
+  ],
+  "author": "Classytic <classytic.dev@gmail.com> (https://github.com/classytic)",
+  "contributors": [
+    "Sadman Chowdhury (https://github.com/siam923)"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/classytic/mongokit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/classytic/mongokit/issues"
+  },
+  "homepage": "https://github.com/classytic/mongokit#readme",
+  "peerDependencies": {
+    "mongoose": ">=9.4.1",
+    "@classytic/repo-core": ">=0.2.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run --project unit --project integration",
+    "test:unit": "vitest run --project unit",
+    "test:integration": "vitest run --project integration",
+    "test:e2e": "vitest run --project e2e",
+    "test:all": "vitest run --project unit --project integration --project e2e",
+    "test:watch": "vitest --project unit --project integration",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "typecheck:tests": "tsc --noEmit -p tsconfig.tests.json",
+    "lint": "biome check src/",
+    "lint:fix": "biome check src/ --write",
+    "format": "biome format src/ --write",
+    "check": "biome ci src/ --diagnostic-level=error",
+    "prepublishOnly": "npm run check && npm run build && npm run typecheck && npm run typecheck:tests && npm test",
+    "publish:dry": "npm publish --dry-run --access public",
+    "publish:npm": "npm publish --access public",
+    "release": "npm run check && npm run build && npm run typecheck && npm run typecheck:tests && npm test && npm publish --access public",
+    "release:patch": "npm version patch && npm run release",
+    "release:minor": "npm version minor && npm run release",
+    "release:major": "npm version major && npm run release"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@biomejs/biome": "^2.4.10",
+    "@classytic/repo-core": ">=0.2.0",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1",
+    "dotenv": "^17.4.2",
+    "knip": "^6.3.0",
+    "mongodb-memory-server": "^10.4.3",
+    "mongoose": "^9.4.1",
+    "publint": "^0.3.18",
+    "tsdown": "^0.21.8",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.4"
+  }
+}