API Reference

Creates a new LoroDoc from a snapshot. This is useful for loading a document from a previously exported snapshot.

Parameters:

• snapshot - Binary snapshot data

Returns: A new LoroDoc instance

Example:

import { LoroDoc } from "loro-crdt";
 
// Assume we have a snapshot from a previous export
const prevDoc = new LoroDoc();
prevDoc.getText("text").insert(0, "Hello");
const snapshot: Uint8Array = prevDoc.export({ mode: "snapshot" });
 
const doc = LoroDoc.fromSnapshot(snapshot);

Gets the peer ID of the current writer as a bigint.

See Also: PeerID Management

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const id = doc.peerId;

Gets the peer ID as a decimal string.

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const idStr = doc.peerIdStr;

Sets the peer ID for this document. It must be a number, a BigInt, or a decimal string that fits into an unsigned 64-bit integer. See PeerID Management for why uniqueness matters in distributed systems.

Parameters:

• peer - Peer ID as number, bigint, or decimal string

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.setPeerId("42");

⚠️ Critical Pitfall: Never let two parallel peers (e.g., multiple tabs/devices) share the same PeerID — it creates duplicate op IDs and causes document divergence. Common mistakes:

• Don’t assign a fixed PeerId to a user (users have multiple devices)
• Don’t assign a fixed PeerId to a device (multiple tabs can open the same document)
• If you must reuse PeerIDs, enforce single ownership with strict locking mechanisms
• Best practice: Use random IDs (default behavior) unless you have a strong reason not to

See PeerID reuse for safe reuse patterns.

Configures whether to automatically record timestamps for changes. Timestamps use Unix time (seconds since epoch). Learn more about storing timestamps and typical use cases in Storing Timestamps.

Parameters:

• auto_record - Whether to automatically record timestamps

⚠️ Important: This setting doesn’t persist in exported Updates or Snapshots. You must reapply this configuration each time you initialize a document.

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.setRecordTimestamp(true);

Sets the interval in milliseconds for merging continuous local changes into a single change record. In Loro, multiple low-level operations are grouped into higher-level Changes for readability and syncing. See Operations and Changes.

Parameters:

• interval - Merge interval in milliseconds

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.setChangeMergeInterval(1000); // Merge changes within 1 second

Configures the behavior of text styles (marks) in rich text containers. Marks can expand when edits happen at their edges (before/after/both/none). For a primer on rich text and marks in Loro, see Text.

Parameters:

• styles - Configuration object mapping style names to their config

StyleConfig Type:

type StyleConfig = Record<string, {
  expand?: "after" | "before" | "both" | "none"
}>

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.configTextStyle({
  bold: { expand: "after" },
  italic: { expand: "none" },
  link: { expand: "none" }
});

Configures the default text style for the document when using LoroText. If undefined is provided, the default style is reset.

Parameters:

• style - Default style configuration (optional)

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.configDefaultTextStyle({ expand: "after" });

Gets or creates a text container with the given name. New to LoroText and marks? See Text.

Parameters:

• name - The container name

Returns: A LoroText instance

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const text = doc.getText("content");
text.insert(0, "Hello");

Gets or creates a list container with the given name. Unsure whether to use List or MovableList? See List and Movable List and the type selection guide Choosing CRDT Types.

Parameters:

• name - The container name

Returns: A LoroList instance

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const list = doc.getList("items");
list.push("Item 1");

Gets or creates a map container with the given name. See Map for basics and patterns.

Parameters:

• name - The container name

Returns: A LoroMap instance

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const map = doc.getMap("settings");
map.set("theme", "dark");

Gets or creates a tree container with the given name. Learn about hierarchical editing and moves in Tree.

Parameters:

• name - The container name

Returns: A LoroTree instance

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const tree = doc.getTree("fileSystem");
const root = tree.createNode();

Gets or creates a counter container with the given name. Counters are special CRDTs that sum concurrent increments; see Counter.

