DocsConceptsPeerID Management

PeerID Management

Quick Reference

Peer IDs are unique identifiers for each editing session in Loro’s distributed system. They ensure operation uniqueness without coordination between peers.

Key Concepts

  • Peer ID: A 64-bit unique identifier for each client/session
  • Operation ID: Combination of (peerId, counter) that uniquely identifies each operation
  • Counter: Monotonically increasing number starting at 0 for each peer
interface OpId {
  peerId: `${number}`;  // Unique peer identifier. It's string because 64bit integers are not supported in JS.
  counter: number;      // Monotonically increasing counter
}

Peer ID Assignment

Automatic (Default)

const  = new (); // Gets a random peer ID
// Safe, no coordination needed

Note: New peer ID generated for each LoroDoc instance, even when loading same document.

Manual

const  = new ();
.("123123123");  // You can only set 64 bit integers as peer IDs

⚠️ Warning: Manual assignment requires careful conflict avoidance.

If you intentionally reuse a Peer ID, persist the document’s local data (snapshot, updates, or durable cache) alongside that ID and load it before fetching or applying any remote updates. This ensures the (peerId, counter) pairs continue to reference the same operations. Skipping this step risks generating a new operation that reuses an existing operation ID, which leads to inconsistent replicas.

Counter System

Each peer maintains a monotonic counter starting at 0:

const  = new ();
.("1");
const  = .("text");
 
.(0, "H");    // Operation ("1", 0)
.(1, "i!");    // Operation ("1", 1) and Operation ("1", 2) are created
.(.()); // { "1": 2 }

Properties: Monotonic, continuous, per-peer, persistent.

Common Pitfalls

❌ Never:

  • Use user IDs as peer IDs, because an user can have multiple devices
  • Use fixed IDs
  • Reuse IDs without proper management
  • Allow multiple browser tabs or processes to operate on the same reused Peer ID in parallel—coordinate access with locks so that only one session emits operations for that ID at a time

Related Documentation

Import Status and Pending OperationsEvent Graph Walker (Eg-Walker)