datum-merge 1.3.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "datum-merge",
-	"version": "1.3.0",
+	"version": "1.5.0",
 	"author": "Rohit Kulkarni <rohk@live.com>",
 	"license": "MIT",
 	"description": "Simplified diff and merging for deeply nested objects",
@@ -27,7 +27,7 @@
 	"scripts": {
 		"lint": "npx eslint src",
 		"pretty": "prettier -c ./src",
-		"scantask": "findstr /s /i todo src\\*.*",
+		"scantask": "findstr /s /i todo src\\*.ts",
 		"test": "jest",
 		"build:dts": "tsc --outDir dist/dts --declaration --declarationMap --emitDeclarationOnly",
 		"build:cjs": "tsc --outDir dist/cjs",
@@ -43,26 +43,26 @@
 	},
 	"bugs": "https://github.com/therohk/datum-merge/issues",
 	"devDependencies": {
-		"@types/node": "^16.11.6",
+		"@types/node": "^25.2.3",
 		"@typescript-eslint/eslint-plugin": "8.53.1",
 		"@typescript-eslint/parser": "8.53.1",
-		"@types/lodash": "^4.17.23",
+		"@types/lodash": "^4.17.24",
 		"@types/lodash-es": "^4.17.12",
 		"@types/jest": "^29.5.2",
 		"eslint": "^8.57.1",
 		"prettier": "^3.1.0",
-		"npm-run-all2": "^6.2.0",
-		"dpdm": "^3.14.0",
+		"npm-run-all2": "^6.2.6",
+		"dpdm": "^4.2.0",
 		"jest": "^29.7.0",
 		"ts-jest": "^29.1.0",
 		"ts-node": "^10.9.2",
-		"tslib": "2.4.0",
-		"typescript": "5.4.5",
-		"lodash": "^4.17.23",
+		"tslib": "2.8.1",
+		"typescript": "5.7.3",
+		"lodash": "4.18.1",
 		"esbuild": "0.25.6"
 	},
 	"dependencies": {
-		"fast-deep-equal": "^3.1.3",
-		"lodash-es": "^4.17.23"
+		"fast-deep-equal": "3.1.3",
+		"lodash-es": "4.18.1"
 	}
 }

package/src/datum-utils.ts

@@ -27,6 +27,10 @@ export function createValueKeys<T>(
     return Object.fromEntries(keys.map((k) => [k, value]));
 }
 
