A common requirement in real-time applications is reliable state synchronization between two parties - usually a client and server - so that both remain consistent as changes occur. There are multiple approaches to this problem, with the simplest one being a full retransmission of the state after each change. This has the apparent downside that it is highly inefficient in systems where updates consistent of many small changes on big states, thus the common method is to transmit partial state representations that encode only the changes since the previous version.
A widely adopted solution to this problem is JSON Patch, a standard defined by the IETF, that builds on the JSON format and has seen broad adoption across the current software ecosystem with a variety of libraries. At its core, JSON Patch represents changes as a flat JSON array of patch operations that must be applied onto the original object in order for it to become the desired object. Fig. 1 illustrates this structure using the example provided on the official jsonpatch.com website:
- add: Adds a value at the specified path; if the path already exists, insert or overwrite based on the container type.
- remove: Removes the value at the specified path.
- replace: Overwrites the value at the specified path.
- move: Moves the value from a source path to a destination path.
- copy: Copies the value from a source path to a destination path.
- test: Verifies that the value at the specified path matches a given value, causing the operation to fail if they differ.
With this understanding, we can mentally reconstruct the changes shown in Fig. 1 to arrive at the same resulting state.
My interest in partial JSON synchronization predates UltraPatch: I first encountered the concept through a blog post by the creator of Microdiff back when it got released, a library that is self-proclaimed to be "the fastest JavaScript data differ", which implements a diffing format inspired by JSON Patch. Out of curiousity, I went ahead and adopted Microdiff in my projects, but quickly came to the realization that the library was missing a key feature: the library was capable of generating diffs, yet lacked the complementary functionality to apply those diffs to a target object. To address this gap, I implemented a simple and naive patching function here: that ultimately evolved into a standalone project maintained by the original author.
More than 3 years later, in early 2025, I imposed a small and fun challenge to myself: I wanted to make the fastest JavaScript library for both diffing and patching, with two explicit constraints: full compliance with the JSON Patch specification and complete coverage of the official test suite. I gave myself a single weekend for start to initial release in order to not over-engineer this.
Embedding a gist for the library source code is a bit impractical, you can
find the source code here.- My library is tailored to environments with controlled and predictable data flow, where invalid objects or malformed patches are not supplied. This strict assumption allows my hot path in the patch function to remain intentionally lenient, avoiding defensive validation logic that would otherwise introduce more branches. Furthermore, support for class instances and non-JSON-native types like "Set" and "RegExp" is omitted (as explained in the README); that minimizes the amount of type checks and removes the need for conversions in both diffing and patching.
- Most JSONPatch libraries rely on recursive function calls when traversing deeply nested objects. This approach allocates an entire stack frame on each recursive function call and introduces the risk of stack overflows for very deep structures. In my approach, I am manually managing a flat stack array to perform depth-first traversal within a tight loop. Although less readable than the recursive approach, this approach has shown to provide better and more consistent performance in my testing.
- The patch function has to provide reliable deep cloning of objects/arrays for copy operations. Whereas many JavaScript JSON Patch implementations rely on "JSON.parse(JSON.stringify(object))" or custom JavaScript deep clone utility functions (like lodash's cloneDeep), I am leveraging the modern and native structuredClone API that is available across browsers since March 2022 and in Node.js since v17 (October 2019) for significantly improved performance.
I have not gone much further beyond applying the aforementioned optimizations, and regardless this was enough to beat some of the major JSONPatch implementations in my benchmarks in both diffing and patching. As of the time of writing, my benchmarks do not include a very deeply nested object where UltraPatch is expected to excel the most. Even so, it is worth acknowledging the competitive results of the fast-json-patch library; if me or anyone else wanted to seek further optimizations, it might be worthwhile to check out their implementation as a reference.
After reaching my initial goal, ensuring functional completeness and passing the official test suite, I published the package to GitHub and npm for public use, and it is also listed on the jsonpatch.com website. Since its release, the package has seen consistent download activity next to the other JSON Patch libraries uploaded on npm, as seen here.