@warlock.js/cascade 4.0.174 → 4.1.1

package/esm/database-dirty-tracker.d.mts

@@ -0,0 +1,254 @@
+//#region ../../@warlock.js/cascade/src/database-dirty-tracker.d.ts
+/**
+ * Flattened record type representing dot-notation paths mapped to their values.
+ */
+type FlatRecord = Record<string, unknown>;
+/**
+ * Represents the old and new values of a dirty column.
+ */
+type DirtyColumnValues = {
+  oldValue: unknown;
+  newValue: unknown;
+};
+/**
+ * Tracks changes to model data by maintaining snapshots of initial and current state.
+ *
+ * The tracker stores both raw (nested) and flattened (dot-notation) versions of the data
+ * to accurately detect modifications, additions, and removals at any nesting level.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new DatabaseDirtyTracker({ name: "Alice", age: 30 });
+ * tracker.mergeChanges({ age: 31 });
+ * console.log(tracker.hasChanges()); // true
+ * console.log(tracker.getDirtyColumns()); // ["age"]
+ * console.log(tracker.getDirtyColumnsWithValues());
+ * // { age: { oldValue: 30, newValue: 31 } }
+ * ```
+ */
+declare class DatabaseDirtyTracker {
+  /**
+   * The initial raw data snapshot taken at construction or last reset.
+   * Used as the baseline for comparison.
+   */
+  protected initialRaw: Record<string, unknown>;
+  /**
+   * The current raw data snapshot reflecting all changes made via merge/unset.
+   */
+  protected currentRaw: Record<string, unknown>;
+  /**
+   * Flattened version of the initial data using dot-notation keys.
+   * Example: { "address.city": "NYC" }
+   */
+  protected initialFlattened: FlatRecord;
+  /**
+   * Flattened version of the current data using dot-notation keys.
+   */
+  protected currentFlattened: FlatRecord;
+  /**
+   * Set of column names (dot-notation paths) that have been modified.
+   */
+  protected readonly dirtyColumns: Set<string>;
+  /**
+   * Set of column names (dot-notation paths) that existed initially but have been removed.
+   */
+  protected readonly removedColumns: Set<string>;
+  constructor(data: Record<string, unknown>);
+  /**
+   * Returns the list of dirty columns using dot-notation.
+   *
+   * A column is considered dirty if its value has changed compared to the initial snapshot.
+   *
+   * @returns An array of column names (dot-notation paths) that have been modified
+   *
+   * @example
+   * ```typescript
+   * tracker.mergeChanges({ name: "Bob", "address.city": "LA" });
+   * tracker.getDirtyColumns(); // ["name", "address.city"]
+   * ```
+   */
+  getDirtyColumns(): string[];
+  /**
+   * Determines whether there are any tracked changes.
+   *
+   * Returns `true` if any columns have been modified or removed since the initial snapshot.
+   *
+   * @returns `true` if there are changes, `false` otherwise
+   *
+   * @example
+   * ```typescript
+   * const tracker = new DatabaseDirtyTracker({ name: "Alice" });
+   * tracker.hasChanges(); // false
+   * tracker.mergeChanges({ name: "Bob" });
+   * tracker.hasChanges(); // true
+   * tracker.unset("name");
+   * tracker.hasChanges(); // true (removed column counts as a change)
+   * ```
+   */
+  hasChanges(): boolean;
+  /**
+   * Check if the given column is dirty (changed)
+   */
+  isDirty(column: string): boolean;
+  /**
+   * Returns the set of columns that have been removed compared to the baseline.
+   *
+   * A column is considered removed if it existed in the initial snapshot but has been
+   * explicitly unset or deleted from the current data.
+   *
+   * @returns An array of column names (dot-notation paths) that have been removed
+   *
+   * @example
+   * ```typescript
+   * const tracker = new DatabaseDirtyTracker({ name: "Alice", temp: "value" });
+   * tracker.unset("temp");
+   * tracker.getRemovedColumns(); // ["temp"]
+   * ```
+   */
+  getRemovedColumns(): string[];
+  /**
+   * Provides a mapping of dirty columns to their previous and current values.
+   *
+   * This is useful for generating audit logs, building partial update payloads,
+   * or displaying change summaries to users.
+   *
+   * @returns A record mapping each dirty column to an object containing oldValue and newValue
+   *
+   * @example
+   * ```typescript
+   * const tracker = new DatabaseDirtyTracker({ name: "Alice", age: 30 });
+   * tracker.mergeChanges({ age: 31 });
+   * tracker.getDirtyColumnsWithValues();
+   * // { age: { oldValue: 30, newValue: 31 } }
+   * ```
+   */
+  getDirtyColumnsWithValues(): Record<string, DirtyColumnValues>;
+  /**
+   * Replaces the current data snapshot entirely and recomputes the diff.
+   *
+   * This is useful when you want to replace all current data with a new set,
+   * while keeping the initial baseline for comparison.
+   *
+   * @param data - The new data to set as the current snapshot
+   *
+   * @example
+   * ```typescript
+   * const tracker = new DatabaseDirtyTracker({ name: "Alice" });
+   * tracker.replaceCurrentData({ name: "Bob", email: "bob@example.com" });
+   * tracker.getDirtyColumns(); // ["name", "email"]
+   * ```
+   */
+  replaceCurrentData(data: Record<string, unknown>): void;
+  /**
+   * Merges a partial payload into the current snapshot and recomputes the diff.
+   *
+   * This performs a deep merge, preserving existing nested structures while
+   * updating only the specified fields.
+   *
+   * @param partial - Partial data to merge into the current snapshot
+   *
+   * @example
+   * ```typescript
+   * const tracker = new DatabaseDirtyTracker({ name: "Alice", address: { city: "NYC" } });
+   * tracker.mergeChanges({ address: { zip: "10001" } });
+   * // Current data: { name: "Alice", address: { city: "NYC", zip: "10001" } }
+   * tracker.getDirtyColumns(); // ["address.zip"]
+   * ```
+   */
+  mergeChanges(partial: Record<string, unknown>): void;
+  /**
+   * Explicitly removes one or more columns from the current data.
+   *
+   * Supports both single column names and arrays of column names.
+   * Columns can be specified using dot-notation for nested paths.
+   *
+   * @param columns - A single column name or an array of column names to remove
+   *
+   * @example
+   * ```typescript
+   * tracker.unset("tempField");
+   * tracker.unset(["field1", "field2", "nested.field"]);
+   * tracker.getRemovedColumns(); // ["tempField", "field1", "field2", "nested.field"]
+   * ```
+   */
+  unset(columns: string | string[]): void;
+  /**
+   * Resets both the initial and current snapshots to the provided data.
+   *
+   * If no data is provided, the current snapshot becomes the new baseline.
+   * This clears all tracked changes and removed columns.
+   *
+   * @param data - Optional new data to use as the baseline. If omitted, uses current data.
+   *
+   * @example
+   * ```typescript
+   * const tracker = new DatabaseDirtyTracker({ name: "Alice" });
+   * tracker.mergeChanges({ name: "Bob" });
+   * tracker.hasChanges(); // true
+   * tracker.reset(); // Make current state the new baseline
+   * tracker.hasChanges(); // false
+   *
+   * // Or reset to entirely new data:
+   * tracker.reset({ name: "Charlie", age: 25 });
+   * ```
+   */
+  reset(data?: Record<string, unknown>): void;
+  /**
+   * Flattens the given data object.
+   * Can be overridden by subclasses to change flattening behavior.
+   */
+  protected flattenData(data: Record<string, unknown>): FlatRecord;
+  /**
+   * Recomputes the dirty and removed column sets by comparing initial and current snapshots.
+   *
+   * This method is called internally after any operation that modifies the current data.
+   * It iterates through all keys in both flattened snapshots and determines which columns
+   * have been modified or removed.
+   *
+   * @protected
+   */
+  protected updateDirtyState(): void;
+  /**
+   * Recursively merges source object into target object, performing a deep merge.
+   *
+   * For nested objects, the merge is recursive. For arrays and primitives, the source
+   * value replaces the target value. All values are cloned to prevent reference sharing.
+   *
+   * @param target - The object to merge into
+   * @param source - The object to merge from
+   * @private
+   */
+  protected mergeIntoRaw(target: Record<string, unknown>, source: Record<string, unknown>): void;
+  /**
+   * Deletes a field from the current raw data using a dot-notation path.
+   *
+   * Supports nested paths (e.g., "address.city") and array indices (e.g., "items.0").
+   * If any segment in the path doesn't exist, the operation is a no-op.
+   *
+   * @param path - The dot-notation path to the field to delete
+   * @private
+   */
+  protected deleteFromRaw(path: string): void;
+  /**
+   * Resolves a single segment of a dot-notation path within a container.
+   *
+   * Handles both object property access and array index access.
+   *
+   * @param container - The object or array to access
+   * @param segment - The property name or array index as a string
+   * @returns The value at the specified segment, or undefined if not found
+   * @private
+   */
+  protected resolveSegment(container: unknown, segment: string): unknown;
+  /**
+   * Creates a deep clone of the provided data.
+   *
+   * @param data - The data to clone
+   * @returns A deep clone of the data
+   * @private
+   */
+  protected cloneData<T>(data: T): T;
+}
+//#endregion
+export { DatabaseDirtyTracker };
+//# sourceMappingURL=database-dirty-tracker.d.mts.map

