skills/plugins/document-navigator/docs/foundation/data/diff/README.md

@suaveplan/diff - Zero-dependency RFC 6902 JSON Patch engine with structural diffing, patch application/inversion, linear history manager, sync manager, and rich path utilities

Summary

Zero-dependency RFC 6902 JSON Patch engine for computing, applying, and inverting structural differences between JSON documents. The diff(a, b) function produces a minimal patch using index-based or LCS array strategies; applyPatch applies it; revertPatch undoes it; and invertPatch creates an inverse patch. A HistoryManager provides undo/redo with configurable depth and branch truncation on new edits. A SyncManager handles optimistic concurrency: apply local changes speculatively, then reconcile when the server responds. RFC 6901 JSON Pointer parsing and formatting is exposed as a standalone path module. Use this package for collaborative editing, undo/redo stacks, change-event streams, and any system where you need to track or transmit the delta between two object states rather than the full state itself.

Documentation tree

• diff — (no submodules)
  • diff — (no submodules)
• errors — (no submodules)
  • diff-error — (no submodules)
• history — (no submodules)
  • history — (no submodules)
• operations — (no submodules)
  • operations — (no submodules)
• patch — (no submodules)
  • patch — (no submodules)
• path — (no submodules)
  • path — (no submodules)
• sync — (no submodules)
  • sync — (no submodules)
• utils — (no submodules)
  • utils — (no submodules)

- [diff](./src/diff/diff.md) — _(no submodules)_- [errors](./src/errors/diff-error.md) — _(no submodules)_- [diff-error](./src/errors/diff-error.md) — _(no submodules)_- [history](./src/history/history.md) — _(no submodules)_- [history](./src/history/history.md) — _(no submodules)_- [operations](./src/operations/operations.md) — _(no submodules)_- [operations](./src/operations/operations.md) — _(no submodules)_- [patch](./src/patch/patch.md) — _(no submodules)_- [patch](./src/patch/patch.md) — _(no submodules)_- [path](./src/path/path.md) — _(no submodules)_- [path](./src/path/path.md) — _(no submodules)_- [sync](./src/sync/sync.md) — _(no submodules)_- [sync](./src/sync/sync.md) — _(no submodules)_- [utils](./src/utils/utils.md) — _(no submodules)_- [utils](./src/utils/utils.md) — _(no submodules)_- [diff](./src/diff/diff.md) — _(no submodules)_- [errors](./src/errors/diff-error.md) — _(no submodules)_- [diff-error](./src/errors/diff-error.md) — _(no submodules)_- [history](./src/history/history.md) — _(no submodules)_- [history](./src/history/history.md) — _(no submodules)_- [operations](./src/operations/operations.md) — _(no submodules)_- [operations](./src/operations/operations.md) — _(no submodules)_- [patch](./src/patch/patch.md) — _(no submodules)_- [patch](./src/patch/patch.md) — _(no submodules)_- [path](./src/path/path.md) — _(no submodules)_- [path](./src/path/path.md) — _(no submodules)_- [sync](./src/sync/sync.md) — _(no submodules)_- [sync](./src/sync/sync.md) — _(no submodules)_- [utils](./src/utils/utils.md) — _(no submodules)_- [utils](./src/utils/utils.md) — _(no submodules)_- [diff](./src/diff/diff.md) — _(no submodules)_- [errors](./src/errors/diff-error.md) — _(no submodules)_- [diff-error](./src/errors/diff-error.md) — _(no submodules)_- [history](./src/history/history.md) — _(no submodules)_- [history](./src/history/history.md) — _(no submodules)_- [operations](./src/operations/operations.md) — _(no submodules)_- [operations](./src/operations/operations.md) — _(no submodules)_- [patch](./src/patch/patch.md) — _(no submodules)_- [patch](./src/patch/patch.md) — _(no submodules)_- [path](./src/path/path.md) — _(no submodules)_- [path](./src/path/path.md) — _(no submodules)_- [sync](./src/sync/sync.md) — _(no submodules)_- [sync](./src/sync/sync.md) — _(no submodules)_- [utils](./src/utils/utils.md) — _(no submodules)_- [utils](./src/utils/utils.md) — _(no submodules)_- [diff](./src/diff/diff.md) — _(no submodules)_- [errors](./src/errors/diff-error.md) — _(no submodules)_ - [diff-error](./src/errors/diff-error.md) — _(no submodules)_- [history](./src/history/history.md) — _(no submodules)_ - [history](./src/history/history.md) — _(no submodules)_- [operations](./src/operations/operations.md) — _(no submodules)_ - [operations](./src/operations/operations.md) — _(no submodules)_- [patch](./src/patch/patch.md) — _(no submodules)_ - [patch](./src/patch/patch.md) — _(no submodules)_- [path](./src/path/path.md) — _(no submodules)_ - [path](./src/path/path.md) — _(no submodules)_- [sync](./src/sync/sync.md) — _(no submodules)_ - [sync](./src/sync/sync.md) — _(no submodules)_- [utils](./src/utils/utils.md) — _(no submodules)_ - [utils](./src/utils/utils.md) — _(no submodules)_

Packages

Module	Description
./path	RFC 6901 JSON Pointer parsing, formatting, and path utilities
./utils	Deep clone, equality, hashing, and document path navigation
./operations	RFC 6902 operation types, factories, validation, and inversion
./diff	Structural diff producing minimal JSON Patch (index and LCS strategies)
./patch	RFC 6902 patch application and revert with OTel integration
./history	Linear undo/redo history manager
./sync	Optimistic concurrency sync manager
./errors	Structured error class with stable code registry

Quick Start

import { diff, applyPatch, createHistory, revertPatch } from "@suaveplan/diff";
import type { JsonValue } from "@suaveplan/diff";

let doc: JsonValue = { name: "Alice", age: 30, tags: ["a", "b"] };
const history = createHistory({ maxEntries: 100 });

// Compute and apply a patch
const next: JsonValue = { name: "Alice", age: 31, tags: ["a", "b", "c"] };
const patch = diff(doc, next);
doc = applyPatch(doc, patch).doc;
history.push(patch);

// Undo
const undoPatch = history.undo()!;
const snapshot = { name: "Alice", age: 30, tags: ["a", "b"] }; // pre-patch state
doc = revertPatch(doc, undoPatch, snapshot);

Installation

bun add @suaveplan/diff

License

MIT