JSON-Patch

A leaner and meaner implementation of JSON-Patch. Small footprint. High performance.

With Fast-JSON-Patch, you can:

apply patches
observe for changes (and generate patches when a change is detected)
compare two objects (to obtain the difference)
validate a sequence of patches

Why you should use JSON-Patch

JSON-Patch (RFC6902) is a standard format that allows you to update a JSON document by sending the changes rather than the whole document. JSON Patch plays well with the HTTP PATCH verb (method) and REST style programming.

Mark Nottingham has a nice blog about it.

Footprint

1.22 KB minified and gzipped (3 KB minified)

Performance

Features

Allows you to apply patches on object trees for incoming traffic.
Allows you to freely manipulate object trees and then generate patches for outgoing traffic.
ES7 Object.observe() is used when available.
Tested in IE 8-10, Firefox, Chrome and Node.js

Install

Install the current version (and save it as a dependency):

npm

$ npm install fast-json-patch --save

bower

$ bower install fast-json-patch --save

download as ZIP

Adding to your project

In a web browser

Include json-patch.js if you want support for applying patches or include json-patch-duplex.js if you also want to generate patches.

In Node.js

Call require to get the instance:

var jsonpatch = require('fast-json-patch')

💡 Node.js supports native Object.observe in preview release 0.11.x (and only when started with --harmony_observation flag). With stable versions of Node, a shimmed version of Object.observe is used.

Usage

Applying patches:

var myobj = { firstName:"Albert", contactDetails: { phoneNumbers: [ ] } };
var patches = [
   {op:"replace", path:"/firstName", value:"Joachim" },
   {op:"add", path:"/lastName", value:"Wester" },
   {op:"add", path:"/contactDetails/phoneNumbers/0", value:{ number:"555-123" }  }
   ];
jsonpatch.apply( myobj, patches );
// myobj == { firstName:"Joachim", lastName:"Wester", contactDetails:{ phoneNumbers[ {number:"555-123"} ] } };

Generating patches:

var myobj = { firstName:"Joachim", lastName:"Wester", contactDetails: { phoneNumbers: [ { number:"555-123" }] } };
observer = jsonpatch.observe( myobj );
myobj.firstName = "Albert";
myobj.contactDetails.phoneNumbers[0].number = "123";
myobj.contactDetails.phoneNumbers.push({number:"456"});
var patches = jsonpatch.generate(observer);
// patches  == [
//   { op:"replace", path="/firstName", value:"Albert"},
//   { op:"replace", path="/contactDetails/phoneNumbers/0/number", value:"123"},
//   { op:"add", path="/contactDetails/phoneNumbers/1", value:{number:"456"}}];

Comparing two object trees:

var objA = {user: {firstName: "Albert", lastName: "Einstein"}};
var objB = {user: {firstName: "Albert", lastName: "Collins"}};
var diff = jsonpatch.compare(objA, objB));
//diff == [{op: "replace", path: "/user/lastName", value: "Collins"}]

Validating a sequence of patches:

var obj = {user: {firstName: "Albert"}};
var patches = [{op: "replace", path: "/user/firstName", value: "Albert"}, {op: "replace", path: "/user/lastName", value: "Einstein"}];
var errors = jsonpatch.validate(patches, obj);
if (errors.length == 0) {
 //there are no errors!
}
else {
  for (var i=0; i<errors.length; i++) {
    if (!errors[i]) {
      console.log("Valid patch at index", i, patches[i]);
    }
    else {
      console.error("Invalid patch at index", i, errors[i], patches[i]);
    }
  }
}

Testing

In a web browser

Testing json-patch.js

Load test/SpecRunner.html in your web browser

Testing json-patch-duplex.js

Load test/SpecRunnerDuplex.html in your web browser

Each of the test suite files contains Jasmine unit test suite and Benchmark.js performance test suite.

To run Benchmark.js performance tests, press "Run Tests" button.

In Node.js

Go to directory where you have cloned the repo
Install Jasmine Node.js module by running command npm install jasmine-node -g
Testing json-patch.js

Run command jasmine-node --matchall --config duplex no test/spec/coreSpec.js

Testing json-patch-duplex.js

Run command jasmine-node --matchall --config duplex yes test/spec/coreSpec.js test/spec/duplexSpec.js

API

jsonpatch.apply (`obj` Object, `patches` Array) : boolean

Available in json-patch.js and json-patch-duplex.js

Applies patches array on obj.

If patch was succesfully applied, returns true. Otherwise returns false.

If there was a test patch in patches array, returns the result of the test.

If there was more than one patch in the array, the result of the last patch is returned.