package/esm/database-dirty-tracker.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-dirty-tracker.d.mts","names":[],"sources":["../../../../../@warlock.js/cascade/src/database-dirty-tracker.ts"],"mappings":";;;;KA+CK,UAAA,GAAa,MAAM;;AAAA;AAAA;KAKnB,iBAAA;EAAsB,QAAA;EAAmB,QAAQ;AAAA;AAkBtD;;;;;;;;;;;;;;;;AAAA,cAAa,oBAAA;EAqSoB;;;;EAAA,UAhSrB,UAAA,EAAY,MAAA;EA2XY;;;EAAA,UAtXxB,UAAA,EAAY,MAAA;EAAA;;;;EAAA,UAMZ,gBAAA,EAAkB,UAAA;EAUT;;;EAAA,UALT,gBAAA,EAAkB,UAAA;;;;qBAKT,YAAA,EAAY,GAAA;EAmDxB;;;EAAA,mBA9CY,cAAA,EAAc,GAAA;cAEd,IAAA,EAAM,MAAA;EA0FW;;;;;;;;;;;;;EAnE7B,eAAA,CAAA;EA4LqB;;;;;;;;;;;;;;;;;EAvKrB,UAAA,CAAA;EAmT0B;;AAAC;EA5S3B,OAAA,CAAQ,MAAA;;;;;;;;;;;;;;;;EAmBR,iBAAA,CAAA;;;;;;;;;;;;;;;;;EAoBA,yBAAA,CAAA,GAA6B,MAAA,SAAe,iBAAA;;;;;;;;;;;;;;;;EA+B5C,kBAAA,CAAmB,IAAA,EAAM,MAAA;;;;;;;;;;;;;;;;;EAsBzB,YAAA,CAAa,OAAA,EAAS,MAAA;;;;;;;;;;;;;;;;EAqBtB,KAAA,CAAM,OAAA;;;;;;;;;;;;;;;;;;;;;EA+BN,KAAA,CAAM,IAAA,GAAO,MAAA;;;;;YAgBV,WAAA,CAAY,IAAA,EAAM,MAAA,oBAA0B,UAAA;;;;;;;;;;YAa5C,gBAAA,CAAA;;;;;;;;;;;YAoCA,YAAA,CAAa,MAAA,EAAQ,MAAA,mBAAyB,MAAA,EAAQ,MAAA;;;;;;;;;;YA2BtD,aAAA,CAAc,IAAA;;;;;;;;;;;YAwCd,cAAA,CAAe,SAAA,WAAoB,OAAA;;;;;;;;YAwBnC,SAAA,GAAA,CAAa,IAAA,EAAM,CAAA,GAAI,CAAA;AAAA"}

