@warlock.js/cascade 4.9.0 → 4.9.1

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

@@ -211,8 +211,17 @@ declare class DatabaseDirtyTracker {
   /**
    * 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.
+   * Only **plain** objects are merged recursively. Everything else — arrays,
+   * primitives, and class instances such as `Date` / `Map` / `Set` / `RegExp` —
+   * replaces the target value. All values are cloned to prevent reference sharing.
+   *
+   * The plain-object guard is load-bearing, not tidiness. A bare
+   * `typeof value === "object"` also matches a `Date`, and `Object.entries(date)`
+   * is `[]` — so merging a `Date` over a column that already held a `Date`
+   * recursed into it, copied nothing, and left the old value in the snapshot.
+   * The column then never went dirty and `save()` returned
+   * `{ success: true, modifiedCount: 0 }` without issuing an `UPDATE`. This is
+   * the same lesson `canBeFlatten` above already encodes.
    *
    * @param target - The object to merge into
    * @param source - The object to merge from

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

@@ -1 +1 @@
-{"version":3,"file":"database-dirty-tracker.d.mts","names":[],"sources":["../../../../../../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;EA4LqB;;;;;;;;;;;;;;;;;EAvKrB,UAAA;EAmT0B;;AAAC;EA5S3B,OAAA,CAAQ,MAAA;;;;;;;;;;;;;;;;EAmBR,iBAAA;;;;;;;;;;;;;;;;;EAoBA,yBAAA,IAA6B,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;;;;;;;;;;;YAoCA,YAAA,CAAa,MAAA,EAAQ,MAAA,mBAAyB,MAAA,EAAQ,MAAA;;;;;;;;;;YA2BtD,aAAA,CAAc,IAAA;;;;;;;;;;;YAwCd,cAAA,CAAe,SAAA,WAAoB,OAAA;;;;;;;;YAwBnC,SAAA,IAAa,IAAA,EAAM,CAAA,GAAI,CAAA;AAAA"}
+{"version":3,"file":"database-dirty-tracker.d.mts","names":[],"sources":["../../../../../../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;EA8SoB;;;;EAAA,UAzSrB,UAAA,EAAY,MAAA;EA6XY;;;EAAA,UAxXxB,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;EA4LqB;;;;;;;;;;;;;;;;;EAvKrB,UAAA;EAqT0B;;AAAC;EA9S3B,OAAA,CAAQ,MAAA;;;;;;;;;;;;;;;;EAmBR,iBAAA;;;;;;;;;;;;;;;;;EAoBA,yBAAA,IAA6B,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;;;;;;;;;;;;;;;;;;;;YA6CA,YAAA,CAAa,MAAA,EAAQ,MAAA,mBAAyB,MAAA,EAAQ,MAAA;;;;;;;;;;YAoBtD,aAAA,CAAc,IAAA;;;;;;;;;;;YAwCd,cAAA,CAAe,SAAA,WAAoB,OAAA;;;;;;;;YAwBnC,SAAA,IAAa,IAAA,EAAM,CAAA,GAAI,CAAA;AAAA"}

package/esm/database-dirty-tracker.mjs

@@ -280,8 +280,17 @@ var DatabaseDirtyTracker = class {
 	/**
 	* 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.
+	* Only **plain** objects are merged recursively. Everything else — arrays,
+	* primitives, and class instances such as `Date` / `Map` / `Set` / `RegExp` —
+	* replaces the target value. All values are cloned to prevent reference sharing.
+	*
+	* The plain-object guard is load-bearing, not tidiness. A bare
+	* `typeof value === "object"` also matches a `Date`, and `Object.entries(date)`
+	* is `[]` — so merging a `Date` over a column that already held a `Date`
+	* recursed into it, copied nothing, and left the old value in the snapshot.
+	* The column then never went dirty and `save()` returned
+	* `{ success: true, modifiedCount: 0 }` without issuing an `UPDATE`. This is
+	* the same lesson `canBeFlatten` above already encodes.
 	*
 	* @param target - The object to merge into
 	* @param source - The object to merge from
@@ -289,7 +298,7 @@ var DatabaseDirtyTracker = class {
 	*/
 	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])) {
+			if (isPlainObject(value) && isPlainObject(target[key])) {
 				this.mergeIntoRaw(target[key], value);
 				continue;
 			}

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

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

package/llms-full.txt

@@ -2556,6 +2556,24 @@ for (const [field, { oldValue, newValue }] of Object.entries(dirty)) {
 }
 ```
 
+## How a merge decides what changed
+
+`.merge()` deep-merges **plain objects only**. Every other value — primitives, arrays, and class instances such as `Date`, `Map`, `Set`, `RegExp` — **replaces** the target outright.
+
+```ts
+// plain object → merged key-by-key, siblings survive
+user.merge({ profile: { age: 26 } });     // profile.city untouched
+user.getDirtyColumns();                    // ["profile.age"]
+
+// Date → replaced, not merged
+conversation.merge({ lastOutboundAt: new Date() });
+conversation.getDirtyColumns();            // ["lastOutboundAt"]
+```
+
+:::note[Fixed in 4.9.1]
+Before 4.9.1 a `Date` merged over a column that **already held a `Date`** was silently dropped: the merge treated it as a mergeable container and recursed into it, and a `Date` has no own enumerable properties, so nothing was copied. The column never went dirty and `save()` returned `{ success: true, modifiedCount: 0 }` with no `UPDATE` issued. Writing into an empty column always worked, so only overwrites were affected. If you are on 4.9.0 or earlier, upgrade.
+:::
+
 ## Things NOT to do
 
 - Don't use `hasChanges()` / `isDirty()` after `save()` to verify the save persisted. The tracker resets to clean on save — these become false regardless. Read back from the DB if you need verification.

package/package.json

@@ -27,9 +27,9 @@
     "@mongez/events": "^2.2.6",
     "@mongez/reinforcements": "^3.3.0",
     "@mongez/supportive-is": "^2.1.3",
-    "@warlock.js/context": "4.9.0",
-    "@warlock.js/logger": "4.9.0",
-    "@warlock.js/seal": "4.9.0",
+    "@warlock.js/context": "4.9.1",
+    "@warlock.js/logger": "4.9.1",
+    "@warlock.js/seal": "4.9.1",
     "citty": "^0.2.2",
     "fast-glob": "^3.3.3"
   },
@@ -40,7 +40,7 @@
   "bin": {
     "cascade": "bin/cascade.js"
   },
-  "version": "4.9.0",
+  "version": "4.9.1",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/track-changes/SKILL.md

@@ -97,6 +97,24 @@ for (const [field, { oldValue, newValue }] of Object.entries(dirty)) {
 }
 ```
 
+## How a merge decides what changed
+
+`.merge()` deep-merges **plain objects only**. Every other value — primitives, arrays, and class instances such as `Date`, `Map`, `Set`, `RegExp` — **replaces** the target outright.
+
+```ts
+// plain object → merged key-by-key, siblings survive
+user.merge({ profile: { age: 26 } });     // profile.city untouched
+user.getDirtyColumns();                    // ["profile.age"]
+
+// Date → replaced, not merged
+conversation.merge({ lastOutboundAt: new Date() });
+conversation.getDirtyColumns();            // ["lastOutboundAt"]
+```
+
+:::note[Fixed in 4.9.1]
+Before 4.9.1 a `Date` merged over a column that **already held a `Date`** was silently dropped: the merge treated it as a mergeable container and recursed into it, and a `Date` has no own enumerable properties, so nothing was copied. The column never went dirty and `save()` returned `{ success: true, modifiedCount: 0 }` with no `UPDATE` issued. Writing into an empty column always worked, so only overwrites were affected. If you are on 4.9.0 or earlier, upgrade.
+:::
+
 ## Things NOT to do
 
 - Don't use `hasChanges()` / `isDirty()` after `save()` to verify the save persisted. The tracker resets to clean on save — these become false regardless. Read back from the DB if you need verification.