@classytic/mongokit 3.6.3 → 3.7.0

package/dist/index.mjs

@@ -1,13 +1,14 @@
-import { a as warn, n as parseDuplicateKeyError, r as configureLogger, t as createError } from "./error-Bpbi_NKo.mjs";
-import { y as LookupBuilder } from "./update-AVfKWNGt.mjs";
+import { r as warn, t as configureLogger } from "./logger-DJ7egMnd.mjs";
+import { y as LookupBuilder } from "./update-BDsQ3cdy.mjs";
+import { n as parseDuplicateKeyError, t as createError } from "./error-Lw9GEAro.mjs";
 import { t as actions_exports } from "./actions/index.mjs";
-import { t as PaginationEngine } from "./PaginationEngine-CunXkR9p.mjs";
-import { A as auditTrailPlugin, C as HOOK_PRIORITY, D as AggregationBuilder, E as withTransaction, M as aggregateHelpersPlugin, O as batchOperationsPlugin, S as cachePlugin, T as isTransactionUnsupported, _ 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, j as auditLogPlugin, k as AuditTrailQuery, 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-7A5qGEQq.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-CPmZv7Ds.mjs";
+import { A as AuditTrailQuery, C as cachePlugin, D as withTransaction, E as isTransactionUnsupported, M as auditLogPlugin, N as aggregateHelpersPlugin, O as AggregationBuilder, 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-CEyJssZl.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-C5o7jyyA.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";
 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-MlaD3C0B.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-DUwXPStK.mjs";
 //#region src/query/QueryParser.ts
 /**
 * Modern Query Parser
@@ -48,15 +49,47 @@ var QueryParser = class {
 	*/
 	_schemaIndexes;
 	/**
-	* Regex patterns that can cause catastrophic backtracking (ReDoS attacks)
-	* Detects:
+	* Regex patterns that can cause catastrophic backtracking (ReDoS attacks).
+	* Detects common footguns:
 	* - Quantifiers: {n,m}
 	* - Possessive quantifiers: *+, ++, ?+
 	* - Nested quantifiers: (a+)+, (a*)*
 	* - Backreferences: \1, \2, etc.
 	* - Complex character classes: [...]...[...]
+	*
+	* This pattern detector is FAIL-SAFE (on match, the input is escaped), but
+	* it is not exhaustive. {@link _regexComplexityExceedsBudget} complements
+	* it with a deterministic static complexity budget so patterns that happen
+	* to evade the detector still fail over when their unbounded-quantifier
+	* density is pathological.
 	*/
 	dangerousRegexPatterns = /(\{[0-9,]+\}|\*\+|\+\+|\?\+|(\(.+\))\+|\(\?:|\\[0-9]|(\[.+\]).+(\[.+\]))/;
+	/**
+	* Static complexity budget for user-supplied regex patterns.
+	* Returns `true` if the pattern crosses a budget that empirically correlates
+	* with ReDoS risk — independent of the heuristic regex detector.
+	*
+	* Budget components (any single threshold crossed → over budget):
+	*   - unbounded quantifiers (`*`, `+`, `?`) — hard cap 20
+	*   - nested groups `(` — hard cap 8
+	*   - alternations `|` — hard cap 10
+	*   - combined: (quantifiers * groups) — hard cap 40
+	*
+	* These thresholds are intentionally permissive for legitimate queries and
+	* tight enough to refuse known-pathological patterns like `(a+)+b` with
+	* heavy repetition.
+	*/
+	_regexComplexityExceedsBudget(patternStr) {
+		const stripped = patternStr.replace(/\\[^\\]/g, "");
+		const unboundedQuantifiers = (stripped.match(/[*+?]/g) ?? []).length;
+		const groups = (stripped.match(/\(/g) ?? []).length;
+		const alternations = (stripped.match(/\|/g) ?? []).length;
+		if (unboundedQuantifiers > 20) return true;
+		if (groups > 8) return true;
+		if (alternations > 10) return true;
+		if (unboundedQuantifiers * groups > 40) return true;
+		return false;
+	}
 	constructor(options = {}) {
 		this.options = {
 			maxRegexLength: options.maxRegexLength ?? 500,
@@ -770,6 +803,10 @@ var QueryParser = class {
 			warn("[mongokit] Potentially dangerous regex pattern, escaping");
 			return new RegExp(this._escapeRegex(patternStr), flags);
 		}
+		if (this._regexComplexityExceedsBudget(patternStr)) {
+			warn("[mongokit] Regex complexity budget exceeded, escaping");
+			return new RegExp(this._escapeRegex(patternStr), flags);
+		}
 		try {
 			return new RegExp(patternStr, flags);
 		} catch {
@@ -783,7 +820,11 @@ var QueryParser = class {
 	* Sanitize $match configuration to prevent dangerous operators
 	* Recursively filters out operators like $where, $function, $accumulator
 	*/
-	_sanitizeMatchConfig(config) {
+	_sanitizeMatchConfig(config, depth = 0) {
+		if (depth > this.options.maxFilterDepth) {
+			warn(`[mongokit] $match sanitize depth ${depth} exceeds maximum ${this.options.maxFilterDepth}, truncating branch`);
+			return {};
+		}
 		const sanitized = {};
 		const logicalArrayOps = new Set([
 			"$or",
@@ -795,10 +836,10 @@ var QueryParser = class {
 				warn(`[mongokit] Blocked dangerous operator in aggregation: ${key}`);
 				continue;
 			}
-			if (value && typeof value === "object" && !Array.isArray(value)) sanitized[key] = this._sanitizeMatchConfig(value);
+			if (value && typeof value === "object" && !Array.isArray(value)) sanitized[key] = this._sanitizeMatchConfig(value, depth + 1);
 			else if (Array.isArray(value)) {
 				const sanitizedArray = value.map((item) => {
-					if (item && typeof item === "object" && !Array.isArray(item)) return this._sanitizeMatchConfig(item);
+					if (item && typeof item === "object" && !Array.isArray(item)) return this._sanitizeMatchConfig(item, depth + 1);
 					return item;
 				});
 				if (logicalArrayOps.has(key)) {
@@ -945,4 +986,4 @@ function createRepository(Model, plugins = [], paginationConfig = {}, options =
 }
 var src_default = Repository;
 //#endregion
-export { AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, PaginationEngine, QueryParser, Repository, actions_exports as actions, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, configureLogger, createError, createFieldPreset, createMemoryCache, createRepository, customIdPlugin, dateSequentialId, src_default as default, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getNextSequence, getSystemManagedFields, immutableField, isFieldUpdateAllowed, isTransactionUnsupported, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, parseDuplicateKeyError, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validateUpdateBody, validationChainPlugin, withTransaction };
+export { AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, PaginationEngine, QueryParser, Repository, actions_exports as actions, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, configureLogger, createError, createFieldPreset, createMemoryCache, createRepository, createTenantContext, customIdPlugin, dateSequentialId, src_default as default, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getNextSequence, getSystemManagedFields, immutableField, isFieldUpdateAllowed, isTransactionUnsupported, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, parseDuplicateKeyError, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validateUpdateBody, validationChainPlugin, withTransaction };

package/dist/logger-DJ7egMnd.mjs

@@ -0,0 +1,30 @@
+//#region src/utils/logger.ts
+const noop = () => {};
+let current = {
+	warn: console.warn.bind(console),
+	debug: noop
+};
+/**
+* Configure the internal logger.
+* Pass `false` to silence all output.
+*/
+function configureLogger(config) {
+	if (config === false) current = {
+		warn: noop,
+		debug: noop
+	};
+	else current = {
+		...current,
+		...config
+	};
+}
+/** Emit a warning — security blocks, config issues, performance hints */
+function warn(message, ...args) {
+	current.warn(message, ...args);
+}
+/** Emit debug info — only visible when debug is enabled */
+function debug(message, ...args) {
+	current.debug(message, ...args);
+}
+//#endregion
+export { debug as n, warn as r, configureLogger as t };

package/dist/{mongooseToJsonSchema-MlaD3C0B.mjs → mongooseToJsonSchema-DUwXPStK.mjs}

@@ -1,4 +1,4 @@
-import { n as isObjectIdInstance } from "./id-resolution-LZ-cCwR5.mjs";
+import { n as isObjectIdInstance } from "./id-resolution-e4BT9zAV.mjs";
 import mongoose from "mongoose";
 //#region src/utils/memory-cache.ts
 /**
@@ -245,10 +245,10 @@ function buildJsonSchemaFromPaths(mongooseSchema, options) {
 	}
 	for (const [rootField, fieldPaths] of rootFields.entries()) if (fieldPaths.length === 1 && fieldPaths[0].path === rootField) {
 		const schemaType = fieldPaths[0].schemaType;
-		properties[rootField] = schemaTypeToJsonSchema(schemaType);
+		properties[rootField] = schemaTypeToJsonSchema(schemaType, options);
 		if (schemaType.isRequired && !isSoftRequired(rootField, schemaType)) required.push(rootField);
 	} else {
-		const nestedSchema = buildNestedJsonSchema(fieldPaths, rootField);
+		const nestedSchema = buildNestedJsonSchema(fieldPaths, rootField, options);
 		properties[rootField] = nestedSchema.schema;
 		if (nestedSchema.required) required.push(rootField);
 	}
@@ -271,14 +271,14 @@ function buildJsonSchemaFromPaths(mongooseSchema, options) {
 /**
 * Build nested JSON schema from dot-notation paths
 */
-function buildNestedJsonSchema(fieldPaths, rootField) {
+function buildNestedJsonSchema(fieldPaths, rootField, options = {}) {
 	const properties = {};
 	const required = [];
 	let hasRequiredFields = false;
 	for (const { path, schemaType } of fieldPaths) {
 		const parts = path.substring(rootField.length + 1).split(".");
 		if (parts.length === 1) {
-			properties[parts[0]] = schemaTypeToJsonSchema(schemaType);
+			properties[parts[0]] = schemaTypeToJsonSchema(schemaType, options);
 			if (schemaType.isRequired) {
 				required.push(parts[0]);
 				hasRequiredFields = true;
@@ -292,7 +292,7 @@ function buildNestedJsonSchema(fieldPaths, rootField) {
 			const nestedObj = properties[fieldName];
 			if (!nestedObj.properties) nestedObj.properties = {};
 			const deepPath = parts.slice(1).join(".");
-			nestedObj.properties[deepPath] = schemaTypeToJsonSchema(schemaType);
+			nestedObj.properties[deepPath] = schemaTypeToJsonSchema(schemaType, options);
 		}
 	}
 	const schema = {
@@ -324,10 +324,10 @@ function buildNestedJsonSchema(fieldPaths, rootField) {
 *      `{ type: 'object', additionalProperties: true }` so we never block a
 *      valid payload with the old `{ type: 'string' }` default.
 */
-function introspectArrayItems(schemaType) {
-	if (hasInnerSchema(schemaType)) return subSchemaToJsonSchema(schemaType.schema);
+function introspectArrayItems(schemaType, options = {}) {
+	if (hasInnerSchema(schemaType)) return subSchemaToJsonSchema(schemaType.schema, options);
 	const caster = schemaType?.caster;
-	if (caster && typeof caster === "object" && "instance" in caster && caster.instance) return schemaTypeToJsonSchema(caster);
+	if (caster && typeof caster === "object" && "instance" in caster && caster.instance) return schemaTypeToJsonSchema(caster, options);
 	const declaredType = schemaType?.options?.type;
 	if (Array.isArray(declaredType) && declaredType.length > 0) {
 		const inner = declaredType[0];
@@ -335,7 +335,7 @@ function introspectArrayItems(schemaType) {
 			type: "object",
 			additionalProperties: true
 		};
-		return jsonTypeFor(inner, {}, /* @__PURE__ */ new WeakSet());
+		return jsonTypeFor(inner, options, /* @__PURE__ */ new WeakSet());
 	}
 	return {
 		type: "object",
@@ -348,7 +348,7 @@ function introspectArrayItems(schemaType) {
 * does NOT apply create/update field rules — subdocument shape should faithfully
 * reflect the declared schema, not the top-level CRUD-mode omissions.
 */
-function subSchemaToJsonSchema(subSchema) {
+function subSchemaToJsonSchema(subSchema, options = {}) {
 	const properties = {};
 	const required = [];
 	const paths = subSchema.paths ?? {};
@@ -358,7 +358,7 @@ function subSchemaToJsonSchema(subSchema) {
 			const instance = st.instance;
 			if (!instance || isObjectIdInstance(instance)) continue;
 		}
-		properties[path] = schemaTypeToJsonSchema(st);
+		properties[path] = schemaTypeToJsonSchema(st, options);
 		if (st.isRequired) required.push(path);
 	}
 	const result = {
@@ -371,7 +371,7 @@ function subSchemaToJsonSchema(subSchema) {
 /**
 * Convert Mongoose SchemaType to JSON Schema
 */
-function schemaTypeToJsonSchema(schemaType) {
+function schemaTypeToJsonSchema(schemaType, builderOptions = {}) {
 	if (typeof schemaType?.jsonSchema === "function") try {
 		const custom = schemaType.jsonSchema();
 		if (custom && typeof custom === "object") return custom;
@@ -400,16 +400,16 @@ function schemaTypeToJsonSchema(schemaType) {
 	} else if (isObjectIdInstance(instance)) {
 		result.type = "string";
 		result.pattern = "^[0-9a-fA-F]{24}$";
-		if (typeof options.ref === "string" && options.ref.length > 0) result["x-ref"] = options.ref;
+		if (builderOptions.openApiExtensions === true && typeof options.ref === "string" && options.ref.length > 0) result["x-ref"] = options.ref;
 	} else if (instance === "Array") {
 		result.type = "array";
-		result.items = introspectArrayItems(schemaType);
+		result.items = introspectArrayItems(schemaType, builderOptions);
 	} else if (instance === "Map") {
 		result.type = "object";
 		const ofDef = options.of;
 		if (ofDef !== void 0 && ofDef !== null) result.additionalProperties = jsonTypeFor(ofDef, {}, /* @__PURE__ */ new WeakSet());
 		else result.additionalProperties = true;
-	} else if (hasInnerSchema(schemaType)) return subSchemaToJsonSchema(schemaType.schema);
+	} else if (hasInnerSchema(schemaType)) return subSchemaToJsonSchema(schemaType.schema, builderOptions);
 	else {
 		result.type = "object";
 		result.additionalProperties = true;
@@ -511,10 +511,14 @@ function jsonTypeFor(def, options, seen) {
 				additionalProperties: true
 			};
 		}
-		if (isObjectIdType(typedDef.type)) return {
-			type: "string",
-			pattern: "^[0-9a-fA-F]{24}$"
-		};
+		if (isObjectIdType(typedDef.type)) {
+			const objIdResult = {
+				type: "string",
+				pattern: "^[0-9a-fA-F]{24}$"
+			};
+			if (options?.openApiExtensions === true && typeof typedDef.ref === "string" && typedDef.ref.length > 0) objIdResult["x-ref"] = typedDef.ref;
+			return objIdResult;
+		}
 		if (isMongooseSchema(typedDef.type)) {
 			const obj = typedDef.type.obj;
 			if (obj && typeof obj === "object") {
@@ -547,7 +551,7 @@ function jsonTypeFor(def, options, seen) {
 			additionalProperties: true
 		};
 		seen.add(def);
-		return subSchemaToJsonSchema(def);
+		return subSchemaToJsonSchema(def, options);
 	}
 	if (isPlainObject(def)) {
 		if (seen.has(def)) return {

package/dist/{mongooseToJsonSchema-D2YjHo7W.d.mts → mongooseToJsonSchema-Du-UopRK.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-DiQfDesD.mjs";
+import { T as FieldPreset, _ as CrudSchemas, k as HttpError, ot as SchemaBuilderOptions, s as CacheAdapter, xt as ValidationResult, yt as UserContext } from "./types-BgdeBXI1.mjs";
 import mongoose, { Schema } from "mongoose";
 
 //#region src/utils/error.d.ts
@@ -15,13 +15,29 @@ import mongoose, { Schema } from "mongoose";
  * throw createError(403, 'Access denied');
  */
 declare function createError(status: number, message: string): HttpError;
+/** Options for parseDuplicateKeyError */
+interface ParseDuplicateKeyOptions {
+  /**
+   * Include the offending values inline in the error message and under
+   * `error.duplicate.values`. Default is `false` because those values can be
+   * PII (emails, tokens, phone numbers) and end up in logs/crash reports.
+   * Enable in dev or for trusted internal tools only.
+   */
+  exposeValues?: boolean;
+}
 /**
  * Detect and convert a MongoDB E11000 duplicate-key error into
  * a 409 HttpError with an actionable message.
  *
+ * PII-safe by default: the error message lists only the conflicting field
+ * names, never the values. Structured field names are attached under
+ * `error.duplicate.fields` for downstream handlers. Pass
+ * `{ exposeValues: true }` to opt into including the values (dev or trusted
+ * server-to-server contexts only).
+ *
  * Returns `null` when the error is not a duplicate-key error.
  */
-declare function parseDuplicateKeyError(error: unknown): HttpError | null;
+declare function parseDuplicateKeyError(error: unknown, options?: ParseDuplicateKeyOptions): HttpError | null;
 //#endregion
 //#region src/utils/field-selection.d.ts
 /**

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-DiQfDesD.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-BgdeBXI1.mjs";
 import { Model } from "mongoose";
 
 //#region src/pagination/PaginationEngine.d.ts
@@ -11,6 +11,8 @@ interface ResolvedPaginationConfig {
   maxPage: number;
   deepPageThreshold: number;
   cursorVersion: number;
+  minCursorVersion: number;
+  strictKeysetSortFields: string[] | undefined;
   useEstimatedCount: boolean;
 }
 /**

package/dist/pagination/PaginationEngine.mjs

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

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-BsFzKVnO.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 };
+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-Be9rG04B.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 auditTrailPlugin, M as aggregateHelpersPlugin, O as batchOperationsPlugin, 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, j as auditLogPlugin, k as AuditTrailQuery, 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-7A5qGEQq.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 };
+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-CEyJssZl.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/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-B19MD38s.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-oM8G4b6m.mjs";
 export { FieldType, SchemaPathsLike, buildFieldTypeMap, coerceFieldValue, coerceHeuristic, coerceToType, normalizeMongooseType };

package/dist/query/primitives/coercion.mjs

@@ -1,4 +1,4 @@
-import { n as isObjectIdInstance } from "../../id-resolution-LZ-cCwR5.mjs";
+import { n as isObjectIdInstance } from "../../id-resolution-e4BT9zAV.mjs";
 import mongoose from "mongoose";
 //#region src/query/primitives/coercion.ts
 /**

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

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

package/dist/{sort-C-BJEWUZ.mjs → sort-ffe-9JBg.mjs}

@@ -21,21 +21,36 @@ function normalizeSort(sort) {
 	return normalized;
 }
 /**
-* Validates and normalizes sort for keyset pagination
-* Auto-adds _id tie-breaker if needed
-* Ensures _id direction matches primary field
+* Validates and normalizes sort for keyset pagination.
+* Auto-adds `_id` tie-breaker if needed; ensures `_id` direction matches the
+* primary field.
+*
+* **Known limitation (MongoDB mixed-type sort):** keyset pagination across a
+* field that can hold both typed values (Date, Number) and `null`/`undefined`
+* is lossy — `$lt/$gt` don't cross the type boundary in BSON comparison, so
+* some docs at the null/non-null boundary are unreachable. If your sort field
+* is nullable, either:
+*   - sort by `_id` alone (always safe), or
+*   - use `allowedPrimaryFields` to lock keyset sort to fields your schema
+*     guarantees non-null (see `PaginationConfig.strictKeysetSortFields`).
 *
 * @param sort - Sort specification
+* @param allowedPrimaryFields - Optional allowlist of primary (non-_id) sort
+*   field names. When set, rejects sorts whose primary field isn't listed.
+*   `_id` is always allowed.
 * @returns Validated and normalized sort
 * @throws Error if sort is invalid for keyset pagination
 */
-function validateKeysetSort(sort) {
+function validateKeysetSort(sort, allowedPrimaryFields) {
 	const keys = Object.keys(sort);
 	if (keys.length === 0) throw new Error("Keyset pagination requires at least one sort field");
 	if (keys.length === 1 && keys[0] === "_id") return normalizeSort(sort);
 	for (const key of keys) if (sort[key] !== 1 && sort[key] !== -1) throw new Error(`Invalid sort direction for "${key}": must be 1 or -1, got ${sort[key]}`);
 	const nonIdKeys = keys.filter((k) => k !== "_id");
 	const primaryDirection = sort[nonIdKeys[0]];
+	if (allowedPrimaryFields && allowedPrimaryFields.length > 0) {
+		for (const key of nonIdKeys) if (!allowedPrimaryFields.includes(key)) throw new Error(`Keyset sort field "${key}" is not in the strictKeysetSortFields allowlist. Allowed: ${allowedPrimaryFields.join(", ")}. (See PaginationConfig.strictKeysetSortFields — protects against lossy null/non-null keyset boundaries.)`);
+	}
 	for (const key of nonIdKeys) if (sort[key] !== primaryDirection) throw new Error("All sort fields must share the same direction for keyset pagination");
 	if (keys.includes("_id") && sort._id !== primaryDirection) throw new Error("_id direction must match primary field direction");
 	if (!keys.includes("_id")) return normalizeSort({

package/dist/{types-DiQfDesD.d.mts → types-BgdeBXI1.d.mts}

@@ -570,6 +570,19 @@ interface RepositoryOptions {
    * Required for regex mode to take effect.
    */
   searchFields?: string[];
+  /**
+   * How to react to a plugin composition that is known to be unsafe.
+   * - 'warn' (default): log a warning via the configured logger.
+   * - 'throw': fail fast at construction time — recommended for production.
+   * - 'off': disable the check entirely.
+   *
+   * Checks currently enforced:
+   *   - soft-delete must precede batch-operations (otherwise deleteMany /
+   *     updateMany skip the soft-delete filter injection).
+   *   - multi-tenant must precede cache (otherwise cache keys are computed
+   *     before tenant scoping → cross-tenant cache poisoning risk).
+   */
+  pluginOrderChecks?: 'warn' | 'throw' | 'off';
 }
 /** Pagination configuration */
 interface PaginationConfig {
@@ -583,6 +596,27 @@ interface PaginationConfig {
   deepPageThreshold?: number;
   /** Cursor version for forward compatibility (default: 1) */
   cursorVersion?: number;
+  /**
+   * Minimum cursor version accepted. Bump alongside `cursorVersion` when a
+   * breaking format change ships so stale client cursors are rejected with a
+   * clear error instead of silently paginating from the wrong position.
+   * Default: 1 (accept any cursor <= cursorVersion).
+   */
+  minCursorVersion?: number;
+  /**
+   * Allowlist of primary sort fields for keyset pagination. When set, any
+   * `getAll({ sort })` whose primary (non-_id) field is not in this list
+   * throws at validation time.
+   *
+   * Use this to lock down keyset pagination to fields that are structurally
+   * guaranteed non-null in your schema — keyset sort across null/non-null
+   * boundaries is lossy (MongoDB's `$lt/$gt` semantics leave a gap at the
+   * type boundary, so not every doc is reachable).
+   *
+   * `_id` is always allowed regardless of this list.
+   * Undefined (default) = no allowlist, any sort field accepted.
+   */
+  strictKeysetSortFields?: string[];
   /** Use estimatedDocumentCount for faster counts on large collections */
   useEstimatedCount?: boolean;
 }
@@ -1079,6 +1113,19 @@ interface SchemaBuilderOptions {
       type: string;
     } | unknown>;
   };
+  /**
+   * Emit OpenAPI vendor extensions (`x-*` keywords like `x-ref` for populated
+   * ObjectId fields). Default: `false`.
+   *
+   * Why opt-in: Ajv's strict mode THROWS on any `x-*` keyword it doesn't
+   * recognize (`strict mode: unknown keyword: "x-ref"`). Consumers validating
+   * request bodies with Ajv strict need a keyword-clean schema; consumers
+   * generating OpenAPI documentation want the vendor extensions. Default is
+   * OFF so Ajv-strict-mode consumers are safe out of the box. Turn ON to
+   * include `x-ref` etc. in the output (typically when feeding the schema
+   * into a docgen tool like @fastify/swagger or redocly).
+   */
+  openApiExtensions?: boolean;
 }
 /** JSON Schema type */
 interface JsonSchema {
@@ -1256,6 +1303,17 @@ interface CacheOptions {
   skipIf?: {
     largeLimit?: number;
   };
+  /**
+   * TTL jitter to mitigate cache stampedes. When many entries share the same
+   * TTL and expire simultaneously, every concurrent reader misses and hammers
+   * the DB at once. Jitter spreads expirations over a window.
+   *
+   * - `number` in [0, 1]: fractional symmetric jitter. `0.1` multiplies the
+   *   TTL by a random factor in [0.9, 1.1]. Default: 0 (no jitter).
+   * - `function(ttl)`: full control — receive the configured TTL (seconds),
+   *   return the effective TTL (seconds) to store with.
+   */
+  jitter?: number | ((ttlSeconds: number) => number);
 }
 /** Options for cache-aware operations */
 interface CacheOperationOptions {
@@ -1312,6 +1370,16 @@ interface HttpError extends Error {
     validator: string;
     error: string;
   }>;
+  /**
+   * Structured metadata for duplicate-key (E11000) errors. Safe to surface in
+   * logs/audit. Includes the offending field names and a boolean-only mirror
+   * of whether each field had a duplicate value — never the value itself
+   * unless `parseDuplicateKeyError` was called with `{ exposeValues: true }`.
+   */
+  duplicate?: {
+    fields: string[]; /** Only populated when parseDuplicateKeyError was called with exposeValues:true. */
+    values?: Record<string, unknown>;
+  };
 }
 /**
  * Combines all plugin method types into a single type

package/dist/{update-AVfKWNGt.mjs → update-BDsQ3cdy.mjs}

@@ -1,5 +1,6 @@
 import { t as __exportAll } from "./chunk-CfYAbeIz.mjs";
-import { a as warn, t as createError } from "./error-Bpbi_NKo.mjs";
+import { r as warn } from "./logger-DJ7egMnd.mjs";
+import { t as createError } from "./error-Lw9GEAro.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 { Z as PopulateSpec, pt as SortSpec, st as SelectSpec } from "../types-DiQfDesD.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-D2YjHo7W.mjs";
+import { Z as PopulateSpec, pt as SortSpec, st as SelectSpec } from "../types-BgdeBXI1.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-Du-UopRK.mjs";
 
 //#region src/utils/cache-keys.d.ts
 /**

package/dist/utils/index.mjs

@@ -1,5 +1,6 @@
-import { r as configureLogger, t as createError } from "../error-Bpbi_NKo.mjs";
-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-MlaD3C0B.mjs";
+import { t as configureLogger } from "../logger-DJ7egMnd.mjs";
+import { t as createError } from "../error-Lw9GEAro.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 { a as isFieldUpdateAllowed, i as getSystemManagedFields, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-DUwXPStK.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-BsFzKVnO.d.mts → validation-chain.plugin-Be9rG04B.d.mts}

@@ -1,5 +1,6 @@
-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-DiQfDesD.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-BgdeBXI1.mjs";
 import mongoose, { ClientSession } from "mongoose";
+import { AsyncLocalStorage } from "node:async_hooks";
 
 //#region src/plugins/aggregate-helpers.plugin.d.ts
 /**
@@ -1062,6 +1063,28 @@ interface SubdocumentMethods<TDoc> {
   deleteSubdocument(parentId: string | ObjectId, arrayPath: string, subId: string | ObjectId, options?: Record<string, unknown>): Promise<TDoc>;
 }
 //#endregion
+//#region src/plugins/tenant-context.d.ts
+interface TenantStore {
+  tenantId: string | undefined;
+  [key: string]: unknown;
+}
+interface TenantContext {
+  /** Run `fn` with the given tenant store active for its entire async tree. */
+  run<T>(store: TenantStore, fn: () => T): T;
+  /** Current tenant ID, or undefined if no context is active. */
+  getTenantId(): string | undefined;
+  /** Full store for the current context (use for extra per-request metadata). */
+  getStore(): TenantStore | undefined;
+  /**
+   * Assert that a tenant context is active; throw otherwise.
+   * Useful in hot paths where a missing tenant must fail loud, not silent.
+   */
+  requireTenantId(): string;
+  /** Underlying AsyncLocalStorage — escape hatch for advanced composition. */
+  readonly storage: AsyncLocalStorage<TenantStore>;
+}
+declare function createTenantContext(): TenantContext;
+//#endregion
 //#region src/plugins/timestamp.plugin.d.ts
 /**
  * Timestamp plugin that auto-injects timestamps
@@ -1110,4 +1133,4 @@ declare function immutableField(field: string): ValidatorDefinition;
  */
 declare function uniqueField(field: string, errorMessage?: string): ValidatorDefinition;
 //#endregion
-export { dateSequentialId as A, AuditEntry as B, elasticSearchPlugin as C, PrefixedIdOptions as D, IdGenerator as E, CacheMethods as F, AuditTrailOptions as G, AuditQueryOptions as H, cachePlugin as I, auditLogPlugin as J, AuditTrailQuery as K, BatchOperationsMethods as L, prefixedId as M, sequentialId as N, SequentialIdOptions as O, cascadePlugin as P, BulkWriteResult as R, ElasticSearchOptions as S, DateSequentialIdOptions as T, AuditQueryResult as U, AuditOperation as V, AuditTrailMethods as W, aggregateHelpersPlugin as X, AggregateHelpersMethods as Y, MongoOperationsMethods as _, uniqueField as a, methodRegistryPlugin as b, SubdocumentMethods as c, softDeletePlugin as d, ObservabilityOptions as f, multiTenantPlugin as g, MultiTenantOptions as h, requireField as i, getNextSequence as j, customIdPlugin as k, subdocumentPlugin as l, observabilityPlugin as m, blockIf as n, validationChainPlugin as o, OperationMetric as p, auditTrailPlugin as q, immutableField as r, timestampPlugin as s, autoInject as t, SoftDeleteMethods as u, mongoOperationsPlugin as v, CustomIdOptions as w, fieldFilterPlugin as x, MethodRegistryRepository as y, batchOperationsPlugin as z };
+export { aggregateHelpersPlugin as $, PrefixedIdOptions as A, BatchOperationsMethods as B, methodRegistryPlugin as C, CustomIdOptions as D, elasticSearchPlugin as E, prefixedId as F, AuditQueryOptions as G, batchOperationsPlugin as H, sequentialId as I, AuditTrailOptions as J, AuditQueryResult as K, cascadePlugin as L, customIdPlugin as M, dateSequentialId as N, DateSequentialIdOptions as O, getNextSequence as P, AggregateHelpersMethods as Q, CacheMethods as R, MethodRegistryRepository as S, ElasticSearchOptions as T, AuditEntry as U, BulkWriteResult as V, AuditOperation as W, auditTrailPlugin as X, AuditTrailQuery as Y, auditLogPlugin as Z, observabilityPlugin as _, uniqueField as a, MongoOperationsMethods as b, TenantContext as c, SubdocumentMethods as d, subdocumentPlugin as f, OperationMetric as g, ObservabilityOptions as h, requireField as i, SequentialIdOptions as j, IdGenerator as k, TenantStore as l, softDeletePlugin as m, blockIf as n, validationChainPlugin as o, SoftDeleteMethods as p, AuditTrailMethods as q, immutableField as r, timestampPlugin as s, autoInject as t, createTenantContext as u, MultiTenantOptions as v, fieldFilterPlugin as w, mongoOperationsPlugin as x, multiTenantPlugin as y, cachePlugin as z };