json-diff-ts

json-diff-ts is a TypeScript library that calculates and applies differences between JSON objects. A standout feature is its ability to identify elements in arrays using keys instead of indices, which offers a more intuitive way to handle arrays. It also supports JSONPath, a query language for JSON, which enables you to target specific parts of a JSON document with precision.

Another significant feature of this library is its ability to transform changesets into atomic changes. This means that each change in the data can be isolated and applied independently, providing a granular level of control over the data manipulation process.

This library is particularly valuable for applications where tracking changes in JSON data is crucial. It simplifies the process of comparing JSON objects and applying changes. The support for key-based array identification can be especially useful in complex JSON structures where tracking by index is not efficient or intuitive. JSONPath support further enhances its capabilities by allowing precise targeting of specific parts in a JSON document, making it a versatile tool for handling JSON data.

Starting with version 3, json-diff-ts now supports both ECMAScript Modules and CommonJS. This makes the library more versatile and compatible with various JavaScript environments. Whether you're working in a modern project that uses ES modules, or a Node.js project that uses CommonJS, you can now use json-diff-ts seamlessly.

Installation

1npm install json-diff-ts

In TypeScript or ES Modules, you can import the diff function like this:

1import { diff } from 'json-diff-ts';

In CommonJS, you can import the diff function like this:

1const { diff } = require('json-diff-ts');

Capabilities

diff

Generates a difference set for JSON objects. When comparing arrays, if a specific key is provided, differences are determined by matching elements via this key rather than array indices.

Examples using Star Wars data:

1import { diff } from 'json-diff-ts';
2
3const oldData = {
4  planet: 'Tatooine',
5  faction: 'Jedi',
6  characters: [
7    { id: 'LUK', name: 'Luke Skywalker', force: true },
8    { id: 'LEI', name: 'Leia Organa', force: true }
9  ],
10  weapons: ['Lightsaber', 'Blaster']
11};
12
13const newData = {
14  planet: 'Alderaan',
15  faction: 'Rebel Alliance',
16  characters: [
17    { id: 'LUK', name: 'Luke Skywalker', force: true, rank: 'Commander' },
18    { id: 'HAN', name: 'Han Solo', force: false }
19  ],
20  weapons: ['Lightsaber', 'Blaster', 'Bowcaster']
21};
22
23const diffs = diff(oldData, newData, { embeddedObjKeys: { characters: 'id' } });
24
25const expectedDiffs = [
26  {
27    type: 'UPDATE',
28    key: 'planet',
29    value: 'Alderaan',
30    oldValue: 'Tatooine'
31  },
32  {
33    type: 'UPDATE',
34    key: 'faction',
35    value: 'Rebel Alliance',
36    oldValue: 'Jedi'
37  },
38  {
39    type: 'UPDATE',
40    key: 'characters',
41    embeddedKey: 'id',
42    changes: [
43      {
44        type: 'UPDATE',
45        key: 'LUK',
46        changes: [
47          {
48            type: 'ADD',
49            key: 'rank',
50            value: 'Commander'
51          }
52        ]
53      },
54      {
55        type: 'ADD',
56        key: 'HAN',
57        value: {
58          id: 'HAN',
59          name: 'Han Solo',
60          force: false
61        }
62      },
63      {
64        type: 'REMOVE',
65        key: 'LEI',
66        value: {
67          id: 'LEI',
68          name: 'Leia Organa',
69          force: true
70        }
71      }
72    ]
73  },
74  {
75    type: 'UPDATE',
76    key: 'weapons',
77    embeddedKey: '$index',
78    changes: [
79      {
80        type: 'ADD',
81        key: '2',
82        value: 'Bowcaster'
83      }
84    ]
85  }
86];

Advanced

Paths can be utilized to identify keys within nested arrays.

1const diffs = diff(oldData, newData, { embeddedObjKeys { 'characters.subarray': 'id' }});

You can also designate the root by using '.' instead of an empty string ('').

1const diffs = diff(oldData, newData, { embeddedObjKeys: { '.characters.subarray': 'id' } });

Determine if type changes are treated as a replace (remove, add) or as an update; default is replace.

1const diffs = diff(oldData, newData, { treatTypeChangeAsReplace: false });

You can use a function to dynamically resolve the key of the object. The first parameter is the object and the second is to signal if the function should return the key name instead of the value. This is needed to flatten the changeset

