json-patch-to-crdt 0.2.0 → 0.4.0

package/README.md

@@ -31,10 +31,7 @@ Node.js `>=18`.
 ```ts
 import { applyPatch, createState, toJson, type JsonPatchOp } from "json-patch-to-crdt";
 
-const state = createState(
-  { todos: ["write docs"], done: false },
-  { actor: "client-A" },
-);
+const state = createState({ todos: ["write docs"], done: false }, { actor: "client-A" });
 
 const patch: JsonPatchOp[] = [
   { op: "add", path: "/todos/-", value: "ship package" },
@@ -88,8 +85,31 @@ console.log(delta);
 //   { op: "add", path: "/profile/active", value: true },
 //   { op: "add", path: "/tags/1", value: "b" }
 // ]
+
+const reordered = diffJsonPatch(
+  { tags: ["a", "b", "c"] },
+  { tags: ["b", "a", "c"] },
+  { arrayStrategy: "lcs", emitMoves: true },
+);
+
+console.log(reordered);
+// [{ op: "move", from: "/tags/0", path: "/tags/1" }]
 ```
 
+For array-heavy snapshots, `diffJsonPatch` and `crdtToJsonPatch` support:
+
+- `arrayStrategy: "lcs"`: deterministic index-level array edits using the classic LCS matrix. This is the default.
+- `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 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`
+rewrites.
+
 ## Serialize / Restore State
 
 ```ts
@@ -111,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.
@@ -129,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:
@@ -139,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)`
@@ -155,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