JSONG
JSONG passes the entire json-patch-tests suite; see Tests
npm install jsong-patch
// Node.js / io.js / webpack / browserify / ...
var JSONG = require('jsong-patch');
// browsers
// <script src="node_modules/jsong-patch/JSONG.js">
var JSONG = window.JSONG;
For performance concerns JSONG mutates documents; if you'd like JSONG to work on its own shallow copy of your document:
doc = JSONG.clone(doc)
See Clone.
JSON Patch
var doc = {
"name": "John Doe",
"address": {
"street": "...",
"number": 42,
"city": "Neverland"
},
"tags": ["friends", "coworker"],
"age": 25,
"starred": true,
"height": null
});
Patch
doc = JSONG.patch(doc, [
{ "op": "add", "path": "/tags/0", "value": "family" },
{ "op": "remove", "path": "/height" },
{ "op": "replace", "path": "/age", "value": "26" },
{ "op": "move", "from": "/address/city", "path": "/address/country" },
{ "op": "copy", "from": "/starred", "to": "bookmarked" },
{ "op": "test", "path": "/starred", "value": true }
]);
JSONG.patch
returns a document because the JSON Patch specification states that an operation can replace the original document.
JSONG.patch
is atomic, if any operation fails, the document will be restored to its original state and an error will be thrown.
Apply
JSONG.apply
is an alias to JSON.patch
and behave exactly the same.
Revert
If JSONG.patch
is passed with a third argument {revert: true}
it will return an array [doc, items]
.
The items object can be used to revert a patch on a document.
// apply the patch
var patchResult = JSONG.patch(doc, patch, {revert: true});
doc = patchResult[0];
// revert the patch
doc = JSONG.revert(doc, patchResult[1]);
// doc is strictly identical (in the JSON sense) to the original
Operations
add
, copy
, replace
, move
, remove
, test
operations return an array of the form [document, previous, idx]
The first argument is returned for the same reason JSONG.apply
returns a document see Patch
The second argument is the previous value at the specified destination if any, undefined otherwise.
The third argument is the index of the new element. For add
operation only using the JSON Pointer '-' token to push an item at the end of an array.
Add
doc = JSONG.add(doc, '/foo', 'foo')[0]
Remove
doc = JSONG.remove(doc, '/foo')[0];
Replace
doc = JSONG.replace(doc, '/foo', 'foo')[0];
Move
doc = JSONG.move(doc, '/foo', '/bar')[0];
Copy
doc = JSONG.copy(doc, '/foo', '/bar')[0];
Test
doc = JSONG.test(doc, '/foo', 'bar')[0];
Extra operations
Get
JSONG.get(doc, '/foo');
// returns value at /foo
Has
JSONG.has(doc, '/foo');
// returns true if foo property exists, false otherwise
JSONG.Document
JSONG.Document
is a class that abstracts JSON document
It adds many benefit over using JSONG against native object and array.
Per RFC an operation can replace the original document. JSONG.Document
keeps a reference to the document so you don't need to re-declare it for each operation.
var JSONGDoc = new JSONG.Document(doc);
//JSONGDoc.doc === doc
var newDoc = {"something": "else"};
JSONGDoc.replace('', newDoc)
//JSONGDoc.doc === newDoc
Most JSONG methods are available on JSONG.Document
objects; they behave the same except for you don't need to pass a document object and they do not return a document object.
patch, revert, apply
Do not return anything.
add, remove, replace, move, copy, test
Return the previous value at the location if any, undefined otherwise.
get, has
Same return value as their JSONG counterparts.
JSON Pointer
http://tools.ietf.org/html/rfc6901
Parse
JSONG.pointer.parse('/foo/bar/hello');
// returns ['foo', 'bar', 'hello'];
Serialize
JSONG.pointer.serialize(['foo', 'bar', 'hello']);
// returns ('/foo/bar/hello');
JSON Merge Patch
https://tools.ietf.org/html/rfc7396
doc = JSONG.mergePatch(doc, {"name": "Jeanette doe"});
JSON
Clone
Deep clone a JSON object or array
var doc = {
"foo": {
"bar": {}
}
}
var copy = JSONG.clone(doc)
console.log(copy)
//{
// "foo": {
// "bar": {}
// }
//}
copy === doc
//false
Equal
Test for JSON equality between two objects or arrays.
JSONG.equal({foo: 'bar', bar: 'foo'}, {bar: 'foo', foo: 'bar'})
// true
Tests
git submodule update --init --recursive
npm install -g webpack eslint mocha
npm test