json-patch-to-crdt 0.5.0 → 1.0.0

package/dist/{depth-CM1kCxhm.d.mts → depth-C5m9qI-V.d.mts}

@@ -118,13 +118,36 @@ interface LegacySerializedState {
 /** JSON-serializable form of a full CRDT state (document + clock). */
 type SerializedState = SerializedStateV1 | LegacySerializedState;
 /** Typed reasons for rejecting malformed serialized CRDT payloads. */
-type DeserializeErrorReason = "INVALID_SERIALIZED_SHAPE" | "INVALID_SERIALIZED_INVARIANT";
+type DeserializeErrorReason = "INVALID_SERIALIZED_SHAPE" | "INVALID_SERIALIZED_INVARIANT" | "OPERATION_CANCELLED";
+type ResourceBudgetKind = "patchOperations" | "objectEntries" | "sequenceElements" | "visitedNodes" | "serializedElements" | "arrayDiffCells";
+interface ResourceBudget {
+  patchOperations?: number;
+  objectEntries?: number;
+  sequenceElements?: number;
+  visitedNodes?: number;
+  serializedElements?: number;
+  arrayDiffCells?: number;
+}
+interface ResourceBudgetExceededFailure {
+  code: 409;
+  reason: "RESOURCE_BUDGET_EXCEEDED";
+  message: string;
+  budget: ResourceBudgetKind;
+  limit: number;
+  actual: number;
+  path?: string;
+  opIndex?: number;
+}
 /** Structured failure payload used by non-throwing deserialize helpers. */
 type DeserializeFailure = {
   code: 409;
   reason: DeserializeErrorReason;
   path: string;
   message: string;
+} | ResourceBudgetExceededFailure | {
+  code: 409;
+  reason: "OPERATION_CANCELLED";
+  message: string;
 } | {
   code: 409;
   reason: "MAX_DEPTH_EXCEEDED";
@@ -231,6 +254,7 @@ type ApplyPatchAsActorOptions = {
   semantics?: PatchSemantics;
   strictParents?: boolean;
   jsonValidation?: JsonValidationMode;
+  signal?: AbortSignalLike;
 };
 /** Non-throwing result for internals-only `tryApplyPatchAsActor`. */
 type TryApplyPatchAsActorResult = ({
@@ -240,7 +264,12 @@ type TryApplyPatchAsActorResult = ({
   error: ApplyError;
 };
 /** 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" | "DOT_GENERATION_EXHAUSTED" | "MAX_DEPTH_EXCEEDED" | "LINEAGE_MISMATCH";
+type PatchErrorReason = "INVALID_PATCH" | "INVALID_POINTER" | "MISSING_PARENT" | "MISSING_TARGET" | "INVALID_TARGET" | "OUT_OF_BOUNDS" | "TEST_FAILED" | "INVALID_MOVE" | "DOT_GENERATION_EXHAUSTED" | "MAX_DEPTH_EXCEEDED" | "RESOURCE_BUDGET_EXCEEDED" | "LINEAGE_MISMATCH" | "OPERATION_CANCELLED";
+/** Minimal structural signal accepted by cancellable APIs. Compatible with AbortSignal. */
+interface AbortSignalLike {
+  readonly aborted: boolean;
+  readonly reason?: unknown;
+}
 /** Structured conflict payload used by non-throwing APIs. */
 type ApplyError = {
   ok: false; /** HTTP-friendly status code for conflict-style failures. */
@@ -248,7 +277,10 @@ type ApplyError = {
   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;
+  opIndex?: number; /** Resource-budget context when `reason` is `RESOURCE_BUDGET_EXCEEDED`. */
+  budget?: ResourceBudgetKind;
+  limit?: number;
+  actual?: number;
 };
 /** Result of applying a patch: success or structured conflict details. */
 type ApplyResult = {
@@ -270,11 +302,26 @@ type TryDeserializeStateResult = {
   ok: false;
   error: DeserializeFailure;
 };
+/** Non-throwing validation-only result for serialized docs. */
+type ValidateSerializedDocResult = {
+  ok: true;
+} | {
+  ok: false;
+  error: DeserializeFailure;
+};
+/** Non-throwing validation-only result for serialized states. */
+type ValidateSerializedStateResult = {
+  ok: true;
+} | {
+  ok: false;
+  error: DeserializeFailure;
+};
 /** How JSON Patch operations are interpreted during application. */
 type PatchSemantics = "base" | "sequential";
 /** Options for compile/validation helpers. */
 type CompilePatchOptions = {
   semantics?: PatchSemantics;
+  resourceBudget?: ResourceBudget;
 };
 /**
  * Options for immutable patch application (`applyPatch` / `tryApplyPatch`).
@@ -286,10 +333,13 @@ type ApplyPatchOptions = {
   base?: CrdtState;
   testAgainst?: "head" | "base";
   semantics?: PatchSemantics;
+  resourceBudget?: ResourceBudget;
   /**
    * Reject array inserts when the base parent path is missing.
-   * Defaults to `false` to preserve legacy behavior that can auto-create
-   * missing arrays for index `0` / append intents.
+   * Defaults to `true` for RFC 6902-compatible parent semantics.
+   * Use `withStrictRfc6902Parents(...)` for RFC 6902-compatible missing-parent
+   * behavior. Explicitly setting `false` preserves the legacy behavior that can
+   * auto-create missing arrays for index `0` / append intents.
    */
   strictParents?: boolean;
   /**
@@ -297,6 +347,7 @@ type ApplyPatchOptions = {
    * Defaults to `"none"` for backward compatibility.
    */
   jsonValidation?: JsonValidationMode;
+  signal?: AbortSignalLike;
 };
 /** Options for in-place patch application (`applyPatchInPlace` / `tryApplyPatchInPlace`). */
 type ApplyPatchInPlaceOptions = ApplyPatchOptions & {
@@ -353,6 +404,8 @@ type MergeStateOptions = {
    * Ignored when `unrelatedArrays` is also provided.
    */
   requireSharedOrigin?: boolean;
+  resourceBudget?: ResourceBudget;
+  signal?: AbortSignalLike;
 };
 /** Options for `mergeDoc`. */
 type MergeDocOptions = {
@@ -368,7 +421,13 @@ type MergeDocOptions = {
    * Ignored when `unrelatedArrays` is also provided.
    */
   requireSharedOrigin?: boolean;
+  resourceBudget?: ResourceBudget;
+  signal?: AbortSignalLike;
 };
+interface DeserializeOptions {
+  resourceBudget?: ResourceBudget;
+  signal?: AbortSignalLike;
+}
 /** Non-throwing result for `mergeDoc`. */
 type TryMergeDocResult = {
   ok: true;
@@ -423,6 +482,7 @@ type JsonPatchToCrdtOptions = {
   bumpCounterAbove?: (ctr: number) => void;
   semantics?: PatchSemantics;
   strictParents?: boolean;
+  resourceBudget?: ResourceBudget;
 };
 /** Options for `crdtToJsonPatch` and `diffJsonPatch`. */
 type DiffOptions = {
@@ -430,8 +490,8 @@ type DiffOptions = {
    * Array diff mode.
    * - `"lcs"` (default): index-level edits using LCS.
    * - `"lcs-linear"`: index-level edits using a lower-memory LCS variant.
-   *   This reduces memory use but still has `O(n * m)` time complexity and no
-   *   automatic fallback for very large unmatched windows.
+   *   This reduces memory use but still has `O(n * m)` time complexity. Large
+   *   unmatched windows fall back to atomic replacement by default.
    * - `"atomic"`: one-op root/field replacement for changed arrays.
    */
   arrayStrategy?: "atomic" | "lcs" | "lcs-linear";
@@ -444,16 +504,16 @@ type DiffOptions = {
    */
   lcsMaxCells?: number;
   /**
-   * Optional guardrail for `arrayStrategy: "lcs-linear"`.
+   * Guardrail for `arrayStrategy: "lcs-linear"`.
    * Uses the trimmed unmatched window size
    * (`(unmatchedBase.length + 1) * (unmatchedNext.length + 1)`) as a proxy for
    * worst-case work. When the cap is exceeded, the diff falls back to an atomic
    * array replacement instead of running the linear-space traversal.
    *
-   * Unlike `lcsMaxCells`, this is opt-in and defaults to no fallback so
-   * existing `lcs-linear` callers keep their current behavior.
+   * Defaults to `250_000`.
    *
-   * Set to `Number.POSITIVE_INFINITY` to always allow `lcs-linear`.
+   * Set to `Number.POSITIVE_INFINITY` to always allow `lcs-linear` and preserve
+   * the previous unbounded behavior.
    */
   lcsLinearMaxCells?: number;
   /**
@@ -471,6 +531,8 @@ type DiffOptions = {
    * Defaults to `"none"` for backward compatibility.
    */
   jsonValidation?: JsonValidationMode;
+  resourceBudget?: ResourceBudget;
+  signal?: AbortSignalLike;
 };
 /**
  * Internal sentinel key used in `IntentOp` to represent root-level operations.
@@ -478,11 +540,34 @@ type DiffOptions = {
  */
 declare const ROOT_KEY = "@@crdt/root";
 //#endregion
+//#region src/safe.d.ts
+interface SafeCreateStateOptions extends Omit<CreateStateOptions, "jsonValidation"> {}
+interface SafeApplyPatchOptions extends Omit<ApplyPatchOptions, "jsonValidation"> {}
+interface SafeDiffOptions extends Omit<DiffOptions, "jsonValidation"> {}
+interface NormalizedCreateStateOptions extends Omit<CreateStateOptions, "jsonValidation"> {}
+interface NormalizedApplyPatchOptions extends Omit<ApplyPatchOptions, "jsonValidation"> {}
+interface NormalizedDiffOptions extends Omit<DiffOptions, "jsonValidation"> {}
+/** Create a state with strict runtime JSON validation enabled by default. */
+declare function createSafeState(initial: JsonValue, options: SafeCreateStateOptions): CrdtState;
+/** Apply a patch with strict runtime JSON validation enabled by default. */
+declare function applySafePatch(state: CrdtState, patch: JsonPatchOp[], options?: SafeApplyPatchOptions): CrdtState;
+/** Diff JSON values with strict runtime JSON validation enabled by default. */
+declare function diffSafeJsonPatch(base: JsonValue, next: JsonValue, options?: SafeDiffOptions): JsonPatchOp[];
+/** Create a state with normalizing runtime JSON validation enabled by default. */
+declare function createNormalizedState(initial: JsonValue, options: NormalizedCreateStateOptions): CrdtState;
+/** Apply a patch with normalizing runtime JSON validation enabled by default. */
+declare function applyNormalizedPatch(state: CrdtState, patch: JsonPatchOp[], options?: NormalizedApplyPatchOptions): CrdtState;
+/** Diff JSON values with normalizing runtime JSON validation enabled by default. */
+declare function diffNormalizedJsonPatch(base: JsonValue, next: JsonValue, options?: NormalizedDiffOptions): JsonPatchOp[];
+//#endregion
 //#region src/state.d.ts
 /** Error thrown when a JSON Patch cannot be applied. Includes structured conflict metadata. */
 declare class PatchError extends Error {
   readonly code: 409;
   readonly reason: PatchErrorReason;
+  readonly budget?: ResourceBudgetKind;
+  readonly limit?: number;
+  readonly actual?: number;
   readonly path?: string;
   readonly opIndex?: number;
   constructor(error: ApplyError);
@@ -574,6 +659,24 @@ 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/budget.d.ts
+declare class ResourceBudgetError extends Error {
+  readonly reason: "RESOURCE_BUDGET_EXCEEDED";
+  readonly code: 409;
+  readonly budget: ResourceBudgetKind;
+  readonly limit: number;
+  readonly actual: number;
+  readonly path?: string;
+  readonly opIndex?: number;
+  constructor(budget: ResourceBudgetKind, limit: number, actual: number, path?: string, opIndex?: number);
+}
+//#endregion
+//#region src/cancellation.d.ts
+declare class OperationCancelledError extends Error {
+  readonly reasonValue?: unknown;
+  constructor(reason?: unknown);
+}
+//#endregion
 //#region src/patch.d.ts
 /** Structured compile error used to map patch validation failures to typed reasons. */
 declare class PatchCompileError extends Error {
@@ -609,7 +712,7 @@ declare function compileJsonPatchToIntent(baseJson: JsonValue, patch: JsonPatchO
  * By default arrays use a deterministic LCS strategy.
  * Pass `{ arrayStrategy: "atomic" }` for single-op array replacement.
  * Pass `{ arrayStrategy: "lcs-linear" }` for a lower-memory LCS variant.
- * Use `lcsLinearMaxCells` to optionally cap worst-case `lcs-linear` work and
+ * Use `lcsLinearMaxCells` to cap worst-case `lcs-linear` work and
  * fall back to an atomic array replacement for very large unmatched windows.
  * Pass `{ emitMoves: true }` or `{ emitCopies: true }` to opt into RFC 6902
  * move/copy emission when a deterministic rewrite is available.
@@ -624,6 +727,34 @@ declare function stableJsonValueKey(value: JsonValue, structuralKeyCache?: WeakM
 /** Deep equality check for JSON values (null-safe, handles arrays and objects). */
 declare function jsonEquals(a: JsonValue, b: JsonValue): boolean;
 //#endregion
+//#region src/options.d.ts
+/** Options that reject legacy missing-parent array auto-creation. */
+declare const strictRfc6902PatchOptions: {
+  readonly strictParents: true;
+};
+/**
+ * Build `applyPatch` options for strict RFC 6902 parent semantics.
+ *
+ * Use this when patches come from an RFC 6902 boundary and missing array
+ * parents should fail instead of being materialized.
+ */
+declare function withStrictRfc6902Parents(): typeof strictRfc6902PatchOptions;
+declare function withStrictRfc6902Parents<T extends ApplyPatchOptions>(options: T): T & typeof strictRfc6902PatchOptions;
+/**
+ * Build `applyPatch` options for the legacy missing-parent array behavior.
+ *
+ * @deprecated Missing-parent array auto-creation is not RFC 6902 compatible.
+ * Prefer `withStrictRfc6902Parents(...)` unless you are preserving legacy data
+ * flows that intentionally materialize missing arrays for `/path/0` or
+ * `/path/-` inserts.
+ */
+declare function withLegacyMissingArrayParents(): {
+  strictParents: false;
+};
+declare function withLegacyMissingArrayParents<T extends ApplyPatchOptions>(options: T): T & {
+  strictParents: false;
+};
+//#endregion
 //#region src/serialize.d.ts
 declare class DeserializeError extends Error {
   readonly code: 409;
@@ -634,9 +765,11 @@ declare class DeserializeError extends Error {
 /** 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;
+declare function deserializeDoc(data: SerializedDoc, options?: DeserializeOptions): Doc;
 /** Non-throwing `deserializeDoc` variant with typed validation details. */
-declare function tryDeserializeDoc(data: SerializedDoc): TryDeserializeDocResult;
+declare function tryDeserializeDoc(data: SerializedDoc, options?: DeserializeOptions): TryDeserializeDocResult;
+/** Validate a serialized CRDT document without throwing or returning runtime state. */
+declare function validateSerializedDoc(data: SerializedDoc, options?: DeserializeOptions): ValidateSerializedDocResult;
 /** Serialize a full CRDT state (document + clock) to a JSON-safe representation. */
 declare function serializeState(state: CrdtState): SerializedState;
 /**
@@ -645,15 +778,20 @@ declare function serializeState(state: CrdtState): SerializedState;
  * May throw `TraversalDepthError` when the payload exceeds the maximum
  * supported nesting depth.
  */
-declare function deserializeState(data: SerializedState): CrdtState;
+declare function deserializeState(data: SerializedState, options?: DeserializeOptions): CrdtState;
 /** Non-throwing `deserializeState` variant with typed validation details. */
-declare function tryDeserializeState(data: SerializedState): TryDeserializeStateResult;
+declare function tryDeserializeState(data: SerializedState, options?: DeserializeOptions): TryDeserializeStateResult;
+/** Validate a serialized CRDT state without throwing or returning runtime state. */
+declare function validateSerializedState(data: SerializedState, options?: DeserializeOptions): ValidateSerializedStateResult;
 //#endregion
 //#region src/merge.d.ts
 /** Error thrown by throwing merge helpers (`mergeDoc` / `mergeState`). */
 declare class MergeError extends Error {
   readonly code: 409;
   readonly reason: PatchErrorReason;
+  readonly budget?: ResourceBudgetKind;
+  readonly limit?: number;
+  readonly actual?: number;
   readonly path?: string;
   constructor(error: ApplyError);
 }
@@ -742,4 +880,4 @@ declare class TraversalDepthError extends Error {
   constructor(depth: number, maxDepth?: number);
 }
 //#endregion
-export { Clock as $, cloneClock as A, SerializedClock as At, forkState as B, TryDeserializeDocResult as Bt, diffJsonPatch as C, ObjEntry as Ct, stableJsonValueKey as D, ROOT_KEY as Dt, parseJsonPointer as E, PatchSemantics as Et, PatchError as F, TombstoneCompactionOptions as Ft, validateJsonPatch as G, ValidatePatchResult as Gt, tryApplyPatch as H, TryMergeDocResult as Ht, applyPatch as I, TombstoneCompactionStats as It, ApplyPatchAsActorOptions as J, ActorId as K, VersionVector as Kt, applyPatchAsActor as L, TryApplyPatchAsActorResult as Lt, nextDotForActor as M, SerializedNode as Mt, observeDot as N, SerializedRgaElem as Nt, stringifyJsonPointer as O, RgaElem as Ot, JsonValueValidationError as P, SerializedState as Pt, ApplyResult as Q, applyPatchInPlace as R, TryApplyPatchInPlaceResult as Rt, compileJsonPatchToIntent as S, Node as St, jsonEquals as T, PatchErrorReason as Tt, tryApplyPatchAsActor as U, TryMergeStateResult as Ut, toJson as V, TryDeserializeStateResult as Vt, tryApplyPatchInPlace as W, UnrelatedArraysStrategy as Wt, ApplyPatchInPlaceOptions as X, ApplyPatchAsActorResult as Y, ApplyPatchOptions as Z, serializeDoc as _, JsonValidationMode as _t, intersectVersionVectors as a, DeserializeErrorReason as at, tryDeserializeState as b, MergeDocOptions as bt, versionVectorCovers as c, Doc as ct, mergeState as d, ForkStateOptions as dt, CompactDocTombstonesResult as et, tryMergeDoc as f, IntentOp as ft, deserializeState as g, JsonPrimitive as gt, deserializeDoc as h, JsonPatchToCrdtOptions as ht, compactStateTombstones as i, CreateStateOptions as it, createClock as j, SerializedDoc as jt, ClockValidationError as k, RgaSeq as kt, MergeError as l, Dot as lt, DeserializeError as m, JsonPatchOp as mt, TraversalDepthError as n, CompilePatchOptions as nt, mergeVersionVectors as o, DeserializeFailure as ot, tryMergeState as p, JsonPatch as pt, ApplyError as q, compactDocTombstones as r, CrdtState as rt, observedVersionVector as s, DiffOptions as st, MAX_TRAVERSAL_DEPTH as t, CompactStateTombstonesResult as tt, mergeDoc as u, ElemId as ut, serializeState as v, JsonValue as vt, getAtJson as w, ObjNode as wt, PatchCompileError as x, MergeStateOptions as xt, tryDeserializeDoc as y, LwwReg as yt, createState as z, TryApplyPatchResult as zt };
+export { NormalizedApplyPatchOptions as $, RgaSeq as $t, jsonEquals as A, Dot as At, observeDot as B, LwwReg as Bt, strictRfc6902PatchOptions as C, CrdtState as Ct, compileJsonPatchToIntent as D, DeserializeOptions as Dt, PatchCompileError as E, DeserializeFailure as Et, ResourceBudgetError as F, JsonPatchOp as Ft, applyPatchInPlace as G, ObjNode as Gt, PatchError as H, MergeStateOptions as Ht, ClockValidationError as I, JsonPatchToCrdtOptions as It, toJson as J, ROOT_KEY as Jt, createState as K, PatchErrorReason as Kt, cloneClock as L, JsonPrimitive as Lt, stableJsonValueKey as M, ForkStateOptions as Mt, stringifyJsonPointer as N, IntentOp as Nt, diffJsonPatch as O, DiffOptions as Ot, OperationCancelledError as P, JsonPatch as Pt, validateJsonPatch as Q, RgaElem as Qt, createClock as R, JsonValidationMode as Rt, validateSerializedState as S, CompilePatchOptions as St, withStrictRfc6902Parents as T, DeserializeErrorReason as Tt, applyPatch as U, Node as Ut, JsonValueValidationError as V, MergeDocOptions as Vt, applyPatchAsActor as W, ObjEntry as Wt, tryApplyPatchAsActor as X, ResourceBudgetExceededFailure as Xt, tryApplyPatch as Y, ResourceBudget as Yt, tryApplyPatchInPlace as Z, ResourceBudgetKind as Zt, serializeDoc as _, ValidateSerializedStateResult as _n, ApplyPatchOptions as _t, intersectVersionVectors as a, TombstoneCompactionOptions as an, applyNormalizedPatch as at, tryDeserializeState as b, CompactDocTombstonesResult as bt, versionVectorCovers as c, TryApplyPatchInPlaceResult as cn, createSafeState as ct, mergeState as d, TryDeserializeStateResult as dn, AbortSignalLike as dt, SerializedClock as en, NormalizedCreateStateOptions as et, tryMergeDoc as f, TryMergeDocResult as fn, ActorId as ft, deserializeState as g, ValidateSerializedDocResult as gn, ApplyPatchInPlaceOptions as gt, deserializeDoc as h, ValidatePatchResult as hn, ApplyPatchAsActorResult as ht, compactStateTombstones as i, SerializedState as in, SafeDiffOptions as it, parseJsonPointer as j, ElemId as jt, getAtJson as k, Doc as kt, MergeError as l, TryApplyPatchResult as ln, diffNormalizedJsonPatch as lt, DeserializeError as m, UnrelatedArraysStrategy as mn, ApplyPatchAsActorOptions as mt, TraversalDepthError as n, SerializedNode as nn, SafeApplyPatchOptions as nt, mergeVersionVectors as o, TombstoneCompactionStats as on, applySafePatch as ot, tryMergeState as p, TryMergeStateResult as pn, ApplyError as pt, forkState as q, PatchSemantics as qt, compactDocTombstones as r, SerializedRgaElem as rn, SafeCreateStateOptions as rt, observedVersionVector as s, TryApplyPatchAsActorResult as sn, createNormalizedState as st, MAX_TRAVERSAL_DEPTH as t, SerializedDoc as tn, NormalizedDiffOptions as tt, mergeDoc as u, TryDeserializeDocResult as un, diffSafeJsonPatch as ut, serializeState as v, VersionVector as vn, ApplyResult as vt, withLegacyMissingArrayParents as w, CreateStateOptions as wt, validateSerializedDoc as x, CompactStateTombstonesResult as xt, tryDeserializeDoc as y, Clock as yt, nextDotForActor as z, JsonValue as zt };