Home

Awesome

immutable-json-patch

Immutable JSON patch with support for reverting operations.

Features:

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:

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

CommonJs:

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

Use

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

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

const document = {
  baz: 'qux',
  foo: 'bar'
}
console.log('document', document)

const operations = [
  { op: 'replace', path: '/baz', value: 'boo' },
  { op: 'add', path: '/hello', value: ['world'] },
  { op: 'remove', path: '/foo' }
]
console.log('operations', operations)

const updatedDocument = immutableJSONPatch(document, operations)
console.log('updatedDocument', updatedDocument)
// updatedDocument = {
//   "baz": "boo",
//   "hello": ["world"]
// }

const reverseOperations = revertJSONPatch(document, operations)
console.log('reverseOperations', reverseOperations)
// reverseOperations = [
//   { op: 'add', path: '/foo', value: 'bar' },
//   { op: 'remove', path: '/hello' },
//   { op: 'replace', path: '/baz', value: 'qux' }
// ]

const revertedDocument = immutableJSONPatch(updatedJsonupdatedDocument, reverseOperations)
console.log('revertedDocument', revertedJsonrevertedDocument)
// revertedDocument = {
//   "baz": "qux",
//   "foo": "bar"
// }

API

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

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

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

Where:

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.

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

Where:

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:

declare function parsePath<T>(document: T, path: JSONPointer): JSONPath
declare function parseFrom(path: JSONPointer): JSONPath

declare function parseJSONPointer (pointer: JSONPointer) : JSONPath
declare function compileJSONPointer (path: JSONPath) : JSONPointer
declare function compileJSONPointerProp (pathProp: string | number) : JSONPointer
declare function appendToJSONPointer (pointer: JSONPointer, pathProp: string | number) : JSONPointer
declare function startsWithJSONPointer (pointer: JSONPointer, searchPointer: JSONPointer) : boolean

declare function isJSONPatchOperation(operation: unknown): operation is JSONPatchOperation
declare function isJSONPatchAdd(operation: unknown): operation is JSONPatchAdd
declare function isJSONPatchRemove(operation: unknown): operation is JSONPatchRemove
declare function isJSONPatchReplace(operation: unknown): operation is JSONPatchReplace
declare function isJSONPatchCopy(operation: unknown): operation is JSONPatchCopy
declare function isJSONPatchMove(operation: unknown): operation is JSONPatchMove
declare function isJSONPatchTest(operation: unknown): operation is JSONPatchTest

declare function getIn<T, U = unknown>(object: U, path: JSONPath) : T | undefined
declare function setIn<T, U = unknown, V = unknown> (object: U, path: JSONPath, value: V, createPath = false) : T
declare function updateIn<T, U = unknown, V = unknown> (object: T, path: JSONPath, transform: (value: U) => V) : T
declare function deleteIn<T, U = unknown> (object: U, path: JSONPath) : T
declare function existsIn<T> (document: T, path: JSONPath) : boolean
declare function insertAt<T, U = unknown> (document: T, path: JSONPath, value: U) : T
declare function transform <T, U = unknown, V = unknown, W = unknown> (
  document: U, 
  callback: (document: V, path: JSONPath) => W, path: JSONPath = []
) : 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.