1const diffs = diff(oldData, newData, {
2  embeddedObjKeys: {
3    characters: (obj, shouldReturnKeyName) => (shouldReturnKeyName ? 'id' : obj.id)
4  }
5});

If you're using the Map type, you can employ regular expressions for path identification.

1const embeddedObjKeys: EmbeddedObjKeysMapType = new Map();
2
3embeddedObjKeys.set(/^char\w+$/, 'id'); // instead of 'id' you can specify a function
4
5const diffs = diff(oldObj, newObj, { embeddedObjKeys });

Compare string arrays by value instead of index

1const diffs = diff(oldObj, newObj, { embeddedObjKeys: { stringArr: '$value' } });

atomizeChangeset

Transforms a complex changeset into a list of atomic changes, each describable by a JSONPath.

Examples:

1const atomicChanges = atomizeChangeset(diffs);
2// Restore the changeset from a selection of atomic changes
3const changeset = unatomizeChangeset(flatChanges.slice(0, 3));
4// Alternatively, apply the changes using a JSONPath-capable library
5// ...

Atomic Changes will have the following structure:

1[
2  { type: 'UPDATE', key: 'planet', value: 'Alderaan', oldValue: 'Tatooine', path: '$.planet', valueType: 'String' },
3  // ... Additional flat changes here
4  { type: 'ADD', key: 'rank', value: 'Commander', path: "$.characters[?(@.id=='LUK')].rank", valueType: 'String' }
5];

applyChange

Examples:

1const oldData = {
2  // ... Initial data here
3};
4
5// Sample diffs array, similar to the one generated in the diff example
6const diffs = [
7  // ... Diff objects here
8];
9
10changesets.applyChanges(oldData, diffs);
11
12expect(oldData).to.eql({
13  // ... Updated data here
14});

revertChange

Examples:

1const newData = {
2  // ... Updated data here
3};
4
5// Sample diffs array
6const diffs = [
7  // ... Diff objects here
8];
9
10changesets.revertChanges(newData, diffs);
11
12expect(newData).to.eql({
13  // ... Original data restored here
14});

jsonPath

The json-diff-ts library uses JSONPath to address specific parts of a JSON document in both the changeset and the application/reversion of changes.

Examples:

1
2const jsonPath = changesets.jsonPath;
3
4cost data = {
5  // ... Some JSON data
6};
7
8const value = jsonPath.query(data, '$.characters[?(@.id=="LUK")].name');
9
10expect(value).to.eql(['Luke Skywalker']);

Contributing

Contributions are welcome! Please follow the provided issue templates and code of conduct.

Contact

Reach out to the maintainer via LinkedIn or Twitter:

• LinkedIn: Christian Glessner
• Twitter: @leitwolf_io

Discover more about the company behind this project: hololux

Release Notes

• v4.0.0: Change naming of flattenChangest and unflattenChanges to atomizeChangeset and unatomizeChangeset; option to set treatTypeChangeAsReplace
• v3.0.1: Fix issue with unflattenChanges when a key has periods
• v3.0.0: Supports CommonJS and ECMAScript Modules. Dependency to lodash-es was replaced with lodash to support both ECMAScript and CommonJS.
• v2.2.0: Fix lodash-es decependency, exclude keys, compare string arrays by value
• v2.1.0: Resolves a problem related to JSON Path filters by replacing the single equal sign (=) with a double equal sign (==). This update maintains compatibility with existing flat changes. Allows to use either '' or '.' as root in the path.
• v2.0.0: json-diff-ts has been upgraded to an ECMAScript module! This major update brings optimizations and enhanced documentation. Additionally, a previously existing issue where all paths were treated as regex has been fixed. In this new version, you'll need to use a Map instead of a Record for regex paths. Please note that this is a breaking change if you were using regex paths in the previous versions.
• v1.2.6: Enhanced JSON Path handling for period-inclusive segments.
• v1.2.5: Patched dependencies; added key name resolution support for key functions.
• v1.2.4: Documentation updates; upgraded TypeScript and Lodash.
• v1.2.3: Dependency updates; switched to TypeScript 4.5.2.
• v1.2.2: Implemented object key resolution functions support.

Acknowledgments

This project takes inspiration and code from diff-json by viruschidai@gmail.com.

License

json-diff-ts is open-sourced software licensed under the MIT license.

The original diff-json project is also under the MIT License. For more information, refer to its license details.