How benjamine/jsondiffpatch works
Project Type and Purpose
• Monorepo for an open-source JavaScript/TypeScript library called jsondiffpatch.
• Provides a core diff/patch engine, multiple formatters (JSON, HTML, console, JSON-Patch, annotated), a plugin-style pipeline for filters, and a small companion package (diff-mcp).
• Ships as both a CLI tool and a browser/Node ESM library.
High-Level File/Package Structure
• .github/workflows/: CI, release, and GitHub Pages deployment pipelines.
• packages/jsondiffpatch/:
• src/contexts/, src/filters/, src/formatters/, src/processor.ts, src/index.ts → core engine, pipes & filters implementation, formatters.
• test/, bin/jsondiffpatch.js → CLI entry point and test suites.
• packages/diff-mcp/: secondary diff/patch package, its own src, tests, and server example.
• demos/: user-facing examples (console, HTML visual diff, plugin demo).
• docs/: API guides (arrays, deltas, formatters, plugins, React).
• Top-level TypeScript configs, package.json (workspace dependencies), lockfile, and license/readme.
Architecture Overview – Main Components
A. Input Layer
• JSON objects or strings (via CLI, browser script, or API call).
• Optional third-party library for text diffs: diff-match-patch.
B. Core Diff Engine
• Central DiffPatcher class (pipes & filters pattern).
• Filters (arrays, nested objects, dates, texts) determine delta entries.
• Produces a delta (compact JSON structure).
C. Patch & Reverse Engine
• Same pipeline concept to apply (patch) or revert (reverse/unpatch) a delta.
D. Formatters
• Plug-in modules (console, html, annotated, jsonpatch, etc.)
• Transform delta + source into human-readable or machine-readable output.
E. CLI & Bundles
• bin/jsondiffpatch.js → CLI wrapper calling core engine + formatters.
• Bundled ESM builds for browser demos (html-demo) and npm package.
F. Demos & Docs
• Demonstrate usage patterns, embed formatters, highlight plugin extension points.
G. CI/CD & Release
• GitHub Actions workflows for build, test, release to npm, and docs site.
Component Relationships and Data Flows
1. User Input (CLI < left.json > right.json or API call)
→ 2. Core Diff Engine (create or default instance)
→ passes through filter chain → outputs delta
→ 3a. Patch/Reverse Module (optionally apply/unapply delta)
→ 3b. Formatter Modules (choose one or multiple)
→ render to console, HTML, annotated JSON, or JSON-Patch.
→ 4. Output (console STDOUT,
in browser, or returned JS object).
• Demos wire Input → Core Engine → Formatter → UI.
• diff-mcp is a thin wrapper around core engine for MC Protocol (metadata-centric).
Architectural Patterns and Principles
• Pipes & Filters: every diff/patch/reverse is a sequence of filter functions.
• Separation of Concerns:
• Core diff logic vs. formatters vs. CLI/bundling.
• Demo code lives outside core package.
• Monorepo Workspace: shared toolchain, isolated packages.
• ESM-only distribution for modern browser and Node.