package/esm/database-dirty-tracker.mjs

@@ -0,0 +1,356 @@
+import { areEqual, clone } from "@mongez/reinforcements";
+import { isPlainObject } from "@mongez/supportive-is";
+
+//#region ../../@warlock.js/cascade/src/database-dirty-tracker.ts
+function canBeFlatten(object) {
+	return isPlainObject(object);
+}
+/**
+* A fix for flatten as non-plain object is being flatten as well which it should not be
+*/
+function flatten(object, separator = ".", keepNestedOriginalObject = false, parent, root = {}) {
+	if (canBeFlatten(object) === false) return object;
+	for (const key of Object.keys(object)) {
+		const value = object[key];
+		const keyChain = parent ? parent + separator + key : key;
+		if (Array.isArray(value) && value.length === 0 || typeof value === "function") root[keyChain] = value;
+		else if (canBeFlatten(value)) {
+			if (keepNestedOriginalObject) root[keyChain] = value;
+			flatten(value, separator, keepNestedOriginalObject, keyChain, root);
+		} else root[keyChain] = value;
+	}
+	return root;
+}
+/**
+* Tracks changes to model data by maintaining snapshots of initial and current state.
+*
+* The tracker stores both raw (nested) and flattened (dot-notation) versions of the data
+* to accurately detect modifications, additions, and removals at any nesting level.
+*
+* @example
+* ```typescript
+* const tracker = new DatabaseDirtyTracker({ name: "Alice", age: 30 });
+* tracker.mergeChanges({ age: 31 });
+* console.log(tracker.hasChanges()); // true
+* console.log(tracker.getDirtyColumns()); // ["age"]
+* console.log(tracker.getDirtyColumnsWithValues());
+* // { age: { oldValue: 30, newValue: 31 } }
+* ```
+*/
+var DatabaseDirtyTracker = class {
+	/**
+	* The initial raw data snapshot taken at construction or last reset.
+	* Used as the baseline for comparison.
+	*/
+	initialRaw;
+	/**
+	* The current raw data snapshot reflecting all changes made via merge/unset.
+	*/
+	currentRaw;
+	/**
+	* Flattened version of the initial data using dot-notation keys.
+	* Example: { "address.city": "NYC" }
+	*/
+	initialFlattened;
+	/**
+	* Flattened version of the current data using dot-notation keys.
+	*/
+	currentFlattened;
+	/**
+	* Set of column names (dot-notation paths) that have been modified.
+	*/
+	dirtyColumns = /* @__PURE__ */ new Set();
+	/**
+	* Set of column names (dot-notation paths) that existed initially but have been removed.
+	*/
+	removedColumns = /* @__PURE__ */ new Set();
+	constructor(data) {
+		this.initialRaw = this.cloneData(data);
+		this.currentRaw = this.cloneData(data);
+		this.initialFlattened = this.flattenData(this.initialRaw);
+		this.currentFlattened = { ...this.initialFlattened };
+		this.updateDirtyState();
+	}
+	/**
+	* Returns the list of dirty columns using dot-notation.
+	*
+	* A column is considered dirty if its value has changed compared to the initial snapshot.
+	*
+	* @returns An array of column names (dot-notation paths) that have been modified
+	*
+	* @example
+	* ```typescript
+	* tracker.mergeChanges({ name: "Bob", "address.city": "LA" });
+	* tracker.getDirtyColumns(); // ["name", "address.city"]
+	* ```
+	*/
+	getDirtyColumns() {
+		return Array.from(this.dirtyColumns);
+	}
+	/**
+	* Determines whether there are any tracked changes.
+	*
+	* Returns `true` if any columns have been modified or removed since the initial snapshot.
+	*
+	* @returns `true` if there are changes, `false` otherwise
+	*
+	* @example
+	* ```typescript
+	* const tracker = new DatabaseDirtyTracker({ name: "Alice" });
+	* tracker.hasChanges(); // false
+	* tracker.mergeChanges({ name: "Bob" });
+	* tracker.hasChanges(); // true
+	* tracker.unset("name");
+	* tracker.hasChanges(); // true (removed column counts as a change)
+	* ```
+	*/
+	hasChanges() {
+		return this.dirtyColumns.size > 0 || this.removedColumns.size > 0;
+	}
+	/**
+	* Check if the given column is dirty (changed)
+	*/
+	isDirty(column) {
+		return this.dirtyColumns.has(column);
+	}
+	/**
+	* Returns the set of columns that have been removed compared to the baseline.
+	*
+	* A column is considered removed if it existed in the initial snapshot but has been
+	* explicitly unset or deleted from the current data.
+	*
+	* @returns An array of column names (dot-notation paths) that have been removed
+	*
+	* @example
+	* ```typescript
+	* const tracker = new DatabaseDirtyTracker({ name: "Alice", temp: "value" });
+	* tracker.unset("temp");
+	* tracker.getRemovedColumns(); // ["temp"]
+	* ```
+	*/
+	getRemovedColumns() {
+		return Array.from(this.removedColumns);
+	}
+	/**
+	* Provides a mapping of dirty columns to their previous and current values.
+	*
+	* This is useful for generating audit logs, building partial update payloads,
+	* or displaying change summaries to users.
+	*
+	* @returns A record mapping each dirty column to an object containing oldValue and newValue
+	*
+	* @example
+	* ```typescript
+	* const tracker = new DatabaseDirtyTracker({ name: "Alice", age: 30 });
+	* tracker.mergeChanges({ age: 31 });
+	* tracker.getDirtyColumnsWithValues();
+	* // { age: { oldValue: 30, newValue: 31 } }
+	* ```
+	*/
+	getDirtyColumnsWithValues() {
+		const result = {};
+		for (const column of this.dirtyColumns) {
+			const hasCurrent = this.currentFlattened[column] !== void 0 || column in this.currentFlattened;
+			result[column] = {
+				oldValue: this.initialFlattened[column],
+				newValue: hasCurrent ? this.currentFlattened[column] : void 0
+			};
+		}
+		return result;
+	}
+	/**
+	* Replaces the current data snapshot entirely and recomputes the diff.
+	*
+	* This is useful when you want to replace all current data with a new set,
+	* while keeping the initial baseline for comparison.
+	*
+	* @param data - The new data to set as the current snapshot
+	*
+	* @example
+	* ```typescript
+	* const tracker = new DatabaseDirtyTracker({ name: "Alice" });
+	* tracker.replaceCurrentData({ name: "Bob", email: "bob@example.com" });
+	* tracker.getDirtyColumns(); // ["name", "email"]
+	* ```
+	*/
+	replaceCurrentData(data) {
+		this.currentRaw = this.cloneData(data);
+		this.currentFlattened = this.flattenData(this.currentRaw);
+		this.updateDirtyState();
+	}
+	/**
+	* Merges a partial payload into the current snapshot and recomputes the diff.
+	*
+	* This performs a deep merge, preserving existing nested structures while
+	* updating only the specified fields.
+	*
+	* @param partial - Partial data to merge into the current snapshot
+	*
+	* @example
+	* ```typescript
+	* const tracker = new DatabaseDirtyTracker({ name: "Alice", address: { city: "NYC" } });
+	* tracker.mergeChanges({ address: { zip: "10001" } });
+	* // Current data: { name: "Alice", address: { city: "NYC", zip: "10001" } }
+	* tracker.getDirtyColumns(); // ["address.zip"]
+	* ```
+	*/
+	mergeChanges(partial) {
+		this.mergeIntoRaw(this.currentRaw, partial);
+		this.currentFlattened = this.flattenData(this.currentRaw);
+		this.updateDirtyState();
+	}
+	/**
+	* Explicitly removes one or more columns from the current data.
+	*
+	* Supports both single column names and arrays of column names.
+	* Columns can be specified using dot-notation for nested paths.
+	*
+	* @param columns - A single column name or an array of column names to remove
+	*
+	* @example
+	* ```typescript
+	* tracker.unset("tempField");
+	* tracker.unset(["field1", "field2", "nested.field"]);
+	* tracker.getRemovedColumns(); // ["tempField", "field1", "field2", "nested.field"]
+	* ```
+	*/
+	unset(columns) {
+		const targets = Array.isArray(columns) ? columns : [columns];
+		for (const path of targets) this.deleteFromRaw(path);
+		this.currentFlattened = this.flattenData(this.currentRaw);
+		this.updateDirtyState();
+	}
+	/**
+	* Resets both the initial and current snapshots to the provided data.
+	*
+	* If no data is provided, the current snapshot becomes the new baseline.
+	* This clears all tracked changes and removed columns.
+	*
+	* @param data - Optional new data to use as the baseline. If omitted, uses current data.
+	*
+	* @example
+	* ```typescript
+	* const tracker = new DatabaseDirtyTracker({ name: "Alice" });
+	* tracker.mergeChanges({ name: "Bob" });
+	* tracker.hasChanges(); // true
+	* tracker.reset(); // Make current state the new baseline
+	* tracker.hasChanges(); // false
+	*
+	* // Or reset to entirely new data:
+	* tracker.reset({ name: "Charlie", age: 25 });
+	* ```
+	*/
+	reset(data) {
+		const source = data ?? this.currentRaw;
+		this.initialRaw = this.cloneData(source);
+		this.currentRaw = this.cloneData(source);
+		this.initialFlattened = this.flattenData(this.initialRaw);
+		this.currentFlattened = this.flattenData(this.currentRaw);
+		this.dirtyColumns.clear();
+		this.removedColumns.clear();
+	}
+	/**
+	* Flattens the given data object.
+	* Can be overridden by subclasses to change flattening behavior.
+	*/
+	flattenData(data) {
+		return flatten(data);
+	}
+	/**
+	* Recomputes the dirty and removed column sets by comparing initial and current snapshots.
+	*
+	* This method is called internally after any operation that modifies the current data.
+	* It iterates through all keys in both flattened snapshots and determines which columns
+	* have been modified or removed.
+	*
+	* @protected
+	*/
+	updateDirtyState() {
+		this.dirtyColumns.clear();
+		this.removedColumns.clear();
+		const keys = new Set([...Object.keys(this.initialFlattened), ...Object.keys(this.currentFlattened)]);
+		for (const key of keys) {
+			const hasCurrent = this.currentFlattened[key] !== void 0 || key in this.currentFlattened;
+			const hasInitial = this.initialFlattened[key] !== void 0 || key in this.initialFlattened;
+			if (!hasCurrent && hasInitial) this.removedColumns.add(key);
+			const initialValue = this.initialFlattened[key];
+			if (!areEqual(initialValue, hasCurrent ? this.currentFlattened[key] : void 0)) this.dirtyColumns.add(key);
+		}
+	}
+	/**
+	* Recursively merges source object into target object, performing a deep merge.
+	*
+	* For nested objects, the merge is recursive. For arrays and primitives, the source
+	* value replaces the target value. All values are cloned to prevent reference sharing.
+	*
+	* @param target - The object to merge into
+	* @param source - The object to merge from
+	* @private
+	*/
+	mergeIntoRaw(target, source) {
+		for (const [key, value] of Object.entries(source)) {
+			if (value && typeof value === "object" && !Array.isArray(value) && target[key] && typeof target[key] === "object" && !Array.isArray(target[key])) {
+				this.mergeIntoRaw(target[key], value);
+				continue;
+			}
+			target[key] = this.cloneData(value);
+		}
+	}
+	/**
+	* Deletes a field from the current raw data using a dot-notation path.
+	*
+	* Supports nested paths (e.g., "address.city") and array indices (e.g., "items.0").
+	* If any segment in the path doesn't exist, the operation is a no-op.
+	*
+	* @param path - The dot-notation path to the field to delete
+	* @private
+	*/
+	deleteFromRaw(path) {
+		const segments = path.split(".");
+		let container = this.currentRaw;
+		for (let index = 0; index < segments.length - 1; index += 1) {
+			if (container === void 0 || container === null) return;
+			container = this.resolveSegment(container, segments[index]);
+		}
+		if (container === void 0 || container === null) return;
+		const lastSegment = segments[segments.length - 1];
+		if (Array.isArray(container)) {
+			const numericIndex = Number(lastSegment);
+			if (!Number.isNaN(numericIndex)) container.splice(numericIndex, 1);
+			return;
+		}
+		if (typeof container === "object") delete container[lastSegment];
+	}
+	/**
+	* Resolves a single segment of a dot-notation path within a container.
+	*
+	* Handles both object property access and array index access.
+	*
+	* @param container - The object or array to access
+	* @param segment - The property name or array index as a string
+	* @returns The value at the specified segment, or undefined if not found
+	* @private
+	*/
+	resolveSegment(container, segment) {
+		if (Array.isArray(container)) {
+			const numericIndex = Number(segment);
+			if (Number.isNaN(numericIndex)) return;
+			return container[numericIndex];
+		}
+		if (container && typeof container === "object") return container[segment];
+	}
+	/**
+	* Creates a deep clone of the provided data.
+	*
+	* @param data - The data to clone
+	* @returns A deep clone of the data
+	* @private
+	*/
+	cloneData(data) {
+		return clone(data);
+	}
+};
+
+//#endregion
+export { DatabaseDirtyTracker };
+//# sourceMappingURL=database-dirty-tracker.mjs.map

