Crdt.Model_api

High-level editing API

High-level editing API.

Provides a user-friendly interface for editing CRDT documents with path-based access, transaction support, and automatic node creation.

Key features:

• Path-based navigation using JSON Pointer syntax
• Transaction support with flush/commit
• Automatic node creation for nested structures
• Type-safe node proxies for editing Usage:

  let api = Model_api.create model in

  (* Direct editing *)
  Model_api.set api "/" (Value.String "hello");

  (* String editing *)
  let str_node = Model_api.str api "/text" in
  Model_api.str_insert str_node ~pos:0 ~text:"hello";

  (* Object editing *)
  let obj_node = Model_api.obj api "/data" in
  Model_api.obj_set obj_node ~key:"name" ~value:(Value.String "Alice");

  (* Flush changes to patch *)
  let patch = Model_api.flush api

Types

type t = {
  model : Model.t;
  mutable builder : Patch_builder.t;
}

An API handle for editing a model with transaction support

Creation

val create : Model.t -> t

Create an API handle for a model

val reset : t -> unit

Reset the transaction state, discarding any pending changes

Transaction Support

val flush : t -> Patch.t option

Flush pending operations as a patch. Returns None if no operations.

val commit : t -> Patch.t option

Flush and apply the patch to the model atomically. Returns the patch.

val has_pending : t -> bool

Check if there are pending operations

val pending_count : t -> int

Get the number of pending operations

Clock Access

val current_time : t -> int

Get the current logical time

val session_id : t -> int

Get the session ID

val model : t -> Model.t

Get the model

Path Resolution

type path_result = 
  | Found of Node.t (* Found the node *)
  | Not_found (* Path doesn't exist *)
  | Type_mismatch of string (* Wrong node type for path segment *)

Result of resolving a path

val resolve_path : t -> string -> path_result

Resolve a JSON Pointer path to a node

Node Access

val get : t -> string -> Node.t option

Get a node at a path, or None if not found

val get_value : t -> string -> Value.t option

Get the value at a path

val view : t -> string -> Value.t option

Get the fully resolved value at a path

Internal Helpers

val next_id : t -> Clock.timestamp

Get the next ID that will be assigned (before adding an op)

val add_const : t -> Value.t -> Clock.timestamp

Add a new_con operation and return the ID that will be assigned

val set_root : t -> Value.t -> unit

Set the document root to a value

Object Operations

type obj_proxy = {
  obj_api : t;
  obj_id : Clock.timestamp;
}

Object proxy for editing

val obj : t -> string -> obj_proxy option

Get or create an object at a path. For an existing object, returns a proxy to edit it. For an unset val node, creates a new object and returns its proxy. The object won't exist in the model until commit is called.

val obj_set : obj_proxy -> key:string -> value:Value.t -> Clock.timestamp

Set a key in an object proxy. Returns the timestamp of the new value node.

val obj_delete : obj_proxy -> key:string -> unit

Delete a key from an object. This sets the key to undefined.

val obj_get : obj_proxy -> key:string -> Node.t option

Get a value from the object (only works after commit)

val obj_keys : obj_proxy -> string list

Get all keys in the object (only works after commit)

String Operations

type str_proxy = {
  str_api : t;
  str_id : Clock.timestamp;
  mutable last_insert_end : Clock.timestamp option; (* End of last inserted text *)
}

String proxy for editing. Tracks the last insert position for sequential appends.

val str : t -> string -> str_proxy option

Get or create a string at a path

val str_insert : str_proxy -> pos:int -> text:string -> unit

Insert text at a position in a string.

parameter pos Character position (0 = start) parameter text Text to insert

val str_append : str_proxy -> text:string -> unit

Append text to a string

val str_delete : str_proxy -> pos:int -> len:int -> unit

Delete text from a string.

parameter pos Start position parameter len Number of characters to delete

val str_value : str_proxy -> string

Get the current string value (only works after commit or for existing strings)

val str_length : str_proxy -> int

Get the string length

Array Operations

type arr_proxy = {
  arr_api : t;
  arr_id : Clock.timestamp;
}

Array proxy for editing

val arr : t -> string -> arr_proxy option

Get or create an array at a path

val arr_insert : arr_proxy -> pos:int -> value:Value.t -> unit

Insert an element at a position in an array.

parameter pos Array index (0 = start) parameter value Value to insert

val arr_push : arr_proxy -> value:Value.t -> unit

Append an element to an array

val arr_delete : arr_proxy -> pos:int -> count:int -> unit

Delete elements from an array.

parameter pos Start position parameter count Number of elements to delete

val arr_length : arr_proxy -> int

Get the current array length

Binary Operations

type bin_proxy = {
  bin_api : t;
  bin_id : Clock.timestamp;
}

Binary proxy for editing

val bin : t -> string -> bin_proxy option

Get or create a binary blob at a path

val bin_insert : bin_proxy -> pos:int -> data:bytes -> unit

Insert bytes at a position

val bin_append : bin_proxy -> data:bytes -> unit

Append bytes

val bin_delete : bin_proxy -> pos:int -> len:int -> unit

Delete bytes from binary.

parameter pos Start position parameter len Number of bytes to delete

val bin_value : bin_proxy -> bytes

Get the current binary value

val bin_length : bin_proxy -> int

Get the binary length

Vector Operations

type vec_proxy = {
  vec_api : t;
  vec_id : Clock.timestamp;
}

Vector proxy for editing

val vec : t -> string -> vec_proxy option

Get or create a vector at a path

val vec_set : vec_proxy -> idx:int -> value:Value.t -> unit

Set a slot in a vector (0-255)

val vec_get : vec_proxy -> idx:int -> Node.t option

Get a slot value from the vector

Document View

val view_document : t -> Value.t

Get the complete document view

val pp_document : Format.formatter -> t -> unit

Pretty print the document