@classytic/mongokit 3.5.6 → 3.6.0

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

@@ -1,6 +1,6 @@
 import { a as warn, i as debug, n as parseDuplicateKeyError, t as createError } from "./error-Bpbi_NKo.mjs";
 import { a as exists, c as getOrCreate, d as deleteByQuery, g as upsert, i as count, m as createMany, n as updateByQuery, o as getById, p as create, s as getByQuery, t as update, u as deleteById, v as distinct, y as LookupBuilder } from "./update-AVfKWNGt.mjs";
-import { t as PaginationEngine } from "./PaginationEngine-CpsQl471.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-CunXkR9p.mjs";
 import { hasNearOperator, rewriteNearForCount } from "./query/primitives/geo.mjs";
 import { r as isValidIdForType, t as getSchemaIdType } from "./id-resolution-LZ-cCwR5.mjs";
 import { a as byIdKey, c as listQueryKey, l as modelPattern, o as byQueryKey, r as getFieldsForUser, u as versionKey } from "./field-selection-C5o7jyyA.mjs";
@@ -583,12 +583,23 @@ function batchOperationsPlugin() {
 				}
 			});
 			/**
-			* Delete multiple documents
+			* Delete multiple documents matching a query.
+			*
+			* Behavior mirrors `Repository.delete`: defaults to soft-delete when
+			* `softDeletePlugin` is wired, physical delete otherwise. Pass
+			* `{ mode: 'hard' }` to bypass soft-delete for GDPR / cleanup paths —
+			* multi-tenant scoping and audit hooks still fire.
+			*
+			* Rejects empty filters even after policy hooks run, to prevent
+			* accidental collection wipes.
 			*/
 			repo.registerMethod("deleteMany", async function(query, options = {}) {
+				if (!query || Object.keys(query).length === 0) throw createError(400, "deleteMany requires a non-empty query filter. Pass an explicit filter to prevent accidental mass deletes.");
+				const mode = options.mode;
 				const context = await this._buildContext("deleteMany", {
 					query,
-					...options
+					...options,
+					...mode ? { deleteMode: mode } : {}
 				});
 				try {
 					if (context.softDeleted) {
@@ -603,7 +614,7 @@ function batchOperationsPlugin() {
 						return result;
 					}
 					const finalQuery = context.query || query;
-					if (!finalQuery || Object.keys(finalQuery).length === 0) throw createError(400, "deleteMany requires a non-empty query filter. Pass an explicit filter to prevent accidental mass deletes.");
+					if (!finalQuery || Object.keys(finalQuery).length === 0) throw createError(400, "deleteMany requires a non-empty query filter after policy hooks.");
 					const result = await this.Model.deleteMany(finalQuery, { session: options.session }).exec();
 					await this.emitAsync("after:deleteMany", {
 						context,
@@ -1154,6 +1165,60 @@ var AggregationBuilder = class AggregationBuilder {
 *    ```
 */
 //#endregion
+//#region src/transaction.ts
+/**
+* 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;
+* });
+* ```
+*/
+async function withTransaction(connection, callback, options = {}) {
+	const session = await connection.startSession();
+	try {
+		return await session.withTransaction(() => callback(session), options.transactionOptions);
+	} catch (error) {
+		const err = error;
+		if (options.allowFallback && isTransactionUnsupported(err)) {
+			options.onFallback?.(err);
+			return await callback(session);
+		}
+		throw err;
+	} finally {
+		await session.endSession();
+	}
+}
+/**
+* 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.
+*/
+function isTransactionUnsupported(error) {
+	const code = error.code;
+	if (code === 263 || code === 20) return true;
+	const message = (error.message || "").toLowerCase();
+	return message.includes("transaction numbers are only allowed on a replica set member") || message.includes("transaction is not supported");
+}
+//#endregion
 //#region src/Repository.ts
 function ensureLookupProjectionIncludesCursorFields(projection, sort) {
 	if (!projection || !sort) return projection;
@@ -1770,12 +1835,31 @@ var Repository = class {
 		}
 	}
 	/**
-	* 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' });
+	* ```
 	*/
 	async delete(id, options = {}) {
 		const context = await this._buildContext("delete", {
 			id,
-			...options
+			...options,
+			...options.mode ? { deleteMode: options.mode } : {}
 		});
 		try {
 			if (context.softDeleted) {
@@ -2150,25 +2234,7 @@ var Repository = class {
 	* ```
 	*/
 	async withTransaction(callback, options = {}) {
-		const session = await this.Model.db.startSession();
-		try {
-			return await session.withTransaction(() => callback(session), options.transactionOptions);
-		} catch (error) {
-			const err = error;
-			if (options.allowFallback && this._isTransactionUnsupported(err)) {
-				options.onFallback?.(err);
-				return await callback(session);
-			}
-			throw err;
-		} finally {
-			await session.endSession();
-		}
-	}
-	_isTransactionUnsupported(error) {
-		const code = error.code;
-		if (code === 263 || code === 20) return true;
-		const message = (error.message || "").toLowerCase();
-		return message.includes("transaction numbers are only allowed on a replica set member") || message.includes("transaction is not supported");
+		return withTransaction(this.Model.db, callback, options);
 	}
 	/**
 	* Execute custom query with event emission
@@ -2782,39 +2848,73 @@ function cachePlugin(options) {
 //#region src/plugins/cascade.plugin.ts
 /**
 * Cascade Delete Plugin
-* Automatically deletes related documents when a parent document is deleted
 *
-* @example
-* ```typescript
-* import mongoose from 'mongoose';
-* import { Repository, cascadePlugin, methodRegistryPlugin } from '@classytic/mongokit';
+* Automatically deletes related documents when a parent document is deleted.
+*
+* Two routing modes per relation:
+*
+*   1. **Repo-routed (preferred)** — pass `repo: targetRepo` on the relation.
+*      Cascade calls `targetRepo.delete(id, { mode })` / `targetRepo.deleteMany(
+*      query, { mode })`, so the target's `before:delete` / `before:deleteMany`
+*      hooks fire. Multi-tenant scoping, audit logging, cache invalidation,
+*      and the target's own `softDeletePlugin` (with its configured
+*      `deletedField`) all run correctly.
+*
+*   2. **Model-routed (legacy)** — pass `model: 'TargetModelName'`. Cascade
+*      writes directly via `mongoose.models[name].updateMany / deleteMany`,
+*      **bypassing** the target's hooks. Safe only for trivial targets with
+*      no policy plugins. Retained for backwards compatibility — prefer the
+*      repo-routed form for new code.
+*
+* The parent's delete mode propagates: a hard-deleted parent cascades hard,
+* a soft-deleted parent cascades soft — unless `relation.softDelete` overrides
+* the decision per-relation.
 *
+* @example Repo-routed (new)
+* ```ts
 * const productRepo = new Repository(Product, [
 *   methodRegistryPlugin(),
 *   cascadePlugin({
 *     relations: [
-*       { model: 'StockEntry', foreignKey: 'product' },
-*       { model: 'StockMovement', foreignKey: 'product' },
-*     ]
-*   })
+*       { repo: stockEntryRepo,    foreignKey: 'product' },
+*       { repo: stockMovementRepo, foreignKey: 'product' },
+*     ],
+*   }),
 * ]);
+* ```
 *
-* // When a product is deleted, all related StockEntry and StockMovement docs are also deleted
-* await productRepo.delete(productId);
+* @example Model-routed (legacy)
+* ```ts
+* cascadePlugin({
+*   relations: [
+*     { model: 'StockEntry', foreignKey: 'product' },
+*   ],
+* });
 * ```
 */
 /**
-* Cascade delete plugin
-*
-* Deletes related documents after the parent document is deleted.
-* Works with both hard delete and soft delete scenarios.
-*
-* @param options - Cascade configuration
-* @returns Plugin
+* Collect top-level parent-context fields that a target plugin (multi-tenant,
+* audit) will likely need. We can't know the target's contextKey, so we
+* forward a well-known allow-list: `organizationId`, `tenantId`, and `user`.
+* These are the conventions enforced by the built-in plugins.
+*/
+function collectScopeForward(context) {
+	const out = {};
+	if (context.organizationId !== void 0) out.organizationId = context.organizationId;
+	if (context.tenantId !== void 0) out.tenantId = context.tenantId;
+	if (context.user !== void 0) out.user = context.user;
+	return out;
+}
+/**
+* Cascade delete plugin.
 */
 function cascadePlugin(options) {
 	const { relations, parallel = true, logger } = options;
 	if (!relations || relations.length === 0) throw new Error("cascadePlugin requires at least one relation");
+	for (const rel of relations) {
+		if (!rel.repo && !rel.model) throw new Error("cascadePlugin: each relation needs either `repo` (preferred) or `model` (legacy)");
+		if (!rel.foreignKey) throw new Error("cascadePlugin: each relation needs `foreignKey`");
+	}
 	return {
 		name: "cascade",
 		apply(repo) {
@@ -2825,59 +2925,32 @@ function cascadePlugin(options) {
 					logger?.warn?.("Cascade delete skipped: no document ID in context", { model: context.model });
 					return;
 				}
-				const isSoftDelete = context.softDeleted === true;
-				const cascadeDelete = async (relation) => {
-					const RelatedModel = mongoose.models[relation.model];
-					if (!RelatedModel) {
-						logger?.warn?.(`Cascade delete skipped: model '${relation.model}' not found`, {
-							parentModel: context.model,
-							parentId: String(deletedId)
-						});
-						return;
-					}
-					const query = { [relation.foreignKey]: deletedId };
+				const isSoftParent = context.softDeleted === true;
+				const scopeForward = collectScopeForward(context);
+				const cascadeOne = async (relation) => {
+					const shouldSoftDelete = relation.softDelete ?? isSoftParent;
+					const cascadeCtx = {
+						targetModelName: relation.repo ? relation.repo.Model?.modelName ?? "<unknown>" : relation.model ?? "<unknown>",
+						session: context.session,
+						shouldSoftDelete,
+						user: context.user,
+						scopeForward
+					};
 					try {
-						if (relation.softDelete ?? isSoftDelete) {
-							const updateResult = await RelatedModel.updateMany(query, {
-								deletedAt: /* @__PURE__ */ new Date(),
-								...context.user ? { deletedBy: context.user._id || context.user.id } : {}
-							}, { session: context.session });
-							logger?.info?.(`Cascade soft-deleted ${updateResult.modifiedCount} documents`, {
-								parentModel: context.model,
-								parentId: String(deletedId),
-								relatedModel: relation.model,
-								foreignKey: relation.foreignKey,
-								count: updateResult.modifiedCount
-							});
-						} else {
-							const deleteResult = await RelatedModel.deleteMany(query, { session: context.session });
-							logger?.info?.(`Cascade deleted ${deleteResult.deletedCount} documents`, {
-								parentModel: context.model,
-								parentId: String(deletedId),
-								relatedModel: relation.model,
-								foreignKey: relation.foreignKey,
-								count: deleteResult.deletedCount
-							});
-						}
+						if (relation.repo) await cascadeViaRepoBulk(relation, deletedId, cascadeCtx);
+						else await cascadeViaLegacyModel(relation, deletedId, cascadeCtx, logger);
 					} catch (error) {
-						logger?.error?.(`Cascade delete failed for model '${relation.model}'`, {
+						logger?.error?.(`Cascade delete failed for '${cascadeCtx.targetModelName}'`, {
 							parentModel: context.model,
 							parentId: String(deletedId),
-							relatedModel: relation.model,
+							relatedModel: cascadeCtx.targetModelName,
 							foreignKey: relation.foreignKey,
 							error: error.message
 						});
 						throw error;
 					}
 				};
-				if (parallel) {
-					const failures = (await Promise.allSettled(relations.map(cascadeDelete))).filter((r) => r.status === "rejected");
-					if (failures.length) {
-						const err = failures[0].reason;
-						if (failures.length > 1) err.message = `${failures.length} cascade deletes failed. First: ${err.message}`;
-						throw err;
-					}
-				} else for (const relation of relations) await cascadeDelete(relation);
+				await runCascades(relations, cascadeOne, parallel);
 			});
 			repo.on("before:deleteMany", async (context) => {
 				const query = context.query;
@@ -2889,60 +2962,106 @@ function cascadePlugin(options) {
 				const { context } = payload;
 				const ids = context._cascadeIds;
 				if (!ids || ids.length === 0) return;
-				const isSoftDelete = context.softDeleted === true;
-				const cascadeDeleteMany = async (relation) => {
-					const RelatedModel = mongoose.models[relation.model];
-					if (!RelatedModel) {
-						logger?.warn?.(`Cascade deleteMany skipped: model '${relation.model}' not found`, { parentModel: context.model });
-						return;
-					}
-					const query = { [relation.foreignKey]: { $in: ids } };
-					const shouldSoftDelete = relation.softDelete ?? isSoftDelete;
+				const isSoftParent = context.softDeleted === true;
+				const scopeForward = collectScopeForward(context);
+				const cascadeBulk = async (relation) => {
+					const shouldSoftDelete = relation.softDelete ?? isSoftParent;
+					const cascadeCtx = {
+						targetModelName: relation.repo ? relation.repo.Model?.modelName ?? "<unknown>" : relation.model ?? "<unknown>",
+						session: context.session,
+						shouldSoftDelete,
+						user: context.user,
+						scopeForward
+					};
 					try {
-						if (shouldSoftDelete) {
-							const updateResult = await RelatedModel.updateMany(query, {
-								deletedAt: /* @__PURE__ */ new Date(),
-								...context.user ? { deletedBy: context.user._id || context.user.id } : {}
-							}, { session: context.session });
-							logger?.info?.(`Cascade soft-deleted ${updateResult.modifiedCount} documents (bulk)`, {
-								parentModel: context.model,
-								parentCount: ids.length,
-								relatedModel: relation.model,
-								foreignKey: relation.foreignKey,
-								count: updateResult.modifiedCount
-							});
-						} else {
-							const deleteResult = await RelatedModel.deleteMany(query, { session: context.session });
-							logger?.info?.(`Cascade deleted ${deleteResult.deletedCount} documents (bulk)`, {
-								parentModel: context.model,
-								parentCount: ids.length,
-								relatedModel: relation.model,
-								foreignKey: relation.foreignKey,
-								count: deleteResult.deletedCount
-							});
-						}
+						if (relation.repo) await cascadeViaRepoBulkMany(relation, ids, cascadeCtx);
+						else await cascadeViaLegacyModelMany(relation, ids, cascadeCtx, logger);
 					} catch (error) {
-						logger?.error?.(`Cascade deleteMany failed for model '${relation.model}'`, {
+						logger?.error?.(`Cascade deleteMany failed for '${cascadeCtx.targetModelName}'`, {
 							parentModel: context.model,
-							relatedModel: relation.model,
+							relatedModel: cascadeCtx.targetModelName,
 							foreignKey: relation.foreignKey,
 							error: error.message
 						});
 						throw error;
 					}
 				};
-				if (parallel) {
-					const failures = (await Promise.allSettled(relations.map(cascadeDeleteMany))).filter((r) => r.status === "rejected");
-					if (failures.length) {
-						const err = failures[0].reason;
-						if (failures.length > 1) err.message = `${failures.length} cascade deletes failed. First: ${err.message}`;
-						throw err;
-					}
-				} else for (const relation of relations) await cascadeDeleteMany(relation);
+				await runCascades(relations, cascadeBulk, parallel);
 			});
 		}
 	};
 }
+/**
+* Repo-routed cascade for a single parent delete.
+* Calls `repo.deleteMany({ [fk]: parentId }, { mode })` — respects all target
+* hooks (multi-tenant, audit, target's own soft-delete plugin).
+*/
+async function cascadeViaRepoBulk(relation, parentId, ctx) {
+	const targetRepo = relation.repo;
+	if (typeof targetRepo.deleteMany !== "function") throw new Error(`cascadePlugin: target repo for '${ctx.targetModelName}' is missing deleteMany(). Wire batchOperationsPlugin() + methodRegistryPlugin() on the target repo.`);
+	await targetRepo.deleteMany({ [relation.foreignKey]: parentId }, {
+		...ctx.scopeForward,
+		mode: ctx.shouldSoftDelete ? "soft" : "hard",
+		session: ctx.session
+	});
+}
+/**
+* Repo-routed cascade for a bulk parent deleteMany — `$in` over snapshot ids.
+*/
+async function cascadeViaRepoBulkMany(relation, parentIds, ctx) {
+	const targetRepo = relation.repo;
+	if (typeof targetRepo.deleteMany !== "function") throw new Error(`cascadePlugin: target repo for '${ctx.targetModelName}' is missing deleteMany(). Wire batchOperationsPlugin() + methodRegistryPlugin() on the target repo.`);
+	await targetRepo.deleteMany({ [relation.foreignKey]: { $in: parentIds } }, {
+		...ctx.scopeForward,
+		mode: ctx.shouldSoftDelete ? "soft" : "hard",
+		session: ctx.session
+	});
+}
+/**
+* Legacy cascade via `mongoose.models[name]`. Bypasses target hooks.
+* Retained for backwards compatibility with existing cascadePlugin consumers.
+*/
+async function cascadeViaLegacyModel(relation, parentId, ctx, logger) {
+	const RelatedModel = mongoose.models[relation.model];
+	if (!RelatedModel) {
+		logger?.warn?.(`Cascade delete skipped: model '${relation.model}' not found`);
+		return;
+	}
+	const query = { [relation.foreignKey]: parentId };
+	if (ctx.shouldSoftDelete) await RelatedModel.updateMany(query, {
+		deletedAt: /* @__PURE__ */ new Date(),
+		...ctx.user ? { deletedBy: ctx.user._id || ctx.user.id } : {}
+	}, { session: ctx.session });
+	else await RelatedModel.deleteMany(query, { session: ctx.session });
+}
+async function cascadeViaLegacyModelMany(relation, parentIds, ctx, logger) {
+	const RelatedModel = mongoose.models[relation.model];
+	if (!RelatedModel) {
+		logger?.warn?.(`Cascade deleteMany skipped: model '${relation.model}' not found`);
+		return;
+	}
+	const query = { [relation.foreignKey]: { $in: parentIds } };
+	if (ctx.shouldSoftDelete) await RelatedModel.updateMany(query, {
+		deletedAt: /* @__PURE__ */ new Date(),
+		...ctx.user ? { deletedBy: ctx.user._id || ctx.user.id } : {}
+	}, { session: ctx.session });
+	else await RelatedModel.deleteMany(query, { session: ctx.session });
+}
+/**
+* Execute a list of cascade operations, honoring the `parallel` flag.
+* Uses `allSettled` so one failure doesn't abort siblings; throws the first
+* rejection (with a composite message if several failed) after all complete.
+*/
+async function runCascades(relations, fn, parallel) {
+	if (parallel) {
+		const failures = (await Promise.allSettled(relations.map(fn))).filter((r) => r.status === "rejected");
+		if (failures.length) {
+			const err = failures[0].reason;
+			if (failures.length > 1) err.message = `${failures.length} cascade deletes failed. First: ${err.message}`;
+			throw err;
+		}
+	} else for (const relation of relations) await fn(relation);
+}
 //#endregion
 //#region src/plugins/custom-id.plugin.ts
 /**
@@ -3837,6 +3956,7 @@ function softDeletePlugin(options = {}) {
 				});
 			}
 			repo.on("before:delete", async (context) => {
+				if (context.deleteMode === "hard") return;
 				if (options.soft !== false) {
 					const updateData = { [deletedField]: /* @__PURE__ */ new Date() };
 					if (context.user) updateData[deletedByField] = context.user._id || context.user.id;
@@ -3896,6 +4016,7 @@ function softDeletePlugin(options = {}) {
 				}
 			}, { priority: HOOK_PRIORITY.POLICY });
 			repo.on("before:deleteMany", async (context) => {
+				if (context.deleteMode === "hard") return;
 				if (options.soft !== false) {
 					const deleteFilter = buildDeletedFilter(deletedField, filterMode, false);
 					const finalQuery = {
@@ -3948,9 +4069,8 @@ function softDeletePlugin(options = {}) {
 						throw error;
 					}
 					await this.emitAsync("after:restore", {
-						id,
-						result,
-						context
+						context,
+						result
 					});
 					return result;
 				};
@@ -4254,4 +4374,4 @@ function uniqueField(field, errorMessage) {
 	};
 }
 //#endregion
-export { aggregateHelpersPlugin as A, HOOK_PRIORITY as C, AuditTrailQuery as D, batchOperationsPlugin as E, auditTrailPlugin as O, cachePlugin as S, AggregationBuilder as T, dateSequentialId as _, uniqueField as a, sequentialId as b, subdocumentPlugin as c, multiTenantPlugin as d, mongoOperationsPlugin as f, customIdPlugin as g, elasticSearchPlugin as h, requireField as i, auditLogPlugin as k, softDeletePlugin as l, fieldFilterPlugin as m, blockIf as n, validationChainPlugin as o, methodRegistryPlugin as p, immutableField as r, timestampPlugin as s, autoInject as t, observabilityPlugin as u, getNextSequence as v, Repository as w, cascadePlugin as x, prefixedId as y };
+export { auditTrailPlugin as A, HOOK_PRIORITY as C, AggregationBuilder as D, withTransaction as E, aggregateHelpersPlugin as M, batchOperationsPlugin as O, cachePlugin as S, isTransactionUnsupported as T, dateSequentialId as _, uniqueField as a, sequentialId as b, subdocumentPlugin as c, multiTenantPlugin as d, mongoOperationsPlugin as f, customIdPlugin as g, elasticSearchPlugin as h, requireField as i, auditLogPlugin as j, AuditTrailQuery as k, softDeletePlugin as l, fieldFilterPlugin as m, blockIf as n, validationChainPlugin as o, methodRegistryPlugin as p, immutableField as r, timestampPlugin as s, autoInject as t, observabilityPlugin as u, getNextSequence as v, Repository as w, cascadePlugin as x, prefixedId as y };

package/dist/{validation-chain.plugin-BtmT-FFB.d.mts → validation-chain.plugin-COKNRAwp.d.mts}

@@ -1,4 +1,4 @@
-import { I as Logger, J as Plugin, St as ValidatorDefinition, T as FieldPreset, U as OffsetPaginationResult, V as ObjectId, Z as PopulateSpec, bt as ValidationChainOptions, et as RepositoryContext, f as CascadeOptions, l as CacheOptions, nt as RepositoryInstance, pt as SortSpec, st as SelectSpec, u as CacheStats, ut as SoftDeleteOptions } from "./types-BwO4u3JN.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-DiQfDesD.mjs";
 import mongoose, { ClientSession } from "mongoose";
 
 //#region src/plugins/aggregate-helpers.plugin.d.ts
@@ -307,12 +307,21 @@ interface BatchOperationsMethods {
     upsertedId: unknown;
   }>;
   /**
-   * Delete multiple documents matching the query
-   * @param query - Query to match documents
-   * @param options - Operation options
+   * Delete multiple documents matching the query.
+   *
+   * Defaults to soft delete when `softDeletePlugin` is wired, physical delete
+   * otherwise. Pass `{ mode: 'hard' }` for GDPR / admin cleanup — multi-tenant
+   * scoping and audit hooks still fire.
+   *
+   * @param query - Query to match documents (must be non-empty)
+   * @param options - Operation options (session, mode, tenant keys)
    * @returns Delete result with deletedCount
    */
-  deleteMany(query: Record<string, unknown>, options?: Record<string, unknown>): Promise<{
+  deleteMany(query: Record<string, unknown>, options?: {
+    session?: ClientSession;
+    mode?: 'hard' | 'soft';
+    [key: string]: unknown;
+  }): Promise<{
     acknowledged: boolean;
     deletedCount: number;
   }>;
@@ -398,13 +407,7 @@ interface CacheMethods {
 //#endregion
 //#region src/plugins/cascade.plugin.d.ts
 /**
- * Cascade delete plugin
- *
- * Deletes related documents after the parent document is deleted.
- * Works with both hard delete and soft delete scenarios.
- *
- * @param options - Cascade configuration
- * @returns Plugin
+ * Cascade delete plugin.
  */
 declare function cascadePlugin(options: CascadeOptions): Plugin;
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/mongokit",
-  "version": "3.5.6",
+  "version": "3.6.0",
   "description": "Production-grade MongoDB repositories with zero dependencies - smart pagination, events, and plugins",
   "type": "module",
   "sideEffects": false,