Neatly Packaged Manuals

    immutable-json-patch
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.1 • Public • Published

    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 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 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 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:

      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 or after callback returns an object with altered json, 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(json, operations) => reverseOperations

    declare function revertJSONPatch (json: JSONData, operations: JSONPatchDocument) : JSONPatchDocument

    Where:

    • json: JSONData is a JSON document
    • operations: 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: 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 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) : 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.

    Install

    npm i immutable-json-patch

    DownloadsWeekly Downloads

    2,556

    Version

    2.0.1

    License

    ISC

    Unpacked Size

    224 kB

    Total Files

    34

    Last publish

    Collaborators

    • josdejong