mini-rfc6902

Complete TypeScript implementation of RFC6902 "JavaScript Object Notation (JSON) Patch" (including RFC6901 "JavaScript Object Notation (JSON) Pointer"), for creating and consuming application/json-patch+json documents with custom minified format support for reducing bandwidth, with optional support for using the original verbose syntax.

Also offers "diff" functionality to create patches without Object.observe

Installation

npm install mini-rfc6902

Import into your script

const { create, apply } = require('mini-rfc6902');

or

import { create, apply } from 'mini-rfc6902';

or in browser

<script src="https://unpkg.com/mini-rfc6902"></script>

<script>
  const { create, apply } = rfc6902;
</script>

Usage

Calculate diff between two objects

create({ first: 'Jake' }, { first: 'Jake', last: 'Holland' });
// [['+', '/last', 'Holland']]

Apply a patch

const obj = { first: 'Jake' };
const patch = [['+', '/last', 'Holland']];
apply(obj, patch);
// { first: 'Jake', last: 'Holland' }

API

create(input: any, output: any, opts?: CreateOpts): Patch

Optional CreateOpts argument

opts.eq(x: Exclude<any, null | undefined>, y: Exclude<any, null | undefined>, opts: {skip: () => void}): boolean

User defined equality function, this is called whenever we are comparing two values for equality, if two values are deemed equal we do not traverse deeper inside of it to check for differences

calling the opts.skip() method from within this definition will allow the default equality handlers to run

opts.clone<T>(val: T, opts: {skip: () => void)}): T

User defined clone function, this is called whenever we are returning a value from the input back in a patch, to ensure mutations don't occur.

calling the opts.skip() method from within this definition will allow the default clone handlers to run

opts.diff(input: Exclude<any, null | undefined>, output: Exclude<any, null | undefined>, ptr: Pointer, opts: {skip: () => void}): Patch

User defined diff creation function, this is called whenever we hit a point to compute the difference between two values

calling the opts.skip() method from within this definition will allow the default diff handlers to run

opts.transform

Configure whether to transform the output patch into minify, maximize or serialize, by default all inbuilt operations return minified patches, but user defined diffs may not.

If the user wishes to use serialize, the optional bson dependency is required for both serialize and deserialize

Returns a list of operations (a JSON Patch) comprised of the operations to transform input into output. It attempts to produce the smallest patch, this does not necessarily mean the smallest number of operations, as a full replacement may result in more bytes being sent.

For array transformations we attempt to reduce the size of operations by running an edit distance style algorithm, with support for add, remove, replace, copy, array replace operations.

apply(target: any, patch: Patch, opts?: ApplyOpts): any

Optional ApplyOpts argument

opts.eq(x: Exclude<any, null | undefined>, y: Exclude<any, null | undefined>, opts: {skip: () => void}): boolean

User defined equality function, this is called whenever we are comparing two values for equality, if two values are deemed equal we do not traverse deeper inside of it to check for differences

calling the opts.skip() method from within this definition will allow the default equality handlers to run

opts.clone<T>(val: T, opts: {skip: () => void)}): T

User defined clone function, this is called whenever we are returning a value from the input back in a patch, to ensure mutations don't occur.

calling the opts.skip() method from within this definition will allow the default clone handlers to run

opts.transform

Configure whether to transform the output patch into minify, maximize or serialize, by default all inbuilt operations return minified patches, but user defined diffs may not.

If the user wishes to use serialize, the optional bson dependency is required for both serialize and deserialize

Takes a given patch and applies the operations to a deep copy of the target, it returns the final modified outcome of all the patches.

If any of the operations fail, an error is thrown with details as to what happened.

Homepage

You can find more about this on GitHub.

Contributing

Contributions, issues and feature requests are welcome!

Feel free to check issues page.

Credits

Thanks to rfc6902 for the inspiration

Authors

• Jake Holland

See also the list of contributors who participated in this project.

License

This project is MIT licensed.