@warlock.js/cascade 5.27.0 → 5.28.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to `@warlock.js/cascade` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.28.0 - 2026-10-01
+
+### Fixed
+
+- Replacing a nested object on MongoDB (`model.set("nested", obj).save()`) now writes the whole new object with one `$set`, instead of diffing per leaf. Removing keys no longer leaves their parents behind as empty `{}` objects in the stored document. Dotted-path sets (`set("nested.a", v)`) and `merge()` stay partial per-leaf updates, so concurrent writes to other keys still survive. SQL drivers already replace the whole JSON column and are unchanged.
+- `unset("nested.x")` now removes the parents it empties (`unset("a.b.c")` on `{ a: { b: { c: 1 } } }` stores no `a`), and the update `$unset`s that parent rather than leaving `{}`. A parent is pruned only when that unset emptied it: an object stored or set as `{}` is left alone, and arrays are never pruned. `unset("nested")` removes the whole object.
+
 ## 5.27.0 - 2026-10-01
 
 ### Changed

package/cjs/index.cjs

@@ -760,6 +760,40 @@ var UnsupportedUpdateOperationError = class UnsupportedUpdateOperationError exte
 	}
 };
 
+//#endregion
+//#region ../cascade/src/utils/prune-empty-parents.ts
+/**
+* Remove the ancestors of `path` that became empty plain objects, walking from
+* the leaf's parent up to (and including) the top-level field.
+*
+* Call it right AFTER removing the leaf at `path`, and only when that leaf
+* actually existed. Gating on "the leaf existed" is what keeps an object the
+* user deliberately stored as `{}` untouched: unsetting a key that is not there
+* removes nothing, so nothing becomes empty because of the unset and nothing is
+* pruned. An ancestor is only ever pruned because THIS unset emptied it.
+*
+* Only plain objects are pruned, and only while their own container is a plain
+* object (or the root): arrays are never pruned and stop the walk, because
+* deleting an index would shift its siblings.
+*
+* @param root - The data object the path is relative to (mutated in place)
+* @param path - Dot-notation path of the leaf that was just removed
+*/
+function pruneEmptyParents(root, path) {
+	const segments = path.split(".");
+	for (let depth = segments.length - 1; depth >= 1; depth -= 1) {
+		let container = root;
+		for (let index = 0; index < depth - 1; index += 1) {
+			container = container?.[segments[index]];
+			if (!(0, _mongez_supportive_is.isPlainObject)(container)) return;
+		}
+		const key = segments[depth - 1];
+		const candidate = container[key];
+		if (!(0, _mongez_supportive_is.isPlainObject)(candidate) || Object.keys(candidate).length > 0) return;
+		delete container[key];
+	}
+}
+
 //#endregion
 //#region ../cascade/src/database-dirty-tracker.ts
 function canBeFlatten(object) {
@@ -824,6 +858,13 @@ var DatabaseDirtyTracker = class {
 	* Set of column names (dot-notation paths) that existed initially but have been removed.
 	*/
 	removedColumns = /* @__PURE__ */ new Set();
+	/**
+	* Top-level fields that were assigned or unset as a whole (`set("nested", obj)`,
+	* `unset("nested")`) since the last reset. Dotted-path writes
+	* (`set("nested.a", v)`) and `mergeChanges` are partial by intent and never
+	* land here. See {@link getReplacedColumns}.
+	*/
+	replacedRoots = /* @__PURE__ */ new Set();
 	constructor(data) {
 		this.initialRaw = this.cloneData(data);
 		this.currentRaw = this.cloneData(data);
@@ -848,6 +889,64 @@ var DatabaseDirtyTracker = class {
 		return Array.from(this.dirtyColumns);
 	}
 	/**
+	* Removed columns collapsed to the highest path that no longer exists.
+	*
+	* `getRemovedColumns()` reports leaves (`"a.b.c"`). Unsetting just that leaf
+	* would keep `a` and `a.b` in the stored document as empty objects whenever
+	* the unset emptied them (and `unset()` prunes those parents). This returns
+	* the path to actually `$unset`: the shortest prefix that is gone from the
+	* current data, which is the leaf itself when its parents still hold other
+	* keys.
+	*
+	* @returns Distinct paths to remove
+	*/
+	getRemovedPaths() {
+		const paths = /* @__PURE__ */ new Set();
+		for (const column of this.removedColumns) {
+			const segments = column.split(".");
+			let container = this.currentRaw;
+			let path = column;
+			for (let index = 0; index < segments.length; index += 1) {
+				const segment = segments[index];
+				if (container === null || typeof container !== "object" || !(segment in container)) {
+					path = segments.slice(0, index + 1).join(".");
+					break;
+				}
+				container = container[segment];
+			}
+			paths.add(path);
+		}
+		return Array.from(paths);
+	}
+	/**
+	* Top-level fields whose nested object must be written as a WHOLE value.
+	*
+	* Per-leaf diffing cannot express "this object is now exactly this": it only
+	* reports the leaves that changed or vanished, so a key removed from a nested
+	* object leaves its (now empty) parents behind in the stored document. A field
+	* that was assigned or unset as a whole therefore reports here, and the writer
+	* sends one `$set` (or `$unset`) for it instead of per-leaf operations.
+	*
+	* A field is reported only when it was replaced via `set("field", value)` /
+	* `unset("field")`, either its old or new value is a plain object, and the
+	* value actually differs from the baseline. Dotted-path writes
+	* (`set("field.a", v)`) and `mergeChanges` stay per-leaf, so partial updates
+	* keep working. Scalars and arrays are already whole-value leaves in the diff.
+	*
+	* @returns Top-level column names to write as a whole
+	*/
+	getReplacedColumns() {
+		const columns = [];
+		for (const root of this.replacedRoots) {
+			const initial = this.initialRaw[root];
+			const current = this.currentRaw[root];
+			if (!(0, _mongez_supportive_is.isPlainObject)(initial) && !(0, _mongez_supportive_is.isPlainObject)(current)) continue;
+			if ((0, _mongez_reinforcements.areEqual)(initial, current)) continue;
+			columns.push(root);
+		}
+		return columns;
+	}
+	/**
 	* Determines whether there are any tracked changes.
 	*
 	* Returns `true` if any columns have been modified or removed since the initial snapshot.
@@ -966,6 +1065,7 @@ var DatabaseDirtyTracker = class {
 	setAtPath(path, value) {
 		const segments = path.split(".");
 		let container = this.currentRaw;
+		if (segments.length === 1) this.replacedRoots.add(path);
 		for (let index = 0; index < segments.length - 1; index += 1) {
 			const segment = segments[index];
 			if (!(0, _mongez_supportive_is.isPlainObject)(container[segment]) && !Array.isArray(container[segment])) container[segment] = {};
@@ -992,7 +1092,10 @@ var DatabaseDirtyTracker = class {
 	*/
 	unset(columns) {
 		const targets = Array.isArray(columns) ? columns : [columns];
-		for (const path of targets) this.deleteFromRaw(path);
+		for (const path of targets) {
+			if (!path.includes(".")) this.replacedRoots.add(path);
+			this.deleteFromRaw(path);
+		}
 		this.currentFlattened = this.flattenData(this.currentRaw);
 		this.updateDirtyState();
 	}
@@ -1024,6 +1127,7 @@ var DatabaseDirtyTracker = class {
 		this.currentFlattened = this.flattenData(this.currentRaw);
 		this.dirtyColumns.clear();
 		this.removedColumns.clear();
+		this.replacedRoots.clear();
 	}
 	/**
 	* Flattens the given data object.
@@ -1107,7 +1211,11 @@ var DatabaseDirtyTracker = class {
 			if (!Number.isNaN(numericIndex)) container.splice(numericIndex, 1);
 			return;
 		}
-		if (typeof container === "object") delete container[lastSegment];
+		if (typeof container === "object") {
+			const existed = lastSegment in container;
+			delete container[lastSegment];
+			if (existed) pruneEmptyParents(this.currentRaw, path);
+		}
 	}
 	/**
 	* Resolves a single segment of a dot-notation path within a container.
@@ -3460,8 +3568,18 @@ function incrementField(model, field, amount) {
 function decrementField(model, field, amount) {
 	return setFieldValue(model, field, getFieldValue(model, field, 0) - (amount ?? 1));
 }
+/**
+* Remove fields from the model data.
+*
+* Unsetting the last key of a nested object also removes the parents that this
+* unset left empty (`unset("a.b")` on `{ a: { b: 1 } }` leaves `{}`, not
+* `{ a: {} }`). A parent is pruned only when this unset emptied it: an object
+* the user stored as `{}` is never touched, and arrays are never pruned.
+*/
 function unsetFields(model, ...fields) {
+	const existing = fields.filter((field) => hasField(model, field));
 	model.data = (0, _mongez_reinforcements.unset)(model.data, fields);
+	for (const field of existing) pruneEmptyParents(model.data, field);
 	model.dirtyTracker.unset(fields);
 	return model;
 }
@@ -4781,7 +4899,9 @@ var DatabaseWriter = class {
 			"id",
 			"_id"
 		]);
-		const dirtyColumns = this.model.getDirtyColumns().filter((column) => !identityColumns.has(column) && !this.unvalidatedColumns.has(column));
+		const replacedColumns = this.model.dirtyTracker.getReplacedColumns().filter((column) => !identityColumns.has(column) && !this.unvalidatedColumns.has(column));
+		const isUnderReplaced = (column) => replacedColumns.some((root) => column === root || column.startsWith(`${root}.`));
+		const dirtyColumns = this.model.getDirtyColumns().filter((column) => !identityColumns.has(column) && !this.unvalidatedColumns.has(column) && !isUnderReplaced(column));
 		if (dirtyColumns.length > 0) {
 			operations.$set = {};
 			for (const column of dirtyColumns) {
@@ -4789,11 +4909,21 @@ var DatabaseWriter = class {
 				operations.$set[column] = this.model.get(column);
 			}
 		}
-		const removedColumns = this.model.getRemovedColumns().filter((column) => !identityColumns.has(column));
+		const removedColumns = this.model.dirtyTracker.getRemovedPaths().filter((column) => !identityColumns.has(column) && !isUnderReplaced(column));
 		if (removedColumns.length > 0) {
 			operations.$unset = {};
 			for (const column of removedColumns) operations.$unset[column] = 1;
 		}
+		for (const column of replacedColumns) {
+			const value = this.model.get(column);
+			if (value === void 0) {
+				operations.$unset ??= {};
+				operations.$unset[column] = 1;
+				continue;
+			}
+			operations.$set ??= {};
+			operations.$set[column] = value;
+		}
 		return operations;
 	}
 	/**