Recursive-Diff

A JavaScript library (with TypeScript support) to find diff between two JS Objects/Array, support for complex nested JS Objects

---

This library can be used to get diff between two JS Objects/Arrays(or other primitive values). Diff are returned in the form of Array where each ARRAY item represents a change in the original Object/Array. A diff item can have following three properties:

• path: An array representation of nested path
• op: Can be any one of the following - add, update or delete
• val: New value after change

1const rdiff = require('recursive-diff');
2const initialVal = {
3  a: {
4    b: 1,
5    c: 2,
6    d: [1]
7  }
8}
9const changedVal = {
10  a: {
11    b: 2,
12    d: [1, 2],
13  },
14};
15
16const diff = rdiff.getDiff(initialVal, changedVal);
17/***
18Diff of initialVal and changedVal is: [
19  {
20    "path": [
21      "a",
22      "b"
23    ],
24    "op": "update",
25    "val": 2
26  },
27  {
28    "path": [
29      "a",
30      "c"
31    ],
32    "op": "delete"
33  },
34  {
35    "path": [
36      "a",
37      "d",
38      1
39    ],
40    "op": "add",
41    "val": 2
42  }
43]
44**/
45
46const c = rdiff.applyDiff(initialVal, diff);
47assert.deepEqual(c, changedVal);
48

Api details

• getDiff(oldVal, newVal, keepOldVal?): getDiff takes following parameters

  • oldVal (required): initial value, can be Array/Object or even primitive type such as number, boolean or string
  • newVal (required): changed value ( required ), can be Array/Object or even primitive type such as number, boolean or string
  • keepOldValueInDiff (optional): boolean parameter which if set to true, every diff value will have an additional property oldValue which will denote the old value before mutation

• applyDiff (oldVal, diff, visitorCallbackFn?) applyDiff takes three arguments:

  • oldVal (required): original value,
  • diff (required): diff returned by getDiff API
  • visitorCallbackFn (optional): This callback function is called at each depth level while applying the diff. It can be used to mark the mutation path with some meta properties eg: { isMutated: true }. For more details, please check the examples directory of this repo.

Using recursive diff library in Node

• Install library using the command : npm install recursive-diff
• sample code is given below

1const diff = require('recursive-diff');
2const oldVal = {a:1};
3const newVal = {a:2};
4const delta = diff.getDiff(oldVal, newVal);
5const ob3 = diff.applyDiff(oldVal, delta);
6assert.deepEqual(ob3, newVal);

Using recursive diff library in the Browser

'dist/recursive-diff.min.js' can be directly injected into a HTML page using the URL https://unpkg.com/recursive-diff@latest/dist/recursive-diff.min.js. Once it is included into the HTML file, diff API is accessible using window.recursiveDiff. Example given below.

1<script type="text" src="https://unpkg.com/recursive-diff@latest/dist/recursive-diff.min.js"/>
2<script type="text/javascript">
3 const oldVal = { a: 1 };
4 const newVal = { a: 2 };
5 const delta = recursiveDiff.getDiff(oldVal, newVal);
6 const ob3 = recursiveDiff.applyDiff(oldVal, delta); //expect ob3 is deep equal to newVal
7</script>

Using recursive diff library in TypeScript

1import { getDiff, applyDiff, rdiffResult } from 'recursive-diff';
2
3const oldVal = [1, 2];
4const newVal = [2, 3, 4];
5const diff:rdiffResult[] = getDiff(oldVal, newVal);
6console.log('diff', diff);
7const final = applyDiff(oldVal, diff);
8console.log('applydiff', final); // final should deep equal to newVal

Tests

Unit test can be run using the command npm test. This repo has more than 99% code coverage.

Examples

You can find more examples in the example folder of this repo. Few of the examples are listed below.

1/* eslint-disable no-param-reassign */
2/* eslint-disable no-console */
3import { getDiff, applyDiff } from '../dist/recursive-diff';
4
5let [a, b, c, delta] = [];
6// testing primitive data type
7a = 3;
8b = 10;
9delta = getDiff(a, b);
10console.log(delta);
11// Output: [{path: [], op: 'update', val: 10}]
12c = applyDiff(a, delta);
13console.log(c); // Output: 10
14
15// testing array
16a = [1, 2];
17b = [1, 30, 40];
18delta = getDiff(a, b, true); // third parameter : keepOldValInDiff, see output below
19console.log(delta);
20/** *
21Output:
22[
23  { path: [1], op: 'update', val: 30, oldVal: 2 },
24  { path: [2], op: 'add', val: 40 },
25]
26* */
27c = applyDiff(a, delta);
28console.log(c); // Output: [1,30,40]
29
30// testing objects
31a = {
32  a: '10',
33  b: '20',
34  c: '30',
35};
36b = {
37  a: '10',
38  b: '40',
39};
40delta = getDiff(a, b);
41console.log(delta);
42/** * Output:
43[
44  { path: ['b'], op: 'update', val: 40 },
45  { path: ['c'], op: 'delete', val: undefined },
46]
47* */
48c = applyDiff(a, delta);
49console.log(c); // Output: {a:'10', 'b':40}
50
51// testing complex deep object
52a = {
53  b: [1, 2, [3, 4]],
54  c: {
55    c1: 20,
56    c2: {
57      c21: 'hello',
58    },
59    c3: 'India',
60  },
61};
62b = {
63  b: [1, 2, [4]],
64  c: {
65    c1: 20,
66    c2: {
67      c21: 'hi',
68      c22: 'welcome',
69    },
70    c3: 'cosmic',
71  },
72};
73
74delta = getDiff(a, b);
75console.log(delta);
76/**
77Output:
78[
79  { path: ['b', 2, 0], op: 'update', val: 4 },
80  { path: ['b', 2, 1], op: 'delete', val: undefined },
81  { path: ['c', 'c2', 'c21'], op: 'update', val: 'hi' },
82  { path: ['c', 'c2', 'c22'], op: 'add', val: 'welcome' },
83  { path: ['c', 'c3'], op: 'update', val: 'cosmic' },
84]
85* */
86c = applyDiff(a, delta);
87console.log(c);
88/** *Output
89 {
90    b: [1,2,[4]],
91    c: {
92        c1 : 20,
93        c2 : {
94            c21: 'hi',
95            c22: 'welcome'
96        },
97        c3: 'cosmic'
98    }
99}
100* */
101