• 100% coverage of JSON Patch Tests (excluding faulty ones, see below)
• Runs in all modern JavaScript runtimes like Bun, Node.JS, Deno but also Browsers
• TypeScript & CommonJS support, zero dependencies and extremely lightweight

• Usage
• Benchmarks
• Testing & Contributing

A very fast JSONPatch library that is capable of generating diffs and patching existing objects with compatible diffs. The implementation is naive, meaning that it does not handle edge cases like...

• circular references
• using invalid diffs when patching
• using non-supported types, this library only supports string | number | bigint | boolean | undefined | null or nested objects/arrays with those types, the library intentionally does not try to cover Set | RegExp | Symbol, class instances, ...

When doing one of those things wrong, in best case, you will (sometimes) get cryptic errors when patching with invalid diffs, and in worst case you will be stuck in an infinite loop due to a circular reference when diffing.

If you want to diff/patch internally or, in a network environment, synchronize state from an authoritative server to clients whilst leveraging a technology like WebSockets, where you can reliably send in-order patches of state, then this library is for you. You can also feel free to generate diffs with any other library of your choice (as long as it complies with the JSONPatch standards) and only leverage the patch functionality that this library provides, or do the reverse.

Install this library with the package manager of your choice:

bun add ultrapatch      # Bun
npm i ultrapatch        # Node
deno add npm:ultrapatch # Deno

... then simply use the two provided methods like this:

import * as UltraPatch from "ultrapatch";

const original = { a: 1, b: [1, 2] };
const modified = { a: 2, b: [1, 2, 3] };

// returns the list of changes in JSONPatch format
const diff = UltraPatch.diff(original, modified);

// modifies the first argument in-place to apply the changes in the second argument and returns the result (reference to first argument or entirely new object in case you modify at root-level)
const desired = UltraPatch.patch(original, diff);

// desired === { a: 2, b: [1, 2, 3] } === modified

Due to the given constraints that I have set for UltraPatch, this library is able to outperform the currently fastest JSONPatch implementations by orders of magnitude (in best case) in both diffing and patching. This comes at the price of only supporting basic datatypes, not verifying validity of diffs when patching and risking infinite loops if working with objects that include circular references.

For reference, here are all the samples that have been used in the benchmarking process.
Each OriginDiffDestBundle represents the original object, the diff from original <-> modified and the modified object.

To benchmark the diffing, we diff the original from the modified object of each sample.
For the patching, we patch the original with the provided diff of the sample (that has been precomputed).

Disclaimer: I have removed the jiff library from the diff benchmarks due to wrong results that artificially resulted in fast times because jiff simply didn't diff at all and rather outputted "add" operations for the entire destination object.

Tested on:

clk: ~2.97 GHz
cpu: AMD Ryzen 5 5600X 6-Core Processor
runtime: bun 1.3.10 (x64-win32)

summary
  ultrapatch
   4.63x faster than fast-json-patch
   7.63x faster than microdiff
   31.93x faster than jsondiffts
   150.92x faster than rfc6902

summary
  ultrapatch
   2.87x faster than fast-json-patch
   7.22x faster than microdiff
   25.91x faster than jsondiffts
   42.16x faster than rfc6902

Disclaimer: rfc6902 crashed in the following test so its excluded

summary
  ultrapatch
   1.65x faster than fast-json-patch
   4.39x faster than microdiff
   26.76x faster than jsondiffts

summary
  ultrapatch
   1.09x faster than fast-json-patch
   2.05x faster than microdiff
   11.07x faster than jsondiffts
   113.32x faster than rfc6902

In all given benchmarks, UltraPatch outperforms the other major JSONPatch libraries whilst keeping memory usage at a stable low.

summary
  ultrapatch
   1.42x faster than jiff
   1.7x faster than json-joy
   1.72x faster than fast-json-patch
   3.74x faster than rfc6902

summary
  ultrapatch
   1.54x faster than fast-json-patch
   2.02x faster than json-joy
   2.98x faster than jiff
   4.29x faster than rfc6902

summary
  ultrapatch
   1.41x faster than fast-json-patch
   1.65x faster than json-joy
   2.04x faster than jiff
   3.07x faster than rfc6902

summary
  ultrapatch
   1.28x faster than fast-json-patch
   1.67x faster than json-joy
   2.95x faster than rfc6902
   18.5x faster than jiff

UltraPatch also has the upper hand in every patching benchmark.

Feel free to report bugs or issue suggestions for this project! Although supporting more types beyond the aforementioned primitive types is probably outside of the scope of what this project tries to achieve, I would be more than willing to add more in case people want them. Also any findings for further optimizations would be greatly appreciated!

To test and build the library, you need Bun, bun run build builds the JS files and definition types inside /dist which is also the version of UltraPatch that is linked in the benchmarks inside /bench.

With bun test, you can see if your version passes through all tests that I have used when releasing the library. To run the benchmarks, use bun bench:diff and bun bench:patch (or the node equivalents with npm run node:bench:...).