Parameters:

• name - The container name

Returns: A LoroCounter instance

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const counter = doc.getCounter("likes");
counter.increment(1);

Gets or creates a movable list container with the given name. MovableList is designed for reordering with concurrent moves. See List and Movable List and Choosing CRDT Types.

Parameters:

• name - The container name

Returns: A LoroMovableList instance

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const movableList = doc.getMovableList("tasks");
movableList.push("Task 1");
movableList.push("Task 2");
movableList.push("Task 3");
movableList.move(0, 2); // Move first item to third position

Gets a container by its unique ID. Container IDs (CID) uniquely reference containers across updates; see Container ID and Container.

Parameters:

• id - The container ID

Returns: The container instance or undefined if not found

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const text = doc.getText("text");
const textId = text.id;
const sameText = doc.getContainerById(textId);

Exports the document in various formats for synchronization or persistence. For a walkthrough of export modes—snapshot, update, shallow-snapshot, and updates-in-range—see Export Mode. Shallow snapshots remove history while keeping current state; see Shallow Snapshots. VersionVector and Frontiers are two ways to represent versions; see Version Vector and Frontiers.

Parameters:

• mode - Export configuration (optional)

ExportMode Options:

type ExportMode = 
  | { mode: "snapshot" }
  | { mode: "update", from?: VersionVector }
  | { mode: "shallow-snapshot", frontiers: Frontiers }
  | { mode: "updates-in-range", spans: { id: OpId; len: number }[] }

Returns: Encoded binary data

⚠️ Important Notes:

• Shallow snapshots: Cannot import updates from before the shallow start point. Peers can only sync if they have versions after this point.
• Auto-commit: The document automatically commits pending operations before export.
• Performance: Export new snapshots periodically to reduce import times for new peers.

Examples:

import { LoroDoc, VersionVector } from "loro-crdt";
 
const doc = new LoroDoc();
// ... make some changes to the document ...
 
// Export full snapshot
const snapshot = doc.export({ mode: "snapshot" });
 
// Export updates from a specific version
const lastSyncVersion = doc.version(); // Get current version
// ... make more changes ...
const updates = doc.export({ 
  mode: "update", 
  from: lastSyncVersion 
});
 
// Export shallow snapshot at current version
const shallowSnapshot = doc.export({ 
  mode: "shallow-snapshot",
  frontiers: doc.frontiers()
});

Imports updates or snapshots into the document. Returns an ImportStatus describing which peer ranges were applied or are pending. See Sync and Import Status for how Loro handles out-of-order and partial updates.

Parameters:

• data - Binary data or another LoroDoc to import from

⚠️ Important: LoroDoc will automatically commits pending operations before import. If the doc is in detached mode, the imported operations are recorded into OpLog but not applied to DocState until you call attach(), see Attached vs Detached States adn OpLog and DocState.

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
// Receive updates from another peer (e.g., via network)
const otherDoc = new LoroDoc();
otherDoc.getText("text").insert(0, "Hello");
const updates: Uint8Array = otherDoc.export({ mode: "update" });
 
// Import binary updates
const status = doc.import(updates);
console.log(status.success);

Efficiently imports multiple updates in a single batch operation. See Batch Import for performance considerations and usage.

Parameters:

• data - Array of binary updates

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
declare const update1: Uint8Array;
declare const update2: Uint8Array;
declare const update3: Uint8Array;
 
// Usage example:
const updates = [update1, update2, update3];
const status = doc.importBatch(updates);

Exports updates in JSON format for debugging or alternative storage. See Export Mode for format details and trade-offs.

Parameters:

• start - Starting version (optional)
• end - Ending version (optional)

Returns: JSON representation of updates

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const jsonUpdates = doc.exportJsonUpdates();
console.log(JSON.stringify(jsonUpdates, null, 2));

Imports updates from JSON format. Useful for debugging, migration, or custom storage layers; see Export Mode.

