json-patch-to-crdt 0.0.0 → 0.1.1

package/dist/{merge-QmPXxE6_.d.ts → merge-DQ_KDtnE.d.mts}

@@ -161,33 +161,83 @@ type CrdtState = {
   doc: Doc;
   clock: Clock;
 };
+/** Options for `forkState`. */
+interface ForkStateOptions {
+  /**
+   * Allow reusing the origin actor ID when forking.
+   * Defaults to `false` to prevent duplicate-dot collisions across replicas.
+   */
+  allowActorReuse?: boolean;
+}
 /** 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. */
+/** Options for internals-only `applyPatchAsActor`. */
+type ApplyPatchAsActorOptions = {
+  base?: Doc;
+  testAgainst?: "head" | "base";
+  semantics?: PatchSemantics;
+};
+/** Typed failure reason used across patch/merge helpers. */
+type PatchErrorReason = "INVALID_PATCH" | "INVALID_POINTER" | "MISSING_PARENT" | "MISSING_TARGET" | "INVALID_TARGET" | "OUT_OF_BOUNDS" | "TEST_FAILED" | "INVALID_MOVE" | "LINEAGE_MISMATCH";
+/** Structured conflict payload used by non-throwing APIs. */
+type ApplyError = {
+  ok: false; /** HTTP-friendly status code for conflict-style failures. */
+  code: 409; /** Machine-readable reason for branching logic. */
+  reason: PatchErrorReason; /** Human-readable description of the failure. */
+  message: string; /** Optional pointer/path context when available. */
+  path?: string; /** Optional patch operation index when available. */
+  opIndex?: number;
+};
+/** Result of applying a patch: success or structured conflict details. */
 type ApplyResult = {
   ok: true;
-} | {
-  ok: false;
-  code: 409;
-  message: string;
-};
+} | ApplyError;
 /** How JSON Patch operations are interpreted during application. */
 type PatchSemantics = "base" | "sequential";
+/** Options for compile/validation helpers. */
+type CompilePatchOptions = {
+  semantics?: PatchSemantics;
+};
 /**
- * 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`).
+ * Options for immutable patch application (`applyPatch` / `tryApplyPatch`).
+ * - `semantics: "sequential"` applies operations one-by-one against the evolving head (default).
+ * - `semantics: "base"` maps array indices against a fixed snapshot.
+ * - `base` should be a previously observed state snapshot from the same document lineage.
  */
 type ApplyPatchOptions = {
-  base?: Doc;
+  base?: CrdtState;
   testAgainst?: "head" | "base";
   semantics?: PatchSemantics;
+};
+/** Options for in-place patch application (`applyPatchInPlace` / `tryApplyPatchInPlace`). */
+type ApplyPatchInPlaceOptions = ApplyPatchOptions & {
   atomic?: boolean;
 };
+/** Non-throwing result for immutable patch application. */
+type TryApplyPatchResult = {
+  ok: true;
+  state: CrdtState;
+} | {
+  ok: false;
+  error: ApplyError;
+};
+/** Non-throwing result for in-place patch application. */
+type TryApplyPatchInPlaceResult = {
+  ok: true;
+} | {
+  ok: false;
+  error: ApplyError;
+};
+/** Non-throwing result for patch validation preflight. */
+type ValidatePatchResult = {
+  ok: true;
+} | {
+  ok: false;
+  error: ApplyError;
+};
 /** Options for `mergeState`. */
 type MergeStateOptions = {
   /**
@@ -209,6 +259,32 @@ type MergeDocOptions = {
    */
   requireSharedOrigin?: boolean;
 };
