jsong-patch v0.1.0

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

http://jsonpatch.com/

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