@atscript/db 0.1.38 → 0.1.40

package/dist/{nested-writer-NEN51mnR.mjs → nested-writer-Dmm1gbZV.mjs}

@@ -1,32 +1,31 @@
-import { resolveRelationTargetTable } from "./relation-helpers-DyBIlQnB.mjs";
+import { r as resolveRelationTargetTable } from "./relation-helpers-CLasawQq.mjs";
 import { ValidatorError } from "@atscript/typescript/utils";
-
-//#region packages/db/src/db-error.ts
-function _define_property(obj, key, value) {
-	if (key in obj) Object.defineProperty(obj, key, {
-		value,
-		enumerable: true,
-		configurable: true,
-		writable: true
-	});
-else obj[key] = value;
-	return obj;
-}
+//#region src/db-error.ts
 var DbError = class extends Error {
+	name = "DbError";
 	constructor(code, errors, message) {
-		super(message ?? errors[0]?.message ?? "Database error"), _define_property(this, "code", void 0), _define_property(this, "errors", void 0), _define_property(this, "name", void 0), this.code = code, this.errors = errors, this.name = "DbError";
-		this.stack = undefined;
+		super(message ?? errors[0]?.message ?? "Database error");
+		this.code = code;
+		this.errors = errors;
+		this.stack = void 0;
 	}
 };
-
 //#endregion
-//#region packages/db/src/table/error-utils.ts
+//#region src/table/error-utils.ts
+/**
+* Prefixes error paths with a nav field context.
+* Ensures errors from child table operations (e.g., FK violations on a comment)
+* get paths like `comments[0].authorId` instead of just `authorId`.
+*/
 function prefixErrorPaths(errors, prefix) {
 	return errors.map((err) => ({
 		...err,
 		path: err.path ? `${prefix}.${err.path}` : prefix
 	}));
 }
