json-patch-to-crdt 0.5.0 → 1.0.0

package/README.md

@@ -104,12 +104,45 @@ For array-heavy snapshots, `diffJsonPatch` and `crdtToJsonPatch` support:
 
 `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.
+`lcsLinearMaxCells` is the matching guardrail for `arrayStrategy: "lcs-linear"` and defaults to `250_000`. 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`. Set `lcsLinearMaxCells: Number.POSITIVE_INFINITY` only when you explicitly want the previous unbounded behavior and accept the CPU cost for large unmatched arrays.
 
 `diffJsonPatch` keeps the existing `add`/`remove`/`replace` output by default. Set
 `emitMoves` and/or `emitCopies` to opt into deterministic RFC 6902 `move`/`copy`
 rewrites.
 
+## Cancellation
+
+Expensive high-level APIs accept an optional `signal` compatible with `AbortSignal`:
+`diffJsonPatch`, `applyPatch`, `applyPatchInPlace`, `tryApplyPatch`, `tryApplyPatchInPlace`,
+`mergeState`, `tryMergeState`, `deserializeState`, and `tryDeserializeState`.
+
+Cancellation is checked at safe points between traversal steps and array-diff loop iterations.
+Immutable APIs either return no result or leave the input state unchanged when cancelled. In-place
+patch application with `atomic: true` keeps the same all-or-nothing behavior; with `atomic: false`,
+operations already applied before cancellation remain applied. Non-throwing APIs return
+`reason: "OPERATION_CANCELLED"` and throwing APIs throw their usual domain error wrappers where
+applicable.
+
+## Performance Gates
+
+CI runs `bun run test:perf-gate` as a fixed-size performance smoke test for
+the hottest paths: array diffing, merge traversal, and sequential patch
+application. These gates are intentionally smaller and more stable than the
+microbenchmarks in `bench/`; they fail with the measured median, sample list,
+threshold, and tuning variable so regressions are actionable.
+
+Run the gate locally before changing hot-path code:
+
+```bash
+bun run test:perf-gate
+```
+
+The default budgets are deliberately generous for shared CI. If a runner needs
+environment-specific tuning, set `PERF_GATE_ARRAY_DIFF_MS`,
+`PERF_GATE_MERGE_TRAVERSAL_MS`, `PERF_GATE_SEQUENTIAL_APPLY_MS`, or
+`PERF_GATE_RUNS`. Use the `bench:*` scripts for deeper investigation and only
+raise a gate after confirming the slowdown is intentional.
+
 ## Serialize / Restore State
 
 ```ts
@@ -118,12 +151,18 @@ import {
   createState,
   deserializeState,
   serializeState,
+  validateSerializedState,
   toJson,
 } from "json-patch-to-crdt";
 
 const state = createState({ counter: 1 }, { actor: "A" });
 const saved = serializeState(state);
 
+const validation = validateSerializedState(saved);
+if (!validation.ok) {
+  throw new Error(`Invalid snapshot at ${validation.error.path}: ${validation.error.message}`);
+}
+
 const restored = deserializeState(saved);
 const next = applyPatch(restored, [{ op: "replace", path: "/counter", value: 2 }]);
 
@@ -135,10 +174,40 @@ Persisted snapshot compatibility:
 
 - `serializeState(...)` emits a versioned envelope.
 - `deserializeState(...)` accepts both the current versioned format and legacy unversioned snapshots.
+- `validateSerializedState(...)` and `validateSerializedDoc(...)` preflight serialized payloads and return typed failures without requiring callers to catch exceptions.
 - 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`.
+`deserializeDoc(...)` helpers. Use the validation-only helpers at trust boundaries
+when you need to reject malformed snapshots before restoring runtime state; they
+walk the serialized payload and CRDT invariants without allocating the runtime
+document maps returned by the deserializers. Use `deserializeState(...)` or
+`deserializeDoc(...)` when you need the CRDT data structures.
+
+### Resource Budgets for Serialized Payloads
+
+When accepting serialized CRDT payloads from network clients, pass
+`resourceBudget` limits to `deserializeState(...)`, `deserializeDoc(...)`, or the
+non-throwing `tryDeserialize*` variants. These limits reject hostile shallow
+payloads before validation allocates large maps or walks excessive element sets.
+
+```ts
+const result = tryDeserializeState(payload, {
+  resourceBudget: {
+    objectEntries: 10_000,
+    sequenceElements: 50_000,
+    serializedElements: 100_000,
+    visitedNodes: 100_000,
+  },
+});
+```
+
+Tune these caps to your product limits. For network-exposed services, start with
+caps near the largest document you intend to accept and lower them where request
+size, latency, or memory limits are tighter. `objectEntries` covers object keys
+and tombstone maps, `sequenceElements` covers RGA sequence elements and JSON
+arrays, `serializedElements` caps the combined serialized breadth, and
+`visitedNodes` caps total decoded node/value traversal.
 
 ## Error Handling
 
