Docs
Tutorial
Encoding

Encoding

Loro uses a custom binary format inspired by Automerge to minimize the inherent redundancy found in CRDT documents.

Loro introduces two encoding schemes to meet the needs for different use cases.:

  • Snapshot Encoding: Encodes the entire document, including both the current document state and all the operations.
  • Updates Encoding: Focuses on encoding only selected ops, optimizing for quicker encoding times at the cost of potentially slower decoding.

Snapshot Encoding

const doc1 = new Loro();
const doc2 = new Loro();
 
doc2.getText("text").insert(0, "hello");
const bytes = doc2.exportSnapshot(); // Uint8Array
// These bytes can be stored in a database or transmitted over a network.
doc1.import(bytes);
console.log(doc1.toJSON()); // { text: "hello" }

Snapshot Encoding comprehensively captures a document's current state and its historical changes. By leveraging the sequence of operations for encoding, this scheme ensures efficient storage and swift loading of the document's state.

Updates Encoding

const doc1 = new Loro();
const doc2 = new Loro();
 
doc2.getText("text").insert(0, "hello");
const bytes = doc2.exportFrom(); // Uint8Array
// These bytes can be stored in a database or transmitted over a network.
doc1.import(bytes);
console.log(doc1.toJSON()); // { text: "hello" }

Updates Encoding selectively encodes operations from a chosen initial version to the most recent, enhancing support for real-time collaboration by focusing on incremental changes rather than the entire document state.

Best Practices for Persisting Loro Documents

  • Use Updates Encoding to export delta updates with each keystroke, facilitating immediate synchronization.
  • When the accumulation of updates begins to affect import speed, consolidate these updates with a Snapshot. This not only accelerates future imports but also reduces the overall document size.

The efficiency of encoding improves with the number of operations because the overhead is amortized over more operations

For collaborative purposes, the binary data generated by Snapshot/Updates Encoding can be transmitted through any medium, such as WebRTC, WebSocket, or HTTP.

The strong eventual consistency in CRDTs ensures that peers with identical sets of operations will converge to the same document state, obviating concerns about the order, duplication, or timing of operation delivery.

VersionCursor