json-touch-patch

Immutable JSON Patch implementation based on RFC 6902

Features

• Immutable: The original JSON is not update. The patches apply to a new JSON.
• Touch: The patches create a new object if it includes some changes into child elements.
• Rollback: If error occurs, all patches are rejected. Return the original JSON.
• Customizable: You can add custom operator using the operator API. → Wiki
• Maybe, these features are suitable to operate store in React and Redux architecture.

Installation

$ npm install --save json-touch-patch

API

• patch(prevObject: object, patches: object[], [ opts: object ]): object
  • opts.custom: object custom operator definition.
  • opts.partial: boolean not reject patches if error occurs (partial patching)
  • opts.strict: boolean throw an exception if error occurs
  • opts.error: object point to a cause patch if error occurs
  • returns nextObject: object

Quick example

1const patch = require("json-touch-patch");
2
3const prevObject = { "baz": "qux", "foo": "bar" };
4const patches = [
5  { "op": "replace", "path": "/baz", "value": "boo" },
6];
7const nextObject = patch(prevObject, patches);
8// → { "baz": "boo", "foo": "bar" }
9//              |
10//             replaced
11
12console.log(prevObject);
13// → { "baz": "qux", "foo": "bar" }
14//              |
15//             not changed

How to apply patches

add

1const patches = [
2  { op: "add", path: "/matrix/1/-", value: 9 },
3];

Return a new JSON. It contains shallow-copied elements that have some changes into child elements. And it contains original elements that are not updated any.

1assert(prevObject.matrix[0] === nextObject.matrix[0]);
2assert(prevObject.matrix[1] !== nextObject.matrix[1]);
3assert(prevObject.matrix[2] === nextObject.matrix[2]);

remove

1const patches = [
2  { op: "remove", path: "/matrix/1" },
3];

Return a new JSON. It contains shallow-copied elements that have some changes into child elements. And it contains original elements that are not updated any.

1assert(prevObject.matrix[0] === nextObject.matrix[0]);
2assert(prevObject.matrix[1] !== nextObject.martix[1]);
3assert(prevObject.matrix[2] === nextObject.matrix[1]);

replace

1const patches = [
2  { op: "replace", path: "/matrix/1/1", value: 9 },
3];

Return a new JSON. It contains shallow-copied elements that have some changes into child elements. And it contains original elements that are not updated any.

1assert(prevObject.matrix[0] === nextObject.matrix[0]);
2assert(prevObject.matrix[1] !== nextObject.matrix[1]);
3assert(prevObject.matrix[2] === nextObject.matrix[2]);

replace (no changes)

1const patches = [
2  { op: "replace", path: "/matrix/1/1", value: 4 },
3];

Return the original JSON. Because all elements are not changed.

prevObject.matrix[1][1] is already 4. So, this patch is need not to update any.

1assert(prevObject === nextObject);

move

1const patches = [
2  { op: "move", from: "/matrix/1", path: "/matrix/2" },
3];

Return a new JSON. [op:move] works as [op:get(from)] -> [op:remove(from)] -> [op:add(path)].

1assert(prevObject.matrix[0] === nextObject.matrix[0]);
2assert(prevObject.matrix[1] === nextObject.martix[2]);
3assert(prevObject.matrix[2] === nextObject.matrix[1]);

copy

1const patches = [
2  { op: "copy", from: "/matrix/1", path: "/matrix/1" },
3];

Return a new JSON. [op:copy] works as [op:get(from)] -> [op:add(path)].

1assert(prevObject.matrix[0] === nextObject.matrix[0]);
2assert(prevObject.matrix[1] === nextObject.martix[1]);
3assert(prevObject.matrix[1] === nextObject.martix[2]);
4assert(prevObject.matrix[2] === nextObject.matrix[3]);

test failed

1const patch = [
2  { op: "add" , path: "/matrix/1/-", value: 9 },
3  { op: "test", path: "/matrix/1/1", value: 0 },
4];

Return the original JSON. Because a test op is failed. All patches are rejected.

prevObject.matrix[1][1] is not 0 but 4. So, this test is failed.

1assert(prevObject === nextObject);

invalid patch

1const json = [
2  { op: "replace", path: "/matrix/1/100", value: 9 },
3];

Return the original JSON. Because all patches are rejected when error occurs.

prevObject.matrix[1][100] is not defined. So, this patch is invalid.

1assert(prevObject === nextObject);

License

MIT