@classytic/mongokit 3.5.5 → 3.5.6

package/README.md

@@ -15,9 +15,13 @@
 - **17 built-in plugins** - Caching, soft delete, audit trail, validation, multi-tenant, custom IDs, observability, Elasticsearch, and more
 - **Distributed cache safety** - List cache versions stored in the adapter (Redis) for multi-pod correctness
 - **Search governance** - Text index guard (throws `400` if no index), allowlisted sort/filter fields, ReDoS protection
+- **Geo queries** - `[near]`, `[nearSphere]`, `[withinRadius]`, `[geoWithin]` URL operators with auto sort/count handling
+- **Schema-aware coercion** - Pass `schema: Model.schema` to QueryParser for deterministic type-safe filter values
+- **String/UUID/Number `_id` support** - Works out of the box with any `_id` type, not just ObjectId
+- **Query primitives** - Composable pure functions (`coercion`, `geo`, `indexes`) importable standalone for custom parsers
 - **Vector search** - MongoDB Atlas `$vectorSearch` with auto-embedding and multimodal support
 - **TypeScript first** - Full type safety with discriminated unions, typed events, and field autocomplete
-- **Extensively tested** — battle-tested and production-ready
+- **Extensively tested** — 1500+ tests, Mongoose 9.4.1 aligned, battle-tested and production-ready
 
 ## Installation
 
