OCaml CRDT Library#

A full OCaml 5.2+ implementation of JSON CRDTs compatible with json-joy.

Overview#

This library provides:

• JSON CRDT Document Model - 7 node types for representing any JSON structure
• Patch Operations - 18 opcodes for document mutations
• Multiple Codec Formats - Verbose, Compact, Binary, Sidecar, Indexed
• JSON-Rx RPC Protocol - Real-time synchronization over WebSocket/TCP
• Full ClockVector Support - Multi-session conflict resolution

Installation#

opam install crdt

Quick Example#

open Crdt

(* Create a new document *)
let model = Model.create 12345

(* Build a patch to set root to an object with a "name" field *)
let patch = Patch_builder.create model
  |> Patch_builder.set_root_obj
  |> Patch_builder.set_string "name" "Alice"
  |> Patch_builder.build

(* Apply the patch *)
Patch.iter_with_id (fun id op -> Model.apply_op model id op) patch;

(* View the document as JSON *)
let json = Model.view model
(* => Object [("name", String "Alice")] *)

(* Encode to binary for transmission *)
let bytes = Model_codec.Binary.encode model

Documentation#

• Architecture - Module structure and design
• json-joy Mapping - TypeScript to OCaml mapping
• Codecs - Encoding formats explained
• Getting Started - Tutorial with examples

Compatibility#

This library is wire-compatible with json-joy. Documents encoded in one can be decoded in the other. The conformance test suite in test/fixtures/traces/ validates this compatibility.

Module Index#

Demo Applications#

Three demo applications showcase real-time collaboration between OCaml (this library) and TypeScript (json-joy):

wb - HCS WebSocket Server#

A collaborative whiteboard server using the HCS HTTP library (Eio-based).

dune exec bin/wb/wb.exe
# or with custom port
PORT=3000 dune exec bin/wb/wb.exe

• Runtime: Eio (OCaml 5 effects)
• Protocol: WebSocket with JSON messages
• Frontend: HTML Canvas + json-joy
• Features: Drawing, presence cursors, chat, stroke history

Open http://localhost:8080 in multiple browsers to collaborate.

wbd - Dream WebSocket Server#

Same whiteboard application using the Dream framework (Lwt-based).

dune exec bin/wbd/wbd.exe

• Runtime: Lwt (promise-based async)
• Protocol: WebSocket with JSON messages
• Frontend: Shared with wb (static/)

Useful for comparing Eio vs Lwt implementations.

wbr - Raylib Native GUI#

A native desktop whiteboard using Raylib for graphics.

dune exec bin/wbr/wbr.exe -- --name "Alice" --host        # Start server
dune exec bin/wbr/wbr.exe -- --name "Bob" --connect HOST  # Connect to server
dune exec bin/wbr/wbr.exe -- --name "Carol"               # Local-only mode

• Runtime: Eio with Raylib bindings
• Protocol: Binary TCP with length-prefixed frames
• Features: Drawing, colors, brush sizes, presence, chat panel

Interoperability#

All demos demonstrate interoperability with json-joy:

1. Wire format: Binary patches encoded by OCaml can be decoded by json-joy and vice versa
2. Web frontend: The HTML/JS frontend uses json-joy for CRDT operations
3. Sync protocol: JSON-Rx messages are compatible between implementations

License#

ISC