Crdt.Op

crdt · API reference

CRDT patch operations - all 18 opcodes with full data structures

CRDT patch operations.

This module defines all 18 patch opcodes from json-joy with their full data structures, matching the json-crdt-patch specification.

Core Types

type timestamp = Clock.timestamp

A timestamp reference sid, time

type timespan = Clock.timespan

A timespan sid, time, span for delete operations

type obj_entry = string * timestamp

Object entry: key and value reference

Operation Types

type new_con = {
  con_value : Value.t;
}

Create constant node - stores a JSON primitive value. The value can be null, boolean, number (int/float), or string.

type new_val = unit

Create mutable value node - wrapper for a single reference. Initially points to nothing, set via ins_val.

type new_obj = unit

Create object node - LWW-Map of string keys to node references.

type new_vec = unit

Create vector node - fixed-size tuple with positional slots.

type new_str = unit

Create string node - RGA of UTF-16 characters.

type new_bin = unit

Create binary node - RGA of bytes.

type new_arr = unit

Create array node - RGA of node references.

type ins_val = {
  ins_val_obj : timestamp; (* Target value node *)
  ins_val_value : timestamp; (* Reference to set *)
}

Set value node reference.

parameter obj The value node to modify parameter value Reference to the new value node

type ins_obj = {
  ins_obj_obj : timestamp; (* Target object node *)
  ins_obj_value : obj_entry list; (* Key-value pairs *)
}

Insert/update object entries.

parameter obj The object node to modify parameter value List of (key, node_ref) pairs to set

type ins_vec = {
  ins_vec_obj : timestamp; (* Target vector node *)
  ins_vec_idx : int; (* Slot index *)
  ins_vec_value : timestamp; (* Reference to set *)
}

Set vector slot.

parameter obj The vector node to modify parameter idx Slot index (0-based) parameter value Reference to the node to set

type ins_str = {
  ins_str_obj : timestamp; (* Target string node *)
  ins_str_after : timestamp; (* Insert after this position *)
  ins_str_value : string; (* Text to insert *)
}

Insert text into string node (RGA insert).

parameter obj The string node to modify parameter after Insert position (after this element) parameter value Text to insert (UTF-16)

type ins_bin = {
  ins_bin_obj : timestamp; (* Target binary node *)
  ins_bin_after : timestamp; (* Insert after this position *)
  ins_bin_value : bytes; (* Bytes to insert *)
}

Insert bytes into binary node (RGA insert).

parameter obj The binary node to modify parameter after Insert position (after this element) parameter value Bytes to insert (base64 encoded in JSON)

type ins_arr = {
  ins_arr_obj : timestamp; (* Target array node *)
  ins_arr_after : timestamp; (* Insert after this position *)
  ins_arr_value : timestamp; (* Reference to insert *)
  ins_arr_values : timestamp list; (* References inserted by this op *)
}

Insert element into array node (RGA insert).

parameter obj The array node to modify parameter after Insert position (after this element) parameter value Reference to node to insert

type upd_arr = {
  upd_arr_obj : timestamp; (* Target array node *)
  upd_arr_pos : timestamp; (* Position to update *)
  upd_arr_value : timestamp; (* New reference *)
}

Update array element (overwrite at existing position).

parameter obj The array node to modify parameter pos Element position to update parameter value New reference to set

type del = {
  del_obj : timestamp; (* Target node *)
  del_what : timespan list; (* Ranges to delete *)
}

Delete ranges from an RGA (string, binary, or array).

parameter obj The node to delete from parameter what List of timespans to delete

type nop = {
  nop_len : int;
}

No-op operation - used for padding/alignment.

parameter len Number of IDs consumed by this nop

Operation Sum Type