@@ -25,7 +29,7 @@
 npm install @classytic/mongokit mongoose
 ```
 
-> Requires Mongoose `^9.0.0` | Node.js `>=22`
+> Requires Mongoose `>=9.4.1` | Node.js `>=22`
 
 ## Quick Start
 
@@ -231,6 +235,89 @@ User input is regex-escaped (literal substring match), and any pre-existing
 > (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.
 
+### Geo queries
+
+QueryParser supports 4 geo operators that compile to canonical GeoJSON-shaped
+MongoDB queries. All validate coordinate ranges and reject malformed input by
+dropping the filter (not silently widening).
+
+```javascript
+const parser = new QueryParser({ schema: PlaceModel.schema });
+
+// Distance-sorted (implicit distance ordering, no explicit sort allowed)
+const near = parser.parse({ "location[near]": "-73.98,40.76,5000" });
+// → { location: { $near: { $geometry: { type: 'Point', coordinates: [-73.98, 40.76] }, $maxDistance: 5000 } } }
+
+// Count-compatible radius — use this for paginated getAll (supports sort + count)
+const radius = parser.parse({ "location[withinRadius]": "-73.98,40.76,5000" });
+// → { location: { $geoWithin: { $centerSphere: [[-73.98, 40.76], 0.000783...] } } }
+
+// Bounding box (works without a 2dsphere index)
+const box = parser.parse({ "location[geoWithin]": "-74,40.7,-73.9,40.8" });
+// → { location: { $geoWithin: { $box: [[-74, 40.7], [-73.9, 40.8]] } } }
+```
+
+**Repository integration:** `Repository.getAll` auto-detects `$near` /
+`$nearSphere` in filters and handles the MongoDB constraints transparently:
+
+- Skips the default `-createdAt` sort (MongoDB forbids explicit sort with `$near`)
+- Warns and drops any caller-supplied sort that conflicts
+- Rewrites the count query via `$geoWithin: $centerSphere` for accurate `total`
+- Falls back to `countStrategy: 'none'` for unbounded `$near` (no `$maxDistance`)
+- All plugins (multi-tenant, soft-delete, cache, populate) compose unchanged
+
+Use `[near]` when you need distance-sorted results. Use `[withinRadius]` when
+you need paginated lists with `total` and custom sort.
+
+### String / UUID / Number `_id`
+
+Schemas that declare `_id` as `String`, `Number`, or `UUID` instead of the
+default `ObjectId` work out of the box — no configuration needed:
+
+```typescript
+const SessionSchema = new Schema({
+  _id: { type: String, default: () => randomUUID() },
+  userId: { type: String, required: true },
+});
+
+const repo = new Repository(SessionModel);
+await repo.create({ userId: "user-1" });         // _id auto-generated as UUID
+await repo.getById("550e8400-e29b-...");          // works — no ObjectId validation
+await repo.update("550e8400-e29b-...", { ... });  // works
+```
+
+The `id-resolution` utility detects the `_id` type from the schema and
+validates accordingly. Schema generation also includes String `_id` as an
+optional field in `createBody` so Fastify/AJV validation accepts user-supplied
+IDs. Available standalone:
+
+```typescript
+import { getSchemaIdType, isValidIdForType } from "@classytic/mongokit/utils";
+
+const idType = getSchemaIdType(SessionModel.schema); // 'string'
+isValidIdForType("550e8400-...", idType);             // true
+isValidIdForType("not-valid", "objectid");            // false
+```
+
+### Query primitives
+
+Pure, composable functions that power QueryParser internals — importable
+standalone for custom parsers, Arc controllers, migration scripts, and AI
+agents that build queries programmatically:
+
+```typescript
+// Geo
+import { parseGeoFilter, hasNearOperator } from "@classytic/mongokit/query/primitives/geo";
+// Coercion
+import { coerceFieldValue, buildFieldTypeMap } from "@classytic/mongokit/query/primitives/coercion";
+// Schema indexes
+import { extractSchemaIndexes } from "@classytic/mongokit/query/primitives/indexes";
+```
+
+Each primitive is independently unit-tested, tree-shake friendly (no barrel),
+and decoupled from Mongoose — they accept structural types, not concrete
+Mongoose instances.
+
 ## Plugins
 
 ### Using Plugins
@@ -1206,6 +1293,12 @@ GET /users?sort=-createdAt,name
 # Search (default: text index; or configure searchMode: 'regex' / 'auto')
 GET /users?search=john
 
+# Geo queries (requires 2dsphere index for near/nearSphere)
+GET /places?location[near]=-73.98,40.76,5000         # Within 5km, distance-sorted
+GET /places?location[nearSphere]=-73.98,40.76,5000    # Spherical variant
+GET /places?location[withinRadius]=-73.98,40.76,5000   # Count-compatible radius (use for paginated lists)
+GET /places?location[geoWithin]=-74,40.7,-73.9,40.8   # Bounding box (no index required)
+
 # Simple populate
 GET /posts?populate=author,category
 
@@ -1601,14 +1694,15 @@ await repo.getById('my-chat-uuid', { idField: 'chatId' });  // by chatId
 
 All plugins respect `idField`: soft-delete, cascade, audit-log, audit-trail, validation-chain, elastic, cache, observability.
 
-## No Breaking Changes
+## Mongoose Compatibility
 
-Extending Repository works exactly the same with Mongoose 8 and 9. The package:
+Requires Mongoose `>=9.4.1`. Tested and aligned with Mongoose 9.4.1. The package:
 
 - Uses its own event system (not Mongoose middleware)
 - Defines its own `FilterQuery` type (unaffected by Mongoose 9 rename)
 - Properly gates update pipelines (safe for Mongoose 9's stricter defaults)
-- Full test suite passes on Mongoose 9
+- Reads `embeddedSchemaType.instance` for array element types (Mongoose 9.x)
+- 1500+ tests pass on Mongoose 9.4.1
 
 ## License
 

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-Buj7P006.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-DmVbUzDL.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-CWUL0yiw.mjs";
+import { J as Plugin } from "../types-BwO4u3JN.mjs";
 import { ClientSession, PipelineStage } from "mongoose";
 
 //#region src/ai/types.d.ts

package/dist/id-resolution-LZ-cCwR5.mjs

@@ -0,0 +1,81 @@
+import mongoose from "mongoose";
+//#region src/utils/id-resolution.ts
+/**
+* ID Resolution Primitive
+*
+* Pure functions for detecting a Mongoose schema's _id type and validating
+* id values against it. Used by Repository.getById to decide whether to
+* run ObjectId validation (for ObjectId schemas) or skip it (for String /
+* Number / UUID schemas).
+*
+* Also usable standalone — Arc controllers, custom repositories, migration
+* scripts, or test harnesses can import these directly to make the same
+* decision without depending on Repository.
+*
+* Design: no `this`, no Model, no DB calls. Only reads `schema.paths._id.instance`.
+*/
+/**
+* Check if a Mongoose SchemaType `instance` string is an ObjectId variant.
+* Mongoose 9.x uses `'ObjectId'`, older versions use `'ObjectID'`. This
+* is the single source of truth — use it instead of inline
+* `instance === 'ObjectId' || instance === 'ObjectID'` checks.
+*/
+function isObjectIdInstance(instance) {
+	return instance === "ObjectId" || instance === "ObjectID";
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+* Detect the _id path type from a Mongoose schema.
+*
+* Returns 'objectid' as the safe default when:
+*   - No schema is provided (mock models, test harnesses)
+*   - The schema has no `paths._id` (auto-generated ObjectId)
+*   - The instance string is unrecognized
+*
+* This safe-default means existing callers that don't set _id explicitly
+* get the same ObjectId validation they always had — the behavioral change
+* is strictly opt-in via schema declaration.
+*/
+function getSchemaIdType(schema) {
+	const instance = schema?.paths?._id?.instance;
+	if (!instance) return "objectid";
+	if (isObjectIdInstance(instance)) return "objectid";
+	switch (instance) {
+		case "String": return "string";
+		case "Number": return "number";
+		case "UUID": return "uuid";
+		default: return "unknown";
+	}
+}
+/**
+* Validate an id value against a known _id type — WITHOUT hitting the DB.
+*
+* Returns `true` when the value is structurally valid for the given type.
+* Returns `false` when it's definitely invalid (Repository should return
+* 404 / null immediately rather than wasting a round-trip).
+*
+* For `'string'` and `'unknown'` types, validation is intentionally
+* permissive: any truthy, non-empty value is accepted. The DB is the
+* authority for whether the document exists — we only reject values that
+* are structurally impossible (null, undefined, empty string).
+*/
+function isValidIdForType(id, idType) {
+	if (id === null || id === void 0) return false;
+	switch (idType) {
+		case "objectid": {
+			if (typeof id === "object") return mongoose.Types.ObjectId.isValid(id);
+			const s = String(id);
+			return s.length > 0 && mongoose.Types.ObjectId.isValid(s);
+		}
+		case "string": return String(id).length > 0;
+		case "number": {
+			if (typeof id === "number") return Number.isFinite(id);
+			const n = Number(id);
+			return Number.isFinite(n);
+		}
+		case "uuid": return typeof id === "string" && UUID_RE.test(id);
+		case "unknown": return String(id).length > 0;
+	}
+}
+//#endregion
+export { isObjectIdInstance as n, isValidIdForType as r, getSchemaIdType as t };

package/dist/{index-Buj7P006.d.mts → index-DmVbUzDL.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-CWUL0yiw.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-BwO4u3JN.mjs";
 import { ClientSession, 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, 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 { $ 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-BwO4u3JN.mjs";
+import { t as index_d_exports } from "./index-DmVbUzDL.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-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 { 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-BtmT-FFB.mjs";
+import { n as SchemaPathsLike, t as FieldType$1 } from "./coercion-B19MD38s.mjs";
+import { n as SchemaIndexes } from "./indexes-qIBCZ3mY.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-DQMU0Dlv.mjs";
 import * as _$mongoose from "mongoose";
 import { ClientSession, Expression, Model, PipelineStage, PopulateOptions } from "mongoose";
 
@@ -1111,6 +1111,21 @@ declare class Repository<TDoc = unknown> {
    * 4. DEFAULT (500) — user-registered hooks
    */
   _buildContext(operation: string, options: Record<string, unknown> | object): Promise<RepositoryContext>;
+  /**
+   * Resolve the effective sort for getAll. Handles $near conflict detection
+   * (warns + drops explicit sort when $near is in filters).
+   */
+  private _resolveSort;
+  /**
+   * Detect whether to use keyset (cursor) or offset (page) pagination.
+   */
+  private _detectPaginationMode;
+  /**
+   * Build the MongoDB query filter with search merged in. Handles text
+   * search ($text), regex search ($or of $regex), and the search-resolver
+   * plugin contract (search already cleared by a before:getAll hook).
+   */
+  private _buildSearchQuery;
   /**
    * Parse sort string or object
    */

package/dist/index.mjs

@@ -2,12 +2,12 @@ import { a as warn, n as parseDuplicateKeyError, r as configureLogger, t as crea
 import { y as LookupBuilder } from "./update-AVfKWNGt.mjs";
 import { t as actions_exports } from "./actions/index.mjs";
 import { t as PaginationEngine } from "./PaginationEngine-CpsQl471.mjs";
-import { A as aggregateHelpersPlugin, C as HOOK_PRIORITY, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as cachePlugin, T as AggregationBuilder, _ as dateSequentialId, a as uniqueField, b as sequentialId, c as subdocumentPlugin, d as multiTenantPlugin, f as mongoOperationsPlugin, g as customIdPlugin, h as elasticSearchPlugin, i as requireField, k as auditLogPlugin, l as softDeletePlugin, m as fieldFilterPlugin, n as blockIf, o as validationChainPlugin, p as methodRegistryPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as observabilityPlugin, v as getNextSequence, w as Repository, x as cascadePlugin, y as prefixedId } from "./validation-chain.plugin-BCPh2UZG.mjs";
+import { A as aggregateHelpersPlugin, C as HOOK_PRIORITY, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as cachePlugin, T as AggregationBuilder, _ as dateSequentialId, a as uniqueField, b as sequentialId, c as subdocumentPlugin, d as multiTenantPlugin, f as mongoOperationsPlugin, g as customIdPlugin, h as elasticSearchPlugin, i as requireField, k as auditLogPlugin, l as softDeletePlugin, m as fieldFilterPlugin, n as blockIf, o as validationChainPlugin, p as methodRegistryPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as observabilityPlugin, v as getNextSequence, w as Repository, x as cascadePlugin, y as prefixedId } from "./validation-chain.plugin-DCYjnPau.mjs";
 import { isGeoOperator, parseGeoFilter } from "./query/primitives/geo.mjs";
-import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "./field-selection-reyDRzXf.mjs";
+import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "./field-selection-C5o7jyyA.mjs";
 import { buildFieldTypeMap, coerceFieldValue, coerceHeuristic } from "./query/primitives/coercion.mjs";
 import { extractSchemaIndexes } from "./query/primitives/indexes.mjs";
-import { a as isFieldUpdateAllowed, i as getSystemManagedFields, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-DpjhFfaO.mjs";
+import { a as isFieldUpdateAllowed, i as getSystemManagedFields, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-8Cyu3NFJ.mjs";
 //#region src/query/QueryParser.ts
 /**
 * Modern Query Parser

package/dist/{mongooseToJsonSchema-DpjhFfaO.mjs → mongooseToJsonSchema-8Cyu3NFJ.mjs}

@@ -1,3 +1,4 @@
+import { n as isObjectIdInstance } from "./id-resolution-LZ-cCwR5.mjs";
 import "mongoose";
 //#region src/utils/memory-cache.ts
 /**
@@ -93,28 +94,56 @@ function buildCrudSchemasFromModel(mongooseModel, options = {}) {
 	return buildCrudSchemasFromMongooseSchema(mongooseModel.schema, options);
 }
 /**
-* Get fields that are immutable (cannot be updated)
+* Collect fields to omit from a generated schema based on field rules and
+* explicit omit lists. This is the single source of truth for "which fields
+* should NOT appear in the create/update body" — called by both the
+* path-based and tree-based schema builders.
+*/
+function collectFieldsToOmit(options, purpose) {
+	const result = new Set([
+		"createdAt",
+		"updatedAt",
+		"__v"
+	]);
+	const rules = options?.fieldRules || {};
+	for (const [field, rule] of Object.entries(rules)) {
+		if (rule.systemManaged) result.add(field);
+		if (purpose === "update" && (rule.immutable || rule.immutableAfterCreate)) result.add(field);
+	}
+	const explicit = purpose === "create" ? options?.create?.omitFields : options?.update?.omitFields;
+	if (explicit) for (const f of explicit) result.add(f);
+	return result;
+}
+/**
+* Apply omissions + optional-overrides to a built JSON schema in-place.
+* Removes properties and adjusts the `required` array.
+*/
+function applyFieldRules(schema, fieldsToOmit, options) {
+	for (const field of fieldsToOmit) {
+		if (schema.properties?.[field]) delete schema.properties[field];
+		if (schema.required) schema.required = schema.required.filter((k) => k !== field);
+	}
+	const rules = options?.fieldRules || {};
+	for (const [field, rule] of Object.entries(rules)) if (rule.optional && schema.required) schema.required = schema.required.filter((k) => k !== field);
+}
+/**
+* Get fields that are immutable (cannot be updated).
+* Delegates to `collectFieldsToOmit` internally.
 */
 function getImmutableFields(options = {}) {
 	const immutable = [];
-	const fieldRules = options?.fieldRules || {};
-	Object.entries(fieldRules).forEach(([field, rules]) => {
-		if (rules.immutable || rules.immutableAfterCreate) immutable.push(field);
-	});
-	(options?.update?.omitFields || []).forEach((f) => {
-		if (!immutable.includes(f)) immutable.push(f);
-	});
+	const rules = options?.fieldRules || {};
+	for (const [field, rule] of Object.entries(rules)) if (rule.immutable || rule.immutableAfterCreate) immutable.push(field);
+	for (const f of options?.update?.omitFields || []) if (!immutable.includes(f)) immutable.push(f);
 	return immutable;
 }
 /**
-* Get fields that are system-managed (cannot be set by users)
+* Get fields that are system-managed (cannot be set by users).
 */
 function getSystemManagedFields(options = {}) {
 	const systemManaged = [];
-	const fieldRules = options?.fieldRules || {};
-	Object.entries(fieldRules).forEach(([field, rules]) => {
-		if (rules.systemManaged) systemManaged.push(field);
-	});
+	const rules = options?.fieldRules || {};
+	for (const [field, rule] of Object.entries(rules)) if (rule.systemManaged) systemManaged.push(field);
 	return systemManaged;
 }
 /**
@@ -161,7 +190,11 @@ function buildJsonSchemaFromPaths(mongooseSchema, options) {
 	};
 	const rootFields = /* @__PURE__ */ new Map();
 	for (const [path, schemaType] of Object.entries(paths)) {
-		if (path === "_id" || path === "__v") continue;
+		if (path === "__v") continue;
+		if (path === "_id") {
+			const instance = schemaType.instance;
+			if (!instance || isObjectIdInstance(instance)) continue;
+		}
 		const rootField = path.split(".")[0];
 		if (!rootFields.has(rootField)) rootFields.set(rootField, []);
 		rootFields.get(rootField)?.push({
@@ -183,30 +216,12 @@ function buildJsonSchemaFromPaths(mongooseSchema, options) {
 		properties
 	};
 	if (required.length) schema.required = required;
-	const fieldsToOmit = new Set([
-		"createdAt",
-		"updatedAt",
-		"__v"
-	]);
-	(options?.create?.omitFields || []).forEach((f) => {
-		fieldsToOmit.add(f);
-	});
-	const fieldRules = options?.fieldRules || {};
-	Object.entries(fieldRules).forEach(([field, rules]) => {
-		if (rules.systemManaged) fieldsToOmit.add(field);
-	});
-	fieldsToOmit.forEach((field) => {
-		if (schema.properties?.[field]) delete schema.properties[field];
-		if (schema.required) schema.required = schema.required.filter((k) => k !== field);
-	});
+	applyFieldRules(schema, collectFieldsToOmit(options, "create"), options);
 	const reqOv = options?.create?.requiredOverrides || {};
 	const optOv = options?.create?.optionalOverrides || {};
 	schema.required = schema.required || [];
 	for (const [k, v] of Object.entries(reqOv)) if (v && !schema.required.includes(k)) schema.required.push(k);
 	for (const [k, v] of Object.entries(optOv)) if (v && schema.required) schema.required = schema.required.filter((x) => x !== k);
-	Object.entries(fieldRules).forEach(([field, rules]) => {
-		if (rules.optional && schema.required) schema.required = schema.required.filter((x) => x !== field);
-	});
 	const schemaOverrides = options?.create?.schemaOverrides || {};
 	for (const [k, override] of Object.entries(schemaOverrides)) if (schema.properties?.[k]) schema.properties[k] = override;
 	if (options?.strictAdditionalProperties === true) schema.additionalProperties = false;
@@ -270,7 +285,7 @@ function schemaTypeToJsonSchema(schemaType) {
 	else if (instance === "Date") {
 		result.type = "string";
 		result.format = "date-time";
-	} else if (instance === "ObjectId" || instance === "ObjectID") {
+	} else if (isObjectIdInstance(instance)) {
 		result.type = "string";
 		result.pattern = "^[0-9a-fA-F]{24}$";
 	} else if (instance === "Array") {
@@ -285,17 +300,7 @@ function schemaTypeToJsonSchema(schemaType) {
 function buildJsonSchemaForUpdate(createJson, options) {
 	const clone = JSON.parse(JSON.stringify(createJson));
 	delete clone.required;
-	const fieldsToOmit = /* @__PURE__ */ new Set();
-	(options?.update?.omitFields || []).forEach((f) => {
-		fieldsToOmit.add(f);
-	});
-	const fieldRules = options?.fieldRules || {};
-	Object.entries(fieldRules).forEach(([field, rules]) => {
-		if (rules.immutable || rules.immutableAfterCreate) fieldsToOmit.add(field);
-	});
-	fieldsToOmit.forEach((field) => {
-		if (clone.properties?.[field]) delete clone.properties[field];
-	});
+	applyFieldRules(clone, collectFieldsToOmit(options, "update"), options);
 	if (options?.strictAdditionalProperties === true) clone.additionalProperties = false;
 	if (options?.update?.requireAtLeastOne === true) clone.minProperties = 1;
 	return clone;

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

@@ -1,4 +1,4 @@
-import { T as FieldPreset, _ as CrudSchemas, k as HttpError, ot as SchemaBuilderOptions, s as CacheAdapter, xt as ValidationResult, yt as UserContext } from "./types-CWUL0yiw.mjs";
+import { T as FieldPreset, _ as CrudSchemas, k as HttpError, ot as SchemaBuilderOptions, s as CacheAdapter, xt as ValidationResult, yt as UserContext } from "./types-BwO4u3JN.mjs";
 import mongoose, { Schema } from "mongoose";
 
 //#region src/utils/error.d.ts
@@ -146,11 +146,12 @@ declare function buildCrudSchemasFromMongooseSchema(mongooseSchema: Schema, opti
  */
 declare function buildCrudSchemasFromModel(mongooseModel: mongoose.Model<unknown>, options?: SchemaBuilderOptions): CrudSchemas;
 /**
- * Get fields that are immutable (cannot be updated)
+ * Get fields that are immutable (cannot be updated).
+ * Delegates to `collectFieldsToOmit` internally.
  */
 declare function getImmutableFields(options?: SchemaBuilderOptions): string[];
 /**
- * Get fields that are system-managed (cannot be set by users)
+ * Get fields that are system-managed (cannot be set by users).
  */
 declare function getSystemManagedFields(options?: SchemaBuilderOptions): string[];
 /**

package/dist/pagination/PaginationEngine.d.mts

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

package/dist/plugins/index.d.mts

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

package/dist/plugins/index.mjs

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

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

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

package/dist/query/primitives/coercion.mjs

@@ -1,3 +1,4 @@
+import { n as isObjectIdInstance } from "../../id-resolution-LZ-cCwR5.mjs";
 import mongoose from "mongoose";
 //#region src/query/primitives/coercion.ts
 /**
@@ -39,10 +40,10 @@ function normalizeMongooseType(schemaType) {
 		case "Number": return "number";
 		case "Boolean": return "boolean";
 		case "Date": return "date";
-		case "ObjectID":
-		case "ObjectId": return "objectid";
 		case "Mixed": return "mixed";
-		default: return null;
+		default:
+			if (isObjectIdInstance(raw)) return "objectid";
+			return null;
 	}
 }
 /**

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

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

package/dist/utils/index.d.mts

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

package/dist/utils/index.mjs

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

package/dist/{validation-chain.plugin-Dn41aAbK.d.mts → validation-chain.plugin-BtmT-FFB.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-CWUL0yiw.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-BwO4u3JN.mjs";
 import mongoose, { ClientSession } from "mongoose";
 
 //#region src/plugins/aggregate-helpers.plugin.d.ts

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

@@ -2,7 +2,8 @@ import { a as warn, i as debug, n as parseDuplicateKeyError, t as createError }
 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-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 { r as isValidIdForType, t as getSchemaIdType } from "./id-resolution-LZ-cCwR5.mjs";
+import { a as byIdKey, c as listQueryKey, l as modelPattern, o as byQueryKey, r as getFieldsForUser, u as versionKey } from "./field-selection-C5o7jyyA.mjs";
 import mongoose from "mongoose";
 //#region src/plugins/aggregate-helpers.plugin.ts
 /**
@@ -1370,7 +1371,7 @@ var Repository = class {
 				});
 				return result;
 			}
-			if (typeof id === "string" && !mongoose.Types.ObjectId.isValid(id)) {
+			if (!isValidIdForType(id, getSchemaIdType(this.Model.schema))) {
 				if (context.throwOnNotFound === false || options.throwOnNotFound === false) return null;
 				throw createError(404, "Document not found");
 			}
@@ -1549,41 +1550,14 @@ var Repository = class {
 		});
 		const filters = context.filters ?? params.filters ?? {};
 		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 isNearQuery = hasNearOperator(filters);
+		const sort = this._resolveSort(context, params, isNearQuery);
 		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;
 		const mode = context.mode ?? params.mode;
-		let useKeyset = false;
-		if (mode) useKeyset = mode === "keyset";
-		else useKeyset = !page && !!(after || sort !== "-createdAt" && (context.sort ?? params.sort));
-		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"));
-			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 useKeyset = this._detectPaginationMode(mode, page, after, sort, context, params);
+		const query = this._buildSearchQuery(filters, search);
 		const populateSpec = options.populateOptions || params.populateOptions || context.populate || options.populate;
 		const paginationOptions = {
 			filters: query,
@@ -2238,6 +2212,56 @@ var Repository = class {
 		return context;
 	}
 	/**
+	* Resolve the effective sort for getAll. Handles $near conflict detection
+	* (warns + drops explicit sort when $near is in filters).
+	*/
+	_resolveSort(context, params, isNearQuery) {
+		const explicitSort = context.sort ?? params.sort;
+		if (isNearQuery) {
+			if (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.`);
+			return;
+		}
+		return explicitSort ?? "-createdAt";
+	}
+	/**
+	* Detect whether to use keyset (cursor) or offset (page) pagination.
+	*/
+	_detectPaginationMode(mode, page, after, sort, context, params) {
+		if (mode) return mode === "keyset";
+		return !page && !!(after || sort !== "-createdAt" && (context.sort ?? params.sort));
+	}
+	/**
+	* Build the MongoDB query filter with search merged in. Handles text
+	* search ($text), regex search ($or of $regex), and the search-resolver
+	* plugin contract (search already cleared by a before:getAll hook).
+	*/
+	_buildSearchQuery(filters, search) {
+		const query = { ...filters };
+		if (!search) return query;
+		if (this._hasTextIndex === null) this._hasTextIndex = this.Model.schema.indexes().some((idx) => idx[0] && Object.values(idx[0]).includes("text"));
+		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.`);
+		return query;
+	}
+	/**
 	* Parse sort string or object
 	*/
 	_parseSort(sort) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/mongokit",
-  "version": "3.5.5",
+  "version": "3.5.6",
   "description": "Production-grade MongoDB repositories with zero dependencies - smart pagination, events, and plugins",
   "type": "module",
   "sideEffects": false,
@@ -93,7 +93,7 @@
   },
   "homepage": "https://github.com/classytic/mongokit#readme",
   "peerDependencies": {
-    "mongoose": "^9.4.1"
+    "mongoose": ">=9.4.1"
   },
   "engines": {
     "node": ">=22"