json-patch-to-crdt 0.1.1 → 0.1.2

package/README.md

@@ -30,7 +30,25 @@ npm install json-patch-to-crdt
 
 - Node.js `>= 18` (for package consumers).
 - TypeScript `^5` when type-checking in your project.
-- Bun is optional (used for this repo's own build/test scripts).
+- Bun `1.3.7` is used for this repo's own build/test scripts.
+
+## Testing (Repo)
+
+Run all tests:
+
+```bash
+bun run test
+```
+
+Run targeted domain suites:
+
+```bash
+bun run test:state-core
+bun run test:patch-diff-doc
+bun run test:merge-compaction
+bun run test:replica-session
+bun run test:perf-regression
+```
 
 ## Quick Start (Recommended API)
 
@@ -220,6 +238,7 @@ const fullPatch = crdtToFullReplace(doc);
 ### Array Delta Strategy
 
 By default, arrays are diffed with deterministic LCS edits.
+To prevent pathological `O(n*m)` matrix growth on very large arrays, LCS falls back to atomic array replacement when matrix cells exceed `250_000` by default.
 
 If you want atomic array replacement, pass `{ arrayStrategy: "atomic" }`:
 
@@ -227,10 +246,22 @@ If you want atomic array replacement, pass `{ arrayStrategy: "atomic" }`:
 const delta = diffJsonPatch(baseJson, nextJson, { arrayStrategy: "atomic" });
 ```
 
+If you want to tune the LCS fallback threshold, pass `lcsMaxCells`:
+
+```ts
+const delta = diffJsonPatch(baseJson, nextJson, {
+  arrayStrategy: "lcs",
+  lcsMaxCells: 500_000,
+});
+```
+
 Notes:
 
 - LCS diffs are deterministic but not necessarily minimal.
 - Reorders are expressed as remove/add pairs.
+- LCS complexity is `O(n*m)` in time and memory.
+- `lcsMaxCells` sets the matrix cap: `(base.length + 1) * (next.length + 1)`.
+- Set `lcsMaxCells: Number.POSITIVE_INFINITY` to always allow LCS.
 
 ## Merging
 
@@ -264,6 +295,39 @@ Resolution rules:
 `mergeDoc` is commutative (`merge(a, b)` equals `merge(b, a)`) and idempotent.
 For `mergeState`, pass the local actor explicitly (or as the first argument) so each peer keeps a stable actor ID.
 
+## Tombstone Compaction
+
+Long-lived documents can accumulate object/array tombstones.  
+You can compact causally-stable tombstones with:
+
+```ts
+import { compactStateTombstones } from "json-patch-to-crdt";
+
+const { state: compacted, stats } = compactStateTombstones(state, {
+  stable: { A: 120, B: 98, C: 77 },
+});
+
+console.log(stats);
+// { objectTombstonesRemoved: number, sequenceTombstonesRemoved: number }
+```
+
+For server-side workflows operating on raw docs, use internals:
+
+```ts
+import { compactDocTombstones } from "json-patch-to-crdt/internals";
+
+compactDocTombstones(doc, {
+  stable: checkpointVv,
+  mutate: true, // optional in-place compaction
+});
+```
+
+Safety conditions:
+
+- Only compact at checkpoints that are causally stable across all peers you still merge with.
+- Do not merge compacted replicas with peers that may be behind that checkpoint.
+- Compaction preserves materialized JSON output for the compacted document/state.
+
 ## Serialization
 
 ```ts
@@ -389,6 +453,9 @@ Use `crdtToFullReplace(doc)` from `json-patch-to-crdt/internals`, which emits a
 **Why do array deltas look bigger than expected?**
 LCS diffs are deterministic, not minimal. If you prefer one-op array replacement, use `{ arrayStrategy: "atomic" }`.
 
+**Why did my array delta become a full `replace` even with LCS?**
+For scalability, LCS falls back to atomic replacement when arrays exceed the `lcsMaxCells` guardrail (default `250_000` matrix cells). Increase `lcsMaxCells` to allow larger LCS runs.
+
 **Does LCS guarantee the smallest patch?**
 No. It is deterministic and usually compact, but not guaranteed to be minimal.
 
@@ -401,6 +468,9 @@ By default, `forkState` blocks reusing `origin.clock.actor` because same-actor f
 **Why can my local counter jump after a merge?**
 Array inserts that target an existing predecessor may need to outrank sibling insert dots for deterministic ordering. The library can fast-forward the local counter in constant time to avoid expensive loops, but the resulting counter value may still jump upward when merging with peers that already have high counters.
 
+**How should I run tombstone compaction in production?**
+Treat compaction as a maintenance step after a causal-stability checkpoint (for example, after all replicas acknowledge processing through a specific version vector), then compact and persist the compacted snapshot.
+
 ## Limitations
 
 - The array materialization and insert mapping depend on a base snapshot; concurrent inserts resolve by dot order.