@classytic/mongokit 3.32.0 → 3.34.0

package/dist/plugins/index.mjs

@@ -1,6 +1,6 @@
-import { a as customIdPlugin, c as prefixedId, d as AuditTrailQuery, f as auditTrailPlugin, i as multiTenantPlugin, l as sequentialId, m as auditLogPlugin, n as softDeletePlugin, o as dateSequentialId, p as ensureAuditTrailReady, s as getNextSequence, t as timestampPlugin, u as cachePlugin } from "../timestamp.plugin-CAXzHs9y.mjs";
+import { a as customIdPlugin, c as prefixedId, d as AuditTrailQuery, f as auditTrailPlugin, i as multiTenantPlugin, l as sequentialId, m as auditLogPlugin, n as softDeletePlugin, o as dateSequentialId, p as ensureAuditTrailReady, s as getNextSequence, t as timestampPlugin, u as cachePlugin } from "../timestamp.plugin-BEc6TANm.mjs";
 import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "../method-registry.plugin-DblM7V6j.mjs";
-import { _ as cascadePlugin, a as uniqueField, c as subdocumentPlugin, d as mongoOperationsPlugin, f as leasePlugin, g as elasticSearchPlugin, h as fieldFilterPlugin, i as requireField, l as observabilityPlugin, m as idempotencyStorePlugin, n as blockIf, o as validationChainPlugin, p as immutableStatesPlugin, r as immutableField, s as createTenantContext, t as autoInject, u as MONGOKIT_PLUGIN_NAMES, v as appendOnlyPlugin, y as aggregateHelpersPlugin } from "../validation-chain.plugin-BihbMQRq.mjs";
+import { _ as cascadePlugin, a as uniqueField, c as subdocumentPlugin, d as mongoOperationsPlugin, f as leasePlugin, g as elasticSearchPlugin, h as fieldFilterPlugin, i as requireField, l as observabilityPlugin, m as idempotencyStorePlugin, n as blockIf, o as validationChainPlugin, p as immutableStatesPlugin, r as immutableField, s as createTenantContext, t as autoInject, u as MONGOKIT_PLUGIN_NAMES, v as appendOnlyPlugin, y as aggregateHelpersPlugin } from "../validation-chain.plugin-CyK1s9Ze.mjs";
 //#region src/plugins/change-log.plugin.ts
 const PLUGIN_NAME = "changeLog";
 function isSkipped(context) {

package/dist/{repository-Q16ErTu8.d.mts → repository-H_ffGgpE.d.mts}

@@ -109,6 +109,14 @@ interface RepositoryOptions {
   /** Custom ID field used by getById/update/delete (default: '_id').
    * Set to 'slug', 'code', 'chatId', etc. for non-ObjectId lookups. */
   idField?: string;
+  /**
+   * Field carrying the optimistic-concurrency version for `ifVersion` CAS
+   * writes. Default `'__v'` — the versionKey every mongoose schema already
+   * carries, so CAS works with zero schema changes. Note mongoose only
+   * auto-increments `__v` on array-mutating `save()`; mongokit's CAS path
+   * `$inc`s it explicitly on every versioned write, which is the contract.
+   */
+  versionField?: string;
   /**
    * How Repository.getAll handles the `search` parameter.
    * - 'text' (default): uses MongoDB $text; requires a text index.

package/dist/testkit/index.d.mts

@@ -1,5 +1,5 @@
-import { n as Repository } from "../Repository-BAzymuOz.mjs";
-import { n as CreateRepositoryConfig } from "../create-repository-mEdfH9sz.mjs";
+import { n as Repository } from "../Repository-BdSkQ8vc.mjs";
+import { n as CreateRepositoryConfig } from "../create-repository-BU4x9Kb0.mjs";
 import { Connection, Model, Schema } from "mongoose";
 import { MongoMemoryReplSet, MongoMemoryServer } from "mongodb-memory-server";
 //#region src/testkit/index.d.ts

package/dist/testkit/index.mjs

@@ -1,4 +1,4 @@
-import { t as createRepository } from "../create-repository-a3DQ5tzt.mjs";
+import { t as createRepository } from "../create-repository-CPNbktFG.mjs";
 import { createConnection } from "mongoose";
 //#region src/testkit/index.ts
 function idempotentStop(server) {

package/dist/{timestamp.plugin-CAXzHs9y.mjs → timestamp.plugin-BEc6TANm.mjs}

@@ -1,4 +1,4 @@
-import { c as ALL_OPERATIONS, t as HOOK_PRIORITY, u as OP_REGISTRY } from "./Repository-B_1y9cCf.mjs";
+import { c as ALL_OPERATIONS, t as HOOK_PRIORITY, u as OP_REGISTRY } from "./Repository-BArvU32x.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { throwIfAborted, withRetry } from "@classytic/repo-core/repository";
 import mongoose from "mongoose";
@@ -1355,10 +1355,12 @@ function softDeletePlugin(options = {}) {
 					const limit = params.limit || 20;
 					const skip = (page - 1) * limit;
 					let sortSpec = { [deletedField]: -1 };
-					if (params.sort) if (typeof params.sort === "string") {
-						const sortOrder = params.sort.startsWith("-") ? -1 : 1;
-						sortSpec = { [params.sort.startsWith("-") ? params.sort.substring(1) : params.sort]: sortOrder };
-					} else sortSpec = params.sort;
+					if (params.sort) {
+						if (typeof params.sort === "string") {
+							const sortOrder = params.sort.startsWith("-") ? -1 : 1;
+							sortSpec = { [params.sort.startsWith("-") ? params.sort.substring(1) : params.sort]: sortOrder };
+						} else sortSpec = params.sort;
+					}
 					let query = this.Model.find(combinedFilters).sort(sortSpec).skip(skip).limit(limit);
 					if (getDeletedOptions.session) query = query.session(getDeletedOptions.session);
 					if (getDeletedOptions.select) {

package/dist/{to-plain-BuX1RUZV.d.mts → to-plain-Dyz_qvuo.d.mts}

@@ -1,9 +1,9 @@
-import { v as UserContext } from "./repository-Q16ErTu8.mjs";
-import { r as FieldPreset } from "./plugin-options-BsFH0sTi.mjs";
+import { v as UserContext } from "./repository-H_ffGgpE.mjs";
+import { r as FieldPreset } from "./plugin-options-DXnlKM3B.mjs";
 import mongoose, { Schema } from "mongoose";
 import { CacheAdapter } from "@classytic/repo-core/cache";
-import { CrudSchemas, SchemaBuilderOptions } from "@classytic/repo-core/schema";
 import { HttpError } from "@classytic/repo-core/errors";
+import { CrudSchemas, SchemaBuilderOptions } from "@classytic/repo-core/schema";
 //#region src/utils/error.d.ts
 /** Optional structured fields for createError. */
 interface CreateErrorOptions {

package/dist/{update-w5i-pa_c.mjs → update-jSXp3nu3.mjs}

@@ -119,7 +119,26 @@ function compile(filter) {
 			return { [filter.field]: { $nin: [...filter.values] } };
 		case "exists": return filter.exists ? { [filter.field]: { $ne: null } } : { [filter.field]: null };
 		case "like": return { [filter.field]: likeToRegex(filter.pattern, filter.caseSensitivity) };
-		case "regex": return { [filter.field]: { $regex: filter.pattern } };
+		/**
+		* `flags` is part of the IR (`FilterRegex.flags` in repo-core) and MUST be
+		* carried into `$options` — dropping it silently downgrades every
+		* case-insensitive search to case-sensitive.
+		*
+		* This was live: arc's CRUD list route normalises the parsed query through
+		* `toRepositoryFilter` → `policyRecordToFilter`, which correctly produced
+		* `{ op:'regex', pattern:'heritage', flags:'i' }` from BOTH parser shapes
+		* (mongokit's `/heritage/i` and arc's `{$regex,$options:'i'}`). This line
+		* then rebuilt the query without the flags, so `?name[like]=heritage`
+		* returned 0 while `?name[like]=Heritage` returned 3 — in a product whose
+		* OpenAPI descriptions promise "contains substring (CASE-INSENSITIVE)".
+		* Nothing errored; every operator search box in the app just under-returned,
+		* and an operator typing a name in lower case concluded the record did not
+		* exist.
+		*/
+		case "regex": return { [filter.field]: filter.flags ? {
+			$regex: filter.pattern,
+			$options: filter.flags
+		} : { $regex: filter.pattern } };
 		case "and": {
 			if (filter.children.length === 0) return {};
 			const parts = filter.children.map(compile);
@@ -330,34 +349,35 @@ var LookupBuilder = class LookupBuilder {
 		const stages = [];
 		const usePipelineForm = pipeline || letVars || coerce;
 		let lookupStage;
-		if (usePipelineForm) if (!pipeline || pipeline.length === 0) {
-			if (!localField || !foreignField) throw new Error("LookupBuilder: When using pipeline form without a custom pipeline, both localField and foreignField are required to auto-generate the pipeline");
-			const autoPipeline = [{ $match: { $expr: { $eq: [`$${foreignField}`, `$$${localField}`] } } }];
-			lookupStage = { $lookup: {
-				from,
-				let: {
-					[localField]: localCorrelation(localField, coerce),
-					...letVars || {}
-				},
-				pipeline: autoPipeline,
-				as: outputField
-			} };
-		} else {
-			const safePipeline = this.options.sanitize !== false ? LookupBuilder.sanitizePipeline(pipeline) : pipeline;
-			let effectiveLet = letVars;
-			let effectivePipeline = safePipeline;
-			if (localField && foreignField && !letVars) {
-				effectiveLet = { lookupJoinVal: localCorrelation(localField, coerce) };
-				effectivePipeline = [{ $match: { $expr: { $eq: [`$${foreignField}`, "$$lookupJoinVal"] } } }, ...safePipeline];
+		if (usePipelineForm) {
+			if (!pipeline || pipeline.length === 0) {
+				if (!localField || !foreignField) throw new Error("LookupBuilder: When using pipeline form without a custom pipeline, both localField and foreignField are required to auto-generate the pipeline");
+				const autoPipeline = [{ $match: { $expr: { $eq: [`$${foreignField}`, `$$${localField}`] } } }];
+				lookupStage = { $lookup: {
+					from,
+					let: {
+						[localField]: localCorrelation(localField, coerce),
+						...letVars || {}
+					},
+					pipeline: autoPipeline,
+					as: outputField
+				} };
+			} else {
+				const safePipeline = this.options.sanitize !== false ? LookupBuilder.sanitizePipeline(pipeline) : pipeline;
+				let effectiveLet = letVars;
+				let effectivePipeline = safePipeline;
+				if (localField && foreignField && !letVars) {
+					effectiveLet = { lookupJoinVal: localCorrelation(localField, coerce) };
+					effectivePipeline = [{ $match: { $expr: { $eq: [`$${foreignField}`, "$$lookupJoinVal"] } } }, ...safePipeline];
+				}
+				lookupStage = { $lookup: {
+					from,
+					...effectiveLet && { let: effectiveLet },
+					pipeline: effectivePipeline,
+					as: outputField
+				} };
 			}
-			lookupStage = { $lookup: {
-				from,
-				...effectiveLet && { let: effectiveLet },
-				pipeline: effectivePipeline,
-				as: outputField
-			} };
-		}
-		else {
+		} else {
 			if (!localField || !foreignField) throw new Error("LookupBuilder: localField and foreignField are required for simple lookup");
 			lookupStage = { $lookup: {
 				from,

package/dist/utils/index.d.mts

@@ -1,2 +1,54 @@
-import { _ as getMongooseProjection, a as createMemoryCache, b as createError, c as IdType, d as isObjectIdInstance, f as isValidIdForType, g as getFieldsForUser, h as filterResponseData, i as buildCrudSchemasFromMongooseSchema, l as getSchemaIdType, m as createFieldPreset, n as CrudSchemasFramework, o as LoggerConfig, p as toObjectId, r as buildCrudSchemasFromModel, s as configureLogger, t as toPlain, v as CreateErrorOptions, y as ParseDuplicateKeyOptions } from "../to-plain-BuX1RUZV.mjs";
-export { type CreateErrorOptions, type CrudSchemasFramework, type IdType, type LoggerConfig, type ParseDuplicateKeyOptions, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType, toObjectId, toPlain };
+import { _ as getMongooseProjection, a as createMemoryCache, b as createError, c as IdType, d as isObjectIdInstance, f as isValidIdForType, g as getFieldsForUser, h as filterResponseData, i as buildCrudSchemasFromMongooseSchema, l as getSchemaIdType, m as createFieldPreset, n as CrudSchemasFramework, o as LoggerConfig, p as toObjectId, r as buildCrudSchemasFromModel, s as configureLogger, t as toPlain, v as CreateErrorOptions, y as ParseDuplicateKeyOptions } from "../to-plain-Dyz_qvuo.mjs";
+import { ClientSession, Model } from "mongoose";
+//#region src/utils/id-chunks.d.ts
+/**
+ * Default slice for `$in` fan-out. Larger than `runChunkedPurge`'s 1000 on purpose:
+ * a purge chunk bounds the WRITE LOCK SCOPE of each progressive strategy step, while a
+ * snapshot slice bounds only the query-document size and the per-call working set —
+ * 10k ObjectIds is ~120 KB of `$in`, far under every limit, at 10× fewer round trips.
+ */
+declare const DEFAULT_ID_CHUNK = 10000;
+/**
+ * Collect the bare id values matching `filter`, streaming via a driver cursor so the
+ * only O(n) allocation is the returned array itself (a `find().lean()` materializes an
+ * intermediate array of `{_id}` documents first — roughly double the peak for large n).
+ */
+declare function collectIds(model: Model<unknown>, filter: Record<string, unknown>, options?: {
+  session?: ClientSession | undefined;
+  idField?: string;
+}): Promise<unknown[]>;
+/**
+ * Yield `ids` in consecutive slices of at most `size`. Yields nothing for an empty
+ * array. `size` must be a positive integer — sliced `$in` correctness depends on it,
+ * so a nonsense size throws instead of silently degrading to one giant slice.
+ */
+declare function idChunks<T>(ids: readonly T[], size: number): Generator<T[], void, undefined>;
+/**
+ * Compose the keyset-progressed select filter: the base predicate, narrowed to rows past
+ * the last committed `_id`. `cursor == null` means "from the start". Selection paired
+ * with this must sort `_id`-ascending ({@link selectKeysetChunk} does), so `$gt: cursor`
+ * never revisits a processed row and never skips an unprocessed one. Never mutates
+ * `baseFilter`.
+ */
+declare function keysetFilter(baseFilter: Record<string, unknown>, cursor: unknown): Record<string, unknown>;
+/**
+ * The `_id`-ascending bounded chunk select both action ports share:
+ * `find(filter).sort({_id: 1}).limit(limit).lean()`. Lean on purpose — chunk consumers
+ * want plain objects, not hydrated documents. Pass `projection: {_id: 1}` when only ids
+ * are needed (the purge port's common path); omit it for full docs (archive's readChunk,
+ * anonymize-functional).
+ */
+declare function selectKeysetChunk<T>(model: Model<T>, filter: Record<string, unknown>, limit: number, options?: {
+  session?: ClientSession | undefined;
+  projection?: Record<string, 1 | 0> | undefined;
+}): Promise<T[]>;
+/**
+ * Re-assert the base predicate on an id-narrowed WRITE: `{...base, _id: {$in: ids}}`.
+ * The `$in` alone would be enough to address the chunk, but carrying the base predicate
+ * defends against a row whose scope fields changed between the chunk select and the
+ * write — such a row is silently skipped instead of written outside its cohort. Both
+ * action ports use this shape; use it for any select-then-write over a chunk.
+ */
+declare function narrowToIds(baseFilter: Record<string, unknown>, ids: readonly unknown[]): Record<string, unknown>;
+//#endregion
+export { type CreateErrorOptions, type CrudSchemasFramework, DEFAULT_ID_CHUNK, type IdType, type LoggerConfig, type ParseDuplicateKeyOptions, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, collectIds, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, idChunks, isObjectIdInstance, isValidIdForType, keysetFilter, narrowToIds, selectKeysetChunk, toObjectId, toPlain };

package/dist/utils/index.mjs

@@ -1,7 +1,8 @@
 import { a as toObjectId, i as isValidIdForType, r as isObjectIdInstance, t as getSchemaIdType } from "../id-resolution-BqDrk0S2.mjs";
+import { a as narrowToIds, i as keysetFilter, n as collectIds, o as selectKeysetChunk, r as idChunks, t as DEFAULT_ID_CHUNK } from "../id-chunks-BmAwsqNk.mjs";
 import { t as configureLogger } from "../logger-K7dPmu2U.mjs";
 import { t as createError } from "../error-BuByZwKU.mjs";
 import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "../field-selection-FSQFLpsU.mjs";
 import { n as createMemoryCache, t as toPlain } from "../to-plain-vksRrLtc.mjs";
 import { n as buildCrudSchemasFromMongooseSchema, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-DKbnKduN.mjs";
-export { buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType, toObjectId, toPlain };
+export { DEFAULT_ID_CHUNK, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, collectIds, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, idChunks, isObjectIdInstance, isValidIdForType, keysetFilter, narrowToIds, selectKeysetChunk, toObjectId, toPlain };

package/dist/{validation-chain.plugin-BihbMQRq.mjs → validation-chain.plugin-CyK1s9Ze.mjs}

@@ -1,5 +1,6 @@
-import { c as ALL_OPERATIONS, u as OP_REGISTRY } from "./Repository-B_1y9cCf.mjs";
-import { _ as upsert } from "./update-w5i-pa_c.mjs";
+import { n as collectIds, r as idChunks, t as DEFAULT_ID_CHUNK } from "./id-chunks-BmAwsqNk.mjs";
+import { c as ALL_OPERATIONS, u as OP_REGISTRY } from "./Repository-BArvU32x.mjs";
+import { _ as upsert } from "./update-jSXp3nu3.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { t as createError } from "./error-BuByZwKU.mjs";
 import { r as getFieldsForUser } from "./field-selection-FSQFLpsU.mjs";
@@ -207,6 +208,97 @@ function appendOnlyPlugin(options = {}) {
 * forward a well-known allow-list: `organizationId`, `tenantId`, and `user`.
 * These are the conventions enforced by the built-in plugins.
 */
+/**
+* Count referencing documents through the target REPOSITORY, carrying the parent's session
+* and scope.
+*
+* Both are load-bearing and were missing in the first cut:
+*   - without `session`, the count reads OUTSIDE the parent's transaction, so children
+*     created in the same uncommitted transaction are invisible and the guard passes;
+*   - without the forwarded scope, a tenant-scoped target either reads unscoped (refusing a
+*     delete because ANOTHER tenant references the row) or relies on ambient context that a
+*     background job does not have.
+*
+* REFUSES rather than falling back to `Model.countDocuments` when the repository has no
+* `count`: a raw count silently bypasses the target's own policy, which is the thing this
+* guard exists to respect.
+*/
+async function countReferencing(relation, filter, session, scopeForward) {
+	const targetRepo = relation.repo;
+	if (!targetRepo || typeof targetRepo.count !== "function") throw new Error(`cascadePlugin: onDelete:'restrict' on '${relation.foreignKey}' needs a repository with \`count()\` — a raw model count would bypass the target's tenant scoping and policy`);
+	const options = { ...scopeForward };
+	if (session) options.session = session;
+	return targetRepo.count(filter, options);
+}
+/**
+* ENFORCE that a guarded foreign key is indexed.
+*
+* `restrict` and `detach` issue a query per relation on every delete. MongoDB gives no index
+* for free the way an FK constraint does, so an unindexed `foreignKey` turns each delete into
+* a COLLECTION SCAN of the child collection — invisible in tests (small fixtures) and
+* crippling in production, which is the shape of defect this codebase treats as the default
+* hazard.
+*
+* Documentation was not enough: a type comment saying the key "SHOULD" be indexed stops no
+* scan. This is checked at BIND time, where the declaration is, and THROWS — the policies are
+* opt-in and brand new, so nothing pre-existing can be broken by refusing.
+*
+* Prefix rule, matching Mongo's own: an index on `{a:1, b:1}` serves a query on `a`, so the
+* foreign key qualifies when it is the FIRST key of any declared index. `schema.indexes()`
+* includes path-level `{index: true}` as well as explicit `schema.index(...)` calls.
+*/
+function assertForeignKeyIndexed(relation) {
+	const schema = relation.repo?.Model?.schema;
+	if (!schema || typeof schema.indexes !== "function") return;
+	if (schema.indexes().some(([keys]) => Object.keys(keys)[0] === relation.foreignKey)) return;
+	const target = relation.repo?.Model?.modelName ?? relation.model ?? "<unknown>";
+	throw new Error(`cascadePlugin: onDelete:'${relation.onDelete}' on '${relation.foreignKey}' requires an index on ${target}.${relation.foreignKey} — the guard queries it on every delete, and Mongo has no foreign-key index. Add \`index: true\` to the path or a leading \`schema.index(...)\`.`);
+}
+/**
+* A TTL index on the PROTECTED parent makes `restrict` a promise the plugin cannot keep.
+*
+* `restrict` means "do not delete this document while anything references it". A TTL index
+* means "delete this document N seconds after its date field, server-side". Mongo's expiry
+* thread runs no application code — no repository, no hook, no count — so it will remove a
+* referenced parent and leave every child dangling, silently, at a time nobody chose.
+*
+* The two are a direct contradiction, so this THROWS rather than warns. Refusing at bind time
+* is the only point where anyone can see both declarations at once; at runtime the expiry
+* simply happens.
+*
+* NOTE this is about the PARENT (the repo declaring the relations). A TTL on the CHILD is
+* fine and even useful — expiring children is how references legitimately drain away.
+*/
+function assertNoTtlOnProtectedParent(repo, relation) {
+	const schema = repo.Model?.schema;
+	if (!schema || typeof schema.indexes !== "function") return;
+	const ttl = schema.indexes().find(([, options]) => options?.expireAfterSeconds !== void 0);
+	if (!ttl) return;
+	const parent = repo.Model?.modelName ?? "<unknown>";
+	const key = Object.keys(ttl[0])[0];
+	throw new Error(`cascadePlugin: ${parent} declares onDelete:'restrict' on '${relation.foreignKey}' but also carries a TTL index on '${key}' (expireAfterSeconds). Mongo's expiry runs server-side and fires no hooks, so it would delete a referenced document and orphan its children — the restrict guarantee cannot hold. Remove the TTL, or use a retention sweep that deletes through the repository.`);
+}
+/**
+* `detach` — clear the reference through the target REPOSITORY (`SET NULL`).
+*
+* Routed through `repo.updateMany`, not `repo.Model.updateMany`. The first cut used the raw
+* model while the comment beside it claimed the target's hooks ran: they did not, so tenant
+* policy, audit hooks, cache invalidation and update hooks were all skipped on a write that
+* mutates the child. A comment asserting a guarantee the code does not provide is worse than
+* no comment.
+*/
+async function detachReferences(relation, filter, ctx) {
+	const update = { $unset: { [relation.foreignKey]: "" } };
+	const options = { ...ctx.scopeForward };
+	if (ctx.session) options.session = ctx.session;
+	const targetRepo = relation.repo;
+	if (targetRepo && typeof targetRepo.updateMany === "function") {
+		await targetRepo.updateMany(filter, update, options);
+		return;
+	}
+	if (targetRepo) throw new Error(`cascadePlugin: onDelete:'detach' on '${relation.foreignKey}' needs a repository with \`updateMany()\` — a raw model update would skip the child's hooks and tenant policy`);
+	await mongoose.models[relation.model]?.updateMany(filter, update, ctx.session ? { session: ctx.session } : {}).exec();
+}
 function collectScopeForward(context) {
 	const out = {};
 	if (context.organizationId !== void 0) out.organizationId = context.organizationId;
@@ -218,15 +310,54 @@ function collectScopeForward(context) {
 * Cascade delete plugin.
 */
 function cascadePlugin(options) {
-	const { relations, parallel = true, logger } = options;
+	const { relations, parallel = true, batchSize = DEFAULT_ID_CHUNK, logger } = options;
 	if (!relations || relations.length === 0) throw new Error("cascadePlugin requires at least one relation");
+	if (!Number.isInteger(batchSize) || batchSize < 1) throw new Error(`cascadePlugin: batchSize must be a positive integer, got ${String(batchSize)}`);
 	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`");
+		/**
+		* `restrict` must be able to COUNT the referencing documents before the parent goes,
+		* and the legacy model-routed path writes through `mongoose.models[...]` without the
+		* target's scoping. A restrict that counted unscoped rows would refuse a delete on
+		* evidence from another tenant, so it requires the repo-routed form.
+		*/
+		if (rel.onDelete === "restrict" && !rel.repo) throw new Error(`cascadePlugin: relation on '${rel.foreignKey}' uses onDelete:'restrict', which requires \`repo\` (the legacy \`model\` route cannot apply the target's tenant scoping to the count)`);
 	}
+	const restrictions = relations.filter((r) => r.onDelete === "restrict");
+	const detachments = relations.filter((r) => r.onDelete === "detach");
+	/** Everything else keeps the historical behaviour — an absent `onDelete` is `cascade`. */
+	const cascades = relations.filter((r) => (r.onDelete ?? "cascade") === "cascade");
 	return {
 		name: "cascade",
 		apply(repo) {
+			/**
+			* Bind time, not construction time: the relation carries a repo whose Model (and
+			* therefore its schema) is only reliably available once the plugin is applied.
+			*/
+			for (const relation of [...restrictions, ...detachments]) assertForeignKeyIndexed(relation);
+			for (const relation of restrictions) assertNoTtlOnProtectedParent(repo, relation);
+			if (restrictions.length > 0) repo.on("before:delete", async (context) => {
+				const id = context.id;
+				if (!id) return;
+				const scopeForward = collectScopeForward(context);
+				for (const relation of restrictions) {
+					const remaining = await countReferencing(relation, { [relation.foreignKey]: id }, context.session, scopeForward);
+					if (remaining > 0) {
+						const target = relation.repo?.Model?.modelName ?? relation.model ?? "<unknown>";
+						const err = /* @__PURE__ */ new Error(`Cannot delete this ${context.model ?? "document"}: ${remaining} ${target} record(s) still reference it via '${relation.foreignKey}'. Remove or reassign them first.`);
+						err.code = "REFERENCE_RESTRICTED";
+						err.details = {
+							model: context.model,
+							id: String(id),
+							referencedBy: target,
+							foreignKey: relation.foreignKey,
+							count: remaining
+						};
+						throw err;
+					}
+				}
+			});
 			repo.on("after:delete", async (payload) => {
 				const { context } = payload;
 				const deletedId = context.id;
@@ -259,13 +390,59 @@ function cascadePlugin(options) {
 						throw error;
 					}
 				};
-				await runCascades(relations, cascadeOne, parallel);
+				/**
+				* `detach` — the RDBMS `SET NULL`. Clear the pointer, keep the child.
+				*
+				* Runs beside the cascades and before them in intent: a detached child must not be
+				* reachable through a reference to a document that no longer exists. Routed through
+				* the target repo so its hooks and scoping apply, exactly as cascade is.
+				*/
+				const detachOne = async (relation) => detachReferences(relation, { [relation.foreignKey]: deletedId }, {
+					session: context.session,
+					scopeForward
+				});
+				const txSession = context.session;
+				if (detachments.length > 0) await runCascades(detachments, detachOne, parallel, txSession);
+				await runCascades(cascades, cascadeOne, parallel, txSession);
 			});
 			repo.on("before:deleteMany", async (context) => {
 				const query = context.query;
 				if (!query || Object.keys(query).length === 0) return;
 				const idField = repo.idField || "_id";
-				context._cascadeIds = (await repo.Model.find(query, { [idField]: 1 }).lean().session(context.session ?? null)).map((doc) => doc[idField]);
+				const ids = await collectIds(repo.Model, query, {
+					session: context.session,
+					idField
+				});
+				context._cascadeIds = ids;
+				/**
+				* RESTRICT applies to bulk too — and its absence here was a destructive bug.
+				*
+				* The first cut split the policies on the single-delete path only and then passed
+				* ALL relations to the bulk cascade, so `deleteMany` DELETED the children of a
+				* `restrict` relation (and of a `detach` one). Bulk was therefore strictly worse
+				* than declaring nothing at all. Checked in the same hook that snapshots the ids,
+				* so it cannot be reordered apart from them.
+				*/
+				if (restrictions.length > 0 && ids.length > 0) {
+					const scopeForward = collectScopeForward(context);
+					for (const relation of restrictions) {
+						let remaining = 0;
+						for (const chunk of idChunks(ids, batchSize)) remaining += await countReferencing(relation, { [relation.foreignKey]: { $in: chunk } }, context.session, scopeForward);
+						if (remaining > 0) {
+							const target = relation.repo?.Model?.modelName ?? relation.model ?? "<unknown>";
+							const err = /* @__PURE__ */ new Error(`Cannot delete these ${context.model ?? "documents"}: ${remaining} ${target} record(s) still reference ${ids.length} of them via '${relation.foreignKey}'. Remove or reassign them first.`);
+							err.code = "REFERENCE_RESTRICTED";
+							err.details = {
+								model: context.model,
+								ids: ids.map(String),
+								referencedBy: target,
+								foreignKey: relation.foreignKey,
+								count: remaining
+							};
+							throw err;
+						}
+					}
+				}
 			});
 			repo.on("after:deleteMany", async (payload) => {
 				const { context } = payload;
@@ -283,8 +460,8 @@ function cascadePlugin(options) {
 						scopeForward
 					};
 					try {
-						if (relation.repo) await cascadeViaRepoBulkMany(relation, ids, cascadeCtx);
-						else await cascadeViaLegacyModelMany(relation, ids, cascadeCtx, logger);
+						if (relation.repo) await cascadeViaRepoBulkMany(relation, ids, batchSize, cascadeCtx);
+						else await cascadeViaLegacyModelMany(relation, ids, batchSize, cascadeCtx, logger);
 					} catch (error) {
 						logger?.error?.(`Cascade deleteMany failed for '${cascadeCtx.targetModelName}'`, {
 							parentModel: context.model,
@@ -295,7 +472,16 @@ function cascadePlugin(options) {
 						throw error;
 					}
 				};
-				await runCascades(relations, cascadeBulk, parallel);
+				/** `detach` in bulk — the same `$unset`, routed through the target repository, sliced. */
+				const detachBulk = async (relation) => {
+					for (const chunk of idChunks(ids, batchSize)) await detachReferences(relation, { [relation.foreignKey]: { $in: chunk } }, {
+						session: context.session,
+						scopeForward
+					});
+				};
+				const txSession = context.session;
+				if (detachments.length > 0) await runCascades(detachments, detachBulk, parallel, txSession);
+				await runCascades(cascades, cascadeBulk, parallel, txSession);
 			});
 		}
 	};
@@ -315,12 +501,13 @@ async function cascadeViaRepoBulk(relation, parentId, ctx) {
 	});
 }
 /**
-* Repo-routed cascade for a bulk parent deleteMany — `$in` over snapshot ids.
+* Repo-routed cascade for a bulk parent deleteMany — sliced `$in` over snapshot ids
+* (`batchSize` bounds each query document; see `utils/id-chunks.ts`).
 */
-async function cascadeViaRepoBulkMany(relation, parentIds, ctx) {
+async function cascadeViaRepoBulkMany(relation, parentIds, batchSize, ctx) {
 	const targetRepo = relation.repo;
 	if (typeof targetRepo.deleteMany !== "function") throw new Error(`cascadePlugin: target repo for '${ctx.targetModelName}' is missing deleteMany(). Ensure the target is a mongokit Repository or implements the StandardRepo deleteMany contract.`);
-	await targetRepo.deleteMany({ [relation.foreignKey]: { $in: parentIds } }, {
+	for (const chunk of idChunks(parentIds, batchSize)) await targetRepo.deleteMany({ [relation.foreignKey]: { $in: chunk } }, {
 		...ctx.scopeForward,
 		mode: ctx.shouldSoftDelete ? "soft" : "hard",
 		session: ctx.session
@@ -343,26 +530,38 @@ async function cascadeViaLegacyModel(relation, parentId, ctx, logger) {
 	}, { session: ctx.session });
 	else await RelatedModel.deleteMany(query, { session: ctx.session });
 }
-async function cascadeViaLegacyModelMany(relation, parentIds, ctx, logger) {
+async function cascadeViaLegacyModelMany(relation, parentIds, batchSize, 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 });
+	for (const chunk of idChunks(parentIds, batchSize)) {
+		const query = { [relation.foreignKey]: { $in: chunk } };
+		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.
+*
+* **`parallel` is IGNORED inside a transaction.** A `ClientSession` is not
+* safe for concurrent operations — MongoDB's driver serialises commands per
+* session, and issuing several at once is undefined behaviour that surfaces
+* as transaction-state errors rather than a clean failure. Since cascades
+* began propagating the parent session, `parallel: true` (the default) meant
+* every multi-relation cascade inside `withTransaction()` was doing exactly
+* that. Sequential execution is the only correct mode there, so the flag is
+* downgraded rather than obeyed — the alternative is a throughput option
+* that silently corrupts transactions.
 */
-async function runCascades(relations, fn, parallel) {
-	if (parallel) {
+async function runCascades(relations, fn, parallel, session) {
+	if (parallel && !session) {
 		const failures = (await Promise.allSettled(relations.map(fn))).filter((r) => r.status === "rejected");
 		if (failures.length) {
 			const err = failures[0].reason;

package/dist/{validation-chain.plugin-BSshLJTA.d.mts → validation-chain.plugin-yQRob3Av.d.mts}

@@ -1,6 +1,6 @@
 import { a as PopulateSpec, i as ObjectId, l as SortSpec, s as SelectSpec } from "./core-62oo3N1C.mjs";
-import { h as RepositoryInstance, l as Plugin, p as RepositoryContext } from "./repository-Q16ErTu8.mjs";
-import { c as ValidationChainOptions, i as Logger, l as ValidatorDefinition, o as SoftDeleteOptions, r as FieldPreset, t as CascadeOptions } from "./plugin-options-BsFH0sTi.mjs";
+import { h as RepositoryInstance, l as Plugin, p as RepositoryContext } from "./repository-H_ffGgpE.mjs";
+import { c as ValidationChainOptions, i as Logger, l as ValidatorDefinition, o as SoftDeleteOptions, r as FieldPreset, t as CascadeOptions } from "./plugin-options-DXnlKM3B.mjs";
 import { BulkWriteResult } from "@classytic/repo-core/repository";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { OffsetPaginationResult } from "@classytic/repo-core/pagination";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/mongokit",
-  "version": "3.32.0",
+  "version": "3.34.0",
   "description": "Production-grade MongoDB repositories - smart pagination, events, and plugins. Built on @classytic/repo-core.",
   "type": "module",
   "sideEffects": false,
@@ -122,7 +122,7 @@
   },
   "homepage": "https://github.com/classytic/mongokit#readme",
   "peerDependencies": {
-    "@classytic/repo-core": ">=0.20.0",
+    "@classytic/repo-core": ">=0.23.0",
     "mongodb-memory-server": ">=10.4.3",
     "mongoose": ">=9.4.1"
   },
@@ -169,25 +169,25 @@
     "check:forgotten-exports": "node scripts/check-forgotten-exports.mjs"
   },
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.18.2",
-    "@better-auth/api-key": "^1.6.22",
-    "@better-auth/mongo-adapter": "^1.6.22",
-    "@biomejs/biome": "^2.4.10",
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@better-auth/api-key": "^1.6.29",
+    "@better-auth/mongo-adapter": "^1.6.29",
+    "@biomejs/biome": "^2.5.8",
     "@classytic/dev-tools": "^0.2.0",
-    "@classytic/repo-core": "^0.21.0",
-    "@types/node": "^22.0.0",
-    "@vitest/coverage-v8": "^4.1.4",
-    "ajv": "^8.18.0",
+    "@classytic/repo-core": "^0.23.0",
+    "@types/node": "^26.2.0",
+    "@vitest/coverage-v8": "^4.1.10",
+    "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "better-auth": "^1.6.23",
+    "better-auth": "^1.6.29",
     "dotenv": "^17.4.2",
-    "knip": "^6.31.0",
+    "knip": "^6.32.2",
     "mongodb": "^7.5.0",
-    "mongodb-memory-server": "^10.4.3",
-    "mongoose": "^9.9.1",
-    "publint": "^0.3.18",
+    "mongodb-memory-server": "^11.2.0",
+    "mongoose": "^9.9.2",
+    "publint": "^0.3.23",
     "tsdown": "^0.22.14",
-    "typescript": "~5.9.0",
-    "vitest": "^4.1.4"
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.10"
   }
 }