+/** Non-throwing result for `mergeDoc`. */
+type TryMergeDocResult = {
+  ok: true;
+  doc: Doc;
+} | {
+  ok: false;
+  error: ApplyError;
+};
+/** Non-throwing result for `mergeState`. */
+type TryMergeStateResult = {
+  ok: true;
+  state: CrdtState;
+} | {
+  ok: false;
+  error: ApplyError;
+};
+/** Options-object overload shape for low-level JSON Patch -> CRDT conversion. */
+type JsonPatchToCrdtOptions = {
+  base: Doc;
+  head: Doc;
+  patch: JsonPatchOp[];
+  newDot: () => Dot;
+  evalTestAgainst?: "head" | "base";
+  bumpCounterAbove?: (ctr: number) => void;
+  semantics?: PatchSemantics;
+};
 /** Options for `crdtToJsonPatch` and `diffJsonPatch`. */
 type DiffOptions = {
   arrayStrategy?: "atomic" | "lcs";
@@ -220,10 +296,14 @@ type DiffOptions = {
 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). */
+/** Error thrown when a JSON Patch cannot be applied. Includes structured conflict metadata. */
 declare class PatchError extends Error {
-  readonly code: number;
-  constructor(message: string, code?: number);
+  readonly code: 409;
+  readonly reason: PatchErrorReason;
+  readonly path?: string;
+  readonly opIndex?: number;
+  constructor(error: ApplyError);
+  constructor(message: string, code?: 409, reason?: PatchErrorReason);
 }
 /**
  * Create a new CRDT state from an initial JSON value.
@@ -235,6 +315,12 @@ declare function createState(initial: JsonValue, options: {
   actor: ActorId;
   start?: number;
 }): CrdtState;
+/**
+ * Fork a replica from a shared origin state while assigning a new local actor ID.
+ * The forked state has an independent document clone and clock.
+ * By default this rejects actor reuse to prevent duplicate-dot collisions across peers.
+ */
+declare function forkState(origin: CrdtState, actor: ActorId, options?: ForkStateOptions): CrdtState;
 /**
  * Materialize a CRDT document or state back to a plain JSON value.
  * @param target - A `Doc` or `CrdtState` to materialize.
@@ -246,7 +332,7 @@ declare function toJson(target: Doc | CrdtState): JsonValue;
  * 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.
+ * @param options - Optional base state snapshot and patch semantics.
  * @returns A new `CrdtState` with the patch applied.
  */
 declare function applyPatch(state: CrdtState, patch: JsonPatchOp[], options?: ApplyPatchOptions): CrdtState;
@@ -255,90 +341,32 @@ declare function applyPatch(state: CrdtState, patch: JsonPatchOp[], options?: Ap
  * 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.
+ * @param options - Optional base state snapshot, patch semantics, and atomicity.
  */
-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
+declare function applyPatchInPlace(state: CrdtState, patch: JsonPatchOp[], options?: ApplyPatchInPlaceOptions): void;
+/** Non-throwing immutable patch application variant. */
+declare function tryApplyPatch(state: CrdtState, patch: JsonPatchOp[], options?: ApplyPatchOptions): TryApplyPatchResult;
+/** Non-throwing in-place patch application variant. */
+declare function tryApplyPatchInPlace(state: CrdtState, patch: JsonPatchOp[], options?: ApplyPatchInPlaceOptions): TryApplyPatchInPlaceResult;
 /**
- * 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`.
+ * Validate whether a patch is applicable against a JSON base value under the chosen options.
+ * Does not mutate caller-provided values.
  */
-declare function docFromJson(value: JsonValue, nextDot: () => Dot): Doc;
+declare function validateJsonPatch(base: JsonValue, patch: JsonPatchOp[], options?: ApplyPatchOptions): ValidatePatchResult;
 /**
- * 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.
+ * 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 crdtToFullReplace(doc: Doc): JsonPatchOp[];
+declare function applyPatchAsActor(doc: Doc, vv: VersionVector, actor: ActorId, patch: JsonPatchOp[], options?: ApplyPatchAsActorOptions): ApplyPatchAsActorResult;
 //#endregion
 //#region src/patch.d.ts
+/** Structured compile error used to map patch validation failures to typed reasons. */
+declare class PatchCompileError extends Error {
+  readonly reason: PatchErrorReason;
+  readonly path?: string;
+  readonly opIndex?: number;
+  constructor(reason: PatchErrorReason, message: string, path?: string, opIndex?: number);
+}
 /**
  * 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 `""`).
@@ -360,7 +388,7 @@ declare function getAtJson(base: JsonValue, path: string[]): JsonValue;
  * @param patch - Array of JSON Patch operations.
  * @returns An array of `IntentOp` ready for `applyIntentsToCrdt`.
  */
-declare function compileJsonPatchToIntent(baseJson: JsonValue, patch: JsonPatchOp[]): IntentOp[];
+declare function compileJsonPatchToIntent(baseJson: JsonValue, patch: JsonPatchOp[], options?: CompilePatchOptions): IntentOp[];
 /**
  * Compute a JSON Patch delta between two JSON values.
  * By default arrays use a deterministic LCS strategy.
@@ -384,11 +412,14 @@ 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
+/** Error thrown by throwing merge helpers (`mergeDoc` / `mergeState`). */
+declare class MergeError extends Error {
+  readonly code: 409;
+  readonly reason: "LINEAGE_MISMATCH";
+  readonly path?: string;
+  constructor(error: ApplyError);
+}
 /**
  * Merge two CRDT documents from different peers into one.
  * By default this requires shared array lineage for non-empty sequences.
@@ -403,6 +434,8 @@ declare function materialize(node: Node): JsonValue;
  * - **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;
+/** Non-throwing `mergeDoc` variant with structured conflict details. */
+declare function tryMergeDoc(a: Doc, b: Doc, options?: MergeDocOptions): TryMergeDocResult;
 /**
  * Merge two CRDT states.
  *
@@ -415,5 +448,7 @@ declare function mergeDoc(a: Doc, b: Doc, options?: MergeDocOptions): Doc;
  * that actor across both input clocks and the merged document dots.
  */
 declare function mergeState(a: CrdtState, b: CrdtState, options?: MergeStateOptions): CrdtState;
+/** Non-throwing `mergeState` variant with structured conflict details. */
+declare function tryMergeState(a: CrdtState, b: CrdtState, options?: MergeStateOptions): TryMergeStateResult;
 //#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 };
+export { ObjNode as $, ApplyPatchAsActorResult as A, ElemId as B, toJson as C, ActorId as D, validateJsonPatch as E, CompilePatchOptions as F, JsonPatchToCrdtOptions as G, IntentOp as H, CrdtState as I, LwwReg as J, JsonPrimitive as K, DiffOptions as L, ApplyPatchOptions as M, ApplyResult as N, ApplyError as O, Clock as P, ObjEntry as Q, Doc as R, forkState as S, tryApplyPatchInPlace as T, JsonPatch as U, ForkStateOptions as V, JsonPatchOp as W, MergeStateOptions as X, MergeDocOptions as Y, Node as Z, PatchError as _, tryMergeState as a, SerializedClock as at, applyPatchInPlace as b, serializeDoc as c, SerializedRgaElem as ct, compileJsonPatchToIntent as d, TryApplyPatchResult as dt, PatchErrorReason as et, diffJsonPatch as f, TryMergeDocResult as ft, stringifyJsonPointer as g, parseJsonPointer as h, VersionVector as ht, tryMergeDoc as i, RgaSeq as it, ApplyPatchInPlaceOptions as j, ApplyPatchAsActorOptions as k, serializeState as l, SerializedState as lt, jsonEquals as m, ValidatePatchResult as mt, mergeDoc as n, ROOT_KEY as nt, deserializeDoc as o, SerializedDoc as ot, getAtJson as p, TryMergeStateResult as pt, JsonValue as q, mergeState as r, RgaElem as rt, deserializeState as s, SerializedNode as st, MergeError as t, PatchSemantics as tt, PatchCompileError as u, TryApplyPatchInPlaceResult as ut, applyPatch as v, tryApplyPatch as w, createState as x, applyPatchAsActor as y, Dot as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-patch-to-crdt",
-  "version": "0.0.0",
+  "version": "0.1.1",
   "description": "Convert JSON Patch (RFC 6902) to and from a CRDT-friendly representation.",
   "keywords": [
     "crdt",
@@ -9,6 +9,9 @@
     "rfc6902"
   ],
   "license": "MIT",
+  "repository": {
+    "url": "https://github.com/samlaycock/json-patch-to-crdt"
+  },
   "files": [
     "dist"
   ],
@@ -51,8 +54,5 @@
   },
   "peerDependencies": {
     "typescript": "^5"
-  },
-  "engines": {
-    "node": ">=18"
   }
 }