70 lines
9.0 KiB
Markdown
70 lines
9.0 KiB
Markdown
# @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.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [diff](./src/diff/diff.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [diff](./src/diff/diff.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [errors](./src/errors/diff-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [diff-error](./src/errors/diff-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [history](./src/history/history.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [history](./src/history/history.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [operations](./src/operations/operations.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [operations](./src/operations/operations.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [patch](./src/patch/patch.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [patch](./src/patch/patch.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [path](./src/path/path.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [path](./src/path/path.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [utils](./src/utils/utils.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [utils](./src/utils/utils.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
<!-- end:auto-docs --> - [diff](./src/diff/diff.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/diff-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [diff-error](./src/errors/diff-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [history](./src/history/history.md) — <!-- begin:auto-docs --> _(no submodules)_- [history](./src/history/history.md) — <!-- begin:auto-docs --> _(no submodules)_- [operations](./src/operations/operations.md) — <!-- begin:auto-docs --> _(no submodules)_- [operations](./src/operations/operations.md) — <!-- begin:auto-docs --> _(no submodules)_- [patch](./src/patch/patch.md) — <!-- begin:auto-docs --> _(no submodules)_- [patch](./src/patch/patch.md) — <!-- begin:auto-docs --> _(no submodules)_- [path](./src/path/path.md) — <!-- begin:auto-docs --> _(no submodules)_- [path](./src/path/path.md) — <!-- begin:auto-docs --> _(no submodules)_- [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_- [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_- [utils](./src/utils/utils.md) — <!-- begin:auto-docs --> _(no submodules)_- [utils](./src/utils/utils.md) — <!-- begin:auto-docs --> _(no submodules)_- [diff](./src/diff/diff.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/diff-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [diff-error](./src/errors/diff-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [history](./src/history/history.md) — <!-- begin:auto-docs --> _(no submodules)_- [history](./src/history/history.md) — <!-- begin:auto-docs --> _(no submodules)_- [operations](./src/operations/operations.md) — <!-- begin:auto-docs --> _(no submodules)_- [operations](./src/operations/operations.md) — <!-- begin:auto-docs --> _(no submodules)_- [patch](./src/patch/patch.md) — <!-- begin:auto-docs --> _(no submodules)_- [patch](./src/patch/patch.md) — <!-- begin:auto-docs --> _(no submodules)_- [path](./src/path/path.md) — <!-- begin:auto-docs --> _(no submodules)_- [path](./src/path/path.md) — <!-- begin:auto-docs --> _(no submodules)_- [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_- [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_- [utils](./src/utils/utils.md) — <!-- begin:auto-docs --> _(no submodules)_- [utils](./src/utils/utils.md) — <!-- begin:auto-docs --> _(no submodules)_- [diff](./src/diff/diff.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/diff-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [diff-error](./src/errors/diff-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [history](./src/history/history.md) — <!-- begin:auto-docs --> _(no submodules)_- [history](./src/history/history.md) — <!-- begin:auto-docs --> _(no submodules)_- [operations](./src/operations/operations.md) — <!-- begin:auto-docs --> _(no submodules)_- [operations](./src/operations/operations.md) — <!-- begin:auto-docs --> _(no submodules)_- [patch](./src/patch/patch.md) — <!-- begin:auto-docs --> _(no submodules)_- [patch](./src/patch/patch.md) — <!-- begin:auto-docs --> _(no submodules)_- [path](./src/path/path.md) — <!-- begin:auto-docs --> _(no submodules)_- [path](./src/path/path.md) — <!-- begin:auto-docs --> _(no submodules)_- [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_- [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_- [utils](./src/utils/utils.md) — <!-- begin:auto-docs --> _(no submodules)_- [utils](./src/utils/utils.md) — <!-- begin:auto-docs --> _(no submodules)_- [diff](./src/diff/diff.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/diff-error.md) — <!-- begin:auto-docs --> _(no submodules)_ - [diff-error](./src/errors/diff-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [history](./src/history/history.md) — <!-- begin:auto-docs --> _(no submodules)_ - [history](./src/history/history.md) — <!-- begin:auto-docs --> _(no submodules)_- [operations](./src/operations/operations.md) — <!-- begin:auto-docs --> _(no submodules)_ - [operations](./src/operations/operations.md) — <!-- begin:auto-docs --> _(no submodules)_- [patch](./src/patch/patch.md) — <!-- begin:auto-docs --> _(no submodules)_ - [patch](./src/patch/patch.md) — <!-- begin:auto-docs --> _(no submodules)_- [path](./src/path/path.md) — <!-- begin:auto-docs --> _(no submodules)_ - [path](./src/path/path.md) — <!-- begin:auto-docs --> _(no submodules)_- [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_ - [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_- [utils](./src/utils/utils.md) — <!-- begin:auto-docs --> _(no submodules)_ - [utils](./src/utils/utils.md) — <!-- begin:auto-docs --> _(no submodules)_
|
|
## Packages
|
|
|
|
| Module | Description |
|
|
|--------|-------------|
|
|
| [`./path`](src/path/path.md) | RFC 6901 JSON Pointer parsing, formatting, and path utilities |
|
|
| [`./utils`](src/utils/utils.md) | Deep clone, equality, hashing, and document path navigation |
|
|
| [`./operations`](src/operations/operations.md) | RFC 6902 operation types, factories, validation, and inversion |
|
|
| [`./diff`](src/diff/diff.md) | Structural diff producing minimal JSON Patch (index and LCS strategies) |
|
|
| [`./patch`](src/patch/patch.md) | RFC 6902 patch application and revert with OTel integration |
|
|
| [`./history`](src/history/history.md) | Linear undo/redo history manager |
|
|
| [`./sync`](src/sync/sync.md) | Optimistic concurrency sync manager |
|
|
| [`./errors`](src/errors/diff-error.md) | Structured error class with stable code registry |
|
|
|
|
## Quick Start
|
|
|
|
```ts
|
|
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
|
|
|
|
```bash
|
|
bun add @suaveplan/diff
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|