Crdt.Patch_builder

crdt · API reference

Builder API for constructing patches

Builder API for constructing patches.

Provides an ergonomic interface for creating patches with automatic ID assignment from a logical clock.

Usage:

  let builder = Patch_builder.create clock in
  Patch_builder.new_str builder;
  Patch_builder.ins_str builder ~obj:ts1 ~after:ts2 ~value:"hello";
  let patch = Patch_builder.flush builder

Types

type t = {
  clock : Clock.clock_vector; (* Clock for ID assignment *)
  mutable ops : Op.op_data list; (* Operations (in reverse order) *)
  mutable start_id : Clock.timestamp option; (* Starting ID of current patch *)
}

A patch builder with accumulating operations

Creation

val create : Clock.clock_vector -> t

Create a new builder with the given clock vector

val reset : t -> unit

Reset the builder, discarding any pending operations

Building Patches

val ensure_start_id : t -> Clock.timestamp

Internal: ensure we have a start ID, tick the clock if needed

val add_op : t -> Op.op_data -> unit

Internal: add an operation and advance clock by its span

val flush : t -> Patch.t option

Flush the builder and return the completed patch. Returns None if no operations were added.

val flush_or_empty : t -> Patch.t

Flush the builder, returning an empty patch if no operations. The empty patch will have the current clock time as its ID.

Creation Operations

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

Create a constant node with the given value

val new_val : t -> unit

Create a mutable value node

val new_obj : t -> unit

Create an object node

val new_vec : t -> unit

Create a vector node

val new_str : t -> unit

Create a string node

val new_bin : t -> unit

Create a binary node

val new_arr : t -> unit

Create an array node

Edit Operations

val ins_val : t -> obj:Op.timestamp -> value:Op.timestamp -> unit

Set a value node's reference

val ins_obj : t -> obj:Op.timestamp -> entries:Op.obj_entry list -> unit

Insert/update object entries

val ins_vec : t -> obj:Op.timestamp -> idx:int -> value:Op.timestamp -> unit

Set a vector slot

val ins_str : 
  t ->
  obj:Op.timestamp ->
  after:Op.timestamp ->
  value:string ->
  unit

Insert text into a string node

val ins_bin : 
  t ->
  obj:Op.timestamp ->
  after:Op.timestamp ->
  value:bytes ->
  unit

Insert bytes into a binary node

val ins_arr : 
  t ->
  obj:Op.timestamp ->
  after:Op.timestamp ->
  value:Op.timestamp ->
  unit

Insert element into an array node

val upd_arr : 
  t ->
  obj:Op.timestamp ->
  pos:Op.timestamp ->
  value:Op.timestamp ->
  unit

Update an array element

val del : t -> obj:Op.timestamp -> what:Op.timespan list -> unit

Delete ranges from an RGA

val nop : t -> int -> unit

Add a no-op (for padding/alignment)

Utilities

val pending_count : t -> int

Get the number of pending operations

val has_pending : t -> bool

Check if builder has pending operations

val current_time : t -> int

Get the current clock time (for reference)

val session_id : t -> int

Get the session ID

val next_op_id : t -> Clock.timestamp

Get the ID that will be assigned to the next operation added. This is computed as start_id + cumulative_span, where cumulative_span is the sum of spans of all operations added so far. If no operations have been added yet, returns the current clock time (which will become the start_id after the first tick).