immutable-json-patch

Immutable JSON patch with support for reverting operations.

Features:

• Apply JSON patch operations on a JSON document in an immutable way.
• Create inverse of the JSON patch operations to fully revert applied operations.
• Hook into the operations right before and after they are executed.

Try it out on a playground: https://josdejong.github.io/immutable-json-patch/

See http://jsonpatch.com/ for a clear description of the JSONPatch standard itself.

Install

$ npm install immutable-json-patch

Note that in the lib folder, there are builds for ESM, UMD, and CommonJs.

Load

ESM:

1import { immutableJSONPatch, revertJSONPatch } from 'immutable-json-patch'

CommonJs:

1const { immutableJSONPatch, revertJSONPatch } = require('immutable-json-patch')

Use

Example from http://jsonpatch.com/#simple-example, using immutable-json-patch:

1import { immutableJSONPatch, revertJSONPatch } from 'immutable-json-patch'
2
3const document = {
4  baz: 'qux',
5  foo: 'bar'
6}
7console.log('document', document)
8
9const operations = [
10  { op: 'replace', path: '/baz', value: 'boo' },
11  { op: 'add', path: '/hello', value: ['world'] },
12  { op: 'remove', path: '/foo' }
13]
14console.log('operations', operations)
15
16const updatedDocument = immutableJSONPatch(document, operations)
17console.log('updatedDocument', updatedDocument)
18// updatedDocument = {
19//   "baz": "boo",
20//   "hello": ["world"]
21// }
22
23const reverseOperations = revertJSONPatch(document, operations)
24console.log('reverseOperations', reverseOperations)
25// reverseOperations = [
26//   { op: 'add', path: '/foo', value: 'bar' },
27//   { op: 'remove', path: '/hello' },
28//   { op: 'replace', path: '/baz', value: 'qux' }
29// ]
30
31const revertedDocument = immutableJSONPatch(updatedJsonupdatedDocument, reverseOperations)
32console.log('revertedDocument', revertedJsonrevertedDocument)
33// revertedDocument = {
34//   "baz": "qux",
35//   "foo": "bar"
36// }

API

immutableJSONPatch(document, operations [, options]) => updatedDocument

Apply a list with JSON Patch operations to a JSON document.

1declare function immutableJSONPatch<T, U = unknown> (document: T, operations: JSONPatchDocument, options?: JSONPatchOptions) : U

Where:

• document: T is a JSON document

• operations: JSONPatchDocument is an array with JSONPatch operations

• options: JSONPatchOptions is an optional object allowing passing hooks before and after. With those hooks it is possible to alter the JSON document and/or applied operation before and after this is applied. This allows for example to instantiate classes or additional data structures when applying a JSON patch operation. Or you can keep certain data stats up to date. For example, it is possible to have an array with Customer class instances, and instantiate a new Customer when an add operation is performed. And in this library itself, the before callback is used to create inverse operations whilst applying the actual operations on the document.

  The callbacks look like:

  1const options = {
  2  before: (document: unknown, operation: JSONPatchOperation) => {
  3    console.log('before operation', { document, operation })
  4    // return { document?: unknown, operation?: JSONPatchOperation } | undefined
  5  },
  6
  7  after: (document: unknown, operation: JSONPatchOperation, previousDocument: unknown) => {
  8    console.log('after operation', { document, operation, previousDocument })
  9    // return document | undefined
  10  }
  11}

  When the before or after callback returns an object with altered document, this will be used to apply the operation. When and altered operation is returned from before in an object, this operation will be applied instead of the original operation.

The function returns an updated JSON document where the JSON patch operations are applied. The original JSON document is not changed.

revertJSONPatch(document, operations, options) => reverseOperations

Generate the JSON patch operations that will revert the provided list with JSON Patch operations when applied to the provided JSON document.

1declare function revertJSONPatch<T, U> (document: T, operations: JSONPatchDocument, options?: RevertJSONPatchOptions) : JSONPatchDocument

Where:

• document: T is a JSON document
• operations: JSONPatchDocument is an array with JSONPatch operations
• options: JSONPatchOptions is an optional object allowing passing a hook before. With this hook it is possible to alter the JSON document and/or generated reverseOperations before this is applied.

The function returns a list with the reverse JSON Patch operations. These operations can be applied to the updated JSON document (the output of immutableJSONPatch) to restore the original JSON document.

util functions

The library exposes a set of utility functions and typeguards to work with JSON pointers and to do immutable operations on JSON data:

1declare function parsePath<T>(document: T, path: JSONPointer): JSONPath
2declare function parseFrom(path: JSONPointer): JSONPath
3
4declare function parseJSONPointer (pointer: JSONPointer) : JSONPath
5declare function compileJSONPointer (path: JSONPath) : JSONPointer
6declare function compileJSONPointerProp (pathProp: string | number) : JSONPointer
7declare function appendToJSONPointer (pointer: JSONPointer, pathProp: string | number) : JSONPointer
8declare function startsWithJSONPointer (pointer: JSONPointer, searchPointer: JSONPointer) : boolean
9
10declare function isJSONPatchOperation(operation: unknown): operation is JSONPatchOperation
11declare function isJSONPatchAdd(operation: unknown): operation is JSONPatchAdd
12declare function isJSONPatchRemove(operation: unknown): operation is JSONPatchRemove
13declare function isJSONPatchReplace(operation: unknown): operation is JSONPatchReplace
14declare function isJSONPatchCopy(operation: unknown): operation is JSONPatchCopy
15declare function isJSONPatchMove(operation: unknown): operation is JSONPatchMove
16declare function isJSONPatchTest(operation: unknown): operation is JSONPatchTest
17
18declare function getIn<T, U = unknown>(object: U, path: JSONPath) : T | undefined
19declare function setIn<T, U = unknown, V = unknown> (object: U, path: JSONPath, value: V, createPath = false) : T
20declare function updateIn<T, U = unknown, V = unknown> (object: T, path: JSONPath, transform: (value: U) => V) : T
21declare function deleteIn<T, U = unknown> (object: U, path: JSONPath) : T
22declare function existsIn<T> (document: T, path: JSONPath) : boolean
23declare function insertAt<T, U = unknown> (document: T, path: JSONPath, value: U) : T
24declare function transform <T, U = unknown, V = unknown, W = unknown> (
25  document: U, 
26  callback: (document: V, path: JSONPath) => W, path: JSONPath = []
27) : T 

Develop

To build the library (ESM, CommonJs, and UMD output in the folder lib):

$ npm install 
$ npm run build

To run the unit tests:

$ npm test

To run the linter (eslint):

$ npm run lint

To run the linter, build all, and run unit tests and integration tests:

$ npm run build-and-test

License

Released under the ISC license.