@stackomate/json-diff

json-diff

@stackomate/json-diff unites two widely-used packages, fast-json-patch and diff, to produce a succint JSON Patch from two JSON objects.

Differences (pun intended)

• In contrast with fast-json-patch, @stackomate/json-diff will also attempt to track moved items in arrays. This will often generate a JSON patch with a smaller payload and more easily interpreted by humans.

For example, given a baseJSON and a resultJSON defined below, both packages will produce valid patches, although fast-json-patch will focus on performance while @stackomate/json-diff will focus on simplifying the final JSON patch object:

const baseJSON = [
    'a',
    'b',
    'c'
];

const resultJSON = [
    'b',
    'c',
    'd'
];

// fast-json-patch

import { compare } from 'fast-json-patch';
console.log(compare(baseJSON, resultJSON));

// [ 
//     { op: "replace", path: "/2", value: "d" }
//     { op: "replace", path: "/1", value: "c" }
//     { op: "replace", path: "/0", value: "b" }
// ]

// @stackomate/json-diff
import {jsonDiff} from '@stackomate/json-diff';
console.log(jsonDiff(baseJSON, resultJSON));

// [ 
//     { op: 'remove', path: '/0' }, 
//     { op: 'add', path: '/2', value: 'd' } 
// ]

Usage

• For basic usage with primitives only, call the jsonDiff method with the initial and final json objects:

jsonDiff(initialJSON, finalJSON)

• Recommended: Add a trackFunction to help our algorithm identify nested objects in arrays. For example, an id field is commonly used as key:

jsonDiff(initialJSON, finalJSON, (item) => item?.id)

• Important:
  • All keys returned by the function should be unique;
  • This function should aim to return a value !== undefined; Returning undefined for any of the analyzed values will fallback to the default behavior from fast-json-patch for all items in the same array.