+/**
+* Wraps an async nested operation and prefixes error paths with the nav field context.
+*/
 async function wrapNestedError(navField, fn) {
 	try {
 		return await fn();
@@ -36,6 +35,11 @@ async function wrapNestedError(navField, fn) {
 		throw error;
 	}
 }
+/**
+* Catches `DbError('FK_VIOLATION')` with empty paths (from adapters that
+* enforce FKs natively but can't report which field failed) and enriches
+* the error with all FK field names from table metadata.
+*/
 async function enrichFkViolation(meta, fn) {
 	try {
 		return await fn();
@@ -52,6 +56,10 @@ async function enrichFkViolation(meta, fn) {
 		throw error;
 	}
 }
+/**
+* Wraps a delete operation: catches native `FK_VIOLATION` errors (e.g. SQLite
+* RESTRICT) and re-throws as `CONFLICT` (409) with a descriptive message.
+*/
 async function remapDeleteFkViolation(tableName, fn) {
 	try {
 		return await fn();
@@ -63,13 +71,20 @@ async function remapDeleteFkViolation(tableName, fn) {
 		throw error;
 	}
 }
-
 //#endregion
-//#region packages/db/src/rel/nested-writer.ts
+//#region src/rel/nested-writer.ts
+/**
+* Checks if any payload contains navigational data that would be silently
+* dropped because maxDepth is 0.
+*/
 function checkDepthOverflow(payloads, maxDepth, meta) {
 	if (meta.navFields.size === 0) return;
-	for (const payload of payloads) for (const navField of meta.navFields) if (payload[navField] !== undefined) throw new Error(`Nested data in '${navField}' exceeds maxDepth (${maxDepth}). ` + `Increase maxDepth or strip nested data before writing.`);
+	for (const payload of payloads) for (const navField of meta.navFields) if (payload[navField] !== void 0) throw new Error(`Nested data in '${navField}' exceeds maxDepth (${maxDepth}). Increase maxDepth or strip nested data before writing.`);
 }
+/**
+* Validates a batch of items using the given validator and context.
+* Wraps per-item validation errors with array index paths for batch operations.
+*/
 function validateBatch(validator, items, ctx) {
 	for (let i = 0; i < items.length; i++) try {
 		validator.validate(items[i], false, ctx);
@@ -81,6 +96,10 @@ function validateBatch(validator, items, ctx) {
 		throw error;
 	}
 }
+/**
+* Pre-validates FROM children (type + FK constraints) before the main insert.
+* Catches errors early before the parent record is committed.
+*/
 async function preValidateNestedFrom(host, originals) {
 	for (const [navField, relation] of host._meta.relations) {
 		if (relation.direction !== "from") continue;
@@ -104,6 +123,9 @@ async function preValidateNestedFrom(host, originals) {
 		await wrapNestedError(navField, () => targetTable.preValidateItems(allChildren, { excludeFkTargetTable: host.tableName }));
 	}
 }
+/**
+* Batch-creates TO dependencies before the main insert.
+*/
 async function batchInsertNestedTo(host, items, maxDepth, depth) {
 	for (const [navField, relation] of host._meta.relations) {
 		if (relation.direction !== "to") continue;
@@ -128,6 +150,9 @@ async function batchInsertNestedTo(host, items, maxDepth, depth) {
 		for (let j = 0; j < sourceIndices.length; j++) if (fk.localFields.length === 1) items[sourceIndices[j]][fk.localFields[0]] = result.insertedIds[j];
 	}
 }
+/**
+* Batch-creates FROM dependents after the main insert.
+*/
 async function batchInsertNestedFrom(host, originals, parentIds, maxDepth, depth) {
 	for (const [navField, relation] of host._meta.relations) {
 		if (relation.direction !== "from") continue;
@@ -152,6 +177,9 @@ async function batchInsertNestedFrom(host, originals, parentIds, maxDepth, depth
 		}));
 	}
 }
+/**
+* Batch-creates VIA (M:N) targets and junction entries after the main insert.
+*/
 async function batchInsertNestedVia(host, originals, parentIds, maxDepth, depth) {
 	for (const [navField, relation] of host._meta.relations) {
 		if (relation.direction !== "via" || !relation.viaType) continue;
@@ -170,14 +198,14 @@ async function batchInsertNestedVia(host, originals, parentIds, maxDepth, depth)
 			const targets = originals[i][navField];
 			if (!Array.isArray(targets) || targets.length === 0) continue;
 			const parentPK = parentIds[i];
-			if (parentPK === undefined) continue;
+			if (parentPK === void 0) continue;
 			const newTargets = [];
 			const existingIds = [];
 			for (const t of targets) {
 				const rec = t;
 				const pk = rec[targetPKField];
-				if (pk !== undefined && pk !== null) existingIds.push(pk);
-else newTargets.push({ ...rec });
+				if (pk !== void 0 && pk !== null) existingIds.push(pk);
+				else newTargets.push({ ...rec });
 			}
 			const allTargetIds = [...existingIds];
 			if (newTargets.length > 0) {
@@ -197,6 +225,9 @@ else newTargets.push({ ...rec });
 		}
 	}
 }
+/**
+* Batch-replaces TO dependencies before the main replace.
+*/
 async function batchReplaceNestedTo(host, items, maxDepth, depth) {
 	for (const [navField, relation] of host._meta.relations) {
 		if (relation.direction !== "to") continue;
@@ -221,6 +252,9 @@ async function batchReplaceNestedTo(host, items, maxDepth, depth) {
 		for (let j = 0; j < sourceIndices.length; j++) if (fk.localFields.length === 1 && fk.targetFields.length === 1) items[sourceIndices[j]][fk.localFields[0]] = parents[j][fk.targetFields[0]];
 	}
 }
+/**
+* Batch-replaces FROM dependents after the main replace.
+*/
 async function batchReplaceNestedFrom(host, originals, maxDepth, depth) {
 	for (const [navField, relation] of host._meta.relations) {
 		if (relation.direction !== "from") continue;
@@ -232,12 +266,15 @@ async function batchReplaceNestedFrom(host, originals, maxDepth, depth) {
 		for (const original of originals) {
 			const children = original[navField];
 			if (!Array.isArray(children)) continue;
-			const parentPK = host._meta.primaryKeys.length === 1 ? original[host._meta.primaryKeys[0]] : undefined;
-			if (parentPK === undefined || remoteFK.fields.length !== 1) continue;
+			const parentPK = host._meta.primaryKeys.length === 1 ? original[host._meta.primaryKeys[0]] : void 0;
+			if (parentPK === void 0 || remoteFK.fields.length !== 1) continue;
 			await fromReplace(targetTable, children, parentPK, remoteFK.fields[0], childPKs, navField, maxDepth, depth);
 		}
 	}
 }
+/**
+* Handles VIA (M:N) relations during replace.
+*/
 async function batchReplaceNestedVia(host, originals, maxDepth, depth) {
 	for (const [navField, relation] of host._meta.relations) {
 		if (relation.direction !== "via" || !relation.viaType) continue;
@@ -255,12 +292,16 @@ async function batchReplaceNestedVia(host, originals, maxDepth, depth) {
 		for (const original of originals) {
 			const targets = original[navField];
 			if (!Array.isArray(targets)) continue;
-			const parentPK = host._meta.primaryKeys.length === 1 ? original[host._meta.primaryKeys[0]] : undefined;
-			if (parentPK === undefined) continue;
+			const parentPK = host._meta.primaryKeys.length === 1 ? original[host._meta.primaryKeys[0]] : void 0;
+			if (parentPK === void 0) continue;
 			await viaReplace(targetTable, junctionTable, targets, parentPK, targetPKField, fkToThis.fields[0], fkToTarget.fields[0], maxDepth, depth);
 		}
 	}
 }
+/**
+* Batch-patches TO dependencies before the main patch.
+* Reads FK values from DB if not present in the payload.
+*/
 async function batchPatchNestedTo(host, items, maxDepth, depth) {
 	for (const [navField, relation] of host._meta.relations) {
 		if (relation.direction !== "to") continue;
@@ -273,8 +314,8 @@ async function batchPatchNestedTo(host, items, maxDepth, depth) {
 			const nested = item[navField];
 			if (!nested || typeof nested !== "object" || Array.isArray(nested)) continue;
 			const patch = { ...nested };
-			let fkValue = fk.localFields.length === 1 ? item[fk.localFields[0]] : undefined;
-			if (fkValue === undefined) {
+			let fkValue = fk.localFields.length === 1 ? item[fk.localFields[0]] : void 0;
+			if (fkValue === void 0) {
 				const pkFilter = host._extractPrimaryKeyFilter(item);
 				const current = await host.findOne({
 					filter: pkFilter,
@@ -284,9 +325,9 @@ async function batchPatchNestedTo(host, items, maxDepth, depth) {
 					path: navField,
 					message: `Cannot patch relation '${navField}' — source record not found`
 				}]);
-				fkValue = fk.localFields.length === 1 ? current[fk.localFields[0]] : undefined;
+				fkValue = fk.localFields.length === 1 ? current[fk.localFields[0]] : void 0;
 			}
-			if (fkValue === null || fkValue === undefined) throw new DbError("FK_VIOLATION", [{
+			if (fkValue === null || fkValue === void 0) throw new DbError("FK_VIOLATION", [{
 				path: fk.localFields[0],
 				message: `Cannot patch relation '${navField}' — foreign key '${fk.localFields[0]}' is null`
 			}]);
@@ -300,6 +341,10 @@ async function batchPatchNestedTo(host, items, maxDepth, depth) {
 		});
 	}
 }
+/**
+* Batch-patches FROM (1:N) dependencies after the main patch.
+* Supports patch operators: $replace, $insert, $remove, $update, $upsert.
+*/
 async function batchPatchNestedFrom(host, originals, maxDepth, depth) {
 	for (const [navField, relation] of host._meta.relations) {
 		if (relation.direction !== "from") continue;
@@ -310,9 +355,9 @@ async function batchPatchNestedFrom(host, originals, maxDepth, depth) {
 		const childPKs = [...targetTable.primaryKeys];
 		for (const original of originals) {
 			const navValue = original[navField];
-			if (navValue === undefined || navValue === null) continue;
-			const parentPK = host._meta.primaryKeys.length === 1 ? original[host._meta.primaryKeys[0]] : undefined;
-			if (parentPK === undefined || remoteFK.fields.length !== 1) continue;
+			if (navValue === void 0 || navValue === null) continue;
+			const parentPK = host._meta.primaryKeys.length === 1 ? original[host._meta.primaryKeys[0]] : void 0;
+			if (parentPK === void 0 || remoteFK.fields.length !== 1) continue;
 			const fkField = remoteFK.fields[0];
 			const ops = extractNavPatchOps(navValue);
 			if (ops.replace) await fromReplace(targetTable, ops.replace, parentPK, fkField, childPKs, navField, maxDepth, depth);
@@ -325,7 +370,7 @@ async function batchPatchNestedFrom(host, originals, maxDepth, depth) {
 					return f;
 				});
 				if (removeFilters.length === 1) await targetTable.deleteMany(removeFilters[0]);
-else await targetTable.deleteMany({ $or: removeFilters });
+				else await targetTable.deleteMany({ $or: removeFilters });
 			}
 			if (ops.update && ops.update.length > 0) {
 				const items = ops.update.map((child) => {
@@ -344,9 +389,8 @@ else await targetTable.deleteMany({ $or: removeFilters });
 				for (const child of ops.upsert) {
 					const rec = { ...child };
 					rec[fkField] = parentPK;
-					const hasPK = childPKs.length > 0 && childPKs.every((pk) => rec[pk] !== undefined);
-					if (hasPK) toUpdate.push(rec);
-else toInsert.push(rec);
+					if (childPKs.length > 0 && childPKs.every((pk) => rec[pk] !== void 0)) toUpdate.push(rec);
+					else toInsert.push(rec);
 				}
 				if (toUpdate.length > 0) await wrapNestedError(navField, () => targetTable.bulkUpdate(toUpdate, {
 					maxDepth,
@@ -358,11 +402,12 @@ else toInsert.push(rec);
 				}));
 			}
 			if (ops.insert && ops.insert.length > 0) {
-				const items = ops.insert.map((child) => {
-					const rec = { ...child };
+				const items = [];
+				for (let i = 0; i < ops.insert.length; i++) {
+					const rec = { ...ops.insert[i] };
 					rec[fkField] = parentPK;
-					return rec;
-				});
+					items.push(rec);
+				}
 				await wrapNestedError(navField, () => targetTable.insertMany(items, {
 					maxDepth,
 					_depth: depth + 1
@@ -371,6 +416,10 @@ else toInsert.push(rec);
 		}
 	}
 }
+/**
+* Batch-patches VIA (M:N) dependencies after the main patch.
+* Supports patch operators: $replace, $insert, $remove, $update, $upsert.
+*/
 async function batchPatchNestedVia(host, originals, maxDepth, depth) {
 	for (const [navField, relation] of host._meta.relations) {
 		if (relation.direction !== "via" || !relation.viaType) continue;
@@ -387,18 +436,18 @@ async function batchPatchNestedVia(host, originals, maxDepth, depth) {
 		if (!targetPKField || fkToTarget.fields.length !== 1 || fkToThis.fields.length !== 1) continue;
 		for (const original of originals) {
 			const navValue = original[navField];
-			if (navValue === undefined || navValue === null) continue;
-			const parentPK = host._meta.primaryKeys.length === 1 ? original[host._meta.primaryKeys[0]] : undefined;
-			if (parentPK === undefined) continue;
+			if (navValue === void 0 || navValue === null) continue;
+			const parentPK = host._meta.primaryKeys.length === 1 ? original[host._meta.primaryKeys[0]] : void 0;
+			if (parentPK === void 0) continue;
 			const ops = extractNavPatchOps(navValue);
 			if (ops.replace) await viaReplace(targetTable, junctionTable, ops.replace, parentPK, targetPKField, fkToThis.fields[0], fkToTarget.fields[0], maxDepth, depth);
 			if (ops.remove && ops.remove.length > 0) {
-				const targetPKs = ops.remove.map((t) => t[targetPKField]).filter((pk) => pk !== undefined && pk !== null);
+				const targetPKs = ops.remove.map((t) => t[targetPKField]).filter((pk) => pk !== void 0 && pk !== null);
 				if (targetPKs.length === 1) await junctionTable.deleteMany({
 					[fkToThis.fields[0]]: parentPK,
 					[fkToTarget.fields[0]]: targetPKs[0]
 				});
-else if (targetPKs.length > 1) await junctionTable.deleteMany({
+				else if (targetPKs.length > 1) await junctionTable.deleteMany({
 					[fkToThis.fields[0]]: parentPK,
 					[fkToTarget.fields[0]]: { $in: targetPKs }
 				});
@@ -414,7 +463,7 @@ else if (targetPKs.length > 1) await junctionTable.deleteMany({
 				for (const target of ops.upsert) {
 					const rec = { ...target };
 					const pk = rec[targetPKField];
-					if (pk !== undefined && pk !== null) {
+					if (pk !== void 0 && pk !== null) {
 						toUpdate.push(rec);
 						existingPKs.push(pk);
 					} else toInsert.push(rec);
@@ -442,11 +491,10 @@ else if (targetPKs.length > 1) await junctionTable.deleteMany({
 					}
 				}
 				if (toInsert.length > 0) {
-					const insertResult = await targetTable.insertMany(toInsert, {
+					const junctionRows = (await targetTable.insertMany(toInsert, {
 						maxDepth,
 						_depth: depth + 1
-					});
-					const junctionRows = insertResult.insertedIds.map((newId) => ({
+					})).insertedIds.map((newId) => ({
 						[fkToThis.fields[0]]: parentPK,
 						[fkToTarget.fields[0]]: newId
 					}));
@@ -459,8 +507,8 @@ else if (targetPKs.length > 1) await junctionTable.deleteMany({
 				for (const target of ops.insert) {
 					const rec = { ...target };
 					const pk = rec[targetPKField];
-					if (pk !== undefined && pk !== null) existingIds.push(pk);
-else toInsert.push(rec);
+					if (pk !== void 0 && pk !== null) existingIds.push(pk);
+					else toInsert.push(rec);
 				}
 				const allIds = [...existingIds];
 				if (toInsert.length > 0) {
@@ -484,29 +532,30 @@ else toInsert.push(rec);
 /**
 * Extracts patch operations from a nav field value.
 * Plain array → $replace. Object with $insert, $remove, etc. → individual ops.
-*/ function extractNavPatchOps(navValue) {
+*/
+function extractNavPatchOps(navValue) {
 	if (Array.isArray(navValue)) return { replace: navValue };
 	if (typeof navValue !== "object" || navValue === null) return {};
 	const obj = navValue;
 	return {
-		replace: obj.$replace !== undefined ? obj.$replace : undefined,
-		insert: obj.$insert !== undefined ? obj.$insert : undefined,
-		remove: obj.$remove !== undefined ? obj.$remove : undefined,
-		update: obj.$update !== undefined ? obj.$update : undefined,
-		upsert: obj.$upsert !== undefined ? obj.$upsert : undefined
+		replace: obj.$replace !== void 0 ? obj.$replace : void 0,
+		insert: obj.$insert !== void 0 ? obj.$insert : void 0,
+		remove: obj.$remove !== void 0 ? obj.$remove : void 0,
+		update: obj.$update !== void 0 ? obj.$update : void 0,
+		upsert: obj.$upsert !== void 0 ? obj.$upsert : void 0
 	};
 }
 /**
 * FROM $replace helper: delete orphans, replace existing, insert new.
-*/ async function fromReplace(targetTable, children, parentPK, fkField, childPKs, navField, maxDepth, depth) {
+*/
+async function fromReplace(targetTable, children, parentPK, fkField, childPKs, navField, maxDepth, depth) {
 	const toReplace = [];
 	const toInsert = [];
-	const newPKSet = new Set();
+	const newPKSet = /* @__PURE__ */ new Set();
 	for (const child of children) {
 		const childData = { ...child };
 		childData[fkField] = parentPK;
-		const hasPK = childPKs.length > 0 && childPKs.every((pk) => childData[pk] !== undefined);
-		if (hasPK) {
+		if (childPKs.length > 0 && childPKs.every((pk) => childData[pk] !== void 0)) {
 			newPKSet.add(childPKs.map((pk) => String(childData[pk])).join("\0"));
 			toReplace.push(childData);
 		} else toInsert.push(childData);
@@ -525,7 +574,7 @@ else toInsert.push(rec);
 		}
 	}
 	if (orphanFilters.length === 1) await targetTable.deleteMany(orphanFilters[0]);
-else if (orphanFilters.length > 1) await targetTable.deleteMany({ $or: orphanFilters });
+	else if (orphanFilters.length > 1) await targetTable.deleteMany({ $or: orphanFilters });
 	if (toReplace.length > 0) await wrapNestedError(navField, () => targetTable.bulkReplace(toReplace, {
 		maxDepth,
 		_depth: depth + 1
@@ -537,7 +586,8 @@ else if (orphanFilters.length > 1) await targetTable.deleteMany({ $or: orphanFil
 }
 /**
 * VIA $replace helper: clear junctions, replace/insert targets, rebuild junctions.
-*/ async function viaReplace(targetTable, junctionTable, targets, parentPK, targetPKField, fkToThisField, fkToTargetField, maxDepth, depth) {
+*/
+async function viaReplace(targetTable, junctionTable, targets, parentPK, targetPKField, fkToThisField, fkToTargetField, maxDepth, depth) {
 	await junctionTable.deleteMany({ [fkToThisField]: parentPK });
 	const toReplace = [];
 	const toInsert = [];
@@ -545,9 +595,8 @@ else if (orphanFilters.length > 1) await targetTable.deleteMany({ $or: orphanFil
 	for (const t of targets) {
 		const rec = t;
 		const pk = rec[targetPKField];
-		if (pk !== undefined && pk !== null) {
-			const keys = Object.keys(rec).filter((k) => k !== targetPKField);
-			if (keys.length > 0) toReplace.push({ ...rec });
+		if (pk !== void 0 && pk !== null) {
+			if (Object.keys(rec).filter((k) => k !== targetPKField).length > 0) toReplace.push({ ...rec });
 			existingIds.push(pk);
 		} else toInsert.push({ ...rec });
 	}
@@ -571,6 +620,5 @@ else if (orphanFilters.length > 1) await targetTable.deleteMany({ $or: orphanFil
 		await junctionTable.insertMany(junctionRows, { maxDepth: 0 });
 	}
 }
-
 //#endregion
-export { DbError, batchInsertNestedFrom, batchInsertNestedTo, batchInsertNestedVia, batchPatchNestedFrom, batchPatchNestedTo, batchPatchNestedVia, batchReplaceNestedFrom, batchReplaceNestedTo, batchReplaceNestedVia, checkDepthOverflow, enrichFkViolation, preValidateNestedFrom, remapDeleteFkViolation, validateBatch };
+export { batchPatchNestedTo as a, batchReplaceNestedTo as c, preValidateNestedFrom as d, validateBatch as f, DbError as h, batchPatchNestedFrom as i, batchReplaceNestedVia as l, remapDeleteFkViolation as m, batchInsertNestedTo as n, batchPatchNestedVia as o, enrichFkViolation as p, batchInsertNestedVia as r, batchReplaceNestedFrom as s, batchInsertNestedFrom as t, checkDepthOverflow as u };

package/dist/ops-BdRAFLKY.d.mts

@@ -0,0 +1,67 @@
+//#region src/ops.d.ts
+/** A numeric field operation (increment, decrement, or multiply). */
+interface TDbFieldOp {
+  $inc?: number;
+  $dec?: number;
+  $mul?: number;
+}
+/** Increment a numeric field by `value` (default 1). */
+declare function $inc(value?: number): TDbFieldOp;
+/** Decrement a numeric field by `value` (default 1). */
+declare function $dec(value?: number): TDbFieldOp;
+/** Multiply a numeric field by `value`. */
+declare function $mul(value: number): TDbFieldOp;
+/** Replace the entire array. */
+declare function $replace<T>(items: T[]): {
+  $replace: T[];
+};
+/** Append items to an array. */
+declare function $insert<T>(items: T[]): {
+  $insert: T[];
+};
+/** Insert-or-update items by key. */
+declare function $upsert<T>(items: T[]): {
+  $upsert: T[];
+};
+/** Update existing items matched by key. */
+declare function $update<T>(items: Partial<T>[]): {
+  $update: Partial<T>[];
+};
+/** Remove items matched by key or value. */
+declare function $remove<T>(items: Partial<T>[]): {
+  $remove: Partial<T>[];
+};
+/** Pre-separated field operations, ready for adapters. */
+interface TFieldOps {
+  inc?: Record<string, number>;
+  mul?: Record<string, number>;
+}
+/**
+ * Returns `true` when `value` is a field operation object
+ * (`{ $inc: N }`, `{ $dec: N }`, or `{ $mul: N }`).
+ */
+declare function isDbFieldOp(value: unknown): value is TDbFieldOp;
+/**
+ * Extracts the normalized operation from a field op value.
+ * Returns `undefined` when `value` is not a field op.
+ *
+ * `$dec` is normalized to `{ op: 'inc', value: -N }` so consumers
+ * only need to handle `inc` and `mul`.
+ */
+declare function getDbFieldOp(value: unknown): {
+  op: "inc" | "mul";
+  value: number;
+} | undefined;
+/**
+ * Separates field operations from a data payload.
+ *
+ * Mutates `data` in-place (removes op entries) and returns the separated ops.
+ * When no ops are found, returns `undefined` — zero allocation for the
+ * common non-op case.
+ *
+ * Hot path: uses `for...in` (no array allocation), inlines detection to
+ * avoid intermediate `{ op, value }` objects, and short-circuits on typeof.
+ */
+declare function separateFieldOps(data: Record<string, unknown>): TFieldOps | undefined;
+//#endregion
+export { $remove as a, $upsert as c, getDbFieldOp as d, isDbFieldOp as f, $mul as i, TDbFieldOp as l, $inc as n, $replace as o, separateFieldOps as p, $insert as r, $update as s, $dec as t, TFieldOps as u };

package/dist/ops-DXJ4Zw0P.d.cts

@@ -0,0 +1,67 @@
+//#region src/ops.d.ts
+/** A numeric field operation (increment, decrement, or multiply). */
+interface TDbFieldOp {
+  $inc?: number;
+  $dec?: number;
+  $mul?: number;
+}
+/** Increment a numeric field by `value` (default 1). */
+declare function $inc(value?: number): TDbFieldOp;
+/** Decrement a numeric field by `value` (default 1). */
+declare function $dec(value?: number): TDbFieldOp;
+/** Multiply a numeric field by `value`. */
+declare function $mul(value: number): TDbFieldOp;
+/** Replace the entire array. */
+declare function $replace<T>(items: T[]): {
+  $replace: T[];
+};
+/** Append items to an array. */
+declare function $insert<T>(items: T[]): {
+  $insert: T[];
+};
+/** Insert-or-update items by key. */
+declare function $upsert<T>(items: T[]): {
+  $upsert: T[];
+};
+/** Update existing items matched by key. */
+declare function $update<T>(items: Partial<T>[]): {
+  $update: Partial<T>[];
+};
+/** Remove items matched by key or value. */
+declare function $remove<T>(items: Partial<T>[]): {
+  $remove: Partial<T>[];
+};
+/** Pre-separated field operations, ready for adapters. */
+interface TFieldOps {
+  inc?: Record<string, number>;
+  mul?: Record<string, number>;
+}
+/**
+ * Returns `true` when `value` is a field operation object
+ * (`{ $inc: N }`, `{ $dec: N }`, or `{ $mul: N }`).
+ */
+declare function isDbFieldOp(value: unknown): value is TDbFieldOp;
+/**
+ * Extracts the normalized operation from a field op value.
+ * Returns `undefined` when `value` is not a field op.
+ *
+ * `$dec` is normalized to `{ op: 'inc', value: -N }` so consumers
+ * only need to handle `inc` and `mul`.
+ */
+declare function getDbFieldOp(value: unknown): {
+  op: "inc" | "mul";
+  value: number;
+} | undefined;
+/**
+ * Separates field operations from a data payload.
+ *
+ * Mutates `data` in-place (removes op entries) and returns the separated ops.
+ * When no ops are found, returns `undefined` — zero allocation for the
+ * common non-op case.
+ *
+ * Hot path: uses `for...in` (no array allocation), inlines detection to
+ * avoid intermediate `{ op, value }` objects, and short-circuits on typeof.
+ */
+declare function separateFieldOps(data: Record<string, unknown>): TFieldOps | undefined;
+//#endregion
+export { $remove as a, $upsert as c, getDbFieldOp as d, isDbFieldOp as f, $mul as i, TDbFieldOp as l, $inc as n, $replace as o, separateFieldOps as p, $insert as r, $update as s, $dec as t, TFieldOps as u };