@classytic/mongokit 3.5.6 → 3.6.1

package/dist/{PaginationEngine-CpsQl471.mjs → PaginationEngine-CunXkR9p.mjs}

@@ -1,6 +1,72 @@
 import { a as warn, t as createError } from "./error-Bpbi_NKo.mjs";
 import { n as encodeCursor, r as resolveCursorFilter } from "./cursor-CHToazHy.mjs";
 import { r as validateKeysetSort, t as getPrimaryField } from "./sort-C-BJEWUZ.mjs";
+//#region src/pagination/utils/index-hint.ts
+/**
+* Read a Mongoose schema's declared indexes, defensively.
+* Returns an empty array on any introspection failure.
+*/
+function readSchemaIndexes(Model) {
+	try {
+		const schema = Model.schema;
+		if (!schema || typeof schema.indexes !== "function") return [];
+		const raw = schema.indexes();
+		return Array.isArray(raw) ? raw : [];
+	} catch {
+		return [];
+	}
+}
+/**
+* Does any schema-declared compound index satisfy ESR for the given
+* equality filter fields + sort?
+*
+* Rules:
+*   1. The first N keys of the index (N = filterFields.length) must be
+*      exactly the equality filter fields in any order (set equality).
+*   2. The next M keys (M = sortKeys.length) must match the sort keys in
+*      exact declared order.
+*   3. Directions must all match OR all be inverse (MongoDB can walk an
+*      index in reverse, but only if every sort field flips together).
+*   4. Indexes with more total keys than needed are still accepted when
+*      the above prefix holds — Mongo just ignores trailing fields.
+*
+* Notes:
+*   - Hashed / text / 2dsphere indexes are skipped (not usable for sort).
+*   - Unique, partial, sparse options don't affect compatibility.
+*   - When `filterFields` is empty, a sort-only prefix match is sufficient.
+*
+* @param indexes      Raw `[spec, options?]` tuples from `schema.indexes()`.
+* @param filterFields Top-level equality filter keys (already stripped of `$*`).
+* @param sort         Normalized sort spec `{ field: 1 | -1 }`.
+*/
+function hasCompatibleKeysetIndex(indexes, filterFields, sort) {
+	const sortKeys = Object.keys(sort);
+	if (sortKeys.length === 0) return true;
+	const filterSet = new Set(filterFields);
+	const prefixLen = filterFields.length;
+	for (const [spec] of indexes) {
+		if (!spec || typeof spec !== "object") continue;
+		const entries = Object.entries(spec);
+		if (entries.length < prefixLen + sortKeys.length) continue;
+		if (entries.some(([, dir]) => typeof dir !== "number")) continue;
+		const equalityPrefix = entries.slice(0, prefixLen).map(([k]) => k);
+		if (equalityPrefix.length !== prefixLen) continue;
+		if (!(equalityPrefix.every((k) => filterSet.has(k)) && new Set(equalityPrefix).size === prefixLen)) continue;
+		const sortSuffix = entries.slice(prefixLen, prefixLen + sortKeys.length);
+		if (sortSuffix.length !== sortKeys.length) continue;
+		let namesMatch = true;
+		for (let i = 0; i < sortKeys.length; i++) if (sortSuffix[i][0] !== sortKeys[i]) {
+			namesMatch = false;
+			break;
+		}
+		if (!namesMatch) continue;
+		const forward = sortKeys.every((k, i) => sortSuffix[i][1] === sort[k]);
+		const reverse = sortKeys.every((k, i) => sortSuffix[i][1] === -sort[k]);
+		if (forward || reverse) return true;
+	}
+	return false;
+}
+//#endregion
 //#region src/pagination/utils/limits.ts
 /**
 * Validates and sanitizes limit value
@@ -65,6 +131,24 @@ function calculateTotalPages(total, limit) {
 }
 //#endregion
 //#region src/pagination/PaginationEngine.ts
+/**
+* Strip a trailing `_id` tiebreaker from a normalized sort spec.
+*
+* `validateKeysetSort` always appends `_id` to the end of the sort object as
+* a stable-order guarantee. For index-compatibility matching we only care
+* about the primary ordering fields — an index covering those is efficient
+* even without `_id` in the index itself.
+*
+* Returns the sort unchanged if `_id` is the only field (degenerate case).
+*/
+function stripTrailingIdTiebreaker(sort) {
+	const keys = Object.keys(sort);
+	if (keys.length <= 1) return sort;
+	if (keys[keys.length - 1] !== "_id") return sort;
+	const out = {};
+	for (let i = 0; i < keys.length - 1; i++) out[keys[i]] = sort[keys[i]];
+	return out;
+}
 function ensureKeysetSelectIncludesCursorFields(select, sort) {
 	if (!select) return select;
 	const requiredFields = new Set([...Object.keys(sort), "_id"]);
@@ -95,6 +179,11 @@ var PaginationEngine = class {
 	Model;
 	config;
 	/**
+	* Lazily-cached schema index snapshot used by stream() to decide whether
+	* to emit the "missing compound index" warning. Computed on first use.
+	*/
+	_cachedSchemaIndexes = null;
+	/**
 	* Create a new pagination engine
 	*
 	* @param Model - Mongoose model to paginate
@@ -111,6 +200,12 @@ var PaginationEngine = class {
 			useEstimatedCount: config.useEstimatedCount ?? false
 		};
 	}
+	/** Memoized schema index lookup — avoids re-walking schema on every stream(). */
+	_getSchemaIndexes() {
+		if (this._cachedSchemaIndexes !== null) return this._cachedSchemaIndexes;
+		this._cachedSchemaIndexes = readSchemaIndexes(this.Model);
+		return this._cachedSchemaIndexes;
+	}
 	/**
 	* Offset-based pagination using skip/limit
 	* Best for small datasets and when users need random page access
@@ -204,11 +299,12 @@ var PaginationEngine = class {
 		if (!sort) throw createError(400, "sort is required for keyset pagination");
 		const sanitizedLimit = validateLimit(limit, this.config);
 		const normalizedSort = validateKeysetSort(sort);
+		const sortWithoutIdTail = stripTrailingIdTiebreaker(normalizedSort);
 		const filterKeys = Object.keys(filters).filter((k) => !k.startsWith("$"));
-		const sortFields = Object.keys(normalizedSort);
-		if (filterKeys.length > 0 && sortFields.length > 0) {
-			const indexFields = [...filterKeys.map((f) => `${f}: 1`), ...sortFields.map((f) => `${f}: ${normalizedSort[f]}`)];
-			warn(`[mongokit] Keyset pagination with filters [${filterKeys.join(", ")}] and sort [${sortFields.join(", ")}] requires a compound index for O(1) performance. Ensure index exists: { ${indexFields.join(", ")} }`);
+		const effectiveSortFields = Object.keys(sortWithoutIdTail);
+		if (process.env.NODE_ENV !== "test" && filterKeys.length > 0 && effectiveSortFields.length > 0 && !hasCompatibleKeysetIndex(this._getSchemaIndexes(), filterKeys, sortWithoutIdTail)) {
+			const indexFields = [...filterKeys.map((f) => `${f}: 1`), ...effectiveSortFields.map((f) => `${f}: ${sortWithoutIdTail[f]}`)];
+			warn(`[mongokit] Keyset pagination with filters [${filterKeys.join(", ")}] and sort [${effectiveSortFields.join(", ")}] has no matching schema-declared compound index. For O(1) performance, declare: { ${indexFields.join(", ")} }. (Collection-level indexes created outside the schema are not visible here.)`);
 		}
 		let query = { ...filters };
 		if (after) query = resolveCursorFilter(after, normalizedSort, this.config.cursorVersion, query);

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

package/dist/{index-DmVbUzDL.d.mts → index-BSRSsRRx.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-BwO4u3JN.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-DiQfDesD.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-BwO4u3JN.mjs";
-import { t as index_d_exports } from "./index-DmVbUzDL.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-DiQfDesD.mjs";
+import { t as index_d_exports } from "./index-BSRSsRRx.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-BtmT-FFB.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-mI2Z19lM.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 { 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-D2YjHo7W.mjs";
 import * as _$mongoose from "mongoose";
 import { ClientSession, Expression, Model, PipelineStage, PopulateOptions } from "mongoose";
 
@@ -977,10 +977,29 @@ declare class Repository<TDoc = unknown> {
    */
   update(id: string | ObjectId, data: Record<string, unknown>, options?: UpdateOptions): Promise<TDoc>;
   /**
-   * Delete document by ID
+   * Delete a document by ID.
+   *
+   * By default the behavior is decided by the plugin stack:
+   *   - With `softDeletePlugin` wired → soft delete (sets `deletedAt`)
+   *   - Without the plugin → physical delete
+   *
+   * Pass `mode: 'hard'` to force physical deletion regardless of plugins.
+   * All policy hooks (multi-tenant scope, audit trails, cache invalidation,
+   * cascade) still fire — only the soft-delete interception is skipped. This
+   * is the GDPR / admin-cleanup path.
+   *
+   * @example
+   * ```ts
+   * // Respects softDeletePlugin — soft if wired
+   * await userRepo.delete(userId);
+   *
+   * // GDPR erasure — physical delete, audit hooks still fire
+   * await userRepo.delete(userId, { mode: 'hard', organizationId: 'org_123' });
+   * ```
    */
   delete(id: string | ObjectId, options?: SessionOptions & {
     idField?: string;
+    mode?: 'hard' | 'soft';
   }): Promise<DeleteResult>;
   /**
    * Execute aggregation pipeline
@@ -1096,7 +1115,6 @@ declare class Repository<TDoc = unknown> {
    * ```
    */
   withTransaction<T>(callback: (session: ClientSession) => Promise<T>, options?: WithTransactionOptions): Promise<T>;
-  private _isTransactionUnsupported;
   /**
    * Execute custom query with event emission
    */
@@ -1140,6 +1158,45 @@ declare class Repository<TDoc = unknown> {
   _handleError(error: Error): HttpError;
 }
 //#endregion
+//#region src/transaction.d.ts
+/** Minimal shape we need from a Mongoose connection. */
+interface SessionStarter {
+  startSession(): Promise<ClientSession>;
+}
+/**
+ * Run a callback inside a MongoDB transaction on the given connection.
+ *
+ * - Starts a session, runs `session.withTransaction(callback)` (which auto-retries
+ *   on `TransientTransactionError` and `UnknownTransactionCommitResult`), and
+ *   always ends the session in `finally`.
+ * - When `allowFallback` is true and the deployment doesn't support transactions
+ *   (e.g. standalone MongoDB in dev), the callback runs once without a
+ *   transaction on the same session. `onFallback` is invoked with the original
+ *   error so hosts can log the degradation.
+ *
+ * @example
+ * ```ts
+ * import mongoose from 'mongoose';
+ * import { withTransaction } from '@classytic/mongokit';
+ *
+ * await withTransaction(mongoose.connection, async (session) => {
+ *   const order  = await orderRepo.create(data, { session });
+ *   await inventoryRepo.decrement(order.items, { session });
+ *   return order;
+ * });
+ * ```
+ */
+declare function withTransaction<T>(connection: SessionStarter, callback: (session: ClientSession) => Promise<T>, options?: WithTransactionOptions): Promise<T>;
+/**
+ * Detect whether an error indicates the MongoDB deployment does not support
+ * multi-document transactions (standalone server, older topology, etc.).
+ *
+ * Checks MongoDB error codes first — 263 (standalone) and 20 (unsupported
+ * topology) — with a message-matching fallback for edge cases surfaced by
+ * older driver versions.
+ */
+declare function isTransactionUnsupported(error: Error): boolean;
+//#endregion
 //#region src/index.d.ts
 /**
  * Factory function to create a repository instance
@@ -1153,4 +1210,4 @@ declare class Repository<TDoc = unknown> {
  */
 declare function createRepository<TDoc>(Model: _$mongoose.Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions): Repository<TDoc>;
 //#endregion
-export { type AggregateHelpersMethods, type AggregateOptions, type AggregatePaginationOptions, type AggregatePaginationResult, AggregationBuilder, type AllPluginMethods, type AnyDocument, type AnyModel, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BatchOperationsMethods, type BulkWriteResult, type CacheAdapter, type CacheMethods, type CacheOperationOptions, type CacheOptions, type CacheStats, type CacheableOptions, type CascadeOptions, type CascadeRelation, type CollationOptions, type CreateInput, type CreateOptions, type CrudSchemas, type CustomIdOptions, type DateSequentialIdOptions, type DecodedCursor, type DeepPartial, type DeleteResult, type DocField, type ElasticSearchOptions, type EventHandlers, type EventPayload, type EventPhase, type FieldPreset, type FieldRules, type FieldType, type FilterQuery, type GroupResult, HOOK_PRIORITY, type HookMode, type HttpError, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, type IdGenerator, type InferDocument, type InferRawDoc, type JsonSchema, type KeysOfType, type KeysetPaginationOptions, type KeysetPaginationResult, type Logger, LookupBuilder, type LookupOptions, type LookupPopulateOptions, type LookupPopulateResult, type MinMaxResult, type MongoOperationsMethods, type MultiTenantOptions, type NonNullableFields, type ObjectId, type ObservabilityOptions, type OffsetPaginationOptions, type OffsetPaginationResult, type OperationMetric, type OperationOptions, type PaginationConfig, PaginationEngine, type PaginationResult, type ParsedQuery, type PartialBy, type Plugin, type PluginFunction, type PluginType, type PopulateOption, type PopulateSpec, type PrefixedIdOptions, QueryParser, type QueryParserOptions, type ReadOptions, type ReadPreferenceType, Repository, Repository as default, type RepositoryContext, type RepositoryEvent, type RepositoryInstance, type RepositoryOperation, type RepositoryOptions, type RequiredBy, type SchemaBuilderOptions, type SchemaLike, type SearchMode, type SelectSpec, type SequentialIdOptions, type SessionOptions, type SoftDeleteFilterMode, type SoftDeleteMethods, type SoftDeleteOptions, type SoftDeleteRepository, type SortDirection, type SortSpec, type Strict, type SubdocumentMethods, type UpdateInput, type UpdateManyResult, type UpdateOptions, type UpdateWithValidationResult, type UserContext, type ValidationChainOptions, type ValidationResult, type ValidatorDefinition, type WithPlugins, type WithTransactionOptions, index_d_exports as actions, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, configureLogger, createError, createFieldPreset, createMemoryCache, createRepository, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getNextSequence, getSystemManagedFields, immutableField, isFieldUpdateAllowed, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, parseDuplicateKeyError, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validateUpdateBody, validationChainPlugin };
+export { type AggregateHelpersMethods, type AggregateOptions, type AggregatePaginationOptions, type AggregatePaginationResult, AggregationBuilder, type AllPluginMethods, type AnyDocument, type AnyModel, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BatchOperationsMethods, type BulkWriteResult, type CacheAdapter, type CacheMethods, type CacheOperationOptions, type CacheOptions, type CacheStats, type CacheableOptions, type CascadeOptions, type CascadeRelation, type CollationOptions, type CreateInput, type CreateOptions, type CrudSchemas, type CustomIdOptions, type DateSequentialIdOptions, type DecodedCursor, type DeepPartial, type DeleteResult, type DocField, type ElasticSearchOptions, type EventHandlers, type EventPayload, type EventPhase, type FieldPreset, type FieldRules, type FieldType, type FilterQuery, type GroupResult, HOOK_PRIORITY, type HookMode, type HttpError, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, type IdGenerator, type InferDocument, type InferRawDoc, type JsonSchema, type KeysOfType, type KeysetPaginationOptions, type KeysetPaginationResult, type Logger, LookupBuilder, type LookupOptions, type LookupPopulateOptions, type LookupPopulateResult, type MinMaxResult, type MongoOperationsMethods, type MultiTenantOptions, type NonNullableFields, type ObjectId, type ObservabilityOptions, type OffsetPaginationOptions, type OffsetPaginationResult, type OperationMetric, type OperationOptions, type PaginationConfig, PaginationEngine, type PaginationResult, type ParsedQuery, type PartialBy, type Plugin, type PluginFunction, type PluginType, type PopulateOption, type PopulateSpec, type PrefixedIdOptions, QueryParser, type QueryParserOptions, type ReadOptions, type ReadPreferenceType, Repository, Repository as default, type RepositoryContext, type RepositoryEvent, type RepositoryInstance, type RepositoryOperation, type RepositoryOptions, type RequiredBy, type SchemaBuilderOptions, type SchemaLike, type SearchMode, type SelectSpec, type SequentialIdOptions, type SessionOptions, type SoftDeleteFilterMode, type SoftDeleteMethods, type SoftDeleteOptions, type SoftDeleteRepository, type SortDirection, type SortSpec, type Strict, type SubdocumentMethods, type UpdateInput, type UpdateManyResult, type UpdateOptions, type UpdateWithValidationResult, type UserContext, type ValidationChainOptions, type ValidationResult, type ValidatorDefinition, type WithPlugins, type WithTransactionOptions, index_d_exports as actions, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, configureLogger, createError, createFieldPreset, createMemoryCache, createRepository, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getNextSequence, getSystemManagedFields, immutableField, isFieldUpdateAllowed, isTransactionUnsupported, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, parseDuplicateKeyError, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validateUpdateBody, validationChainPlugin, withTransaction };

package/dist/index.mjs

@@ -1,8 +1,8 @@
 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 { 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-DCYjnPau.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-DoOEyM_g.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 { buildFieldTypeMap, coerceFieldValue, coerceHeuristic } from "./query/primitives/coercion.mjs";
@@ -945,4 +945,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, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, parseDuplicateKeyError, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validateUpdateBody, validationChainPlugin };
+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 };

package/dist/{mongooseToJsonSchema-DQMU0Dlv.d.mts → mongooseToJsonSchema-D2YjHo7W.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-BwO4u3JN.mjs";
+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 mongoose, { Schema } from "mongoose";
 
 //#region src/utils/error.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-BwO4u3JN.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-DiQfDesD.mjs";
 import { Model } from "mongoose";
 
 //#region src/pagination/PaginationEngine.d.ts
@@ -20,6 +20,11 @@ interface ResolvedPaginationConfig {
 declare class PaginationEngine<TDoc = AnyDocument> {
   readonly Model: Model<TDoc>;
   readonly config: ResolvedPaginationConfig;
+  /**
+   * Lazily-cached schema index snapshot used by stream() to decide whether
+   * to emit the "missing compound index" warning. Computed on first use.
+   */
+  private _cachedSchemaIndexes;
   /**
    * Create a new pagination engine
    *
@@ -27,6 +32,8 @@ declare class PaginationEngine<TDoc = AnyDocument> {
    * @param config - Pagination configuration
    */
   constructor(Model: Model<TDoc, any, any, any>, config?: PaginationConfig);
+  /** Memoized schema index lookup — avoids re-walking schema on every stream(). */
+  private _getSchemaIndexes;
   /**
    * Offset-based pagination using skip/limit
    * Best for small datasets and when users need random page access

package/dist/pagination/PaginationEngine.mjs

@@ -1,2 +1,2 @@
-import { t as PaginationEngine } from "../PaginationEngine-CpsQl471.mjs";
+import { t as PaginationEngine } from "../PaginationEngine-CunXkR9p.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-BtmT-FFB.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-mI2Z19lM.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-DCYjnPau.mjs";
+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-DoOEyM_g.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/{types-BwO4u3JN.d.mts → types-DiQfDesD.d.mts}

@@ -928,6 +928,17 @@ interface RepositoryContext {
   softDeleted?: boolean;
   /** Include soft-deleted documents in queries */
   includeDeleted?: boolean;
+  /**
+   * Caller-requested delete semantics, read by softDeletePlugin.
+   *
+   * - `undefined` (default) — plugin decides: soft if wired, hard otherwise.
+   * - `'hard'` — bypass soft-delete and physically remove the document.
+   *   All policy hooks (multi-tenant scope, audit trails, cache invalidation)
+   *   still fire; only the soft-delete interception is skipped.
+   * - `'soft'` — reserved. Currently treated as default since softDeletePlugin
+   *   is the only source of soft semantics.
+   */
+  deleteMode?: 'hard' | 'soft';
   /** Skip cache for this operation */
   skipCache?: boolean;
   /** Custom TTL for this operation (seconds) */
@@ -982,7 +993,7 @@ interface RepositoryInstance {
   [key: string]: unknown;
 }
 /** Repository operation names */
-type RepositoryOperation = 'create' | 'createMany' | 'update' | 'updateMany' | 'delete' | 'deleteMany' | 'getById' | 'getByQuery' | 'getOne' | 'getAll' | 'findAll' | 'getOrCreate' | 'count' | 'exists' | 'distinct' | 'aggregate' | 'aggregatePaginate' | 'lookupPopulate' | 'bulkWrite';
+type RepositoryOperation = 'create' | 'createMany' | 'update' | 'updateMany' | 'delete' | 'deleteMany' | 'restore' | 'getById' | 'getByQuery' | 'getOne' | 'getAll' | 'findAll' | 'getOrCreate' | 'count' | 'exists' | 'distinct' | 'aggregate' | 'aggregatePaginate' | 'lookupPopulate' | 'bulkWrite';
 /** Event lifecycle phases */
 type EventPhase = 'before' | 'after' | 'error';
 /** Repository event names (generated from template literals) */
@@ -1263,8 +1274,23 @@ interface CacheStats {
 }
 /** Cascade relation definition */
 interface CascadeRelation {
-  /** Model name to cascade delete to */
-  model: string;
+  /**
+   * Preferred: a Repository instance for the target collection. When present,
+   * cascade routes deletes through `repo.delete` / `repo.deleteMany`, so the
+   * target's `before:delete` / `before:deleteMany` hooks fire — meaning
+   * multi-tenant scoping, audit logging, cache invalidation, and the target's
+   * own soft-delete plugin (with its configured `deletedField`) all run
+   * correctly. Strongly recommended for any target that has policy plugins.
+   */
+  repo?: RepositoryInstance;
+  /**
+   * Legacy: a Mongoose model name. When set without `repo`, cascade writes
+   * directly via `RelatedModel.updateMany` / `RelatedModel.deleteMany`. This
+   * path bypasses the target's hooks — it will NOT enforce tenant scoping,
+   * fire audit events, or honor a custom `deletedField`. Only safe for
+   * trivial targets with no policy plugins. Prefer `repo` for new code.
+   */
+  model?: string;
   /** Foreign key field in the related model that references the deleted document */
   foreignKey: string;
   /** Whether to use soft delete if available (default: follows parent behavior) */

package/dist/utils/index.d.mts

@@ -1,5 +1,5 @@
-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";
+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";
 
 //#region src/utils/cache-keys.d.ts
 /**