Parameters:

• json - JSON string or object containing updates

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const otherDoc = new LoroDoc();
otherDoc.getText("text").insert(0, "Hello");
const jsonStr = otherDoc.exportJsonUpdates();
doc.importJsonUpdates(jsonStr);

Checks out the document to a specific version, making it read-only at that point in history. This is the core of time travel; see Time Travel and Version.

Parameters:

• frontiers - Array of OpIds representing the target version

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const frontiers = doc.frontiers();
// Make some changes...
doc.checkout(frontiers); // Go back to previous version

⚠️ Important: In Loro 1.0, version()/frontiers() include pending (uncommitted) local operations.

📝 Note: After checkout(), the document enters “detached” mode and becomes read-only by default. Use attach() or checkoutToLatest() to return to editing mode. See Version Deep Dive and Attached vs Detached States.

Returns the document to the latest version after a checkout. Related concepts: Frontiers and Version Vector.

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.checkoutToLatest();

Attaches the document to track latest changes after being detached. See Attached vs Detached States for how Loro separates current state from history.

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.attach();

Detaches the document from tracking latest changes, freezing it at current version. See Attached vs Detached States.

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.detach();

Creates a new document that is a fork of the current one with a new peer ID. Forking is useful for branching workflows; see Version.

Returns: A new LoroDoc instance

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const forkedDoc = doc.fork();

Creates a fork at a specific version in history. Learn more about versions, DAG history, and heads in Version Deep Dive.

Parameters:

• frontiers - The version to fork from

Returns: A new LoroDoc instance

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const frontiers = doc.frontiers();
const forkedDoc = doc.forkAt(frontiers);

Subscribes to all document changes. See Event Handling for the event model and best practices.

Parameters:

• listener - Callback function that receives change events

Returns: Unsubscribe function

Event Structure:

interface LoroEventBatch {
  by: "local" | "import" | "checkout"
  origin?: string
  currentTarget?: ContainerID
  events: LoroEvent[]
  from: Frontiers
  to: Frontiers
}

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const unsubscribe = doc.subscribe((event) => {
  console.log("Change type:", event.by);
  event.events.forEach(e => {
    console.log("Container changed:", e.target);
    console.log("Diff:", e.diff);
  });
});
 
// Later: unsubscribe();

⚠️ Important: Events are emitted asynchronously after a microtask.

doc.commit();
await Promise.resolve();
// Now events have been emitted

📝 Note: Multiple operations before a commit are batched into a single event. See Event Handling.

Subscribes only to local changes, useful for syncing with remote peers. This is typically wired to your transport layer; see Sync.

Parameters:

• f - Callback that receives binary updates

Returns: Unsubscribe function

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
declare const websocket: { send: (data: Uint8Array) => void };
 
// Usage example:
const unsubscribe = doc.subscribeLocalUpdates((updates) => {
  // Send updates to remote peers
  websocket.send(updates);
});

Subscribes to the first commit from each peer, useful for tracking peer metadata.

Parameters:

• f - Callback that receives peer information

Returns: Unsubscribe function

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.subscribeFirstCommitFromPeer(({ peer }) => {
  // Store peer metadata
  doc.getMap("peers").set(peer, {
    joinedAt: Date.now(),
    name: `User ${peer}`
  });
});

Commits pending changes as a single transaction. A transaction groups operations into a Change; see Operations and Changes.

⚠️ Critical Distinction: Loro transactions are NOT ACID database transactions:

• No rollback capability
• No isolation guarantees
• Purpose: Bundle local operations for event batching and history grouping
• Many operations (import/export/checkout) trigger implicit commits

See Transaction Model.

Parameters:

• options - Optional commit configuration
  • message - Commit message (persisted in the document like a git commit message, visible to all peers after sync)
  • origin - Origin identifier (local only - used for marking local events, remote peers won’t see this)
  • timestamp - Unix timestamp in seconds (see Storing Timestamps)

