Operations and Changes

Quick Reference

Operations are atomic edits. Changes are logical groups of operations with metadata. Understanding these helps optimize sync and performance.

Key Concepts

Operations

• Atomic units of change (insert a single Unicode character, delete a single character, insert an new entry to a map, etc.)
• Automatically merged internally for efficiency
• Each has unique ID: (peerId, counter)

Changes

• Groups of consecutive operations
• Include metadata (timestamp, dependencies, peer ID)
• Created by commit() or auto-commit

const doc = new LoroDoc();
const text = doc.getText("text");
 
text.insert(0, "Hello");     // Operation
text.insert(5, " World");    // Operation
doc.commit();                // Groups into one Change

Automatic Merging

Consecutive operations from same peer merge into one Change:

const doc = new LoroDoc();
const text = doc.getText("text");
 
text.insert(0, "abc");
doc.commit();  // Change #1
 
text.insert(3, "def");
doc.commit();  // Merges with #1 (same peer, consecutive)

When New Changes Are Created

1. Cross-peer dependencies: After importing remote operations
2. Time separation: When timestamps enabled and > the merge interval (default 1000s) between commits
3. Different commit messages:

const doc = new LoroDoc();
doc.getText("text").insert(0, "v1");
doc.commit(); // Change #1
 
// Import from another peer
const doc2 = new LoroDoc();
doc2.getText("text").insert(0, "v1");
const remote = doc2.export({ mode: "update" });
doc.import(remote);
 
// Next commit creates new Change (dependency on remote)
doc.getText("text").insert(0, "v2");
doc.commit(); // Change #2

Impact on Sync & Storage

• History: Changes track logical units of work
• Sync: Dependencies ensure causal ordering
• Storage: Auto-merging reduces metadata overhead

Related Documentation

• Transaction Model - Grouping operations
• Version Vector - How Changes form versions
• Synchronization - Using Changes for sync