Transaction Model

Quick Reference

Loro transactions are NOT database ACID transactions. They are operation bundling mechanisms for event emission.

Key Concepts

• Purpose: Bundle related operations and control event emission
• No rollback: Failed operations don’t undo previous ones
• Event batching: Single event for all operations in transaction
• History grouping: Operations stay together for undo/redo

Basic Usage

const doc = new LoroDoc();
 
// Without transaction - multiple events
const text = doc.getText("text");
text.insert(0, "Hello");
doc.commit(); // Event emitted
text.insert(5, " World");
doc.commit(); // Another event

How Transactions Work

Pending Operations

Local operations are pending by default and won’t emit events until committed:

const doc = new LoroDoc();
const text = doc.getText("text");
 
// Operation is pending, no event emitted yet
text.insert(0, "Hello");
 
// Explicit commit triggers event emission
doc.commit();

Implicit Commits

Certain operations trigger implicit commits automatically:

const doc = new LoroDoc();
const text = doc.getText("text");
 
text.insert(0, "Hello"); // Pending operation
 
// These operations trigger implicit commit:
doc.import(update); // Implicit commit before import
// or
doc.checkout(doc.frontiers()); // Implicit commit before checkout
// or
doc.export({ mode: "update" }); // Implicit commit before export

Transaction Guarantees

• All operations share the same timestamp (if enabled)
• Operations grouped in a single Change
• One event emitted after transaction completes
• Operations committed together at transaction end
• Before committing, the local edits are not synced to other peers

Related Documentation

• Operations and Changes - How transactions create Changes
• Event System - Understanding event emission
• Undo/Redo - Using transactions for undo boundaries