docs: overhaul README for v6 with API reference and collaborative editing focus

[ricokahler]

This PR is the first in a series of changes for the upcoming v6 release of @sanity/diff-patch. It introduces a comprehensive overhaul of the README.md to better reflect the library's capabilities, particularly its focus on generating conflict-resistant patches for collaborative editing environments, and to provide clearer, more developer-friendly documentation.

Key Changes to the README:

• Updated Core Messaging & New "Objectives" Section:
  • The README now leads with the library's primary goal: generating Sanity patch mutations by comparing two documents/values, creating conflict-resistant patches designed for collaborative editing.
  • A new "Objectives" section clearly outlines the library's design principles:
    • Conflict-resistant patches
    • Performance (optimized for real-time, per-keystroke generation)
    • Intent preservation
    • Reliability
• Comprehensive API Reference:
  • Updated documentation for diffPatch(source, target, options?), clarifying parameters (using source and target) and options.
  • Introduces and documents the new diffValue(source, target, basePath?) function, allowing patch generation for arbitrary values without a document wrapper. Includes examples for both.
• New "Collaborative Editing Example":
  • A detailed example illustrates how diffPatch preserves user intent and minimizes conflicts in a scenario where two users simultaneously edit different aspects of the same document (one reorders paragraphs and fixes a typo, while the other improves text content). The example shows how both sets of changes can be successfully merged.
• New "Technical Details" Section: This section provides deeper insights into:
  • String Diffing with diff-match-patch:
    • Explains the automatic selection criteria for using diff-match-patch vs. a simple set (document size limit, change ratio threshold, small document optimization, system key protection).
    • Includes performance rationale based on testing of the underlying @sanity/diff-match-patch library.
    • Migration from v5: Clearly states that the v5 lengthThresholdAbsolute and lengthThresholdRelative options for diffMatchPatch have been removed in v6 in favor of new, tested defaults that provide consistent performance.
  • Array Handling: Details how keyed arrays (using _key) and index-based arrays are diffed, and how undefined values in arrays are converted to null.
  • System Keys: Lists top-level document keys (_id, _type, _createdAt, _updatedAt, _rev) that are ignored during diffing.
  • Error Handling: Summarizes common error scenarios (missing document ID, immutable _type, multi-dimensional arrays, invalid revision).
• Improved Structure and Readability: The entire README has been reorganized for better clarity, flow, and to serve as a more robust reference document.

Motivation:

The primary motivation for this overhaul is to prepare for the v6 release by:

• Clearly communicating the library's strengths in collaborative editing.
• Providing up-to-date and comprehensive API documentation for both existing and new functionalities.
• Offering practical examples and technical details to help developers understand and effectively use the library.

This updated README aims to be a valuable resource for anyone using @sanity/diff-patch, especially as we move towards v6.

[ricokahler]

• docs: overhaul README for v6 with API reference and collaborative editing focus #45 👈 (View in Graphite)
• refactor: rename itemA/itemB to source/target #44
• refactor: simplify diffItem control flow #43
• feat: add key-based reordering support for keyed object arrays #41
• refactor: preserve order in patch serialization #42 : 1 other dependent PR (#40 )
• feat!: replace diffItem with diffValue #39
• feat!: remove undefined-to-null conversion warnings and simplify internal APIs #38
• refactor: simplify array unset logic by removing revision lock check #37
• feat!: replace configurable DMP with perf-based heuristics #36
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[rexxars]

Had to read the PR to figure this one out; this isn't about how much a string has changed, but about how much the difference in length the string has. Did you determine that this was significant enough to warrant this behavior? I'm curious on prepend/append operations (eg paste something new at the end) whether it would be preferable to use a DMP, if performance is reasonable enough.

Suggested change

	- **Change ratio threshold**: If >40% of text changes, uses `set` (indicates replacement vs. editing)
	- **Change ratio threshold**: If length of text changes >40%, uses `set` (indicates replacement vs. editing)

[ricokahler]

Merge activity

• Jun 13, 8:01 PM UTC: @ricokahler merged this pull request with Graphite.