package/esm/database-dirty-tracker.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-dirty-tracker.mjs","names":[],"sources":["../../../../../@warlock.js/cascade/src/database-dirty-tracker.ts"],"sourcesContent":["import { areEqual, clone } from \"@mongez/reinforcements\";\nimport { isPlainObject } from \"@mongez/supportive-is\";\n\nfunction canBeFlatten(object: unknown): boolean {\n  return isPlainObject(object);\n}\n\n/**\n * A fix for flatten as non-plain object is being flatten as well which it should not be\n */\nfunction flatten(\n  object: Record<string, unknown>,\n  separator = \".\",\n  keepNestedOriginalObject = false,\n  parent?: string,\n  root: Record<string, unknown> = {},\n) {\n  if (canBeFlatten(object) === false) {\n    return object;\n  }\n  // object = toPlainObject(object);\n  for (const key of Object.keys(object)) {\n    const value = object[key];\n    const keyChain = parent ? parent + separator + key : key;\n    if ((Array.isArray(value) && value.length === 0) || typeof value === \"function\") {\n      root[keyChain] = value;\n    } else if (canBeFlatten(value)) {\n      if (keepNestedOriginalObject) {\n        root[keyChain] = value;\n      }\n      flatten(\n        value as Record<string, unknown>,\n        separator,\n        keepNestedOriginalObject,\n        keyChain,\n        root,\n      );\n    } else {\n      root[keyChain] = value;\n    }\n  }\n  return root;\n}\n\n/**\n * Flattened record type representing dot-notation paths mapped to their values.\n */\ntype FlatRecord = Record<string, unknown>;\n\n/**\n * Represents the old and new values of a dirty column.\n */\ntype DirtyColumnValues = { oldValue: unknown; newValue: unknown };\n\n/**\n * Tracks changes to model data by maintaining snapshots of initial and current state.\n *\n * The tracker stores both raw (nested) and flattened (dot-notation) versions of the data\n * to accurately detect modifications, additions, and removals at any nesting level.\n *\n * @example\n * ```typescript\n * const tracker = new DatabaseDirtyTracker({ name: \"Alice\", age: 30 });\n * tracker.mergeChanges({ age: 31 });\n * console.log(tracker.hasChanges()); // true\n * console.log(tracker.getDirtyColumns()); // [\"age\"]\n * console.log(tracker.getDirtyColumnsWithValues());\n * // { age: { oldValue: 30, newValue: 31 } }\n * ```\n */\nexport class DatabaseDirtyTracker {\n  /**\n   * The initial raw data snapshot taken at construction or last reset.\n   * Used as the baseline for comparison.\n   */\n  protected initialRaw: Record<string, unknown>;\n\n  /**\n   * The current raw data snapshot reflecting all changes made via merge/unset.\n   */\n  protected currentRaw: Record<string, unknown>;\n\n  /**\n   * Flattened version of the initial data using dot-notation keys.\n   * Example: { \"address.city\": \"NYC\" }\n   */\n  protected initialFlattened: FlatRecord;\n\n  /**\n   * Flattened version of the current data using dot-notation keys.\n   */\n  protected currentFlattened: FlatRecord;\n\n  /**\n   * Set of column names (dot-notation paths) that have been modified.\n   */\n  protected readonly dirtyColumns = new Set<string>();\n\n  /**\n   * Set of column names (dot-notation paths) that existed initially but have been removed.\n   */\n  protected readonly removedColumns = new Set<string>();\n\n  public constructor(data: Record<string, unknown>) {\n    this.initialRaw = this.cloneData(data);\n    this.currentRaw = this.cloneData(data);\n\n    this.initialFlattened = this.flattenData(this.initialRaw);\n    this.currentFlattened = { ...this.initialFlattened };\n\n    this.updateDirtyState();\n  }\n\n  /**\n   * Returns the list of dirty columns using dot-notation.\n   *\n   * A column is considered dirty if its value has changed compared to the initial snapshot.\n   *\n   * @returns An array of column names (dot-notation paths) that have been modified\n   *\n   * @example\n   * ```typescript\n   * tracker.mergeChanges({ name: \"Bob\", \"address.city\": \"LA\" });\n   * tracker.getDirtyColumns(); // [\"name\", \"address.city\"]\n   * ```\n   */\n  public getDirtyColumns(): string[] {\n    return Array.from(this.dirtyColumns);\n  }\n\n  /**\n   * Determines whether there are any tracked changes.\n   *\n   * Returns `true` if any columns have been modified or removed since the initial snapshot.\n   *\n   * @returns `true` if there are changes, `false` otherwise\n   *\n   * @example\n   * ```typescript\n   * const tracker = new DatabaseDirtyTracker({ name: \"Alice\" });\n   * tracker.hasChanges(); // false\n   * tracker.mergeChanges({ name: \"Bob\" });\n   * tracker.hasChanges(); // true\n   * tracker.unset(\"name\");\n   * tracker.hasChanges(); // true (removed column counts as a change)\n   * ```\n   */\n  public hasChanges(): boolean {\n    return this.dirtyColumns.size > 0 || this.removedColumns.size > 0;\n  }\n\n  /**\n   * Check if the given column is dirty (changed)\n   */\n  public isDirty(column: string): boolean {\n    return this.dirtyColumns.has(column);\n  }\n\n  /**\n   * Returns the set of columns that have been removed compared to the baseline.\n   *\n   * A column is considered removed if it existed in the initial snapshot but has been\n   * explicitly unset or deleted from the current data.\n   *\n   * @returns An array of column names (dot-notation paths) that have been removed\n   *\n   * @example\n   * ```typescript\n   * const tracker = new DatabaseDirtyTracker({ name: \"Alice\", temp: \"value\" });\n   * tracker.unset(\"temp\");\n   * tracker.getRemovedColumns(); // [\"temp\"]\n   * ```\n   */\n  public getRemovedColumns(): string[] {\n    return Array.from(this.removedColumns);\n  }\n\n  /**\n   * Provides a mapping of dirty columns to their previous and current values.\n   *\n   * This is useful for generating audit logs, building partial update payloads,\n   * or displaying change summaries to users.\n   *\n   * @returns A record mapping each dirty column to an object containing oldValue and newValue\n   *\n   * @example\n   * ```typescript\n   * const tracker = new DatabaseDirtyTracker({ name: \"Alice\", age: 30 });\n   * tracker.mergeChanges({ age: 31 });\n   * tracker.getDirtyColumnsWithValues();\n   * // { age: { oldValue: 30, newValue: 31 } }\n   * ```\n   */\n  public getDirtyColumnsWithValues(): Record<string, DirtyColumnValues> {\n    const result: Record<string, DirtyColumnValues> = {};\n\n    for (const column of this.dirtyColumns) {\n      const hasCurrent =\n        this.currentFlattened[column] !== undefined || column in this.currentFlattened;\n\n      result[column] = {\n        oldValue: this.initialFlattened[column],\n        newValue: hasCurrent ? this.currentFlattened[column] : undefined,\n      };\n    }\n\n    return result;\n  }\n\n  /**\n   * Replaces the current data snapshot entirely and recomputes the diff.\n   *\n   * This is useful when you want to replace all current data with a new set,\n   * while keeping the initial baseline for comparison.\n   *\n   * @param data - The new data to set as the current snapshot\n   *\n   * @example\n   * ```typescript\n   * const tracker = new DatabaseDirtyTracker({ name: \"Alice\" });\n   * tracker.replaceCurrentData({ name: \"Bob\", email: \"bob@example.com\" });\n   * tracker.getDirtyColumns(); // [\"name\", \"email\"]\n   * ```\n   */\n  public replaceCurrentData(data: Record<string, unknown>): void {\n    this.currentRaw = this.cloneData(data);\n    this.currentFlattened = this.flattenData(this.currentRaw);\n    this.updateDirtyState();\n  }\n\n  /**\n   * Merges a partial payload into the current snapshot and recomputes the diff.\n   *\n   * This performs a deep merge, preserving existing nested structures while\n   * updating only the specified fields.\n   *\n   * @param partial - Partial data to merge into the current snapshot\n   *\n   * @example\n   * ```typescript\n   * const tracker = new DatabaseDirtyTracker({ name: \"Alice\", address: { city: \"NYC\" } });\n   * tracker.mergeChanges({ address: { zip: \"10001\" } });\n   * // Current data: { name: \"Alice\", address: { city: \"NYC\", zip: \"10001\" } }\n   * tracker.getDirtyColumns(); // [\"address.zip\"]\n   * ```\n   */\n  public mergeChanges(partial: Record<string, unknown>): void {\n    this.mergeIntoRaw(this.currentRaw, partial);\n    this.currentFlattened = this.flattenData(this.currentRaw);\n    this.updateDirtyState();\n  }\n\n  /**\n   * Explicitly removes one or more columns from the current data.\n   *\n   * Supports both single column names and arrays of column names.\n   * Columns can be specified using dot-notation for nested paths.\n   *\n   * @param columns - A single column name or an array of column names to remove\n   *\n   * @example\n   * ```typescript\n   * tracker.unset(\"tempField\");\n   * tracker.unset([\"field1\", \"field2\", \"nested.field\"]);\n   * tracker.getRemovedColumns(); // [\"tempField\", \"field1\", \"field2\", \"nested.field\"]\n   * ```\n   */\n  public unset(columns: string | string[]): void {\n    const targets = Array.isArray(columns) ? columns : [columns];\n\n    for (const path of targets) {\n      this.deleteFromRaw(path);\n    }\n\n    this.currentFlattened = this.flattenData(this.currentRaw);\n    this.updateDirtyState();\n  }\n\n  /**\n   * Resets both the initial and current snapshots to the provided data.\n   *\n   * If no data is provided, the current snapshot becomes the new baseline.\n   * This clears all tracked changes and removed columns.\n   *\n   * @param data - Optional new data to use as the baseline. If omitted, uses current data.\n   *\n   * @example\n   * ```typescript\n   * const tracker = new DatabaseDirtyTracker({ name: \"Alice\" });\n   * tracker.mergeChanges({ name: \"Bob\" });\n   * tracker.hasChanges(); // true\n   * tracker.reset(); // Make current state the new baseline\n   * tracker.hasChanges(); // false\n   *\n   * // Or reset to entirely new data:\n   * tracker.reset({ name: \"Charlie\", age: 25 });\n   * ```\n   */\n  public reset(data?: Record<string, unknown>): void {\n    const source = data ?? this.currentRaw;\n    this.initialRaw = this.cloneData(source);\n    this.currentRaw = this.cloneData(source);\n\n    this.initialFlattened = this.flattenData(this.initialRaw);\n    this.currentFlattened = this.flattenData(this.currentRaw);\n\n    this.dirtyColumns.clear();\n    this.removedColumns.clear();\n  }\n\n  /**\n   * Flattens the given data object.\n   * Can be overridden by subclasses to change flattening behavior.\n   */\n  protected flattenData(data: Record<string, unknown>): FlatRecord {\n    return flatten(data);\n  }\n\n  /**\n   * Recomputes the dirty and removed column sets by comparing initial and current snapshots.\n   *\n   * This method is called internally after any operation that modifies the current data.\n   * It iterates through all keys in both flattened snapshots and determines which columns\n   * have been modified or removed.\n   *\n   * @protected\n   */\n  protected updateDirtyState(): void {\n    this.dirtyColumns.clear();\n    this.removedColumns.clear();\n\n    const keys = new Set([\n      ...Object.keys(this.initialFlattened),\n      ...Object.keys(this.currentFlattened),\n    ]);\n\n    for (const key of keys) {\n      const hasCurrent = this.currentFlattened[key] !== undefined || key in this.currentFlattened;\n      const hasInitial = this.initialFlattened[key] !== undefined || key in this.initialFlattened;\n\n      if (!hasCurrent && hasInitial) {\n        this.removedColumns.add(key);\n      }\n\n      const initialValue = this.initialFlattened[key];\n      const currentValue = hasCurrent ? this.currentFlattened[key] : undefined;\n\n      if (!areEqual(initialValue, currentValue)) {\n        this.dirtyColumns.add(key);\n      }\n    }\n  }\n\n  /**\n   * Recursively merges source object into target object, performing a deep merge.\n   *\n   * For nested objects, the merge is recursive. For arrays and primitives, the source\n   * value replaces the target value. All values are cloned to prevent reference sharing.\n   *\n   * @param target - The object to merge into\n   * @param source - The object to merge from\n   * @private\n   */\n  protected mergeIntoRaw(target: Record<string, unknown>, source: Record<string, unknown>): void {\n    for (const [key, value] of Object.entries(source)) {\n      if (\n        value &&\n        typeof value === \"object\" &&\n        !Array.isArray(value) &&\n        target[key] &&\n        typeof target[key] === \"object\" &&\n        !Array.isArray(target[key])\n      ) {\n        this.mergeIntoRaw(target[key] as Record<string, unknown>, value as Record<string, unknown>);\n        continue;\n      }\n\n      target[key] = this.cloneData(value);\n    }\n  }\n\n  /**\n   * Deletes a field from the current raw data using a dot-notation path.\n   *\n   * Supports nested paths (e.g., \"address.city\") and array indices (e.g., \"items.0\").\n   * If any segment in the path doesn't exist, the operation is a no-op.\n   *\n   * @param path - The dot-notation path to the field to delete\n   * @private\n   */\n  protected deleteFromRaw(path: string): void {\n    const segments = path.split(\".\");\n    let container: unknown = this.currentRaw;\n\n    for (let index = 0; index < segments.length - 1; index += 1) {\n      if (container === undefined || container === null) {\n        return;\n      }\n\n      container = this.resolveSegment(container, segments[index]);\n    }\n\n    if (container === undefined || container === null) {\n      return;\n    }\n\n    const lastSegment = segments[segments.length - 1];\n    if (Array.isArray(container)) {\n      const numericIndex = Number(lastSegment);\n      if (!Number.isNaN(numericIndex)) {\n        container.splice(numericIndex, 1);\n      }\n      return;\n    }\n\n    if (typeof container === \"object\") {\n      delete (container as Record<string, unknown>)[lastSegment];\n    }\n  }\n\n  /**\n   * Resolves a single segment of a dot-notation path within a container.\n   *\n   * Handles both object property access and array index access.\n   *\n   * @param container - The object or array to access\n   * @param segment - The property name or array index as a string\n   * @returns The value at the specified segment, or undefined if not found\n   * @private\n   */\n  protected resolveSegment(container: unknown, segment: string): unknown {\n    if (Array.isArray(container)) {\n      const numericIndex = Number(segment);\n      if (Number.isNaN(numericIndex)) {\n        return undefined;\n      }\n\n      return container[numericIndex];\n    }\n\n    if (container && typeof container === \"object\") {\n      return (container as Record<string, unknown>)[segment];\n    }\n\n    return undefined;\n  }\n\n  /**\n   * Creates a deep clone of the provided data.\n   *\n   * @param data - The data to clone\n   * @returns A deep clone of the data\n   * @private\n   */\n  protected cloneData<T>(data: T): T {\n    return clone(data);\n  }\n}\n"],"mappings":"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"}