diff readme

__tests__/diff-high.test.ts

@@ -0,0 +1,35 @@
+
+import { deepClone, deepEquals } from "../src/datum-utils";
+import { deepDiffLow, deepDiffTyped } from "../src/diff-high";
+
+describe("validate-diff-utils", () => {
+
+    test('objects passed to diff should be immutable', async () => {
+
+        const trg = { arN: ["a"], arD: ["a", "b"], d: "del", e: "old", vD: ["del"], oa: [{ x: "a" }, { b: "b" }], oD: { x: "y" } };
+        const src = { arN: ["y", "z"], arD: ["z"], n: "new", e: "new", vN: ["new"], oa: [{ y: "b" }, { b: "b" }], sN: ["1", "2"] };
+        const trgBkp = deepClone(trg);
+        const srcBkp = deepClone(src);
+        expect(deepEquals(trgBkp, trg)).toEqual(true);
+        expect(deepEquals(srcBkp, src)).toEqual(true);
+
+        const tsDiff = deepDiffLow(trg, src);
+        const stDiff = deepDiffLow(src, trg);
+        const tsoiDiff = deepDiffLow(trg, src, true);
+        const stoiDiff = deepDiffLow(src, trg, true);
+        expect(tsDiff).toBeDefined();
+        expect(stDiff).toBeDefined();
+        expect(tsoiDiff).toBeDefined();
+        expect(stoiDiff).toBeDefined();
+
+        const tsDiff1 = deepDiffTyped<any>(trg, src);
+        const stDiff1 = deepDiffTyped<any>(src, trg);
+        expect(tsDiff1).toBeDefined();
+        expect(stDiff1).toBeDefined();
+
+        //no side effects
+        expect(trg).toEqual(trgBkp);
+        expect(src).toEqual(srcBkp);
+    });
+
+});

src/diff-high.ts

@@ -1,6 +1,6 @@
 import { Diff, applyChange, diff, orderIndependentDiff } from "deep-diff";
 // import { Diff, applyChange, diff, orderIndependentDiff } from "./diff-lib/deep-diff"; //todo
-import { flattenObject, getObjectKeys } from "./datum-utils";
+import { deepClone, flattenObject, getObjectKeys } from "./datum-utils";
 
 export function deepDiffFlat(
     oldFlat: any, //source
@@ -55,7 +55,10 @@ export function deepDiffLow<T, S>(
 ): readonly Diff<T, S>[] | false {
     const differences = !orderInd
         ? diff(lhsObj, rhsObj)
-        : orderIndependentDiff(lhsObj, rhsObj);
+        : orderIndependentDiff(
+            deepClone(lhsObj),
+            deepClone(rhsObj),
+        ); //bug in library
     return !differences?.length
         ? false
         : differences;

src/diff-lib/README.md

@@ -1,19 +1,35 @@
 
 ## sources
 
+the source code of the [deep-diff](https://github.com/flitbit/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.5 [@types/deep-diff](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/deep-diff/index.d.ts)
 
 same interfaces have been exposed to maintain compatibility with last version .
-preferred method of invokation is via diff-utils .
+recommended method of invocation for simple use-cases is via diff-utils .
 
 many thanks to the library author and all previous contributors !
 
+## usage
+
+```
+import { diff, accumulateDiff } from "datum-merge";
+const simpleDiff = diff(target, source);
+const customDiff = accumulateDiff(target, source, prefilter, accum, orderIndep);
+```
+
+see the [readme](https://github.com/flitbit/diff/blob/master/Readme.md#api-documentation) in the original library for detailed examples .
+
 ## changes
 
 * all functions and responses are typed
 * lhs and rhs should be immutable ( bug when orderIndependent=true )
 * diff response should be immutable
+* general code upgrades and variable cleanup
 * avoid introducing any dependancies within module
-* support importing only diff as drop-in replacement
-* should compare nullish keys properly ( todo )
+* support importing only diff as drop-in replacement ( todo )
+
+---