json-patch-to-crdt 0.1.0 → 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)
 
@@ -64,6 +82,7 @@ import { applyPatch, createState, forkState, mergeState, toJson } from "json-pat
 const origin = createState({ count: 0, items: ["a"] }, { actor: "origin" });
 
 // Fork shared-origin replicas with local actor identities.
+// Actor IDs must be unique per live peer (same-actor reuse is rejected by default).
 const peerA = forkState(origin, "A");
 const peerB = forkState(origin, "B");
 
@@ -219,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" }`:
 
@@ -226,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
 
@@ -263,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
@@ -315,7 +380,7 @@ Internals helpers like `jsonPatchToCrdtSafe` and `tryMergeDoc` return the same s
 ### State helpers
 
 - `createState(initial, { actor, start? })` - Create a new CRDT state from JSON.
-- `forkState(origin, actor)` - Fork a shared-origin replica with a new local actor ID.
+- `forkState(origin, actor, options?)` - Fork a shared-origin replica with a new local actor ID. Reusing `origin` actor IDs is rejected by default (`options.allowActorReuse: true` to opt in explicitly).
 - `applyPatch(state, patch, options?)` - Apply a patch immutably, returning a new state (`semantics: "sequential"` by default).
 - `applyPatchInPlace(state, patch, options?)` - Apply a patch by mutating state in place (`atomic: true` by default).
 - `tryApplyPatch(state, patch, options?)` - Non-throwing immutable apply (`{ ok: true, state }` or `{ ok: false, error }`).
@@ -388,15 +453,24 @@ 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.
 
 **How do I merge states from two peers?**
 Use `forkState(origin, actor)` to create each peer from the same origin, then `mergeState(local, remote, { actor: localActorId })`. Each peer should keep a stable unique actor ID across merges. See the [Multi-Peer Sync](#multi-peer-sync) example above.
 
+**Why did `forkState` throw about actor uniqueness?**
+By default, `forkState` blocks reusing `origin.clock.actor` because same-actor forks can mint duplicate dots and produce order-dependent merges. If you intentionally need same-actor cloning, pass `forkState(origin, actor, { allowActorReuse: true })`.
+
 **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.