This package moved to a monorepo. https://github.com/sonnyp/JSON8/tree/master/packages/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
module | root0 | atomic1 | mutates2 |
---|---|---|---|
json8-patch | ☑ | ☑ | ☑ |
jsonpatch | ☑ | ☐ | ☑ |
jiff | ☑ | ☐ | ☑ |
json-patch | ☐ | ☐ | ☑ |
fast-json-patch | ☐ | ☐ | ☑ |
npm install json8-patch
var ooPatch = require('json8-patch');
or
<script src="https://github.com/JSON8/patch/raw/master/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.
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.
Alias for apply method.
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 buildRevertPatch which offers more flexibility.
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.
// apply the patch
var applyResult = ooPatch.apply(doc, patch, {reversible: true});
doc = applyResult.doc
// revert the patch
var revertPatch = ooPatch.buildRevertPatch(applyResult.revert) // this is a valid JSON Patch
doc = ooPatch.apply(doc, revertPatch).doc
// doc is strictly identical to the original
Because buildRevertPatch + apply
offers more flexibility over revert
it is preferred.
buildRevertPatch
making it ideal for storage or transport{reversible: true}
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"}]
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
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"}
]
add
, copy
, replace
, move
, remove
, test
operations return an object of the form {doc: document, previous: value}
doc
is the patched documentprevious
is the previous/replaced valuedoc = ooPatch.add(doc, '/foo', 'foo').doc;
doc = ooPatch.remove(doc, '/foo').doc;
doc = ooPatch.replace(doc, '/foo', 'foo').doc;
doc = ooPatch.move(doc, '/foo', '/bar').doc;
doc = ooPatch.copy(doc, '/foo', '/bar').doc;
doc = ooPatch.test(doc, '/foo', 'bar').doc;
Those are not part of the standard and are only provided for convenience.
ooPatch.get(doc, '/foo');
// returns value at /foo
ooPatch.has(doc, '/foo');
// returns true if there is a value at /foo
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
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"],
]
var patch = ooPatch.unpack(packed);
// [{...}, {...}, ...]
npm install mocha browserify
npm test
See CONTRIBUTING.md
Refers to the library ability to replace/remove root (/) on your target.
Lack of this ability makes the library unable to comply with the specification and will result in unknown/inconsistent states for your target documents.
[
{"op": "replace", "path": "/", "value": "{}"},
{"op": "remove", "path": "/"}
]
Refers to the library ability to revert successful patch operations after a failure on the mutated target.
Lack of this ability makes the library unable to comply with the specification and will result in unknown/inconsistent states for your target documents.
https://tools.ietf.org/html/rfc6902#section-5
Refers to the ability of the library to mutates the target document.
It is best to choose a library which mutate the target document because it leaves you with the choice of creating a shallow copy first.