README
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:
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 json = {
baz: 'qux',
foo: 'bar'
}
console.log('json', json)
const operations = [
{ op: 'replace', path: '/baz', value: 'boo' },
{ op: 'add', path: '/hello', value: ['world'] },
{ op: 'remove', path: '/foo' }
]
console.log('operations', operations)
const updatedJson = immutableJSONPatch(json, operations)
console.log('updated json', updatedJson)
// updatedJson = {
// "baz": "boo",
// "hello": ["world"]
// }
const reverseOperations = revertJSONPatch(json, operations)
console.log('reverse operations', reverseOperations)
// reverseOperations = [
// { op: 'add', path: '/foo', value: 'bar' },
// { op: 'remove', path: '/hello' },
// { op: 'replace', path: '/baz', value: 'qux' }
// ]
const revertedJson = immutableJSONPatch(updatedJson, reverseOperations)
console.log('reverted json', revertedJson)
// revertedJson = {
// "baz": "qux",
// "foo": "bar"
// }
API
immutableJSONPatch(json, operations [, options]) => updatedJson
declare function immutableJSONPatch (json: JSONData, operations: JSONPatchDocument, options?: JSONPatchOptions) : JSONData
Where:
json: JSONData
is a JSON documentoperations: JSONPatchDocument
is an array with JSONPatch operationsoptions: JSONPatchOptions
is an optional object allowing passing hooksbefore
andafter
. 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 special, 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 withCustomer
class instances, and instantiate anew Customer
when anadd
operation is performed. And in this library itself, thebefore
callback is used to create inverse operations whilst applying the actual operations on the document.The callbacks look like:
const options = { before: (json: JSONData, operation: PreprocessedJSONPatchOperation) => { console.log('before operation', { json, operation }) // return { json?: JSONData, operation?: PreprocessedJSONPatchOperation } | undefined }, after: (json: JSONData, operation: PreprocessedJSONPatchOperation, previousJson: JSONData) => { console.log('before operation', { json, operation, previousJson }) // return JSONData | undefined } }
When the
before
orafter
callback returns an object with alteredjson
, this will be used to apply the operation. When and alteredoperation
is returned frombefore
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(json, operations) => reverseOperations
declare function revertJSONPatch (json: JSONData, operations: JSONPatchDocument) : JSONPatchDocument
Where:
json: JSONData
is a JSON documentoperations: JSONPatchDocument
is an array with JSONPatch operations
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 internally used functions to work with JSON pointers and to do immutable operations on JSON data:
declare function parseJSONPointer (pointer: string) : JSONPath
declare function compileJSONPointer (path: JSONPath) : string
declare function getIn(json: JSONData, path: JSONPath) : JSONData
declare function setIn(json: JSONData, path: JSONPath, value: JSONData, createPath?: boolean) : JSONData
declare function updateIn(json: JSONData, path: JSONPath, callback: (json: JSONData) => JSONData)
declare function deleteIn(json: JSONData, path: JSONPath) : JSONData
declare function existsIn(json: JSONData, path: JSONPath) : boolean
declare function insertAt(json: JSONData, path: JSONPath, value: JSONData) : JSONData
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.