jsondiffpatch

jsondiffpatch computes a structural diff between two JavaScript values and produces a compact JSON delta describing exactly what changed. That delta can be applied back to the original value (patch), used to undo a change (unpatch), or flipped into its own inverse (reverse), making it a building block for undo/redo systems, change auditing, real-time sync, and API response diffing.

Unlike a naive deep-equal diff, it treats arrays specially: it runs an LCS (longest common subsequence) match to detect insertions, deletions, and moves rather than reporting a full array replacement, and it supports an optional character-level text diff (via a bundled diff-match-patch fork) for long string fields so large text changes don’t blow up the delta size. The output delta format is itself plain JSON, so it can be stored, transmitted, or rendered.

A formatter system turns the same delta into different presentations: colored console output (also exposed as a CLI), an HTML visual diff, an annotated-JSON explainer, and RFC 6902 JSON Patch generation/application. The library ships ESM-only and is used both in Node and in the browser.

What You Get

• diff(left, right) / patch(left, delta) / unpatch(right, delta) / reverse(delta) — the core delta lifecycle
• Array-aware diffing via an LCS algorithm that detects moves and insertions instead of replacing whole arrays
• Optional character-level text diffing for long strings, powered by a bundled diff-match-patch implementation
• A jsondiffpatch CLI binary for diffing two JSON files from the terminal with colored console output
• Multiple built-in formatters: console, HTML visual diff, annotated JSON, and RFC 6902 JSON Patch
• A dateReviver helper and clone() utility for working with serialized dates and deep-cloning values
• Configurable objectHash for matching objects inside arrays by identity rather than position

Common Use Cases

• Undo/redo stacks that store deltas instead of full document snapshots
• Auditing and change-history views that show exactly what changed between two versions of a record
• Diffing API responses or config files to detect and visualize drift
• Syncing state between client and server by transmitting deltas instead of full payloads
• Rendering human-readable visual diffs of JSON data in a web UI

Under The Hood

Architecture The library is organized around a Processor that runs named Pipe instances (diff, patch, reverse), each composed of an ordered list of filters (src/processor.ts, src/pipe.ts). A DiffPatcher instance wires up the three pipes with filters from src/filters/ (trivial, dates, texts, nested, arrays) in a fixed precedence order, so diffing an object walks trivial equality first, then falls through to date-, text-, nested-object-, and array-specific filters. This filter-pipeline design means new diff behaviors (a new data type, a new array-matching strategy) can be added as another filter rather than branching inside a monolithic diff function — moves handling (src/moves/delta-to-sequence.ts) and formatters plug into the same context objects (src/contexts/) rather than the pipes themselves. Removing the array or nested filters would collapse the whole system to shallow value-level diffing.

Tech Stack Written in TypeScript, published ESM-only ("type": "module") with tsc as the build step and tslib for helper output. The only runtime dependency is @dmsnell/diff-match-patch (a maintained fork of Google’s diff-match-patch), used for the optional text-diff filter. The repo is an npm workspaces monorepo (biome for lint, a separate packages/diff-mcp package, and browser/console/numeric-plugin demo apps); the published jsondiffpatch package lives at packages/jsondiffpatch and ships a small CLI binary alongside the library entrypoints (., ./with-text-diffs, ./formatters/*).

Code Quality Tests use Vitest with coverage-v8 and live under test/, covering the core diff/patch/reverse cycle against a shared example fixture set, formatter output (HTML, annotated, JSON Patch), and a dedicated prototype-pollution regression spec. Linting and type-checking run via Biome and tsc --noEmit, both wired into prepublishOnly so a broken build or failing test cannot be published. Types are hand-written and exported (Delta, Options, Context variants) rather than inferred, giving consumers a typed delta shape to work with.

What Makes It Unique Most JSON-diff libraries either do shallow key comparison or replace changed arrays wholesale; jsondiffpatch’s LCS-based array diffing with optional move detection and its pluggable formatter system (the same delta renders as console color output, an HTML visual diff, an annotated explainer, or a JSON Patch) are what set it apart, plus the built-in character-level text diff for long strings, which keeps deltas compact even when a single field changes substantially.