Important distinction:

• message is persisted in the document’s history and will be synchronized to all peers, similar to git commit messages
• origin is only used locally for filtering events (e.g., excluding certain origins from undo) and is NOT synchronized to remote peers

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.commit({
  message: "Updated document title", // Persisted & synced to all peers
  origin: "user-action",             // Local only, for event filtering
  timestamp: Math.floor(Date.now() / 1000)
});

Converts the entire document to a JSON-compatible value. If you prefer a structure where sub-containers are referenced by ID (for privacy or streaming), use getShallowValue(); see Shallow Snapshots.

Returns: JSON representation of the document

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const json = doc.toJSON();
console.log(JSON.stringify(json, null, 2));

Gets a shallow representation where sub-containers are represented by their IDs. This is helpful when you want to share structure without history; see Shallow Snapshots.

Returns: Shallow JSON value

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const shallow = doc.getShallowValue();
// Sub-containers appear as: "cid:..."

Gets the deep value of the document with container IDs preserved. This is useful when you need to traverse the document structure while maintaining references to container IDs.

Returns: Document value with container IDs

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const deepValue = doc.getDeepValueWithID();

Gets the current version vector of the document. Version vectors track how much data from each peer you’ve seen; see Version Vector.

Returns: Map from PeerID to counter

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const vv = doc.version();
console.log(vv.toJSON());

Gets the current frontiers (heads) of the document. Frontiers are a compact representation of a version; see Frontiers for when to use them instead of version vectors.

📝 Note: Frontiers are a compact version representation.

⚠️ Limitation: When you have a Frontier pointing to operations you don’t know about, you cannot determine the complete set of operation IDs included in that version. Version Vectors don’t have this limitation but are more verbose. See Frontiers for trade-offs.

Returns: Array of OpIds

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const frontiers = doc.frontiers();
// Can be used for checkouts or shallow snapshots

Calculates differences between two versions. Understanding how Loro computes diffs benefits from the history DAG model; see Version Deep Dive.

Parameters:

• from - Starting frontiers
• to - Ending frontiers
• for_json - If true, returns JsonDiff format (default: true)

Returns: Array of container IDs and their diffs

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const fromFrontiers = doc.frontiers();
// Make changes...
const toFrontiers = doc.frontiers();
 
const diffs = doc.diff(fromFrontiers, toFrontiers);
diffs.forEach(([containerId, diff]) => {
  console.log(`Container ${containerId} changed:`, diff);
});

Subscribe to the pre-commit event. You can modify the message and timestamp of the next change. This hook runs right before a Change is recorded; see Transaction Model and Operations and Changes.

Pitfall: commit() can be triggered implicitly by import, export, and checkout. Use this hook to attach metadata even for those implicit commits.

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const unsubscribe = doc.subscribePreCommit(({ modifier }) => {
  modifier
    .setMessage("Tagged by pre-commit")
    .setTimestamp(Math.floor(Date.now() / 1000));
});
doc.getText("text").insert(0, "Hello");
doc.commit();
unsubscribe();

Resolve a stable Cursor to an absolute position. Cursors remain valid across concurrent edits; see Cursor and Stable Positions and Cursor tutorial. The side controls affinity when the cursor sits at an insertion boundary.

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const text = doc.getText("text");
text.insert(0, "abc");
 
// Get cursor at position 1
const c0 = text.getCursor(1);
const pos = doc.getCursorPos(c0!);
console.log(pos.offset); // 1

Get pending operations from the current transaction in JSON format. Useful for debugging what will be included in the next Change; see Transaction Model.

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const text = doc.getText("text");
 
text.insert(0, "Hello");
const pending = doc.getUncommittedOpsAsJson();
doc.commit();
const none = doc.getUncommittedOpsAsJson(); // undefined after commit

Visit ancestors of the given changes in causal order.

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.getText("text").insert(0, "Hello");
doc.commit();
const head = doc.frontiers();
doc.travelChangeAncestors(head, (change) => {
  console.log(change.peer, change.counter);
  return true; // continue
});

