json-patch-to-crdt 0.3.0 → 0.4.0

package/README.md

@@ -102,7 +102,9 @@ For array-heavy snapshots, `diffJsonPatch` and `crdtToJsonPatch` support:
 - `arrayStrategy: "lcs-linear"`: deterministic index-level array edits using a lower-memory linear-space LCS traversal.
 - `arrayStrategy: "atomic"`: replace the whole array with a single patch operation.
 
-`lcsMaxCells` only applies to `arrayStrategy: "lcs"`. If the classic LCS matrix would exceed the configured cap, the diff falls back to an atomic array `replace`. Use `lcs-linear` when you want index-level patches for larger arrays without allocating the full matrix, but note that it still has `O(n * m)` time complexity and does not automatically fall back for very large unmatched windows.
+`lcsMaxCells` only applies to `arrayStrategy: "lcs"`. If the classic LCS matrix for the trimmed unmatched window would exceed the configured cap, the diff falls back to an atomic array `replace`.
+
+`lcsLinearMaxCells` is the matching opt-in guardrail for `arrayStrategy: "lcs-linear"`. It uses the same trimmed unmatched-window estimate, but caps worst-case runtime instead of matrix allocation. When the cap is exceeded, `lcs-linear` also falls back to an atomic array `replace`. If you do not set `lcsLinearMaxCells`, `lcs-linear` keeps its previous behavior and will continue to run without an automatic fallback.
 
 `diffJsonPatch` keeps the existing `add`/`remove`/`replace` output by default. Set
 `emitMoves` and/or `emitCopies` to opt into deterministic RFC 6902 `move`/`copy`
@@ -129,6 +131,15 @@ console.log(toJson(next));
 // { counter: 2 }
 ```
 
+Persisted snapshot compatibility:
+
+- `serializeState(...)` emits a versioned envelope.
+- `deserializeState(...)` accepts both the current versioned format and legacy unversioned snapshots.
+- Future envelope versions are rejected until an explicit migration path is added.
+
+The same compatibility contract applies to the lower-level `serializeDoc(...)` and
+`deserializeDoc(...)` helpers exported from `json-patch-to-crdt/internals`.
+
 ## Error Handling
 
 `applyPatch` throws `PatchError` when a patch cannot be applied.
@@ -147,6 +158,67 @@ try {
 
 If you prefer non-throwing results, use `tryApplyPatch(...)` / `tryMergeState(...)`.
 
+## Version Vector Helpers
+
+`observedVersionVector(...)` lets you inspect the highest observed counter per
+actor from either a `Doc` or a `CrdtState`. Use `mergeVersionVectors(...)` to
+union peer observations, and `intersectVersionVectors(...)` when you need a
+causally-stable checkpoint that every replica has already seen.
+
+```ts
+import {
+  compactStateTombstones,
+  intersectVersionVectors,
+  mergeVersionVectors,
+  observedVersionVector,
+  versionVectorCovers,
+} from "json-patch-to-crdt";
+
+const seenByReplicaA = observedVersionVector(replicaA);
+const seenByReplicaB = observedVersionVector(replicaB);
+
+const mergedCheckpoint = mergeVersionVectors(seenByReplicaA, seenByReplicaB);
+const stableCheckpoint = intersectVersionVectors(seenByReplicaA, seenByReplicaB);
+
+if (versionVectorCovers(mergedCheckpoint, stableCheckpoint)) {
+  const compacted = compactStateTombstones(state, { stable: stableCheckpoint });
+}
+```
+
+Use `mergeVersionVectors(...)` for sync-style "what has this cluster observed?"
+bookkeeping. Use `intersectVersionVectors(...)` for tombstone compaction
+checkpoints, because compaction is only safe once every live peer covers the
+same delete dots. If you call `intersectVersionVectors(...)` with a single
+vector, it returns that vector unchanged.
+
+## Runtime JSON Validation
+
+`createState`, `applyPatch`, `diffJsonPatch`, and `crdtToJsonPatch` accept a
+`jsonValidation` option for callers that may pass runtime values through `any`.
+
+- `"none"` keeps the current behavior with no extra runtime validation.
+- `"strict"` rejects values that are not valid JSON, including non-finite
+  numbers, `undefined`, and non-plain objects such as `Date`, `Map`, `Set`,
+  `RegExp`, typed arrays, and class instances.
+- `"normalize"` coerces invalid values into JSON-safe output. Non-finite
+  numbers become `null`. Non-plain objects also become `null` at the root or
+  inside arrays, and are omitted from object properties.
+
+```ts
+import { createState, toJson } from "json-patch-to-crdt";
+
+const unsafeInput = {
+  keep: true,
+  nested: { when: new Date("2020-01-01") },
+  arr: [new Uint8Array([1, 2, 3])],
+} as any;
+
+const state = createState(unsafeInput, { actor: "A", jsonValidation: "normalize" });
+
+console.log(toJson(state));
+// { keep: true, nested: {}, arr: [null] }
+```
+
 ## API Overview
 
 Main exports most apps need:
@@ -157,6 +229,11 @@ Main exports most apps need:
 - `tryApplyPatch(state, patch, options?)`
 - `mergeState(local, remote, { actor })`
 - `tryMergeState(local, remote, options?)`
+- `observedVersionVector(stateOrDoc)`
+- `mergeVersionVectors(...vectors)`
+- `intersectVersionVectors(...vectors)`
+- `versionVectorCovers(observed, required)`
+- `compactStateTombstones(state, { stable })`
 - `toJson(stateOrDoc)`
 - `diffJsonPatch(baseJson, nextJson, options?)`
 - `serializeState(state)` / `deserializeState(payload)`
@@ -173,6 +250,7 @@ import { crdtToJsonPatch, applyPatchAsActor } from "json-patch-to-crdt/internals
 - Arrays use a CRDT sequence internally; concurrent inserts are preserved.
 - Patches are interpreted relative to a snapshot (RFC-style sequential execution by default).
 - Merge assumes replicas come from the same origin state (use `forkState`).
+- Persisted CRDT snapshots currently use envelope version `1`; legacy unversioned snapshots remain readable.
 
 ## License