+export function shallowEquals(lhs: any, rhs: any): boolean {
+    return lhs === rhs;
+}
+
 export function deepEquals(lhs: any, rhs: any): boolean {
     if (lhs === rhs)
         return true;

package/src/diff-lib/README.md

@@ -1,11 +1,26 @@
+# datum-diff
+
+module recently published as a standalone package [datum-diff](https://www.npmjs.com/package/datum-diff)
+
+works as a drop-in replacement for the deprecated package [deep-diff](https://www.npmjs.com/package/deep-diff)
+
+simply use `datum-diff` instead of the `datum-merge` libary in the examples below .
+
+for usage on browser environments:
+```
+<script src="https://unpkg.com/datum-diff@1.0.3/dist-diff/umd/deep-diff.min.js"></script>
+```
+
 ## sources
 
-the source code of the [deep-diff](https://github.com/flitbit/diff) js library has been migrated to typescript .
+the source code of the [deep-diff](https://www.npmjs.com/package/deep-diff) js library has been migrated to typescript .
 it remains unmaintained and contains some serious bugs that made it unreliable for this project . 
 
-* tag:v1.0.2 [flitbit/diff](https://github.com/flitbit/diff/blob/master/index.js)
-* tag:v1.0.2 [flitbit/diff/tests](https://github.com/flitbit/diff/blob/master/test/tests.js) 
+* tag:v1.0.2 flitbit/diff (was github.com/flitbit/diff/blob/master/index.js)
+* tag:v1.0.2 flitbit/diff/tests (was github.com/flitbit/diff/blob/master/test/tests.js)
 * tag:v1.0.5 [@types/deep-diff](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/deep-diff/index.d.ts)
+* tag:v1.0.2 flitbit/Readme.md (was github.com/flitbit/diff/blob/master/Readme.md)
+* as of 2026 the links to the original github library are no longer working
 
 same interfaces have been exposed to maintain compatibility with the last version .
 
@@ -36,20 +51,7 @@ const patch: PatchResult[] = diffToPatchLog(customDiff, true);
 applyPatchLog(patch, target);
 ```
 
-see the [readme](https://github.com/flitbit/diff/blob/master/Readme.md#api-documentation) in the original library for detailed examples .
-
-## datum-diff
-
-module recently published as a standalone package [datum-diff](https://www.npmjs.com/package/datum-diff)
-
-works as a drop-in replacement for the package [deep-diff](https://www.npmjs.com/package/deep-diff)
-
-simply use `datum-diff` instead of the `datum-merge` libary in the examples above .
-
-for usage on browser environments:
-```
-<script src="https://unpkg.com/datum-diff@1.0.3/dist-diff/umd/deep-diff.min.js"></script>
-```
+see the [readme](dd-README.md) migrated from the original library for detailed examples .
 
 ## changes
 

package/src/diff-lib/dd-README.md

@@ -0,0 +1,238 @@
+# deep-diff
+
+**deep-diff** is a javascript/node.js module providing utility functions for determining the structural differences between objects and includes some utilities for applying differences across objects.
+
+[![NPM](https://nodei.co/npm/datum-diff.png?downloads=true&downloadRank=true&stars=true)](https://www.npmjs.com/package/datum-diff)
+
+## Install
+
+```bash
+npm install datum-diff
+```
+
+## Features
+
+* Get the structural differences between two objects.
+* Observe the structural differences between two objects.
+* When structural differences represent change, apply change from one object to another.
+* When structural differences represent change, selectively apply change from one object to another.
+
+## Simple Examples
+
+In order to describe differences, change revolves around an `origin` object. For consistency, the `origin` object is always the operand on the `left-hand-side` of operations. The `comparand`, which may contain changes, is always on the `right-hand-side` of operations.
+
+``` javascript
+const diff = require('datum-diff').diff;
+
+const lhs = {
+  name: 'my object',
+  description: 'it\'s an object!',
+  details: {
+    it: 'has',
+    an: 'array',
+    with: ['a', 'few', 'elements']
+  }
+};
+
+const rhs = {
+  name: 'updated object',
+  description: 'it\'s an object!',
+  details: {
+    it: 'has',
+    an: 'array',
+    with: ['a', 'few', 'more', 'elements', { than: 'before' }]
+  }
+};
+
+const differences = diff(lhs, rhs);
+```
+
+The code snippet above would result in the following structure describing the differences:
+
+``` javascript
+[ { kind: 'E',
+    path: [ 'name' ],
+    lhs: 'my object',
+    rhs: 'updated object' },
+  { kind: 'E',
+    path: [ 'details', 'with', 2 ],
+    lhs: 'elements',
+    rhs: 'more' },
+  { kind: 'A',
+    path: [ 'details', 'with' ],
+    index: 3,
+    item: { kind: 'N', rhs: 'elements' } },
+  { kind: 'A',
+    path: [ 'details', 'with' ],
+    index: 4,
+    item: { kind: 'N', rhs: { than: 'before' } } }, ]
+```
+
+### Differences
+
+Differences are reported as one or more change records. Change records have the following structure:
+
+* `kind` - indicates the kind of change; will be one of the following:
+  * `N` - indicates a newly added property/element
+  * `D` - indicates a property/element was deleted
+  * `E` - indicates a property/element was edited
+  * `A` - indicates a change occurred within an array
+* `path` - the property path (from the left-hand-side root)
+* `lhs` - the value on the left-hand-side of the comparison (undefined if kind === 'N')
+* `rhs` - the value on the right-hand-side of the comparison (undefined if kind === 'D')
+* `index` - when kind === 'A', indicates the array index where the change occurred
+* `item` - when kind === 'A', contains a nested change record indicating the change that occurred at the array index
+
+Change records are generated for all structural differences between `origin` and `comparand`. The methods only consider an object's own properties and array elements; those inherited from an object's prototype chain are not considered.
+
+Changes to arrays are recorded simplistically. We care most about the shape of the structure; therefore we don't take the time to determine if an object moved from one slot in the array to another. Instead, we only record the structural
+differences. If the structural differences are applied from the `comparand` to the `origin` then the two objects will compare as "deep equal" using most `isEqual` implementations such as found in [lodash](https://lodash.com/) or [underscore](http://underscorejs.org/).
+
+### Changes
+
+When two objects differ, you can observe the differences as they are calculated and selectively apply those changes to the origin object (left-hand-side).
+
+``` javascript
+const observableDiff = require('datum-diff').observableDiff;
+const applyChange = require('datum-diff').applyChange;
+
+const lhs = {
+  name: 'my object',
+  description: 'it\'s an object!',
+  details: {
+    it: 'has',
+    an: 'array',
+    with: ['a', 'few', 'elements']
+  }
+};
+
+const rhs = {
+  name: 'updated object',
+  description: 'it\'s an object!',
+  details: {
+    it: 'has',
+    an: 'array',
+    with: ['a', 'few', 'more', 'elements', { than: 'before' }]
+  }
+};
+
+observableDiff(lhs, rhs, function (d) {
+  // Apply all changes except to the name property...
+  if (d.path.at(-1) !== 'name') {
+    applyChange(lhs, rhs, d);
+  }
+});
+```
+
+## API Documentation
+
+A standard import of the library is assumed in all of the code examples. The import results in an object having the following public properties:
+
+* `diff(lhs, rhs[, options, acc])` — calculates the differences between two objects, optionally using the specified accumulator.
+* `observableDiff(lhs, rhs, observer[, options])` — calculates the differences between two objects and reports each to an observer function.
+* `applyDiff(target, source, filter)` — applies any structural differences from a source object to a target object, optionally filtering each difference.
+* `applyChange(target, unused, change)` — applies a single change record to a target object.
+* `revertChange(target, unused, change)` reverts a single change record to a target object.
+
+### `diff`
+
+The `diff` function calculates the difference between two objects.
+
+#### Arguments
+
+* `lhs` - the left-hand operand; the origin object.
+* `rhs` - the right-hand operand; the object being compared structurally with the origin object.
+* `options` - A configuration object that can have the following properties:
+  * `prefilter` - function that determines whether difference analysis should continue down the object graph. This function can also replace the `options` object in the parameters for backward compatibility.
+  * `normalize` - function that pre-processes every _leaf_ of the tree.
+* `acc` - an optional accumulator/array (requirement is that it have a `push` function). Each difference is pushed to the specified accumulator.
+
+Returns either an array of changes or, if there are no changes, `undefined`. This was originally chosen so the result would be pass a truthy test:
+
+```javascript
+const changes = diff(obja, objb);
+if (changes) {
+  // do something with the changes.
+}
+```
+
+#### Pre-filtering Object Properties
+
+The `prefilter`'s signature should be `function(path, key)` and it should return a truthy value for any `path`-`key` combination that should be filtered. If filtered, the difference analysis does no further analysis of on the identified object-property path.
+
+```javascript
+const diff = require('datum-diff');
+const assert = require('assert');
+
+const data = {
+  issue: 126,
+  submittedBy: 'abuzarhamza',
+  title: 'readme.md need some additional example prefilter',
+  posts: [
+    {
+      date: '2018-04-16',
+      text: `additional example for prefilter for deep-diff would be great.
+      stackoverflow.com/questions/38364639`
+    }
+  ]
+};
+
+const clone = JSON.parse(JSON.stringify(data));
+clone.title = 'README.MD needs additional example illustrating how to prefilter';
+clone.disposition = 'completed';
+
+const two = diff(data, clone);
+const none = diff(data, clone,
+  (path, key) => path.length === 0 && ~['title', 'disposition'].indexOf(key)
+);
+
+assert.equal(two.length, 2, 'should reflect two differences');
+assert.ok(typeof none === 'undefined', 'should reflect no differences');
+```
+#### Normalizing object properties
+
+The `normalize`'s signature should be `function(path, key, lhs, rhs)` and it should return either a falsy value if no normalization has occured, or a `[lhs, rhs]` array to replace the original values. This step doesn't occur if the path was filtered out in the `prefilter` phase.
+
+```javascript
+const diff = require('datum-diff');
+const assert = require('assert');
+
+const data = {
+  pull: 149,
+  submittedBy: 'saveman71',
+};
+
+const clone = JSON.parse(JSON.stringify(data));
+clone.issue = 42;
+
+const two = diff(data, clone);
+const none = diff(data, clone, {
+  normalize: (path, key, lhs, rhs) => {
+    if (lhs === 149) {
+      lhs = 42;
+    }
+    if (rhs === 149) {
+      rhs = 42;
+    }
+    return [lsh, rhs];
+  }
+});
+
+assert.equal(two.length, 1, 'should reflect one difference');
+assert.ok(typeof none === 'undefined', 'should reflect no difference');
+```
+
+### `observableDiff`
+
+The `observableDiff` function calculates the difference between two objects and reports each to an observer function.
+
+#### Argmuments
+
+* `lhs` - the left-hand operand; the origin object.
+* `rhs` - the right-hand operand; the object being compared structurally with the origin object.
+* `observer` - The observer to report to.
+* `options` - A configuration object that can have the following properties:
+  * `prefilter` - function that determines whether difference analysis should continue down the object graph. This function can also replace the `options` object in the parameters for backward compatibility.
+  * `normalize` - function that pre-processes every _leaf_ of the tree.
+
+---

package/src/diff-lib/package-lock.json

@@ -1,26 +1,26 @@
 {
 	"name": "datum-diff",
-	"version": "1.0.3",
+	"version": "1.0.4",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "datum-diff",
-			"version": "1.0.3",
+			"version": "1.0.4",
 			"license": "MIT",
 			"devDependencies": {
 				"@types/jest": "^29.5.2",
-				"@types/node": "^16.11.6",
+				"@types/node": "^25.2.3",
 				"@typescript-eslint/eslint-plugin": "8.53.1",
 				"@typescript-eslint/parser": "8.53.1",
 				"esbuild": "0.25.6",
 				"eslint": "^8.57.1",
 				"jest": "^29.7.0",
-				"npm-run-all2": "^6.2.0",
+				"npm-run-all2": "^6.2.6",
 				"ts-jest": "^29.1.0",
 				"ts-node": "^10.9.2",
-				"tslib": "2.4.0",
-				"typescript": "5.4.5"
+				"tslib": "2.8.1",
+				"typescript": "5.7.3"
 			},
 			"engines": {
 				"node": ">=16",
@@ -1821,11 +1821,14 @@
 			}
 		},
 		"node_modules/@types/node": {
-			"version": "16.18.126",
-			"resolved": "https://registry.npmjs.org/@types/node/-/node-16.18.126.tgz",
-			"integrity": "sha512-OTcgaiwfGFBKacvfwuHzzn1KLxH/er8mluiy8/uM3sGXHaRe73RrSIj01jow9t4kJEW633Ov+cOexXeiApTyAw==",
+			"version": "25.2.3",
+			"resolved": "https://registry.npmjs.org/@types/node/-/node-25.2.3.tgz",
+			"integrity": "sha512-m0jEgYlYz+mDJZ2+F4v8D1AyQb+QzsNqRuI7xg1VQX/KlKS0qT9r1Mo16yo5F/MtifXFgaofIFsdFMox2SxIbQ==",
 			"dev": true,
-			"license": "MIT"
+			"license": "MIT",
+			"dependencies": {
+				"undici-types": "~7.16.0"
+			}
 		},
 		"node_modules/@types/stack-utils": {
 			"version": "2.0.3",
@@ -5682,9 +5685,9 @@
 			}
 		},
 		"node_modules/tslib": {
-			"version": "2.4.0",
-			"resolved": "https://registry.npmjs.org/tslib/-/tslib-2.4.0.tgz",
-			"integrity": "sha512-d6xOpEDfsi2CZVlPQzGeux8XMwLT9hssAsaPYExaQMuYskwb+x1x7J371tWlbBdWHroy99KnVB6qIkUbs5X3UQ==",
+			"version": "2.8.1",
+			"resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+			"integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
 			"dev": true,
 			"license": "0BSD"
 		},
@@ -5725,9 +5728,9 @@
 			}
 		},
 		"node_modules/typescript": {
-			"version": "5.4.5",
-			"resolved": "https://registry.npmjs.org/typescript/-/typescript-5.4.5.tgz",
-			"integrity": "sha512-vcI4UpRgg81oIRUFwR0WSIHKt11nJ7SAVlYNIu+QpqeyXP+gpQJy/Z4+F0aGxSE4MqwjyXvW/TzgkLAx2AGHwQ==",
+			"version": "5.7.3",
+			"resolved": "https://registry.npmjs.org/typescript/-/typescript-5.7.3.tgz",
+			"integrity": "sha512-84MVSjMEHP+FQRPy3pX9sTVV/INIex71s9TL2Gm5FG/WG1SqXeKyZ0k7/blY/4FdOzI12CBy1vGc4og/eus0fw==",
 			"dev": true,
 			"license": "Apache-2.0",
 			"bin": {
@@ -5738,6 +5741,13 @@
 				"node": ">=14.17"
 			}
 		},
+		"node_modules/undici-types": {
+			"version": "7.16.0",
+			"resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.16.0.tgz",
+			"integrity": "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==",
+			"dev": true,
+			"license": "MIT"
+		},
 		"node_modules/update-browserslist-db": {
 			"version": "1.1.3",
 			"resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.1.3.tgz",

package/src/diff-lib/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "datum-diff",
-	"version": "1.0.3",
+	"version": "1.0.4",
 	"author": "Rohit Kulkarni <rohk@live.com>",
 	"license": "MIT",
 	"description": "deep-diff js library rewritten in typescript",
@@ -40,17 +40,17 @@
 	},
 	"bugs": "https://github.com/therohk/datum-merge/issues",
 	"devDependencies": {
-		"@types/node": "^16.11.6",
+		"@types/node": "^25.2.3",
 		"@typescript-eslint/eslint-plugin": "8.53.1",
 		"@typescript-eslint/parser": "8.53.1",
 		"@types/jest": "^29.5.2",
 		"eslint": "^8.57.1",
-		"npm-run-all2": "^6.2.0",
+		"npm-run-all2": "^6.2.6",
 		"jest": "^29.7.0",
 		"ts-jest": "^29.1.0",
 		"ts-node": "^10.9.2",
-		"tslib": "2.4.0",
-		"typescript": "5.4.5",
+		"tslib": "2.8.1",
+		"typescript": "5.7.3",
 		"esbuild": "0.25.6"
 	}
 }

package/src/index.ts

@@ -10,13 +10,15 @@ export { flattenObject, unflattenObject } from "./diff-high";
 export { type PatchResult } from "./patch-low";
 export { diffToPatchLog, deepPatchLog } from "./patch-low";
 export { applyPatchLog, revertPatchLog } from "./patch-low";
-export { immutablePatch, getPointerValue } from "./patch-low";
+export { forcePatchLog, getPointerValue } from "./patch-low";
+export { immutablePatch } from "./patch-low";
 
 export { UpdateCode } from "./merge-low";
 export { UpdateCode as MC } from "./merge-low";
 export { type MergeCode } from "./merge-low";
 export { updateCodeInfo } from "./merge-high";
 
+export { mergeVectors } from "./merge-low";
 export { shallowMerge, immutableMerge } from "./merge-high";
 export { deepMerge, immutableDeepMerge } from "./merge-high";
 export { diffFromMerge, patchFromMerge } from "./merge-high";

package/src/merge-low.ts

@@ -1,6 +1,6 @@
-import { concat, differenceWith, intersectionWith, unionWith, isEqual } from "lodash-es";
+import { concat, differenceWith, intersectionWith, unionWith } from "lodash-es";
 import { emptyValue, isArrayOfAny, isNullish, isPrimitive, typeOfValue } from "./type-utils";
-import { areArraysEqual, deepClone } from "./datum-utils";
+import { areArraysEqual, deepClone, deepEquals } from "./datum-utils";
 
 export const UpdateCode = {
     T: "T", //touch, blank update
@@ -132,14 +132,14 @@ export function mergeVectorField(
             break;
         case UpdateCode.B:
         case UpdateCode.XM:
-            targetVals = unionWith(target[label], sourceVals, isEqual);
+            targetVals = unionWith(target[label], sourceVals, deepEquals);
             break;
         // case UpdateCode.D:
         case UpdateCode.XD:
-            targetVals = differenceWith(target[label], sourceVals, isEqual);
+            targetVals = differenceWith(target[label], sourceVals, deepEquals);
             break;
         case UpdateCode.XI:
-            targetVals = intersectionWith(target[label], sourceVals, isEqual);
+            targetVals = intersectionWith(target[label], sourceVals, deepEquals);
             break;
         default:
             return false;
@@ -154,3 +154,25 @@ export function mergeVectorField(
     target[label] = !changed ? targetVals : deepClone(targetVals);
     return changed;
 };
+
+export function mergeVectors<T>(
+    mergeCode: "XM" | "XI" | "XD" | "XS",
+    arr1: readonly T[],
+    arr2: readonly T[],
+    equalsCond?: (v1: T, v2: T) => boolean,
+): T[] {
+    if (!arr1?.length && !arr2?.length)
+        return [];
+    equalsCond = equalsCond ?? deepEquals;
+    switch (mergeCode) {
+        case UpdateCode.XM:
+            return unionWith<T>(arr1, arr2, equalsCond);
+        case UpdateCode.XI:
+            return intersectionWith<T>(arr1, arr2, equalsCond);
+        case UpdateCode.XD:
+            return differenceWith<T, T>(arr1, arr2, equalsCond);
+        case UpdateCode.XS:
+            return concat(arr1 ?? [], arr2 ?? []);
+    }
+    throw new Error("invalid merge code " + mergeCode);
+}

package/src/patch-low.ts

@@ -1,4 +1,5 @@
 import { get, set, toPath, unset } from "lodash-es";
+import { isNullish, isPrimitive } from "./type-utils";
 import { deepClone, deepEquals } from "./datum-utils";
 import { Diff } from "./diff-lib/deep-diff";
 import { deepDiffLow } from "./diff-high";
@@ -60,6 +61,7 @@ export function deepPatchLog(
 };
 
 /**
+ * subset of standard json patch format
  * reapply patch on a fresh target
  */
 export function applyPatchLog(
@@ -78,10 +80,11 @@ export function applyPatchLog(
             continue;
         }
         const targetVal = get(target, difPath);
-        if (!targetVal && !patchItem.value)
+        const sourceVal = patchItem.value;
+        if (isNullish(targetVal) && isNullish(sourceVal))
             continue;
-        if (!targetVal || !deepEquals(targetVal, patchItem.value)) {
-            set(target, difPath, patchItem.value);
+        if (isNullish(targetVal) || !deepEquals(targetVal, sourceVal)) {
+            set(target, difPath, deepClone(sourceVal));
             changed = true;
         }
     }
@@ -100,24 +103,52 @@ export function revertPatchLog(
     let changed = false;
     for (const patchItem of patchLog) {
         const difPath: string[] = asLodashPath(patchItem.path);
+        if (patchItem.op === "test")
+            continue;
         if (patchItem.op === "add") {
             changed = unset(target, difPath) || changed;
-        } else if (patchItem.op !== "test") {
-            set(target, difPath, patchItem.prev);
-            changed = true;
+            continue;
         }
+        set(target, difPath, patchItem.prev);
+        changed = true;
     }
     return changed;
 }
 
+/**
+ * unofficial json merge-patch format 
+ * op is ignored and nulls are removed
+ */
+export function forcePatchLog(
+    patchLog: { path: string, value?: unknown }[],
+    target: object = {},
+): void {
+    for (const patchItem of patchLog) {
+        const difPath: string[] = patchItem.path.startsWith("/")
+            ? asLodashPath(patchItem.path) : toPath(patchItem.path);
+        if (!difPath?.length)
+            continue;
+        const value = patchItem.value;
+        if (isNullish(value)) {
+            unset(target, difPath);
+        } if (isPrimitive(value)) {
+            set(target, difPath, value);
+        } else {
+            set(target, difPath, deepClone(value));
+        }
+    }
+}
+
 export function immutablePatch(
     target: object,
     patchSrc: PatchResult[],
-    patchDir?: "apply" | "revert",
+    patchDir?: "apply" | "revert" | "force",
 ): object {
     const targetCopy = deepClone(target ?? {});
     if (patchDir === "revert") {
         revertPatchLog(patchSrc, targetCopy);
+    } else if (patchDir === "force") {
+        forcePatchLog(patchSrc, targetCopy);
     } else {
         applyPatchLog(patchSrc, targetCopy);
     }