Find the op id spans that lie between two versions.

Get container IDs modified in the given ID range.

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.getList("list").insert(0, 1);
doc.commit();
const head = doc.frontiers()[0];
const containers = doc.getChangedContainersIn(head, 1);

Revert the document to a given version by generating inverse operations.

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.setPeerId("1");
const t = doc.getText("text");
t.update("Hello");
doc.commit();
doc.revertTo([{ peer: "1", counter: 1 }]);

Apply a batch of diffs to the document.

import { LoroDoc } from "loro-crdt";
const doc1 = new LoroDoc();
const doc2 = new LoroDoc();
 
// Usage example:
doc1.getText("text").insert(0, "Hello");
const diff = doc1.diff([], doc1.frontiers());
doc2.applyDiff(diff);

Enables or disables detached editing mode. Detached editing lets you stage edits separate from the latest head; see Attached vs Detached States.

Parameters:

• enable - Whether to enable detached editing

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.setDetachedEditing(true);

Checks if detached editing mode is enabled.

Returns: True if detached editing is enabled

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const enabled = doc.isDetachedEditingEnabled();

Checks if the document is currently detached.

Returns: True if document is detached

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
console.log(doc.isDetached());

Sets the message for the next commit.

Parameters:

• msg - Commit message

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.setNextCommitMessage("User action");

Sets the origin for the next commit.

Parameters:

• origin - Origin identifier

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.setNextCommitOrigin("ui");

Sets the timestamp for the next commit.

Parameters:

• timestamp - Unix timestamp in seconds

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.setNextCommitTimestamp(Math.floor(Date.now() / 1000));

Sets multiple options for the next commit.

Parameters:

• options - Commit options object

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.setNextCommitOptions({ origin: "ui", message: "batch" });
doc.getText("text").insert(0, "Hi");
doc.commit();

Clears all pending commit options.

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.clearNextCommitOptions();

Converts frontiers to a version vector.

Parameters:

• frontiers - Frontiers to convert

Returns: Version vector representation

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const frontiers = doc.frontiers();
const vv = doc.frontiersToVV(frontiers);

Converts a version vector to frontiers.

Parameters:

• vv - Version vector to convert

Returns: Frontiers representation

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const vv = doc.version();
const frontiers = doc.vvToFrontiers(vv);

Gets the oplog version vector.

Returns: Oplog version vector

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const vv = doc.oplogVersion();

Gets the oplog frontiers.

Returns: Oplog frontiers

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const frontiers = doc.oplogFrontiers();

Compares current document state with given frontiers.

Parameters:

• frontiers - Frontiers to compare with

Returns: -1 if behind, 0 if equal, 1 if ahead

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const frontiers = doc.frontiers();
const cmp = doc.cmpWithFrontiers(frontiers);

Compares two frontiers.

Parameters:

• a - First frontiers
• b - Second frontiers

Returns: -1 if a < b, 0 if equal, 1 if a > b, undefined if incomparable

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const f1 = doc.frontiers();
const f2 = doc.frontiers();
const cmp = doc.cmpFrontiers(f1, f2);

Gets a value or container by its path.

Parameters:

• path - Path string (e.g., “map/key”)

Returns: Value or container at the path, or undefined

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const map = doc.getMap("map");
map.set("key", 1);
 
// Usage example:
const value = doc.getByPath("map/key");

Gets the path to a container by its ID.

Parameters:

• id - Container ID

Returns: Array representing the path, or undefined

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const map = doc.getMap("map");
 
const path = doc.getPathToContainer(map.id);

Queries the document using JSONPath syntax.

Parameters:

• jsonpath - JSONPath query string

Returns: Array of matching values

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const map = doc.getMap("map");
map.set("key", 1);
 
// Usage example:
const results = doc.JSONPath("$.map");

