@classytic/mongokit 3.24.0 → 3.25.0

package/dist/{timestamp.plugin-BhSX0Lu_.mjs → timestamp.plugin-B8252GuQ.mjs}

@@ -1,4 +1,4 @@
-import { l as OP_REGISTRY, s as ALL_OPERATIONS, t as HOOK_PRIORITY } from "./Repository-ClOraFjT.mjs";
+import { l as OP_REGISTRY, s as ALL_OPERATIONS, t as HOOK_PRIORITY } from "./Repository-KKR8jxfD.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { t as createError } from "./error-BuByZwKU.mjs";
 import { throwIfAborted, withRetry } from "@classytic/repo-core/repository";
@@ -108,12 +108,34 @@ function auditLogPlugin(logger) {
 * Audit Trail Plugin
 *
 * Persists operation audit entries to a MongoDB collection.
-* Fire-and-forget: writes happen async and never block or fail the main operation.
+*
+* Two delivery modes (`mode` option):
+*
+* - `'best-effort'` (default): fire-and-forget — writes happen async and
+*   never block or fail the main operation. Suitable for observability,
+*   debugging, and eventually-consistent activity feeds. NOT suitable as a
+*   compliance ledger: an entry can be written for a transaction that later
+*   aborts, and the process can die after the business write but before the
+*   audit write lands.
+*
+* - `'transactional'`: the audit insert is awaited inside the operation and
+*   joins the operation's `session` when one is present. Inside a
+*   `withTransaction` block this makes business write + audit entry atomic —
+*   both commit or both roll back. A failed audit write fails the operation
+*   (after routing through `onWriteError`). This is the mode to use for
+*   compliance-grade trails (SOC 2 / PCI / HIPAA) — but note it is atomic
+*   ONLY inside an actual transaction; without one, an audit failure rejects
+*   the call after the business write has already committed. Call
+*   `ensureAuditTrailReady()` at boot so collection/index creation doesn't
+*   happen inside the first transaction. For durable *asynchronous* auditing,
+*   write an outbox entry in the same transaction instead and relay it
+*   separately (see `@classytic/primitives/outbox`).
 *
 * Features:
 * - Tracks create, update, delete operations
 * - Field-level change tracking (before/after diff on updates)
-* - TTL auto-cleanup via MongoDB TTL index
+* - Connection-aware: models register on the connection you pass (multi-DB safe)
+* - TTL auto-cleanup via MongoDB TTL index — retention conflicts throw
 * - Custom metadata per entry (IP, user-agent, etc.)
 * - Shared `audit_trails` collection across all models
 *
@@ -121,9 +143,11 @@ function auditLogPlugin(logger) {
 * ```typescript
 * const repo = new Repository(Job, [
 *   auditTrailPlugin({
+*     mode: 'transactional',
 *     operations: ['create', 'update', 'delete'],
 *     trackChanges: true,
 *     ttlDays: 90,
+*     connection: jobsConnection, // omit to use mongoose.connection
 *     metadata: (context) => ({
 *       ip: context.req?.ip,
 *     }),
@@ -131,10 +155,56 @@ function auditLogPlugin(logger) {
 * ]);
 * ```
 */
-const modelCache = /* @__PURE__ */ new Map();
-function getAuditModel(collectionName, ttlDays) {
-	const existing = modelCache.get(collectionName);
-	if (existing) return existing;
+/**
+* Per-connection model cache. WeakMap keyed by the Connection object so a
+* closed/discarded connection's models can be garbage collected, and so two
+* connections never share a model even when they use the same collection
+* name (each connection may point at a different database).
+*/
+const modelCaches = /* @__PURE__ */ new WeakMap();
+function ttlDaysToSeconds(ttlDays) {
+	return ttlDays !== void 0 && ttlDays > 0 ? ttlDays * 24 * 60 * 60 : null;
+}
+/**
+* Introspect an already-compiled model (hot reload, duplicate registration
+* outside our cache) for the TTL its schema installed on `timestamp`.
+*/
+function resolveExistingTtlSeconds(model) {
+	for (const [fields, opts] of model.schema.indexes()) {
+		const expireAfterSeconds = opts?.expireAfterSeconds;
+		if (fields.timestamp !== void 0 && typeof expireAfterSeconds === "number") return expireAfterSeconds;
+	}
+	return null;
+}
+function ttlConflictError(collectionName, existing, requested) {
+	const fmt = (s) => s === null ? "no TTL" : `${s / 86400} day(s)`;
+	return /* @__PURE__ */ new Error(`[auditTrailPlugin] TTL conflict for audit collection '${collectionName}': already registered with ${fmt(existing)}, now requested with ${fmt(requested)}. Retention is collection-level configuration — every auditTrailPlugin()/AuditTrailQuery touching the same collection on the same connection must pass the same ttlDays. Changing retention on an existing collection requires an index migration outside the plugin.`);
+}
+function getAuditModel(connection, collectionName, ttlDays, ttlPolicy = "declare") {
+	const conn = connection ?? mongoose.connection;
+	const requestedTtl = ttlDaysToSeconds(ttlDays);
+	const reuseExisting = ttlPolicy === "reuse-existing" && ttlDays === void 0;
+	let cache = modelCaches.get(conn);
+	if (!cache) {
+		cache = /* @__PURE__ */ new Map();
+		modelCaches.set(conn, cache);
+	}
+	const cached = cache.get(collectionName);
+	if (cached) {
+		if (!reuseExisting && cached.ttlSeconds !== requestedTtl) throw ttlConflictError(collectionName, cached.ttlSeconds, requestedTtl);
+		return cached.model;
+	}
+	const modelName = `AuditTrail_${collectionName}`;
+	const existing = conn.models[modelName] ?? (conn === mongoose.connection ? mongoose.models[modelName] : void 0);
+	if (existing) {
+		const existingTtl = resolveExistingTtlSeconds(existing);
+		if (!reuseExisting && existingTtl !== requestedTtl) throw ttlConflictError(collectionName, existingTtl, requestedTtl);
+		cache.set(collectionName, {
+			model: existing,
+			ttlSeconds: existingTtl
+		});
+		return existing;
+	}
 	const schema = new mongoose.Schema({
 		model: {
 			type: String,
@@ -169,8 +239,7 @@ function getAuditModel(collectionName, ttlDays) {
 		metadata: { type: mongoose.Schema.Types.Mixed },
 		timestamp: {
 			type: Date,
-			default: Date.now,
-			index: true
+			default: Date.now
 		}
 	}, {
 		collection: collectionName,
@@ -186,13 +255,13 @@ function getAuditModel(collectionName, ttlDays) {
 		userId: 1,
 		timestamp: -1
 	});
-	if (ttlDays !== void 0 && ttlDays > 0) {
-		const ttlSeconds = ttlDays * 24 * 60 * 60;
-		schema.index({ timestamp: 1 }, { expireAfterSeconds: ttlSeconds });
-	}
-	const modelName = `AuditTrail_${collectionName}`;
-	const model = mongoose.models[modelName] || mongoose.model(modelName, schema);
-	modelCache.set(collectionName, model);
+	if (requestedTtl !== null) schema.index({ timestamp: 1 }, { expireAfterSeconds: requestedTtl });
+	else schema.index({ timestamp: 1 });
+	const model = conn.model(modelName, schema);
+	cache.set(collectionName, {
+		model,
+		ttlSeconds: requestedTtl
+	});
 	return model;
 }
 /** Compute field-level diff between previous and updated document */
@@ -232,30 +301,63 @@ function deepEqual(a, b) {
 function getUserId(context) {
 	return context.user?._id || context.user?.id;
 }
+/** Resolve the effective id field for an operation: per-call override > repo config > '_id'. */
+function getEffectiveIdField(repo, context) {
+	return context.idField ?? repo.idField ?? "_id";
+}
+function invokeWriteErrorCallback(onWriteError, err, entry) {
+	if (!onWriteError) {
+		warn(`[auditTrailPlugin] Failed to write audit entry: ${err.message}`);
+		return;
+	}
+	try {
+		onWriteError(err, entry);
+	} catch (cbErr) {
+		warn(`[auditTrailPlugin] onWriteError callback itself threw: ${cbErr.message}`);
+	}
+}
 /**
-* Fire-and-forget audit write. Never throws into the caller's promise
-* chain (audit failures must not break the primary operation), but
-* routes errors to `onWriteError` for compliance hosts that need
-* surface visibility. Default behavior: `console.warn`-only.
+* Best-effort audit write. Never throws into the caller's promise chain
+* (audit failures must not break the primary operation), but routes errors
+* to `onWriteError` for hosts that need surface visibility.
+*
+* Deliberately does NOT join the operation's session: by the time the
+* microtask runs, a transaction may already be committed or aborted —
+* joining it late would either throw or attach the entry to a doomed
+* transaction. Session-consistent delivery is exactly what
+* `mode: 'transactional'` is for.
 */
-function writeAudit(AuditModel, entry, onWriteError) {
+function writeAuditBestEffort(AuditModel, entry, onWriteError) {
 	Promise.resolve().then(() => {
 		AuditModel.create({
 			...entry,
 			timestamp: /* @__PURE__ */ new Date()
 		}).catch((err) => {
-			if (onWriteError) try {
-				onWriteError(err, entry);
-			} catch (cbErr) {
-				warn(`[auditTrailPlugin] onWriteError callback itself threw: ${cbErr.message}`);
-			}
-			else warn(`[auditTrailPlugin] Failed to write audit entry: ${err.message}`);
+			invokeWriteErrorCallback(onWriteError, err, entry);
 		});
 	});
 }
+/**
+* Transactional audit write. Awaited by the operation's after-hook and
+* attached to the operation's session when present — inside a transaction
+* the entry commits/aborts atomically with the business write. A failed
+* insert rethrows (after `onWriteError`) so the operation fails rather than
+* silently succeeding without its audit entry.
+*/
+async function writeAuditTransactional(AuditModel, entry, session, onWriteError) {
+	try {
+		await AuditModel.create([{
+			...entry,
+			timestamp: /* @__PURE__ */ new Date()
+		}], session ? { session } : {});
+	} catch (err) {
+		invokeWriteErrorCallback(onWriteError, err, entry);
+		throw err;
+	}
+}
 const snapshots = /* @__PURE__ */ new WeakMap();
 function auditTrailPlugin(options = {}) {
-	const { operations = [
+	const { mode = "best-effort", connection, operations = [
 		"create",
 		"update",
 		"delete"
@@ -268,12 +370,20 @@ function auditTrailPlugin(options = {}) {
 	return {
 		name: "auditTrail",
 		apply(repo) {
-			const AuditModel = getAuditModel(collectionName, ttlDays);
+			const AuditModel = getAuditModel(connection ?? repo.Model.db, collectionName, ttlDays);
+			if (mode === "transactional") {
+				if (repo.hooks.mode === "sync") throw new Error("[auditTrailPlugin] mode: 'transactional' requires the repository's hooks: 'async' mode (the default) — this repository uses hooks: 'sync', whose after-hooks are fire-and-forget and cannot await the audit write.");
+			}
+			/** Route one entry through the configured delivery mode. */
+			const deliver = (entry, context) => {
+				if (mode === "transactional") return writeAuditTransactional(AuditModel, entry, context.session, onWriteError);
+				writeAuditBestEffort(AuditModel, entry, onWriteError);
+			};
 			if (opsSet.has("create")) repo.on("after:create", ({ context, result }) => {
 				if (isSkipped(context)) return;
 				const doc = toPlainObject(result);
-				const idKey = repo.idField || "_id";
-				writeAudit(AuditModel, {
+				const idKey = getEffectiveIdField(repo, context);
+				return deliver({
 					model: context.model || repo.model,
 					operation: "create",
 					documentId: doc?.[idKey],
@@ -281,14 +391,20 @@ function auditTrailPlugin(options = {}) {
 					orgId: context.organizationId,
 					document: trackDocument ? sanitizeDoc(doc, excludeFields) : void 0,
 					metadata: metadata?.(context)
-				}, onWriteError);
+				}, context);
 			});
 			if (opsSet.has("update")) {
 				if (trackChanges) repo.on("before:update", async (context) => {
 					if (isSkipped(context)) return;
-					if (!context.id) return;
+					if (context.id === void 0 || context.id === null) return;
 					try {
-						const prev = await repo.Model.findById(context.id).lean();
+						const filter = {
+							[getEffectiveIdField(repo, context)]: context.id,
+							...context.query ?? {}
+						};
+						const query = repo.Model.findOne(filter);
+						if (context.session) query.session(context.session);
+						const prev = await query.lean();
 						if (prev) snapshots.set(context, prev);
 					} catch (err) {
 						warn(`[auditTrailPlugin] Failed to snapshot before update: ${err.message}`);
@@ -303,41 +419,41 @@ function auditTrailPlugin(options = {}) {
 						if (prev && context.data) changes = computeChanges(prev, context.data, excludeFields);
 						snapshots.delete(context);
 					}
-					writeAudit(AuditModel, {
+					return deliver({
 						model: context.model || repo.model,
 						operation: "update",
-						documentId: context.id || doc?.[repo.idField || "_id"],
+						documentId: context.id || doc?.[getEffectiveIdField(repo, context)],
 						userId: getUserId(context),
 						orgId: context.organizationId,
 						changes,
 						metadata: metadata?.(context)
-					}, onWriteError);
+					}, context);
 				});
 			}
 			if (opsSet.has("findOneAndUpdate")) repo.on("after:findOneAndUpdate", ({ context, result }) => {
 				if (isSkipped(context)) return;
 				if (!result) return;
 				const doc = result;
-				const idKey = repo.idField || "_id";
-				writeAudit(AuditModel, {
+				const idKey = getEffectiveIdField(repo, context);
+				return deliver({
 					model: context.model || repo.model,
 					operation: "findOneAndUpdate",
 					documentId: doc?.[idKey],
 					userId: getUserId(context),
 					orgId: context.organizationId,
 					metadata: metadata?.(context)
-				}, onWriteError);
+				}, context);
 			});
 			if (opsSet.has("delete")) repo.on("after:delete", ({ context }) => {
 				if (isSkipped(context)) return;
-				writeAudit(AuditModel, {
+				return deliver({
 					model: context.model || repo.model,
 					operation: "delete",
 					documentId: context.id,
 					userId: getUserId(context),
 					orgId: context.organizationId,
 					metadata: metadata?.(context)
-				}, onWriteError);
+				}, context);
 			});
 			if (typeof repo.registerMethod === "function")
  /**
@@ -379,6 +495,32 @@ function sanitizeDoc(doc, excludeFields) {
 	return result;
 }
 /**
+* Create the audit collection and build its indexes BEFORE traffic begins.
+*
+* Call once at boot (after the plugin is registered, before serving
+* requests) — especially with `mode: 'transactional'`: creating the
+* collection or building indexes lazily inside the first transaction
+* forces MongoDB catalog locks and transient `TransientTransactionError`
+* retries. Idempotent; safe to call on every boot.
+*
+* @example
+* ```typescript
+* const repo = new Repository(Model, [
+*   auditTrailPlugin({ mode: 'transactional', ttlDays: 90 }),
+* ]);
+* await ensureAuditTrailReady(); // collection + indexes exist before traffic
+* ```
+*/
+async function ensureAuditTrailReady(options = {}) {
+	const model = getAuditModel(options.connection, options.collectionName ?? "audit_trails", options.ttlDays, "reuse-existing");
+	try {
+		await model.createCollection();
+	} catch (err) {
+		if (err.codeName !== "NamespaceExists") throw err;
+	}
+	await model.init();
+}
+/**
 * Standalone audit trail query utility.
 * Use this to query audits across all models — e.g., admin dashboards, audit APIs.
 *
@@ -386,7 +528,10 @@ function sanitizeDoc(doc, excludeFields) {
 * ```typescript
 * import { AuditTrailQuery } from '@classytic/mongokit';
 *
-* const auditQuery = new AuditTrailQuery(); // defaults to 'audit_trails' collection
+* const auditQuery = new AuditTrailQuery(); // defaults to 'audit_trails' on mongoose.connection
+*
+* // Named connection (multi-DB apps)
+* const tenantAudits = new AuditTrailQuery({ connection: tenantConnection });
 *
 * // All audits for an org
 * const orgAudits = await auditQuery.query({ orgId: '...' });
@@ -418,8 +563,8 @@ function sanitizeDoc(doc, excludeFields) {
 */
 var AuditTrailQuery = class {
 	model;
-	constructor(collectionName = "audit_trails", ttlDays) {
-		this.model = getAuditModel(collectionName, ttlDays);
+	constructor(options = {}) {
+		this.model = getAuditModel(options.connection, options.collectionName ?? "audit_trails", options.ttlDays, "reuse-existing");
 	}
 	/**
 	* Get the underlying Mongoose model for custom queries
@@ -1179,6 +1324,7 @@ function softDeletePlugin(options = {}) {
 		apply(repo) {
 			try {
 				const schemaPaths = repo.Model.schema.paths;
+				if (!schemaPaths[deletedField]) warn(`[softDeletePlugin] Model '${repo.Model.modelName}' has no '${deletedField}' schema path. Soft-delete marks documents by \`$set\`-ing '${deletedField}', but Mongoose strict mode drops updates to undeclared paths — so delete() will SILENTLY no-op (documents are never soft-deleted). Declare it on the schema: { ${deletedField}: { type: Date, default: ${filterMode === "null" ? "null" : "undefined"} } }`);
 				for (const [pathName, schemaType] of Object.entries(schemaPaths)) {
 					if (pathName === "_id" || pathName === deletedField) continue;
 					if (schemaType.options?.unique) warn(`[softDeletePlugin] Field '${pathName}' on model '${repo.Model.modelName}' has a unique index. With soft-delete enabled, deleted documents will block new documents with the same '${pathName}'. Fix: change to a compound partial index — { ${pathName}: 1 }, { unique: true, partialFilterExpression: { ${deletedField}: null } }`);
@@ -1396,4 +1542,4 @@ function timestampPlugin() {
 	};
 }
 //#endregion
-export { methodRegistryPlugin as a, getNextSequence as c, cachePlugin as d, batchOperationsPlugin as f, auditLogPlugin as h, multiTenantPlugin as i, prefixedId as l, auditTrailPlugin as m, softDeletePlugin as n, customIdPlugin as o, AuditTrailQuery as p, adminBypass$1 as r, dateSequentialId as s, timestampPlugin as t, sequentialId as u };
+export { methodRegistryPlugin as a, getNextSequence as c, cachePlugin as d, batchOperationsPlugin as f, auditLogPlugin as g, ensureAuditTrailReady as h, multiTenantPlugin as i, prefixedId as l, auditTrailPlugin as m, softDeletePlugin as n, customIdPlugin as o, AuditTrailQuery as p, adminBypass$1 as r, dateSequentialId as s, timestampPlugin as t, sequentialId as u };

package/dist/{to-plain-g8-gsVxZ.d.mts → to-plain-DkF5px0R.d.mts}

@@ -1,4 +1,5 @@
-import { C as FieldPreset, gt as UserContext } from "./types-BtMuhoX5.mjs";
+import { v as UserContext } from "./repository-DCHRWRXw.mjs";
+import { r as FieldPreset } from "./plugin-options-vFufQZMZ.mjs";
 import mongoose, { Schema } from "mongoose";
 import { CacheAdapter } from "@classytic/repo-core/cache";
 import { CrudSchemas, SchemaBuilderOptions } from "@classytic/repo-core/schema";
@@ -139,22 +140,17 @@ declare function filterResponseData<T extends Record<string, unknown>>(data: T |
 declare function createFieldPreset(config: Partial<FieldPreset>): FieldPreset;
 //#endregion
 //#region src/utils/id-resolution.d.ts
-/**
- * ID Resolution Primitive
- *
- * Pure functions for detecting a Mongoose schema's _id type and validating
- * id values against it. Used by Repository.getById to decide whether to
- * run ObjectId validation (for ObjectId schemas) or skip it (for String /
- * Number / UUID schemas).
- *
- * Also usable standalone — Arc controllers, custom repositories, migration
- * scripts, or test harnesses can import these directly to make the same
- * decision without depending on Repository.
- *
- * Design: no `this`, no Model, no DB calls. Only reads `schema.paths._id.instance`.
- */
 /** Normalized _id type — covers the common Mongoose _id declarations */
 type IdType = 'objectid' | 'string' | 'number' | 'uuid' | 'unknown';
+/**
+ * Null-tolerant `id → ObjectId` coercion — the single seam for optional
+ * reference/audit-stamp fields (`approvedBy`, `submittedBy`, …) where an
+ * absent actor is a legitimate `null`, not an error. Invalid non-empty
+ * strings still throw (mongoose's own constructor validation) — this helper
+ * only absorbs the absent case, never bad input. Hosts were hand-rolling
+ * this identically at every approval-hook write; import it instead.
+ */
+declare function toObjectId(id: string | null | undefined): mongoose.Types.ObjectId | null;
 /**
  * Check if a Mongoose SchemaType `instance` string is an ObjectId variant.
  * Mongoose 9.x uses `'ObjectId'`, older versions use `'ObjectID'`. This
@@ -324,4 +320,4 @@ declare function buildCrudSchemasFromModel(mongooseModel: mongoose.Model<unknown
  */
 declare function toPlain<T>(value: T): T;
 //#endregion
-export { parseDuplicateKeyError as _, configureLogger as a, idVariants as c, createFieldPreset as d, filterResponseData as f, isDuplicateKeyError as g, createError as h, createMemoryCache as i, isObjectIdInstance as l, getMongooseProjection as m, buildCrudSchemasFromModel as n, IdType as o, getFieldsForUser as p, buildCrudSchemasFromMongooseSchema as r, getSchemaIdType as s, toPlain as t, isValidIdForType as u };
+export { isDuplicateKeyError as _, configureLogger as a, idVariants as c, toObjectId as d, createFieldPreset as f, createError as g, getMongooseProjection as h, createMemoryCache as i, isObjectIdInstance as l, getFieldsForUser as m, buildCrudSchemasFromModel as n, IdType as o, filterResponseData as p, buildCrudSchemasFromMongooseSchema as r, getSchemaIdType as s, toPlain as t, isValidIdForType as u, parseDuplicateKeyError as v };

package/dist/type-utils-CLzRFtIA.d.mts

@@ -0,0 +1,163 @@
+import { Document, Model } from "mongoose";
+import { ValidationResult } from "@classytic/repo-core/schema";
+//#region src/types/type-utils.d.ts
+/**
+ * Infer document type from a Mongoose Model
+ * @example
+ * type UserDoc = InferDocument<typeof UserModel>;
+ */
+type InferDocument<TModel> = TModel extends Model<infer TDoc> ? TDoc : never;
+/**
+ * Infer raw document shape (without Mongoose Document methods)
+ * @example
+ * type User = InferRawDoc<typeof UserModel>;
+ */
+type InferRawDoc<TModel> = TModel extends Model<infer TDoc> ? TDoc extends Document ? Omit<TDoc, keyof Document> : TDoc : never;
+/**
+ * Make specific fields optional
+ * @example
+ * type CreateUser = PartialBy<User, 'createdAt' | 'updatedAt'>;
+ */
+type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/**
+ * Make specific fields required
+ * @example
+ * type UserWithId = RequiredBy<User, '_id'>;
+ */
+type RequiredBy<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+/**
+ * Extract keys of type T that have values of type V
+ * @example
+ * type StringFields = KeysOfType<User, string>; // 'name' | 'email'
+ */
+type KeysOfType<T, V> = { [K in keyof T]: T[K] extends V ? K : never; }[keyof T];
+/**
+ * Deep partial - makes all nested properties optional
+ */
+type DeepPartial<T> = T extends object ? { [P in keyof T]?: DeepPartial<T[P]>; } : T;
+/**
+ * Strict object type - prevents excess properties
+ * Use with `satisfies` for compile-time validation
+ */
+type Strict<T> = T & { [K in Exclude<string, keyof T>]?: never; };
+/**
+ * NonNullable fields extractor
+ */
+type NonNullableFields<T> = { [K in keyof T]: NonNullable<T[K]>; };
+/**
+ * Create/Update input types from document
+ */
+type CreateInput<TDoc> = Omit<TDoc, '_id' | 'createdAt' | 'updatedAt' | '__v'>;
+/**
+ * Partial-document update patch — the shape `repo.update(id, data)` accepts
+ * for its `data` parameter. A `Partial<TDoc>` minus the fields a caller must
+ * never set directly (`_id`, `createdAt`, `__v`).
+ *
+ * **Renamed from `UpdateInput<TDoc>` in 3.11.0** to eliminate a name
+ * collision with `@classytic/repo-core/update`'s `UpdateInput` (the
+ * `UpdateSpec | Record | Record[]` union consumed by `updateMany` /
+ * `findOneAndUpdate`).
+ */
+type UpdatePatch<TDoc> = Partial<Omit<TDoc, '_id' | 'createdAt' | '__v'>>;
+/**
+ * Typed Mongo update document — the operator-shape that `findOneAndUpdate`
+ * / `updateMany` accept on the wire (`{ $set, $inc, $unset, ... }`).
+ *
+ * The explicit operator keys give IDE autocomplete + per-operator value
+ * typing; the trailing `[op: string]: unknown` index signature lets a
+ * caller-built `MongoOperatorUpdate` value assign to `Record<string,
+ * unknown>` without a cast — matching repo-core's `UpdateInput` slot
+ * (`UpdateSpec | Record<string, unknown> | Record<string, unknown>[]`)
+ * and unblocking the historic
+ *
+ *   `normalizeUpdate(update) as unknown as Record<string, unknown>`
+ *
+ * footgun every domain package eventually wrote.
+ *
+ * Trade-off: with the index signature, an operator typo (`$st` instead
+ * of `$set`) won't fail TypeScript — Mongo would silently drop it. The
+ * common operators are listed explicitly so `obj.$set` / `obj.$inc`
+ * autocomplete stays useful; the escape hatch covers everything else
+ * (`$min`, `$max`, `$rename`, `$pop`, etc.).
+ *
+ * @example
+ * ```ts
+ * import type { MongoOperatorUpdate } from '@classytic/mongokit';
+ *
+ * const patch: MongoOperatorUpdate = {
+ *   $set: { status: 'paid', paidAt: new Date() },
+ *   $inc: { revision: 1 },
+ * };
+ * await repo.findOneAndUpdate({ _id: id }, patch);  // no cast
+ * ```
+ */
+interface MongoOperatorUpdate {
+  /** Assign top-level or dotted-path values. */
+  $set?: Record<string, unknown>;
+  /** Set only on insert (upsert path). */
+  $setOnInsert?: Record<string, unknown>;
+  /** Remove fields (`Mongo` accepts `''`, `1`, or `true`). */
+  $unset?: Record<string, '' | 1 | true>;
+  /** Atomic numeric increment / decrement. */
+  $inc?: Record<string, number>;
+  /** Atomic numeric multiplication. */
+  $mul?: Record<string, number>;
+  /** Push to array (or `{ $each, $position, $slice, $sort }`). */
+  $push?: Record<string, unknown>;
+  /** Pull matching values from array. */
+  $pull?: Record<string, unknown>;
+  /** Pull a list of literals from array. */
+  $pullAll?: Record<string, unknown[]>;
+  /** Push only when not already present. */
+  $addToSet?: Record<string, unknown>;
+  /** Remove first / last element (`-1` / `1`). */
+  $pop?: Record<string, -1 | 1>;
+  /** Set only when the new value is smaller / larger. */
+  $min?: Record<string, unknown>;
+  $max?: Record<string, unknown>;
+  /** Rename top-level fields. */
+  $rename?: Record<string, string>;
+  /** Auto-set Date / Timestamp on this update. */
+  $currentDate?: Record<string, true | {
+    $type: 'date' | 'timestamp';
+  }>;
+  /** Bitwise ops on integer fields. */
+  $bit?: Record<string, {
+    and?: number;
+    or?: number;
+    xor?: number;
+  }>;
+  /**
+   * Escape hatch for any operator not explicitly listed above (e.g.
+   * positional-array operators like `$[<identifier>]` inside a path
+   * key). Index signature is what makes the type assign to
+   * `Record<string, unknown>` without a cast.
+   */
+  [op: string]: unknown;
+}
+/**
+ * Extract string keys from a document type, with `string` fallback for untyped usage.
+ * Provides autocomplete for known fields while still accepting arbitrary strings
+ * (e.g. for nested paths like 'address.city').
+ */
+type DocField<TDoc> = (keyof TDoc & string) | (string & {});
+/**
+ * Union emitted by the validation-chain plugin. Keeps the violation shape
+ * from `ValidationResult` without re-exporting the type — consumers that
+ * need `ValidationResult`, `CrudSchemas`, `JsonSchema`, `SchemaBuilderOptions`,
+ * `FieldRule` or `FieldRules` import them straight from
+ * `@classytic/repo-core/schema`.
+ */
+type UpdateWithValidationResult<T> = {
+  success: true;
+  data: T;
+} | {
+  success: false;
+  error: {
+    code: number;
+    message: string;
+    violations?: ValidationResult['violations'];
+  };
+};
+//#endregion
+export { InferRawDoc as a, NonNullableFields as c, Strict as d, UpdatePatch as f, InferDocument as i, PartialBy as l, DeepPartial as n, KeysOfType as o, UpdateWithValidationResult as p, DocField as r, MongoOperatorUpdate as s, CreateInput as t, RequiredBy as u };

package/dist/utils/index.d.mts

@@ -1,2 +1,2 @@
-import { a as configureLogger, d as createFieldPreset, f as filterResponseData, h as createError, i as createMemoryCache, l as isObjectIdInstance, m as getMongooseProjection, n as buildCrudSchemasFromModel, o as IdType, p as getFieldsForUser, r as buildCrudSchemasFromMongooseSchema, s as getSchemaIdType, t as toPlain, u as isValidIdForType } from "../to-plain-g8-gsVxZ.mjs";
-export { type IdType, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType, toPlain };
+import { a as configureLogger, d as toObjectId, f as createFieldPreset, g as createError, h as getMongooseProjection, i as createMemoryCache, l as isObjectIdInstance, m as getFieldsForUser, n as buildCrudSchemasFromModel, o as IdType, p as filterResponseData, r as buildCrudSchemasFromMongooseSchema, s as getSchemaIdType, t as toPlain, u as isValidIdForType } from "../to-plain-DkF5px0R.mjs";
+export { type IdType, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType, toObjectId, toPlain };

package/dist/utils/index.mjs

@@ -1,7 +1,7 @@
-import { i as isValidIdForType, r as isObjectIdInstance, t as getSchemaIdType } from "../id-resolution-P2OzcyRl.mjs";
+import { a as toObjectId, i as isValidIdForType, r as isObjectIdInstance, t as getSchemaIdType } from "../id-resolution-BqDrk0S2.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-CVnrKFDq.mjs";
-export { buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType, toPlain };
+import { n as buildCrudSchemasFromMongooseSchema, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-CByt1VhQ.mjs";
+export { buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType, toObjectId, toPlain };

package/dist/{validation-chain.plugin-Dtt4tO7R.mjs → validation-chain.plugin-C3Vwp-Rk.mjs}

@@ -1,4 +1,4 @@
-import { l as OP_REGISTRY, s as ALL_OPERATIONS } from "./Repository-ClOraFjT.mjs";
+import { l as OP_REGISTRY, s as ALL_OPERATIONS } from "./Repository-KKR8jxfD.mjs";
 import { _ as upsert } from "./update-1Lq9OMD2.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { t as createError } from "./error-BuByZwKU.mjs";

package/dist/{validation-chain.plugin-CFJbr964.d.mts → validation-chain.plugin-DxD15h-2.d.mts}

@@ -1,4 +1,6 @@
-import { B as ObjectId, C as FieldPreset, G as Plugin, J as PopulateSpec, Q as RepositoryContext, _t as ValidationChainOptions, et as RepositoryInstance, it as SelectSpec, j as Logger, l as CascadeOptions, st as SoftDeleteOptions, ut as SortSpec, vt as ValidatorDefinition } from "./types-BtMuhoX5.mjs";
+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-DCHRWRXw.mjs";
+import { c as ValidationChainOptions, i as Logger, l as ValidatorDefinition, o as SoftDeleteOptions, r as FieldPreset, t as CascadeOptions } from "./plugin-options-vFufQZMZ.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.24.0",
+  "version": "3.25.0",
   "description": "Production-grade MongoDB repositories - smart pagination, events, and plugins. Built on @classytic/repo-core.",
   "type": "module",
   "sideEffects": false,
@@ -139,8 +139,10 @@
     "lint:package": "publint && attw --pack . --profile esm-only",
     "format": "biome format src/ --write",
     "check": "biome ci src/ --diagnostic-level=error",
+    "check:dead-code": "knip",
+    "ci": "npm run check && npm run typecheck && npm run typecheck:tests && npm run build && npm run lint:package && npm run check:dead-code && npm test",
     "push": "classytic-push",
-    "prepublishOnly": "npm run check && npm run build && publint && npm run typecheck && npm run typecheck:tests && npm test",
+    "prepublishOnly": "npm run ci",
     "publish:dry": "npm publish --dry-run --access public",
     "publish:npm": "npm publish --access public",
     "release:tag": "node -e \"require('child_process').execSync('npm run push -- v'+require('./package.json').version,{stdio:'inherit'})\"",
@@ -168,7 +170,7 @@
     "mongoose": "^9.4.1",
     "publint": "^0.3.18",
     "tsdown": "^0.22.5",
-    "typescript": "^7.0.2",
+    "typescript": "~5.9.0",
     "vitest": "^4.1.4"
   },
   "overrides": {