fast-json-patch

What is fast-json-patch?

The fast-json-patch package allows for the observation of changes to a JSON document, generating JSON Patch documents to capture these changes, and applying such patches to JSON documents. It is useful for efficiently synchronizing JSON data between clients and servers or among components of an application.

What are fast-json-patch's main functionalities?

Generating patches

This feature allows for the observation of a JSON document and the generation of a JSON Patch document representing the changes made to the observed document.

const jsonpatch = require('fast-json-patch');
const document = { firstName: 'Albert', contact: { phone: '123' } };
const observer = jsonpatch.observe(document);
document.firstName = 'Joachim';
document.contact.phone = '456';
const patches = jsonpatch.generate(observer);

Applying patches

This feature applies a JSON Patch document to a JSON document, modifying the target document according to the operations described in the patch.

const jsonpatch = require('fast-json-patch');
const document = { firstName: 'Albert', contact: { phone: '123' } };
const patches = [{ op: 'replace', path: '/firstName', value: 'Joachim' }, { op: 'replace', path: '/contact/phone', value: '456' }];
jsonpatch.applyPatch(document, patches);

Validating a sequence of operations

This feature validates a sequence of operations against a JSON document to ensure they can be applied without errors, providing a way to check patches for correctness before application.

const jsonpatch = require('fast-json-patch');
const document = { firstName: 'Albert', contact: { phone: '123' } };
const patches = [{ op: 'replace', path: '/firstName', value: 'Joachim' }, { op: 'add', path: '/lastName', value: 'Wagner' }];
const validationResult = jsonpatch.validate(patches, document);

Other packages similar to fast-json-patch

jsonpatch

Similar to fast-json-patch, jsonpatch also allows for the generation and application of JSON Patch documents. The main difference lies in the implementation details and performance optimizations, with fast-json-patch focusing on speed.

immer

Immer is designed for working with immutable data structures and can be used to generate patches in a way similar to fast-json-patch. However, Immer focuses more on producing the next immutable state given the current state and changes, rather than directly working with JSON Patch documents.

README

JSON-Patch

A leaner and meaner implementation of JSON-Patch. Small footprint. High performance. Also support dual directions! I.e. you can both apply patches and generate patches.

Why you should use JSON-Patch

JSON-Patch (RFC6902) is a new 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

0.5 KB minified and gzipped (1.1 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.
• ES6/7 Object.observe() is used when available.

Roadmap

• A /bin directory will be added with minified versions
• More unit tests

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

Add fast-json-patch to dependencies list in your project's package.json, then run npm install. After installation, you are ready to go with require:

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

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"}}];

Testing

In a web browser

1. Testing json-patch.js

• Load src/patchtest.html in your web browser

1. Testing json-patch-duplex.js

• Load src/test-duplex.html in your web browser

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

To run JSLitmus performance tests, press "Run Tests" button.

In Node.js

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

• Run command jasmine-node --matchall --config duplex no src/test.js

1. Testing json-patch-duplex.js

• Run command jasmine-node --matchall --config duplex yes src/test.js src/test-duplex.js