json8-patch
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/json8-patch package

    1.0.6 • Public • Published

    JSON8 Patch

    Introduction

    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


    Comparison

    module root0 atomic1 mutates2
    json8-patch
    jsonpatch
    jiff
    json-patch
    fast-json-patch  

    Getting started

    npm install json8-patch


    const ooPatch = require("json8-patch");

    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

    demo/playground

    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 buildRevertPatch which offers more flexibility.

    buildRevertPatch

    demo/playground

    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.

    • use pack/unpack with the result of buildRevertPatch 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

    demo/playground

    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

    demo/playground

    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

    demo/playground

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

    Footnotes
    root

    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": "/" }
    ]
    atomic

    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

    mutates

    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.

    Install

    npm i json8-patch

    DownloadsWeekly Downloads

    2,431

    Version

    1.0.6

    License

    ISC

    Unpacked Size

    30.7 kB

    Total Files

    23

    Last publish

    Collaborators

    • sonny