JSON-Patch

fast-json-patch is a small, dependency-free implementation of the JSON Patch (RFC 6902) and JSON Pointer standards for JavaScript and TypeScript. It lets you apply an array of patch operations to a document, validate a sequence of operations before applying them, and compare two object trees to generate the minimal patch that turns one into the other — all useful for syncing partial updates over HTTP PATCH requests instead of shipping whole documents.

Beyond the core apply/compare/validate functions, it ships a duplex “observe” API that watches a live JavaScript object for mutations and synchronously emits the corresponding JSON Patch operations when you call generate(). The library ships as CommonJS, native ESM, and a minified browser bundle from the same TypeScript source, and its test suite runs the official json-patch-tests conformance fixtures to guarantee strict RFC 6902 compliance across Node.js and browsers (Chrome, Firefox, Safari, Edge, IE11).

What You Get

• applyPatch / applyOperation for applying RFC 6902 operations to a document, with optional mutation vs. clone semantics
• compare() to diff two JSON document trees and produce the minimal patch array between them
• validate() to check a sequence of operations against a document and surface a typed JsonPatchError on the first invalid op
• observe()/generate()/unobserve() for a duplex change-tracking API that emits patches as an object mutates
• Full TypeScript typings for every operation kind (add, remove, replace, move, copy, test) as a discriminated union
• Zero runtime dependencies and parallel CommonJS, ESM, and browser-bundle builds from one source tree

Common Use Cases

• Sending partial updates to a REST API via HTTP PATCH instead of re-uploading the whole resource
• Computing and storing an audit trail of changes made to a JSON document over time
• Synchronizing client and server state by diffing local and remote copies of a document
• Implementing optimistic UI updates that can be reverted by inverting a generated patch
• Validating incoming JSON Patch payloads from third parties before applying them to internal state

Under The Hood

Architecture The implementation is split across three flat modules under src/: core.ts holds an operation-dispatch table (objOps/arrOps) mapping each RFC 6902 op name to a dedicated handler function, plus the public applyPatch/applyOperation/compare/validate entry points; duplex.ts layers a WeakMap-based “Mirror” shadow-copy mechanism on top of core.ts to power the observe()/generate() change-tracking API; and helpers.ts provides shared primitives (deep clone, path escaping, equality, the PatchError class) that both other modules import. There is no framework, dependency injection, or plugin system — the public index.ts simply re-exports and composes a default object from all three modules, and the design stays approachable because duplex.ts is the only layer built on top of core.ts rather than the reverse.

Tech Stack Written in TypeScript targeting es5 (tsconfig.json) with zero runtime dependencies, the same src/ tree is compiled three ways: a CommonJS package for Node/bundlers, a native ESM build (index.mjs) produced by a custom tsc-to-mjs.sh conversion script, and a minified UMD bundle via Webpack for direct browser <script> tags. Testing runs on Jasmine through a custom —experimental-modules runner (jasmine-run.mjs) and includes a Sauce Labs pipeline for real cross-browser verification against Chrome, Firefox, Safari, Edge, and IE11.

Code Quality The test suite is extensive — roughly 4,700 lines of Jasmine specs across core, duplex, and validation behavior — and additionally runs the official json-patch-tests conformance fixtures vendored under test/spec/json-patch-tests/ to guarantee strict RFC 6902 compliance. Error handling is explicit via a dedicated PatchError/JsonPatchError class rather than swallowed exceptions, and typings are thorough, modeling each operation kind as a discriminated union with a dedicated typingsSpec.ts test verifying the .d.ts surface compiles. There is no linter or formatter configuration checked in, and CI is a legacy Travis pipeline rather than a modern equivalent, consistent with the repo’s currently low commit activity despite its long history.

API Design The public surface is a small, consistent set of top-level functions (applyPatch, applyOperation, compare, validate, observe, generate) that all operate directly on a plain JS document with no required setup or configuration boilerplate, and a mutateDocument flag lets callers opt into either in-place mutation or a cloned result from the same call. The README documents every function with a runnable example, and both CommonJS and ESM entry points work without a bundler. The main friction point is the observe/generate duplex API, whose WeakMap+Mirror internals are powerful but less discoverable than the straightforward apply/compare functions, and represent an older idiom relative to newer Proxy-based change-tracking approaches.