edit-json

Edit a textual JSON (not a JavaScript object) for a minimal diff, either programatically or by applying a JSON Patch (RFC6902).

When serializing the result down to a string, it'll resemble the source JSON as much as possible with regards to property order, whitespace (indentation) and flow types (arrays and objects on one line).

Editing JSON is easy, just JSON.parse() and play around, then JSON.stringify(). To apply a JSON Patch, there are several packages out there.

This package focuses not on working with JSON as a JavaScript object, but as its textual representation. The package parses the JSON string (as e.g. from a file) as tokens, builds up a logical representation of it, and then applies transformations to that representation. Whitespace (tabs, spaces) as well as multi-line or single-line arrays/objects are remembered.

To do the same with YAML, check out yaml-diff-patch.

Example

Given:

{
    "x": "non-alphanumerically ordered properties, obviously",
    "foo": [ "same", "line", "array" ],
    "bar": {
        "some": "object"
    }
}

Applying the JSON Patch:

[ {
    "op": "move",
    "from": "/foo",
    "path": "/bar/herenow"
} ]

Produces:

{
    "x": "non-alphanumerically ordered properties, obviously",
    "bar": {
        "herenow": [ "same", "line", "array" ],
        "some": "object"
    }
}

Properties aren't re-ordered ("x" is still first), but by default, it will try to insert properties orderly, such as when creating "herenow" in "bar". It'll be added before "some", "h" < "s". This is done with a best effort, since it's not always possible (the object might have unordered properties).

Note also that the array is not split into multiple lines, which would happen with default JSON.stringify (unless the whole document is one line of course). The source format is kept if possible.

Install

npm i edit-json or yarn add edit-json

This is a pure ESM package, and requires Node.js >=14.13.1

Simple usage

Exports

The package exports parseJson (to be documented) and jsonPatch.

Definition

jsonPatch( json: string, operations: Operations[], options: Options ): string

Applies a list of JSON Patch operations to the source json and returns the new json string.

The options are:

• whitespace ('auto' | 'tabs' | number): Specifies whitespace strategy. Defaults to 'auto'. Force tabs using 'tabs' or spaces using number (e.g. 2 or 4).
• ordered (boolean): Try to insert new properties in order.

RFC6902

By the spec RFC6902, the path property of an operation (and the from in move and copy operations) must be a well-formed JSON Pointer, with encoded path segments. jsonpos exposes helpers for this.

To be more practical for programmatic usage, this package allows not only JSON Pointer strings as paths, but also arrays of (raw unencoded) strings. So you can use e.g. "/foo/bar" or ["foo", "bar"], whichever you prefer. For path segments containing e.g. a slash, it would be "/f~1o~1o/bar" or ["f/o/o", "bar"].