Gets the version vector since which the document is shallow.

Returns: Version vector

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const vv = doc.shallowSinceVV();

Gets the frontiers since which the document is shallow.

Returns: Frontiers

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const frontiers = doc.shallowSinceFrontiers();

Checks if the document is shallow.

Returns: True if document is shallow

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const shallow = doc.isShallow();

Controls whether empty root containers are hidden in JSON output.

Parameters:

• hide - Whether to hide empty root containers

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.setHideEmptyRootContainers(true);
// Now empty roots are hidden in toJSON()

Deletes a root container.

Parameters:

• cid - Container ID to delete

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const map = doc.getMap("map");
 
// Usage example:
doc.deleteRootContainer(map.id);

Checks if a container exists in the document.

Parameters:

• id - Container ID to check

Returns: True if container exists

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const map = doc.getMap("map");
 
const exists = doc.hasContainer(map.id);

Customize JSON serialization of containers and values.

Parameters:

• replacer - Function to transform values during serialization

Returns: Customized JSON value

Example:

import { LoroDoc, LoroText } from "loro-crdt";
const doc = new LoroDoc();
const text = doc.getText("text");
text.insert(0, "Hello");
 
// Usage example:
const json = doc.toJsonWithReplacer((key, value) => {
  if (value instanceof LoroText) {
    return value.toDelta();
  }
  return value;
});

Prints debug information about the document history.

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.debugHistory();

Gets the total number of changes in the document.

Returns: Number of changes

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const changes = doc.changeCount();

Gets the total number of operations in the document.

Returns: Number of operations

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const ops = doc.opCount();

Gets all changes grouped by peer ID.

Returns: Map of peer ID to changes

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const changes = doc.getAllChanges();

Gets a specific change by operation ID.

Parameters:

• id - Operation ID

Returns: Change object

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.getText("text").insert(0, "hello");
doc.commit()
const changes = doc.getAllChanges();
const change = changes.get(doc.peerIdStr)?.[0];

Gets a change by peer ID and Lamport timestamp.

Parameters:

• peer_id - Peer ID
• lamport - Lamport timestamp

Returns: Change object or undefined

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.getText("text").insert(0, "hello");
const change = doc.getChangeAtLamport(doc.peerIdStr, 1);

Gets all operations in a specific change.

Parameters:

• id - Operation ID

Returns: Array of operations

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.getText("text").insert(0, "hello");
const changes = doc.getAllChanges();
const ops = doc.getOpsInChange(changes[0].id);

Gets the number of pending operations in the current transaction.

Returns: Number of pending operations

Example:

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
doc.getText("text").insert(0, "x");
console.log(doc.getPendingTxnLength());
doc.commit();

Decodes metadata from an import blob.

Parameters:

• blob - Binary data to decode
• check_checksum - Whether to verify checksum

Returns: Import blob metadata

Example:

import { LoroDoc, decodeImportBlobMeta } from "loro-crdt";
 
const doc = new LoroDoc();
const updates = doc.export({ mode: "update" });
const meta = decodeImportBlobMeta(updates, true);

Redacts JSON updates within a specified version range.

Use this to safely remove accidentally leaked sensitive content from history while preserving structure. See Tips: Redaction.

Parameters:

• json - JSON updates to redact
• version_range - Version range for redaction

Returns: Redacted JSON schema

Example:

import { LoroDoc, redactJsonUpdates } from "loro-crdt";
 
const doc = new LoroDoc();
const json = doc.exportJsonUpdates();
const redacted = redactJsonUpdates(json, { [doc.peerIdStr]: [0, 999999] });

Inserts text at the specified position using UTF-16 code unit indices (same as JavaScript string indices).

Parameters:

• index - UTF-16 code unit position to insert at (0-based, same as JavaScript string index)
• text - Text to insert

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const text = doc.getText("text");
 
// Usage example:
text.insert(0, "Hello ");
text.insert(6, "World");

Deletes text from the specified position using UTF-16 code units.

Parameters:

• index - Starting UTF-16 code unit position (same as JavaScript string index)
• len - Number of UTF-16 code units to delete

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const text = doc.getText("text");
text.insert(0, "Hello 😀 World");
text.delete(6, 2); // Delete emoji (2 UTF-16 units)
text.delete(5, 1); // Delete space before World

Applies formatting to a text range. Marks can be configured to expand/stop at edges via configTextStyle(); see Text for mark behavior.

Parameters:

• range - The range to format
• key - Style attribute name
• value - Style value

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const text = doc.getText("text");
text.insert(0, "Hello World");
doc.configTextStyle({ bold: { expand: "after" } });
text.mark({ start: 0, end: 5 }, "bold", true);

Removes formatting from a text range. For how conflicting edits on marks resolve, see Text.

Parameters:

• range - The range to unformat
• key - Style attribute to remove

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const text = doc.getText("text");
text.insert(0, "Hello World");
text.mark({ start: 0, end: 5 }, "bold", true);
text.unmark({ start: 0, end: 5 }, "bold");

Converts text to Delta format (Quill-compatible).

Returns: Array of Delta operations

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const text = doc.getText("text");
text.insert(0, "Hello World");
text.mark({ start: 0, end: 5 }, "bold", true);
const delta = text.toDelta();
// [{ insert: "Hello", attributes: { bold: true } }, { insert: " World" }]

Applies Delta operations to the text.

Parameters:

• delta - Array of Delta operations

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const text = doc.getText("text");
text.applyDelta([
  { insert: "Hello", attributes: { bold: true } },
  { insert: " World" }
]);

Updates the current text to the target text using Myers’ diff algorithm.

Parameters:

• text - New text content
• options - Update options
  • timeoutMs - Optional timeout for the diff computation
  • useRefinedDiff - Use refined diff for better quality on long texts

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const text = doc.getText("text");
 
text.insert(0, "Hello");
text.update("Hello World", { timeoutMs: 100 });

Line-based update that’s faster for large texts (less precise than update).

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const text = doc.getText("text");
 
text.insert(0, "Line A\nLine C");
text.updateByLine("Line A\nLine B\nLine C");

Gets a stable cursor position that survives edits.

Parameters:

• pos - Position in the text
• side - Cursor affinity (-1, 0, or 1)

Returns: Cursor object or undefined

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const text = doc.getText("text");
text.insert(0, "Hello World");
 
const cursor = text.getCursor(5);
// Cursor remains valid even after edits

Converts to plain text string.

Returns: Plain text content

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const text = doc.getText("text");
text.insert(0, "Hello World");
const plainText = text.toString();

Gets the character at a specific UTF-16 code unit position.

Parameters:

• pos - UTF-16 code unit position

Returns: Character at position

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const text = doc.getText("text");
text.insert(0, "Hello");
const char = text.charAt(1); // "e"

Extracts a section of the text using UTF-16 code unit positions.

Parameters:

• start - Start UTF-16 code unit index
• end - End UTF-16 code unit index (exclusive)

Returns: Sliced text

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const text = doc.getText("text");
text.insert(0, "Hello 😀 World");
 
const slice1 = text.slice(0, 5);  // "Hello"
const slice2 = text.slice(6, 8);  // "😀" (emoji spans 6-8)
const slice3 = text.slice(9, 14); // "World"

Replaces text at a position with new content.

Parameters:

• pos - Start position
• len - Length to delete
• s - String to insert

Returns: Deleted text

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const text = doc.getText("text");
text.insert(0, "Hello World");
 
// Usage example:
const deleted = text.splice(6, 5, "Loro"); // returns "World"

Appends text to the end of the document.

Parameters:

• s - String to append

Example:

import { LoroDoc } from "loro-crdt";
const doc = new LoroDoc();
const text = doc.getText("text");
 
text.push("Hello");
text.push(" World");