@@ -158,6 +227,33 @@ try {
 
 If you prefer non-throwing results, use `tryApplyPatch(...)` / `tryMergeState(...)`.
 
+## Strict Parent Semantics
+
+RFC 6902 requires the parent of an `add` target to already exist. For compatibility
+with older CRDT intent flows, missing array parents can still be materialized for
+`/path/0` and `/path/-` inserts when `strictParents` is explicitly disabled.
+
+Use the named strict profile for RFC 6902 boundaries:
+
+```ts
+import { applyPatch, createState, withStrictRfc6902Parents } from "json-patch-to-crdt";
+
+const base = createState({}, { actor: "A" });
+const head = applyPatch(base, [{ op: "add", path: "/items", value: [] }]);
+
+applyPatch(head, [{ op: "add", path: "/items/0", value: "x" }], withStrictRfc6902Parents({ base }));
+// throws PatchError: base array missing at /items
+```
+
+The error is based on the explicit `base` snapshot used for CRDT array index
+resolution. In this example, `base` predates `/items`; without `{ base }`, the
+current `head` state would be used as the base and the insert would succeed.
+
+Callers that intentionally depend on the legacy auto-create behavior should opt
+in explicitly with `withLegacyMissingArrayParents(...)`. That compatibility
+profile is deprecated because accepting missing parents can hide invalid upstream
+patch generation.
+
 ## Version Vector Helpers
 
 `observedVersionVector(...)` lets you inspect the highest observed counter per
@@ -195,6 +291,7 @@ vector, it returns that vector unchanged.
 
 `createState`, `applyPatch`, `diffJsonPatch`, and `crdtToJsonPatch` accept a
 `jsonValidation` option for callers that may pass runtime values through `any`.
+The default remains `"none"` for backward compatibility with earlier releases.
 
 - `"none"` keeps the current behavior with no extra runtime validation.
 - `"strict"` rejects values that are not valid JSON, including non-finite
@@ -219,13 +316,39 @@ console.log(toJson(state));
 // { keep: true, nested: {}, arr: [null] }
 ```
 
+For new untrusted-input boundaries, prefer the safe convenience helpers instead
+of relying on every call site to remember `jsonValidation`.
+
+```ts
+import {
+  applySafePatch,
+  createNormalizedState,
+  createSafeState,
+  diffSafeJsonPatch,
+} from "json-patch-to-crdt";
+
+const strictState = createSafeState(inputFromApi, { actor: "A" });
+const strictNext = applySafePatch(strictState, patchFromApi);
+const strictDelta = diffSafeJsonPatch(previousSnapshot, nextSnapshot);
+
+const normalizedState = createNormalizedState(inputFromApi, { actor: "A" });
+```
+
+The `Safe` helpers use strict validation and reject invalid runtime values. The
+`Normalized` helpers use normalization and coerce invalid runtime values into
+JSON-safe output. Existing `createState`, `applyPatch`, and `diffJsonPatch`
+calls keep their current compatibility defaults unless you opt into a validation
+mode directly.
+
 ## API Overview
 
 Main exports most apps need:
 
 - `createState(initial, { actor })`
+- `createSafeState(initial, { actor })` / `createNormalizedState(initial, { actor })`
 - `forkState(origin, actor)`
 - `applyPatch(state, patch, options?)`
+- `applySafePatch(state, patch, options?)` / `applyNormalizedPatch(state, patch, options?)`
 - `tryApplyPatch(state, patch, options?)`
 - `mergeState(local, remote, { actor })`
 - `tryMergeState(local, remote, options?)`
@@ -236,7 +359,9 @@ Main exports most apps need:
 - `compactStateTombstones(state, { stable })`
 - `toJson(stateOrDoc)`
 - `diffJsonPatch(baseJson, nextJson, options?)`
+- `diffSafeJsonPatch(baseJson, nextJson, options?)` / `diffNormalizedJsonPatch(baseJson, nextJson, options?)`
 - `serializeState(state)` / `deserializeState(payload)`
+- `validateSerializedState(payload)` / `validateSerializedDoc(payload)`
 - `validateJsonPatch(baseJson, patch, options?)`
 
 Advanced/internal helpers are available from: