JSON8 Patch

JSON Patch RFC 6902 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
  • diff
  • valid
  • 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 mutates documents; if you want it to work on its own shallow copy of your document use:

var oo = require('json8')
doc = oo.clone(doc)

See clone.

↑

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 array of the form [doc, revert].

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

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

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

↑

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

↑

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

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 -g mocha babel browserify
npm test

↑

Contributing

See CONTRIBUTING.md

↑