jdiff 1.0.0

A pure Dart implementation of RFC 6902 JSON Patch and RFC 6901 JSON Pointer. Provides diff, patch, and apply operations for JSON-like Dart objects. Ideal for sync apps, offline-first architectures, an [...]

Changelog

All notable changes to jdiff will be documented in this file.

The format follows Keep a Changelog, and this project adheres to Semantic Versioning.

---

1.0.0 — 2026-05-29

Added

Core

• JsonPatch — high-level static API with diff, apply, applyJson, patch, toJsonList, fromJsonList, and six convenience single-operation helpers (add, remove, replace, move, copy, test).
• JsonPointer — complete RFC 6901 implementation:
  • parse() factory with full ~0 / ~1 escape / unescape support.
  • fromTokens() and root constant.
  • get, exists, set, insert, remove navigation methods (all immutable — original document is never mutated).
  • parent, child, isDescendantOf pointer-arithmetic helpers.
  • Round-trip toString() serialisation with correct escaping order.
• All six RFC 6902 operations as const-constructable sealed subclasses: AddOperation, RemoveOperation, ReplaceOperation, MoveOperation, CopyOperation, TestOperation.
• PatchOperation.fromJson / toJson for wire serialisation.
• PatchApplier engine:
  • Atomic application — exceptions bubble up without partial state.
  • Deep copy on copy operations to prevent shared references.
  • Deep equality for test operations.
  • JsonPatchConflictException for illegal move (path is a descendant of from).
• PatchDiffer engine:
  • Object diff: key-by-key add / remove / recursive descent.
  • Array diff: element-wise replace for common prefix, add /- for extra target elements, back-to-front remove for extra source elements.
  • Handles both typed (Map<String, dynamic>) and untyped ({} literal) Dart maps transparently.

Exceptions

• JsonPointerException — pointer syntax / navigation errors.
• JsonPatchException — general patch-application failure with optional operation and path context.
• JsonPatchTestFailedException — test assertion failure, carrying expected and actual values.
• JsonPatchConflictException — move conflict (RFC 6902 §4.4).

Tests — 216 tests across 5 suites

• exceptions_test.dart — all four exception classes (19 tests).
• json_pointer_test.dart — full RFC 6901 coverage (56 tests).
• patch_applier_test.dart — all six operations + atomicity + helpers (47 tests).
• patch_differ_test.dart — no-ops, map diffs, array diffs, type changes, round-trip correctness, serialisation (37 tests).
• rfc6902_compliance_test.dart — all 17 RFC Appendix A cases + extended community edge-case suite (29 tests).

Documentation

• Comprehensive README.md with Quick Start, full API reference, use-cases (offline-first, real-time, optimistic locking, HTTP PATCH), and bandwidth savings analysis.
• Fully documented example/jdiff_example.dart with 6 real-world scenarios.
• Dartdoc comments on every public symbol.

Technical Notes

• Requires Dart SDK >=3.0.0 <4.0.0 — uses sealed classes, pattern matching, abstract final class, and const constructors throughout.
• Zero runtime dependencies — dev_dependencies only (test, lints).
• Strict static analysis via package:lints/recommended.yaml with strict-casts, strict-inference, and strict-raw-types enabled.