json-patch-to-crdt 0.1.1 → 0.1.3

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)
 
@@ -165,6 +183,35 @@ If you prefer a non-throwing low-level compile+apply path, use `jsonPatchToCrdtS
 - `"-"` is treated as append for array inserts.
 - `test` operations can be evaluated against `head` or `base` using the `testAgainst` option.
 
+## Runtime JSON Guardrails
+
+By default, runtime inputs are accepted as-is (`jsonValidation: "none"`) for backward compatibility.
+
+You can opt into stricter runtime behavior on `createState`, `applyPatch`/`tryApplyPatch`/`validateJsonPatch`, and `diffJsonPatch`:
+
+- `jsonValidation: "strict"`: reject non-JSON runtime values (for example `NaN`, `Infinity`, and `undefined`).
+- `jsonValidation: "normalize"`: coerce non-JSON values into JSON-safe values.
+  - non-finite numbers become `null`
+  - invalid array elements become `null`
+  - invalid object-property values are omitted
+
+Examples:
+
+```ts
+const strictState = createState(payload as any, {
+  actor: "A",
+  jsonValidation: "strict",
+});
+
+const next = applyPatch(state, patch as any, {
+  jsonValidation: "normalize",
+});
+
+const delta = diffJsonPatch(base as any, target as any, {
+  jsonValidation: "strict",
+});
+```
+
 ### Semantics Modes
 
 - `semantics: "sequential"` (default): applies operations one-by-one against the evolving head (RFC-like execution).
@@ -220,6 +267,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 +275,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 +324,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
@@ -323,8 +416,9 @@ Internals helpers like `jsonPatchToCrdtSafe` and `tryMergeDoc` return the same s
 - `tryApplyPatchInPlace(state, patch, options?)` - Non-throwing in-place apply result.
 - `validateJsonPatch(baseJson, patch, options?)` - Preflight patch validation (non-mutating).
 - `toJson(docOrState)` - Materialize a JSON value from a doc or state.
-- `applyPatch`/`tryApplyPatch` options: `base` expects a prior `CrdtState` snapshot (not a raw doc), plus `semantics` and `testAgainst`.
+- `applyPatch`/`tryApplyPatch` options: `base` expects a prior `CrdtState` snapshot (not a raw doc), plus `semantics`, `testAgainst`, and optional `jsonValidation` runtime guardrails.
 - `PatchError` - Error class thrown for failed patches (`code`, `reason`, `message`, optional `path`/`opIndex`).
+- `JsonValueValidationError` - Error class thrown by strict runtime validation in APIs that accept raw JSON values (for example `createState` and `diffJsonPatch`).
 
 ### Merge helpers
 
@@ -334,7 +428,7 @@ Internals helpers like `jsonPatchToCrdtSafe` and `tryMergeDoc` return the same s
 
 ### Patch helpers
 
-- `diffJsonPatch(baseJson, nextJson, options?)` - Compute a JSON Patch delta between two JSON values.
+- `diffJsonPatch(baseJson, nextJson, options?)` - Compute a JSON Patch delta between two JSON values (`arrayStrategy`, `lcsMaxCells`, and optional `jsonValidation` guardrails).
 
 ### Serialization
 
@@ -389,6 +483,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 +498,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.