JSON8 Patch

JSON Patch RFC 6902 (and diff) implementation for JavaScript.

See jsonpatch.com for more information about JSON Patch.

JSON8 Patch passes the entire json-patch-tests suite; see Tests

• Getting started
• Methods
  • apply
  • patch
  • revert
  • buildPatchFromRevert
  • diff
  • valid
  • concat
  • Operations
    • add
    • remove
    • replace
    • move
    • copy
    • test
  • Extra operations
    • get
    • has
  • Patch size
    • pack
    • unpack
• Tests
• Contributing

Getting started

npm install json8-patch

---

var ooPatch = require('json8-patch');

or

<script src="node_modules/json8-patch/JSON8Patch.js"></script>

var ooPatch = window.JSON8Patch

For performance concerns JSON8 Patch may mutate target document; if you want it to use its own copy use:

var oo = require('json8')
var myDocument = {foo: 'bar'}
var doc = oo.clone(myDocument)

See clone.

JSON8 Patch never mutates patches.

↑

Methods

apply

doc = ooPatch.apply(doc, patch).doc;

ooPatch.apply (and other ooPatch methods) returns an object with a doc property because per specification a patch can replace the original root document.

The operation is atomic, if any of the patch operation fails, the document will be restored to its original state and an error will be thrown.

↑

patch

Alias for apply method.

↑

revert

If the patch or apply method is called with a third argument {reversible: true} it will return an additional value in the form of a revert property.

The revert object can be used to revert a patch on a document.

// apply the patch with the reversible option
var applyResult = ooPatch.apply(doc, patch, {reversible: true});
doc = applyResult.doc

// revert the patch
doc = ooPatch.revert(doc, applyResult.revert).doc;
// doc is strictly identical to the original

See also buildPatchFromRevert which offers more flexibility.

↑

buildPatchFromRevert

Builds a valid JSON Patch from the result of a reversible apply operation. You can then use this patch with apply method to revert a previously applied patch.

var applyResult = ooPatch.apply(doc, patch, {reversible: true});
doc = applyResult.doc

// revert the patch
var revertPatch = ooPatch.buildPatchFromRevert(applyResult.revert) // this is a valid JSON Patch
doc = ooPatch.apply(doc, revertPatch).doc
// doc is strictly identical to the original

Because buildPatchFromRevert + apply offers more flexibility over revert it is preferred.

• use pack/unpack with the result of buildPatchFromRevert making it ideal for storage or transport
• reverse a revert (and so on...) with {reversible: true}
• diff between reverts
• merge multiple reverts into one
• rebase reverts

↑

diff

Returns a diff in the form of a JSON Patch for 2 JSON values.

ooPatch.diff(true, false)
// [{"op": "replace", "path": "", "value": "false"}]

ooPatch.diff([], [])
// []

ooPatch.diff({}, {"foo": "bar"})
// [{"op": "add", "path": "/foo", "value": "bar"}]

↑

valid

Returns true if the patch is valid, false otherwise.

This method only check for JSON Patch semantic. If you need to verify the patch is JSON valid, use oo.valid

ooPatch.valid({})  // false
ooPatch.valid([{}] // false
ooPatch.valid([{op: "foo", path: null, value: undefined}]) // false
ooPatch.valid([{op: "add", path: "/foo"}]) // false

ooPatch.valid([]) // true
ooPatch.valid([{op: "add", path: "/foo", value: "bar"}]) // true

↑

concat

Concats multiple patches into one.

var patch1 = [{op: "add", value: "bar", path: "/foo"}]
var patch2 = [{op: "remove", path: "/foo"}]
var patch = ooPatch.concat(patch1, patch2)

// patch is
[
  {op: "add", value: "bar", path: "/foo"},
  {op: "remove", path: "/foo"}
]

↑

Operations

add, copy, replace, move, remove, test operations return an object of the form {doc: document, previous: value}

• doc is the patched document
• previous is the previous/replaced value

add

doc = ooPatch.add(doc, '/foo', 'foo').doc;

↑

remove

doc = ooPatch.remove(doc, '/foo').doc;

↑

replace

doc = ooPatch.replace(doc, '/foo', 'foo').doc;

↑

move

doc = ooPatch.move(doc, '/foo', '/bar').doc;

↑

copy

doc = ooPatch.copy(doc, '/foo', '/bar').doc;

↑

test

doc = ooPatch.test(doc, '/foo', 'bar').doc;

↑

Extra operations

Those are not part of the standard and are only provided for convenience.

get

ooPatch.get(doc, '/foo');
// returns value at /foo

↑

has

ooPatch.has(doc, '/foo');
// returns true if there is a value at /foo

↑

Patch size

Per specification patches are pretty verbose. JSON8 provides pack and unpack methods to reduce the size of patches and save memory/space/bandwidth.

Size (in bytes) comparaison for the following patch file

[
  {"op": "add", "path": "/a/b/c", "value": ["foo", "bar"]},
  {"op": "remove", "path": "/a/b/c"},
  {"op": "replace", "path": "/a/b/c", "value": 42},
  {"op": "move", "from": "/a/b/c", "path": "/a/b/d"},
  {"op": "copy", "from": "/a/b/c", "path": "/a/b/e"},
  {"op": "test", "path": "/a/b/c", "value": "foo"}
]

format	size (in bytes)
unpacked	313
unpacked gzip	148
packed	151
packed gzip	99

In pratice I'd recommand to use pack/unpack if

• data compression cannot be used on the transport of the patch
• keeping a large amount of patches in memory/on disk

↑

pack

var patch = [
  {"op": "add", "path": "/a/b/c", "value": ["foo", "bar"]},
  {"op": "remove", "path": "/a/b/c"},
  {"op": "replace", "path": "/a/b/c", "value": 42},
  {"op": "move", "from": "/a/b/c", "path": "/a/b/d"},
  {"op": "copy", "from": "/a/b/c", "path": "/a/b/e"},
  {"op": "test", "path": "/a/b/c", "value": "foo"}
];

var packed = ooPatch.pack(patch);

Here is what packed looks like

[
  [0, "/a/b/c", ["foo", "bar"]],
  [1, "/a/b/c"],
  [2, "/a/b/c", 42],
  [3, "/a/b/d", "/a/b/c"],
  [4, "/a/b/e", "/a/b/c"],
  [5, "/a/b/c", "foo"],
]

↑

unpack

var patch = ooPatch.unpack(packed);
// [{...}, {...}, ...]

↑

Tests

npm install mocha browserify
npm test

↑

Contributing

See CONTRIBUTING.md

↑