type op_data = 
  | Op_new_con of new_con (* Create constant *)
  | Op_new_val (* Create value node *)
  | Op_new_obj (* Create object node *)
  | Op_new_vec (* Create vector node *)
  | Op_new_str (* Create string node *)
  | Op_new_bin (* Create binary node *)
  | Op_new_arr (* Create array node *)
  | Op_ins_val of ins_val (* Set value reference *)
  | Op_ins_obj of ins_obj (* Insert object entries *)
  | Op_ins_vec of ins_vec (* Set vector slot *)
  | Op_ins_str of ins_str (* Insert string text *)
  | Op_ins_bin of ins_bin (* Insert binary data *)
  | Op_ins_arr of ins_arr (* Insert array element *)
  | Op_upd_arr of upd_arr (* Update array element *)
  | Op_del of del (* Delete ranges *)
  | Op_nop of nop (* No-op *)

An operation with all its data

Opcode Enumeration

type opcode = 
  | New_con (* 0: Create constant node *)
  | New_val (* 1: Create mutable value node *)
  | New_obj (* 2: Create object node *)
  | New_vec (* 3: Create vector node *)
  | New_str (* 4: Create string node *)
  | New_bin (* 5: Create binary node *)
  | New_arr (* 6: Create array node *)
  | Ins_val (* 9: Set value node reference *)
  | Ins_obj (* 10: Insert/update object key *)
  | Ins_vec (* 11: Set vector slot *)
  | Ins_str (* 12: Insert text into string *)
  | Ins_bin (* 13: Insert bytes into binary *)
  | Ins_arr (* 14: Insert element into array *)
  | Upd_arr (* 15: Update array element *)
  | Del (* 16: Delete range *)
  | Nop (* 17: No-op *)

Operation opcodes (numeric encoding)

val opcode_to_int : opcode -> int

Get the opcode number

val int_to_opcode : int -> opcode option

Get opcode from number

val opcode_of_op : op_data -> opcode

Get the opcode of an operation

val opcode_name : opcode -> string

Get the operation name (string)

val opcode_of_name : string -> opcode option

Get opcode from name

val op_name : op_data -> string

Get the operation name from op_data

ID Span Calculation

val id_span : op_data -> int

Calculate how many IDs an operation consumes. Most operations use exactly 1 ID, but some use more:

new_con: 1
new_val/new_obj/new_vec/new_str/new_bin/new_arr: 1
ins_val: 1
ins_obj: 1 (the entries reference existing IDs)
ins_vec: 1
ins_str: length of string (UTF-16 code units)
ins_bin: length of bytes
ins_arr: number of inserted elements
upd_arr: 1
del: 1
nop: nop_len

Constructors

val make_new_con : Value.t -> op_data

Create a new_con operation

val make_new_val : unit -> op_data

Create a new_val operation

val make_new_obj : unit -> op_data

Create a new_obj operation

val make_new_vec : unit -> op_data

Create a new_vec operation

val make_new_str : unit -> op_data

Create a new_str operation

val make_new_bin : unit -> op_data

Create a new_bin operation

val make_new_arr : unit -> op_data

Create a new_arr operation

val make_ins_val : obj:timestamp -> value:timestamp -> op_data

Create an ins_val operation

val make_ins_obj : obj:timestamp -> entries:obj_entry list -> op_data

Create an ins_obj operation

val make_ins_vec : obj:timestamp -> idx:int -> value:timestamp -> op_data

Create an ins_vec operation

val make_ins_str : obj:timestamp -> after:timestamp -> value:string -> op_data

Create an ins_str operation

val make_ins_bin : obj:timestamp -> after:timestamp -> value:bytes -> op_data

Create an ins_bin operation

val make_ins_arr : 
  obj:timestamp ->
  after:timestamp ->
  value:timestamp ->
  op_data

Create an ins_arr operation

val make_upd_arr : obj:timestamp -> pos:timestamp -> value:timestamp -> op_data

Create an upd_arr operation

val make_del : obj:timestamp -> what:timespan list -> op_data

Create a del operation

val make_nop : int -> op_data

Create a nop operation

Legacy compatibility

type t = {
  id : timestamp;
  op : op_data;
}

Legacy type alias - an operation with its ID

val name : t -> string

Get operation name from legacy type