json-patch-to-crdt 0.0.0

package/dist/merge-BpAUNaPe.d.mts

@@ -0,0 +1,419 @@
+//#region src/types.d.ts
+/** Unique identifier for a CRDT replica (peer). */
+type ActorId = string;
+/** A Lamport-style causality marker: `(actor, counter)`. */
+type Dot = {
+  actor: ActorId; /** Strictly increasing per actor. */
+  ctr: number;
+};
+/** Maps each known actor to the highest counter seen from that actor. */
+type VersionVector = Record<ActorId, number>;
+/** A JSON leaf value: `null`, `boolean`, `number`, or `string`. */
+type JsonPrimitive = null | boolean | number | string;
+/** Any JSON-compatible value (primitives, arrays, and plain objects). */
+type JsonValue = JsonPrimitive | JsonValue[] | {
+  [k: string]: JsonValue;
+};
+/** Mutable clock that tracks an actor's identity and monotonic counter. */
+type Clock = {
+  actor: ActorId;
+  ctr: number; /** Generate the next unique dot and advance the counter. */
+  next: () => Dot;
+};
+/** Last-Writer-Wins register: stores a single JSON value tagged with a dot. */
+type LwwReg = {
+  kind: "lww";
+  value: JsonValue;
+  dot: Dot;
+};
+/** Serialized element ID in the form `"actor:counter"`. */
+type ElemId = string;
+/** A single element in an RGA sequence, with tombstone support. */
+type RgaElem = {
+  id: ElemId; /** Predecessor element ID (`"HEAD"` for the first element). */
+  prev: ElemId; /** Whether this element has been logically deleted. */
+  tombstone: boolean; /** The child CRDT node stored at this position. */
+  value: Node; /** Dot used for deterministic ordering among concurrent inserts with the same predecessor. */
+  insDot: Dot;
+};
+/** Replicated Growable Array: an ordered sequence CRDT with tombstones. */
+type RgaSeq = {
+  kind: "seq";
+  elems: Map<ElemId, RgaElem>;
+};
+/** A single entry in an object node: a child node tagged with a dot. */
+type ObjEntry = {
+  node: Node;
+  dot: Dot;
+};
+/** Delete-wins object CRDT: a map of string keys to child nodes. */
+type ObjNode = {
+  kind: "obj";
+  entries: Map<string, ObjEntry>; /** Latest delete dot per key (delete-wins semantics). */
+  tombstone: Map<string, Dot>;
+};
+/** A CRDT node: either an object, an RGA sequence, or a LWW register. */
+type Node = ObjNode | RgaSeq | LwwReg;
+/** JSON-serializable form of an RGA element. */
+type SerializedRgaElem = {
+  id: ElemId;
+  prev: ElemId;
+  tombstone: boolean;
+  value: SerializedNode;
+  insDot: Dot;
+};
+/** JSON-serializable form of any CRDT node. */
+type SerializedNode = {
+  kind: "lww";
+  value: JsonValue;
+  dot: Dot;
+} | {
+  kind: "obj";
+  entries: Record<string, {
+    node: SerializedNode;
+    dot: Dot;
+  }>;
+  tombstone: Record<string, Dot>;
+} | {
+  kind: "seq";
+  elems: Record<string, SerializedRgaElem>;
+};
+/** JSON-serializable form of a CRDT document. */
+type SerializedDoc = {
+  root: SerializedNode;
+};
+/** JSON-serializable form of a clock. */
+type SerializedClock = {
+  actor: ActorId;
+  ctr: number;
+};
+/** JSON-serializable form of a full CRDT state (document + clock). */
+type SerializedState = {
+  doc: SerializedDoc;
+  clock: SerializedClock;
+};
+/**
+ * Internal intent operations produced by compiling RFC 6902 JSON Patch ops.
+ * Each variant maps to a specific CRDT mutation.
+ */
+type IntentOp = {
+  t: "ObjSet";
+  path: string[];
+  key: string;
+  value: JsonValue;
+  mode?: "add" | "replace";
+} | {
+  t: "ObjRemove";
+  path: string[];
+  key: string;
+} | {
+  t: "ArrInsert";
+  path: string[];
+  index: number;
+  value: JsonValue;
+} | {
+  t: "ArrDelete";
+  path: string[];
+  index: number;
+} | {
+  t: "ArrReplace";
+  path: string[];
+  index: number;
+  value: JsonValue;
+} | {
+  t: "Test";
+  path: string[];
+  value: JsonValue;
+};
+/** A single RFC 6902 JSON Patch operation. */
+type JsonPatchOp = {
+  op: "add";
+  path: string;
+  value: JsonValue;
+} | {
+  op: "remove";
+  path: string;
+} | {
+  op: "replace";
+  path: string;
+  value: JsonValue;
+} | {
+  op: "move";
+  from: string;
+  path: string;
+} | {
+  op: "copy";
+  from: string;
+  path: string;
+} | {
+  op: "test";
+  path: string;
+  value: JsonValue;
+};
+/** An array of JSON Patch operations (RFC 6902). */
+type JsonPatch = JsonPatchOp[];
+/** Top-level CRDT document wrapper holding the root node. */
+type Doc = {
+  root: Node;
+};
+/** Combined CRDT state: a document and its associated clock. */
+type CrdtState = {
+  doc: Doc;
+  clock: Clock;
+};
+/** Result from applying a patch for a specific actor using a shared version vector. */
+type ApplyPatchAsActorResult = {
+  /** Updated CRDT state for the actor that produced this patch. */state: CrdtState; /** Updated version vector after applying the patch. */
+  vv: VersionVector;
+};
+/** Result of applying a patch: success or a 409 conflict with a message. */
+type ApplyResult = {
+  ok: true;
+} | {
+  ok: false;
+  code: 409;
+  message: string;
+};
+/** How JSON Patch operations are interpreted during application. */
+type PatchSemantics = "base" | "sequential";
+/**
+ * Options for `applyPatch` / `applyPatchInPlace`.
+ * - `semantics: "base"` maps array indices against a fixed snapshot (current default).
+ * - `semantics: "sequential"` applies operations one-by-one against the evolving head.
+ * - `atomic` applies only to `applyPatchInPlace` (ignored by immutable `applyPatch`).
+ */
+type ApplyPatchOptions = {
+  base?: Doc;
+  testAgainst?: "head" | "base";
+  semantics?: PatchSemantics;
+  atomic?: boolean;
+};
+/** Options for `mergeState`. */
+type MergeStateOptions = {
+  /**
+   * Actor to use for the merged clock.
+   * Defaults to the actor from the first state argument.
+   */
+  actor?: ActorId;
+  /**
+   * Require array sequences to share element lineage before merging.
+   * Defaults to `true`.
+   */
+  requireSharedOrigin?: boolean;
+};
+/** Options for `mergeDoc`. */
+type MergeDocOptions = {
+  /**
+   * Require array sequences to share element lineage before merging.
+   * Defaults to `true`.
+   */
+  requireSharedOrigin?: boolean;
+};
+/** Options for `crdtToJsonPatch` and `diffJsonPatch`. */
+type DiffOptions = {
+  arrayStrategy?: "atomic" | "lcs";
+};
+/**
+ * Internal sentinel key used in `IntentOp` to represent root-level operations.
+ * Namespaced to avoid collision with user data keys.
+ */
+declare const ROOT_KEY = "@@crdt/root";
+//#endregion
+//#region src/state.d.ts
+/** Error thrown when a JSON Patch cannot be applied. Includes a numeric `.code` (409 for conflicts). */
+declare class PatchError extends Error {
+  readonly code: number;
+  constructor(message: string, code?: number);
+}
+/**
+ * Create a new CRDT state from an initial JSON value.
+ * @param initial - The initial JSON document.
+ * @param options - Actor ID and optional starting counter.
+ * @returns A new `CrdtState` containing the document and clock.
+ */
+declare function createState(initial: JsonValue, options: {
+  actor: ActorId;
+  start?: number;
+}): CrdtState;
+/**
+ * Materialize a CRDT document or state back to a plain JSON value.
+ * @param target - A `Doc` or `CrdtState` to materialize.
+ * @returns The JSON representation of the current document.
+ */
+declare function toJson(target: Doc | CrdtState): JsonValue;
+/**
+ * Apply a JSON Patch to the state, returning a new immutable state.
+ * Throws `PatchError` on conflict (e.g. out-of-bounds index, failed test op).
+ * @param state - The current CRDT state.
+ * @param patch - Array of RFC 6902 JSON Patch operations.
+ * @param options - Optional base document and test evaluation mode.
+ * @returns A new `CrdtState` with the patch applied.
+ */
+declare function applyPatch(state: CrdtState, patch: JsonPatchOp[], options?: ApplyPatchOptions): CrdtState;
+/**
+ * Apply a JSON Patch to the state in place, mutating the existing state.
+ * Throws `PatchError` on conflict.
+ * @param state - The CRDT state to mutate.
+ * @param patch - Array of RFC 6902 JSON Patch operations.
+ * @param options - Optional base document and test evaluation mode.
+ */
+declare function applyPatchInPlace(state: CrdtState, patch: JsonPatchOp[], options?: ApplyPatchOptions): void;
+/**
+ * Apply a JSON Patch as a specific actor while maintaining an external version vector.
+ * Returns the updated state and a new version vector snapshot.
+ */
+declare function applyPatchAsActor(doc: Doc, vv: VersionVector, actor: ActorId, patch: JsonPatchOp[], options?: ApplyPatchOptions): ApplyPatchAsActorResult;
+//#endregion
+//#region src/clock.d.ts
+/**
+ * Create a new clock for the given actor. Each call to `clock.next()` yields a fresh `Dot`.
+ * @param actor - Unique identifier for this peer.
+ * @param start - Initial counter value (defaults to 0).
+ */
+declare function createClock(actor: ActorId, start?: number): Clock;
+/** Create an independent copy of a clock at the same counter position. */
+declare function cloneClock(clock: Clock): Clock;
+/**
+ * Generate the next per-actor dot from a mutable version vector.
+ * Useful when a server needs to mint dots for many actors.
+ */
+declare function nextDotForActor(vv: VersionVector, actor: ActorId): Dot;
+/** Record an observed dot in a version vector. */
+declare function observeDot(vv: VersionVector, dot: Dot): void;
+//#endregion
+//#region src/doc.d.ts
+/**
+ * Create a CRDT document from a JSON value, using fresh dots for each node.
+ * @param value - The JSON value to convert.
+ * @param nextDot - A function that generates a unique `Dot` on each call.
+ * @returns A new CRDT `Doc`.
+ */
+declare function docFromJson(value: JsonValue, nextDot: () => Dot): Doc;
+/**
+ * Legacy: create a doc using a single dot with counter offsets for array children.
+ * Prefer `docFromJson(value, nextDot)` to ensure unique dots per node.
+ */
+declare function docFromJsonWithDot(value: JsonValue, dot: Dot): Doc;
+/** Deep-clone a CRDT document. The clone is fully independent of the original. */
+declare function cloneDoc(doc: Doc): Doc;
+/**
+ * Apply compiled intent operations to a CRDT document.
+ * Array indices are resolved against the base document.
+ * @param base - The base document snapshot used for index mapping and test evaluation.
+ * @param head - The target document to mutate.
+ * @param intents - Compiled intent operations from `compileJsonPatchToIntent`.
+ * @param newDot - A function that generates a unique `Dot` per mutation.
+ * @param evalTestAgainst - Whether `test` ops are evaluated against `"head"` or `"base"`.
+ * @param bumpCounterAbove - Optional hook that can fast-forward the underlying counter before inserts.
+ * @returns `{ ok: true }` on success, or `{ ok: false, code: 409, message }` on conflict.
+ */
+declare function applyIntentsToCrdt(base: Doc, head: Doc, intents: IntentOp[], newDot: () => Dot, evalTestAgainst?: "head" | "base", bumpCounterAbove?: (ctr: number) => void): ApplyResult;
+/**
+ * Convenience wrapper: compile a JSON Patch and apply it to a CRDT document.
+ * @param base - The base document for index resolution.
+ * @param head - The target document to mutate.
+ * @param patch - Array of RFC 6902 JSON Patch operations.
+ * @param newDot - A function that generates a unique `Dot` per mutation.
+ * @param evalTestAgainst - Whether `test` ops evaluate against `"head"` or `"base"`.
+ * @param bumpCounterAbove - Optional hook that can fast-forward the underlying counter before inserts.
+ * @returns `{ ok: true }` on success, or `{ ok: false, code: 409, message }` on conflict.
+ */
+declare function jsonPatchToCrdt(base: Doc, head: Doc, patch: JsonPatchOp[], newDot: () => Dot, evalTestAgainst?: "head" | "base", bumpCounterAbove?: (ctr: number) => void): ApplyResult;
+/**
+ * Safe wrapper around `jsonPatchToCrdt` that converts compile-time errors into `409` results.
+ * This function never throws for malformed/invalid patch paths.
+ */
+declare function jsonPatchToCrdtSafe(base: Doc, head: Doc, patch: JsonPatchOp[], newDot: () => Dot, evalTestAgainst?: "head" | "base", bumpCounterAbove?: (ctr: number) => void): ApplyResult;
+/**
+ * Generate a JSON Patch delta between two CRDT documents.
+ * @param base - The base document snapshot.
+ * @param head - The current document state.
+ * @param options - Diff options (e.g. `{ arrayStrategy: "lcs" }`).
+ * @returns An array of JSON Patch operations that transform base into head.
+ */
+declare function crdtToJsonPatch(base: Doc, head: Doc, options?: DiffOptions): JsonPatchOp[];
+/**
+ * Emit a single root `replace` patch representing the full document state.
+ * Use `crdtToJsonPatch(base, head)` for delta patches instead.
+ */
+declare function crdtToFullReplace(doc: Doc): JsonPatchOp[];
+//#endregion
+//#region src/patch.d.ts
+/**
+ * Parse an RFC 6901 JSON Pointer into a path array, unescaping `~1` and `~0`.
+ * @param ptr - A JSON Pointer string (e.g. `"/a/b"` or `""`).
+ * @returns An array of path segments.
+ */
+declare function parseJsonPointer(ptr: string): string[];
+/** Convert a path array back to an RFC 6901 JSON Pointer string. */
+declare function stringifyJsonPointer(path: string[]): string;
+/**
+ * Navigate a JSON value by path and return the value at that location.
+ * Throws if the path is invalid, out of bounds, or traverses a non-container.
+ */
+declare function getAtJson(base: JsonValue, path: string[]): JsonValue;
+/**
+ * Compile RFC 6902 JSON Patch operations into CRDT intent operations.
+ * `move`/`copy` are expanded to `add` + optional `remove`. Array indices
+ * and the `"-"` append token are resolved against the base JSON.
+ * @param baseJson - The base JSON value for resolving paths.
+ * @param patch - Array of JSON Patch operations.
+ * @returns An array of `IntentOp` ready for `applyIntentsToCrdt`.
+ */
+declare function compileJsonPatchToIntent(baseJson: JsonValue, patch: JsonPatchOp[]): IntentOp[];
+/**
+ * Compute a JSON Patch delta between two JSON values.
+ * By default arrays use a deterministic LCS strategy.
+ * Pass `{ arrayStrategy: "atomic" }` for single-op array replacement.
+ * @param base - The original JSON value.
+ * @param next - The target JSON value.
+ * @param options - Diff options.
+ * @returns An array of JSON Patch operations that transform `base` into `next`.
+ */
+declare function diffJsonPatch(base: JsonValue, next: JsonValue, options?: DiffOptions): JsonPatchOp[];
+/** Deep equality check for JSON values (null-safe, handles arrays and objects). */
+declare function jsonEquals(a: JsonValue, b: JsonValue): boolean;
+//#endregion
+//#region src/serialize.d.ts
+/** Serialize a CRDT document to a JSON-safe representation (Maps become plain objects). */
+declare function serializeDoc(doc: Doc): SerializedDoc;
+/** Reconstruct a CRDT document from its serialized form. */
+declare function deserializeDoc(data: SerializedDoc): Doc;
+/** Serialize a full CRDT state (document + clock) to a JSON-safe representation. */
+declare function serializeState(state: CrdtState): SerializedState;
+/** Reconstruct a full CRDT state from its serialized form, restoring the clock. */
+declare function deserializeState(data: SerializedState): CrdtState;
+//#endregion
+//#region src/materialize.d.ts
+/** Recursively convert a CRDT node graph into a plain JSON value. */
+declare function materialize(node: Node): JsonValue;
+//#endregion
+//#region src/merge.d.ts
+/**
+ * Merge two CRDT documents from different peers into one.
+ * By default this requires shared array lineage for non-empty sequences.
+ *
+ * Resolution rules:
+ * - **LwwReg**: the register with the higher dot wins (total order by counter then actor).
+ * - **ObjNode**: entries are merged key-by-key; tombstones use max-dot-per-key.
+ *   If both sides have a live entry for the same key, the entry nodes are merged recursively.
+ *   Delete-wins: if a tombstone dot >= an entry dot, the entry is removed.
+ * - **RgaSeq**: elements from both sides are unioned by element ID.
+ *   If both sides have the same element, tombstone wins (delete bias) and values are merged recursively.
+ * - **Kind mismatch**: the node with the higher "representative dot" wins and replaces the other entirely.
+ */
+declare function mergeDoc(a: Doc, b: Doc, options?: MergeDocOptions): Doc;
+/**
+ * Merge two CRDT states.
+ *
+ * The merged clock keeps a stable actor identity:
+ * - defaults to the actor from the first argument (`a`)
+ * - can be overridden via `options.actor`
+ * - optional `options.requireSharedOrigin` controls merge lineage checks
+ *
+ * The merged counter is lifted to the highest counter already observed for
+ * that actor across both input clocks and the merged document dots.
+ */
+declare function mergeState(a: CrdtState, b: CrdtState, options?: MergeStateOptions): CrdtState;
+//#endregion
+export { PatchSemantics as $, createState as A, Dot as B, createClock as C, applyPatch as D, PatchError as E, ApplyResult as F, JsonPrimitive as G, IntentOp as H, Clock as I, MergeDocOptions as J, JsonValue as K, CrdtState as L, ActorId as M, ApplyPatchAsActorResult as N, applyPatchAsActor as O, ApplyPatchOptions as P, ObjNode as Q, DiffOptions as R, cloneClock as S, observeDot as T, JsonPatch as U, ElemId as V, JsonPatchOp as W, Node as X, MergeStateOptions as Y, ObjEntry as Z, crdtToJsonPatch as _, deserializeState as a, SerializedState as at, jsonPatchToCrdt as b, compileJsonPatchToIntent as c, jsonEquals as d, ROOT_KEY as et, parseJsonPointer as f, crdtToFullReplace as g, cloneDoc as h, deserializeDoc as i, SerializedNode as it, toJson as j, applyPatchInPlace as k, diffJsonPatch as l, applyIntentsToCrdt as m, mergeState as n, RgaSeq as nt, serializeDoc as o, VersionVector as ot, stringifyJsonPointer as p, LwwReg as q, materialize as r, SerializedDoc as rt, serializeState as s, mergeDoc as t, RgaElem as tt, getAtJson as u, docFromJson as v, nextDotForActor as w, jsonPatchToCrdtSafe as x, docFromJsonWithDot as y, Doc as z };