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

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

package/dist/actions/index.d.mts

@@ -1,2 +1,2 @@
-import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-BNpVzw_-.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-CkE3mOaW.mjs";
+import { J as Plugin } from "../types-BwO4u3JN.mjs";
 import { ClientSession, PipelineStage } from "mongoose";
 
 //#region src/ai/types.d.ts

package/dist/coercion-B19MD38s.d.mts

@@ -0,0 +1,106 @@
+//#region src/query/primitives/coercion.d.ts
+/**
+ * Value coercion primitives
+ *
+ * Pure functions that convert raw URL-decoded values into typed values
+ * suitable for MongoDB queries. Two layers:
+ *
+ *   1. `coerceHeuristic(value)` — string-shape based, used when no schema
+ *      is configured. Safe defaults: rejects leading zeros, scientific
+ *      notation, and strings >15 chars to preserve zip codes, phone codes,
+ *      and long numeric IDs that exceed JS safe-integer precision.
+ *
+ *   2. `coerceToType(value, type)` — type-directed, used when a Mongoose
+ *      schema or `fieldTypes` map declares the field's type. Strictly
+ *      better than the heuristic when type information is available.
+ *
+ * QueryParser composes these via `coerceFieldValue(field, value, types)`
+ * which prefers the type-directed path and falls back to the heuristic.
+ *
+ * Field-type extraction from a Mongoose schema is also here so the
+ * normalization logic lives next to the coercion that consumes it.
+ */
+/** Normalized field type used for schema-aware coercion */
+type FieldType = 'string' | 'number' | 'boolean' | 'date' | 'objectid' | 'mixed';
+/**
+ * Minimal structural type for a Mongoose schema (read-only `.paths`).
+ * Mongoose stores array element types in two different shadow properties
+ * depending on version and declaration style:
+ *   - `caster.instance`     — older / some array forms
+ *   - `embeddedSchemaType.instance` — Mongoose 8+, both `[Type]` and `[{ type: Type }]`
+ * We read both and prefer whichever is populated.
+ */
+interface SchemaPathsLike {
+  paths: Record<string, {
+    instance?: string;
+    caster?: {
+      instance?: string;
+    };
+    embeddedSchemaType?: {
+      instance?: string;
+    };
+  }>;
+}
+/**
+ * Map a Mongoose `SchemaType.instance` string to our normalized FieldType.
+ * For arrays (`type: [Number]` or `type: [{ type: Number }]`), Mongoose
+ * stores the element type on `embeddedSchemaType.instance` (Mongoose 8+) or
+ * `caster.instance` (older). We probe both — element-level coercion is what
+ * `[in]`/`[nin]` operators need against typed arrays.
+ *
+ * Returns null for paths we cannot classify (embedded documents handled by
+ * their own nested paths).
+ */
+declare function normalizeMongooseType(schemaType: {
+  instance?: string;
+  caster?: {
+    instance?: string;
+  };
+  embeddedSchemaType?: {
+    instance?: string;
+  };
+}): FieldType | null;
+/**
+ * Build a normalized field-type map from a Mongoose schema and an optional
+ * override map. The override wins on a per-path basis. Paths with unmappable
+ * types are silently skipped — `coerceFieldValue` will fall back to the
+ * heuristic for them.
+ */
+declare function buildFieldTypeMap(schema?: SchemaPathsLike | null, overrides?: Record<string, FieldType>): Map<string, FieldType>;
+/**
+ * String-shape heuristic — used when no field type is known.
+ *
+ * Rules (deliberately conservative — silent miscoercion is worse than
+ * leaving a string):
+ *   - `null`/`undefined` pass through
+ *   - Already-typed primitives (number, boolean) pass through
+ *   - Arrays recurse element-wise
+ *   - Objects pass through (filter operator objects, etc.)
+ *   - `'true'`/`'false'` → boolean
+ *   - 24-char hex → kept as string (ObjectId)
+ *   - Strings 1–15 chars matching `^-?(0|[1-9]\d*)(\.\d+)?$` → number
+ *     (rejects leading zeros, scientific notation, hex/octal, NaN, Infinity)
+ *   - Everything else stays a string
+ */
+declare function coerceHeuristic(value: unknown): unknown;
+/**
+ * Type-directed coercion — used when a field's declared type is known.
+ *
+ * Returns the original value unchanged when coercion is impossible
+ * (invalid date, non-numeric string for a Number field) — better to surface
+ * a no-match than to silently produce `Invalid Date` or `NaN` which MongoDB
+ * treats as legitimate query values.
+ */
+declare function coerceToType(value: unknown, type: FieldType): unknown;
+/**
+ * Field-aware coercion. Looks up `field` in `types` and uses
+ * `coerceToType` when found, otherwise falls back to `coerceHeuristic`.
+ *
+ * This is the single choke point QueryParser uses for typed coercion of
+ * direct equality, `[eq]`, `[in]`, `[nin]`, `[gt]`/`[gte]`/`[lt]`/`[lte]`
+ * (the last only when a type is declared — see QueryParser for the
+ * preserves-pre-3.5.5-behavior fallback).
+ */
+declare function coerceFieldValue(field: string, value: unknown, types: Map<string, FieldType>): unknown;
+//#endregion
+export { coerceHeuristic as a, coerceFieldValue as i, SchemaPathsLike as n, coerceToType as o, buildFieldTypeMap as r, normalizeMongooseType as s, FieldType as t };

package/dist/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-BNpVzw_-.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-CkE3mOaW.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