jsondiffpatch
=============


Diff & patch JavaScript objects

-----
Live Demo
-----

- min+gzipped < 6KB
- browser (``/public/build/jsondiffpatch.js`) and server (eg. node.js)
- includes google-diff-match-patch for long text diffs (diff at character level)
- smart array diffing using LCS, IMPORTANT NOTE: to match objects inside an array you must provide an `objectHash` function (this is how objects are matched, otherwise a dumb match by position is used). For more details, check Array diff documentation
- reverse a delta
- unpatch (eg. revert object to its original state using a delta)
- simplistic, pure JSON, low footprint delta format
- multiple output formatters:
- html (check it at the Live Demo)
- annotated json (html), makes the JSON delta format self-explained
- console (colored), try running `./node_modules/.bin/jsondiffpatch left.json right.json`
- write your own! check Formatters documentation

Supported platforms
----------------

* Any modern browser and IE8+

![Testling Status](https://ci.testling.com/benjamine/jsondiffpatch)

And you can test your current browser visiting the test page.

* Node.js ![Build Status](http://travis-ci.org/benjamine/jsondiffpatch)

If you want to run tests locally:
` sh
npm i


will test in node.js and phantomjs (headless browser)

npm test

or test on specific browsers (using karma.js)

BROWSERS=chrome,phantomjs npm test
`
Usage
-----

` javascript
// sample data
var country = {
name: "Argentina",
capital: "Buenos Aires",
independence: new Date(1816, 6, 9),
unasur: true
};

// clone country, using dateReviver for Date objects
var country2 = JSON.parse(JSON.stringify(country), jsondiffpatch.dateReviver);

// make some changes
country2.name = "Republica Argentina";
country2.population = 41324992;
delete country2.capital;

var delta = jsondiffpatch.diff(country, country2);

assertSame(delta, {
"name":["Argentina","Republica Argentina"], // old value, new value
"population":["41324992"], // new value
"capital":["Buenos Aires", 0, 0] // deleted
});

// patch original
jsondiffpatch.patch(country, delta);

// reverse diff
var reverseDelta = jsondiffpatch.reverse(delta);
// also country2 can be return to original value with: jsondiffpatch.unpatch(country2, delta);

var delta2 = jsondiffpatch.diff(country, country2);
assert(delta2 === undefined)
// undefined => no difference
`

Array diffing:

` javascript
// sample data
var country = {
name: "Argentina",
cities: [
{
name: 'Buenos Aires',
population: 13028000,
},
{
name: 'Cordoba',
population: 1430023,
},
{
name: 'Rosario',
population: 1136286,
},
{
name: 'Mendoza',
population: 901126,
},
{
name: 'San Miguel de Tucuman',
population: 800000,
}
]
};

// clone country
var country2 = JSON.parse(JSON.stringify(country));

// delete Cordoba
country.cities.splice(1, 1);

// add La Plata
country.cities.splice(4, 0, {
name: 'La Plata'
});

// modify Rosario, and move it
var rosario = country.cities.splice(1, 1)[0];
rosario.population += 1234;
country.cities.push(rosario);

// create a configured instance, match objects by name
var diffpatcher = jsondiffpatch.create({
objectHash: function(obj) {
return obj.name;
}
});

var delta = diffpatcher.diff(country, country2);

assertSame(delta, {
"cities": {
"_t": "a", // indicates this node is an array (not an object)
"1": [
// inserted at index 1
{
"name": "Cordoba",
"population": 1430023
}]
,
"2": {
// population modified at index 2 (Rosario)
"population": [
1137520,
1136286
]
},
"_3": [
// removed from index 3
{
"name": "La Plata"
}, 0, 0],
"_4": [
// move from index 4 to index 2
'', 2, 3]
}
});
`

For more example cases (nested objects or arrays, long text diffs) check `test/examples/`

If you want to understand deltas, see delta format documentation

Installing
---------------

$3

` sh
npm install jsondiffpatch
`

` js
var jsondiffpatch = require('jsondiffpatch').create(options);
`

$3

` sh
bower install jsondiffpatch
`

browser bundles are in the `/public/build` folder (you can re-generate these using `make` or `gulp`, npm test will do that too):
- `jsondiffpatch.js` main bundle
- `jsondiffpatch.full.js` main bundle + google-diff-match-patch library for text diffs
- `jsondiffpatch-formatters.js` builtin formatters (only those useful in a browser)

All these come in minified versions (`.min.js`), and separate sourcemap files.

Options
-------

` javascript
var jsondiffpatch = require('jsondiffpatch').create({
// used to match objects when diffing arrays, by default only === operator is used
objectHash: function(obj) {
// this function is used only to when objects are not equal by ref
return obj._id || obj.id;
},
arrays: {
// default true, detect items moved inside the array (otherwise they will be registered as remove+add)
detectMove: true,
// default false, the value of items moved is not included in deltas
includeValueOnMove: false
},
textDiff: {
// default 60, minimum string length (left and right sides) to use text diff algorythm: google-diff-match-patch
minLength: 60
}
});
`

Visual Diff
----------------

` html











---

`

To see formatters in action check the Live Demo.

For more details check Formatters documentation

Console
--------

` sh


diff two json files, colored output (using chalk lib)

./node_modules/.bin/jsondiffpatch ./left.json ./right.json

or install globally

npm install -g jsondiffpatch

jsondiffpatch ./demo/left.json ./demo/right.json
`

!console_demo!

Plugins
-------

`diff()`, `patch()` and `reverse()`` functions are implemented using Pipes & Filters pattern, making it extremely customizable by adding or replacing filters on a pipe.

Check Plugins documentation for details.