Struct LoroDoc 

pub struct LoroDoc { /* private fields */ }

LoroDoc is the entry for the whole document. When it’s dropped, all the associated Containers will be invalidated.

Important: Loro is a pure library and does not handle network protocols. It is the responsibility of the user to manage the storage, loading, and synchronization of the bytes exported by Loro in a manner suitable for their specific environment.

Implementations

impl LoroDoc

pub fn new() -> Self

Create a new LoroDoc instance.

pub fn fork(&self) -> Self

Duplicate the document with a different PeerID

The time complexity and space complexity of this operation are both O(n),

When called in detached mode, it will fork at the current state frontiers. It will have the same effect as fork_at(&self.state_frontiers()).

pub fn fork_at(&self, frontiers: &Frontiers) -> LoroDoc

Fork the document at the given frontiers.

The created doc will only contain the history before the specified frontiers.

pub fn config(&self) -> &Configure

Get the configurations of the document.

pub fn get_change(&self, id: ID) -> Option<ChangeMeta>

Get Change at the given id.

Change is a grouped continuous operations that share the same id, timestamp, commit message.

• The id of the Change is the id of its first op.
• The second op’s id is { peer: change.id.peer, counter: change.id.counter + 1 }

The same applies on Lamport:

• The lamport of the Change is the lamport of its first op.
• The second op’s lamport is change.lamport + 1

The length of the Change is how many operations it contains

pub fn decode_import_blob_meta( bytes: &[u8], check_checksum: bool, ) -> LoroResult<ImportBlobMetadata>

Decodes the metadata for an imported blob from the provided bytes.

Example

use loro::{LoroDoc, ExportMode};

let doc = LoroDoc::new();
doc.get_text("t").insert(0, "Hello").unwrap();
let updates = doc.export(ExportMode::all_updates()).unwrap();
let meta = LoroDoc::decode_import_blob_meta(&updates, true).unwrap();
assert!(meta.change_num >= 1);

pub fn set_record_timestamp(&self, record: bool)

Set whether to record the timestamp of each change. Default is false.

If enabled, the Unix timestamp will be recorded for each change automatically. You can also set a timestamp explicitly via [set_next_commit_timestamp].

Important: this is a runtime configuration. It is not serialized into updates or snapshots. You must reapply it for each new LoroDoc you create or load.

NOTE: Timestamps are forced to be in ascending order. If you commit a new change with a timestamp earlier than the latest, the largest existing timestamp will be used instead.

Example

use loro::LoroDoc;
let doc = LoroDoc::new();
doc.set_record_timestamp(true);
doc.get_text("t").insert(0, "hi").unwrap();
doc.commit();

pub fn set_detached_editing(&self, enable: bool)

Enables editing in detached mode, which is disabled by default.

The doc enter detached mode after calling detach or checking out a non-latest version.

Important Notes:

• This mode uses a different PeerID for each checkout.
• Ensure no concurrent operations share the same PeerID if set manually.
• Importing does not affect the document’s state or version; changes are recorded in the OpLog only. Call checkout to apply changes.

Example

use loro::LoroDoc;

let doc = LoroDoc::new();
let v0 = doc.state_frontiers();
// Make some edits…
doc.get_text("t").insert(0, "Hello").unwrap();
doc.commit();

// Travel back and enable detached editing
doc.checkout(&v0).unwrap();
assert!(doc.is_detached());
doc.set_detached_editing(true);
doc.get_text("t").insert(0, "old").unwrap();
// Later, re-attach to see latest again
doc.attach();

pub fn is_detached_editing_enabled(&self) -> bool

Whether editing the doc in detached mode is allowed, which is disabled by default.

The doc enter detached mode after calling detach or checking out a non-latest version.

Important Notes:

• This mode uses a different PeerID for each checkout.
• Ensure no concurrent operations share the same PeerID if set manually.
• Importing does not affect the document’s state or version; changes are recorded in the OpLog only. Call checkout to apply changes.

pub fn set_change_merge_interval(&self, interval: i64)

Set the interval of mergeable changes, in seconds.

If two continuous local changes are within the interval, they will be merged into one change. The default value is 1000 seconds.

By default, we record timestamps in seconds for each change. So if the merge interval is 1, and changes A and B have timestamps of 3 and 4 respectively, then they will be merged into one change.

pub fn config_text_style(&self, text_style: StyleConfigMap)

Set the rich text format configuration of the document.

Configure the expand behavior for marks used by LoroText::mark/LoroText::unmark. This controls how marks grow when text is inserted at their boundaries.

• after (default): inserts just after the range expand the mark
• before: inserts just before the range expand the mark
• both: inserts on either side expand the mark
• none: do not expand at boundaries

Example

use loro::{LoroDoc, StyleConfigMap, StyleConfig, ExpandType};
let doc = LoroDoc::new();
let mut styles = StyleConfigMap::new();
styles.insert("bold".into(), StyleConfig { expand: ExpandType::After });
doc.config_text_style(styles);

pub fn config_default_text_style(&self, text_style: Option<StyleConfig>)

Configures the default text style for the document.

This method sets the default text style configuration for the document when using LoroText. If None is provided, the default style is reset.

Parameters

• text_style: The style configuration to set as the default. None to reset.

Example

use loro::{LoroDoc, StyleConfig, ExpandType};
let doc = LoroDoc::new();
doc.config_default_text_style(Some(StyleConfig { expand: ExpandType::After }));

pub fn attach(&self)

Attach the document state to the latest known version.

The document becomes detached during a checkout operation. Being detached implies that the DocState is not synchronized with the latest version of the OpLog. In a detached state, the document is not editable, and any import operations will be recorded in the OpLog without being applied to the DocState.

pub fn checkout(&self, frontiers: &Frontiers) -> LoroResult<()>

Checkout the DocState to a specific version.

The document becomes detached during a checkout operation. Being detached implies that the DocState is not synchronized with the latest version of the OpLog. In a detached state, the document is not editable, and any import operations will be recorded in the OpLog without being applied to the DocState.

You should call attach (or checkout_to_latest) to reattach the DocState to the latest version of OpLog. If you need to edit while detached, enable [set_detached_editing(true)], but note it uses a different PeerID per checkout.

pub fn checkout_to_latest(&self)

Checkout the DocState to the latest version.

The document becomes detached during a checkout operation. Being detached implies that the DocState is not synchronized with the latest version of the OpLog. In a detached state, the document is not editable, and any import operations will be recorded in the OpLog without being applied to the DocState.

This has the same effect as attach.

pub fn cmp_with_frontiers(&self, other: &Frontiers) -> Ordering

Compare the frontiers with the current OpLog’s version.

If other contains any version that’s not contained in the current OpLog, return Ordering::Less.

pub fn cmp_frontiers( &self, a: &Frontiers, b: &Frontiers, ) -> Result<Option<Ordering>, FrontiersNotIncluded>

Compare two frontiers.

If the frontiers are not included in the document, return FrontiersNotIncluded.

pub fn detach(&self)

Force the document enter the detached mode.

In this mode, importing new updates only records them in the OpLog; the loro_internal::DocState is not updated until you reattach.

Learn more at https://loro.dev/docs/advanced/doc_state_and_oplog#attacheddetached-status

pub fn import_batch(&self, bytes: &[Vec<u8>]) -> LoroResult<ImportStatus>

Import a batch of updates/snapshot.

The data can be in arbitrary order. The import result will be the same. Auto-commit: same as [import], this finalizes the current transaction first.

Example

use loro::{LoroDoc, ExportMode};
let a = LoroDoc::new();
a.get_text("t").insert(0, "A").unwrap();
let u1 = a.export(ExportMode::all_updates()).unwrap();
a.get_text("t").insert(1, "B").unwrap();
let u2 = a.export(ExportMode::all_updates()).unwrap();

let b = LoroDoc::new();
let status = b.import_batch(&[u2, u1]).unwrap(); // arbitrary order
assert!(status.pending.is_none());

pub fn get_container(&self, id: ContainerID) -> Option<Container>

Get a Container by container id.

pub fn get_movable_list<I: IntoContainerId>(&self, id: I) -> LoroMovableList

Get a LoroMovableList by container id.

If the provided id is string, it will be converted into a root container id with the name of the string.

pub fn get_list<I: IntoContainerId>(&self, id: I) -> LoroList

Get a LoroList by container id.

If the provided id is string, it will be converted into a root container id with the name of the string. Note: creating/accessing a root container does not record history; creating nested containers (e.g., Map::insert_container) does.

pub fn get_map<I: IntoContainerId>(&self, id: I) -> LoroMap

Get a LoroMap by container id.

If the provided id is string, it will be converted into a root container id with the name of the string. Note: creating/accessing a root container does not record history; creating nested containers (e.g., Map::insert_container) does.

pub fn get_text<I: IntoContainerId>(&self, id: I) -> LoroText

Get a LoroText by container id.

If the provided id is string, it will be converted into a root container id with the name of the string. Note: creating/accessing a root container does not record history; creating nested containers (e.g., Map::insert_container) does.

pub fn get_tree<I: IntoContainerId>(&self, id: I) -> LoroTree

Get a LoroTree by container id.

If the provided id is string, it will be converted into a root container id with the name of the string. Note: creating/accessing a root container does not record history; creating nested containers (e.g., Map::insert_container) does.

pub fn commit(&self)

Commit the cumulative auto commit transaction.

There is a transaction behind every operation. The events will be emitted after a transaction is committed. A transaction is committed when:

• doc.commit() is called.
• doc.export(mode) is called.
• doc.import(data) is called.
• doc.checkout(version) is called.

Note: Loro transactions are not ACID database transactions. There is no rollback or isolation; they are a grouping mechanism for events/history. For interactive undo/redo, use UndoManager.

Empty-commit behavior: this method is an explicit commit. If the pending transaction is empty, any previously set next-commit options (message/timestamp/origin) are swallowed and will not carry over.

pub fn commit_with(&self, options: CommitOptions)

Commit the cumulative auto commit transaction with custom options.

There is a transaction behind every operation. It will automatically commit when users invoke export or import. The event will be sent after a transaction is committed

See also: [set_next_commit_message], [set_next_commit_origin], [set_next_commit_timestamp]. Commit messages are persisted and replicate to peers; origins are local-only metadata.

Empty-commit behavior: this method is an explicit commit. If the pending transaction is empty, the provided options are swallowed and will not carry over. For implicit commits triggered by export/checkout (commit barriers), message/timestamp/origin from an empty transaction are preserved for the next commit.

pub fn set_next_commit_message(&self, msg: &str)

Set commit message for the current uncommitted changes

It will be persisted.

pub fn set_next_commit_origin(&self, origin: &str)

Set origin for the current uncommitted changes, it can be used to track the source of changes in an event.

It will NOT be persisted.

pub fn set_next_commit_timestamp(&self, timestamp: Timestamp)

Set the timestamp of the next commit.

It will be persisted and stored in the OpLog. You can get the timestamp from the [Change] type.

pub fn set_next_commit_options(&self, options: CommitOptions)

Set the options of the next commit.

It will be used when the next commit is performed.

Example

use loro::{LoroDoc, CommitOptions};
let doc = LoroDoc::new();
doc.set_next_commit_options(CommitOptions::new().origin("ui").commit_msg("tagged"));
doc.get_text("t").insert(0, "x").unwrap();
doc.commit();

pub fn clear_next_commit_options(&self)

Clear the options of the next commit.

pub fn is_detached(&self) -> bool

Whether the document is in detached mode, where the loro_internal::DocState is not synchronized with the latest version of the loro_internal::OpLog.

pub fn from_snapshot(bytes: &[u8]) -> LoroResult<Self>

Create a new LoroDoc from a snapshot.

The snapshot is created via LoroDoc::export with ExportMode::Snapshot.

Example

use loro::{LoroDoc, ExportMode};

let doc = LoroDoc::new();
let text = doc.get_text("text");
text.insert(0, "Hello").unwrap();
let snapshot = doc.export(ExportMode::Snapshot).unwrap();

let restored = LoroDoc::from_snapshot(&snapshot).unwrap();
assert_eq!(restored.get_deep_value(), doc.get_deep_value());

pub fn import(&self, bytes: &[u8]) -> Result<ImportStatus, LoroError>

Import data exported by LoroDoc::export.

Use ExportMode::Snapshot for full-state snapshots, or ExportMode::all_updates / ExportMode::updates for updates.

Example

use loro::{LoroDoc, ExportMode};

let a = LoroDoc::new();
a.get_text("text").insert(0, "Hello").unwrap();
let updates = a.export(ExportMode::all_updates()).unwrap();

let b = LoroDoc::new();
b.import(&updates).unwrap();
assert_eq!(a.get_deep_value(), b.get_deep_value());

Pitfalls:

• Missing dependencies: check the returned ImportStatus. If pending is non-empty, fetch those missing ranges (e.g., using export(ExportMode::updates(&doc.oplog_vv()))) and re-import.
• Auto-commit: import finalizes the current transaction before applying incoming data.

pub fn import_with( &self, bytes: &[u8], origin: &str, ) -> Result<ImportStatus, LoroError>

Import data exported by LoroDoc::export and mark it with a custom origin.

The origin string will be attached to the ensuing change event, which is handy for telemetry or filtering. Pitfalls:

• Same as [import]: verify ImportStatus.pending and fetch dependencies if needed.

pub fn import_json_updates<T: TryInto<JsonSchema>>( &self, json: T, ) -> Result<ImportStatus, LoroError>

Import the json schema updates.

Example

use loro::{LoroDoc, VersionVector};
let a = LoroDoc::new();
a.get_text("t").insert(0, "hi").unwrap();
a.commit();
let json = a.export_json_updates(&VersionVector::default(), &a.oplog_vv());

let b = LoroDoc::new();
b.import_json_updates(json).unwrap();
assert_eq!(a.get_deep_value(), b.get_deep_value());

pub fn export_json_updates( &self, start_vv: &VersionVector, end_vv: &VersionVector, ) -> JsonSchema

Export the current state with json-string format of the document.

Example

use loro::{LoroDoc, VersionVector};
let doc = LoroDoc::new();
let start = VersionVector::default();
let end = doc.oplog_vv();
let json = doc.export_json_updates(&start, &end);

pub fn export_json_updates_without_peer_compression( &self, start_vv: &VersionVector, end_vv: &VersionVector, ) -> JsonSchema

Export the current state with json-string format of the document, without peer compression.

Compared to [export_json_updates], this method does not compress the peer IDs in the updates. So the operations are easier to be processed by application code.

Example

use loro::{LoroDoc, VersionVector};
let doc = LoroDoc::new();
let start = VersionVector::default();
let end = doc.oplog_vv();
let json = doc.export_json_updates_without_peer_compression(&start, &end);

pub fn export_json_in_id_span(&self, id_span: IdSpan) -> Vec<JsonChange>

Exports changes within the specified ID span to JSON schema format.

The JSON schema format produced by this method is identical to the one generated by export_json_updates. It ensures deterministic output, making it ideal for hash calculations and integrity checks.

This method can also export pending changes from the uncommitted transaction that have not yet been applied to the OpLog.

This method will NOT trigger a new commit implicitly.

Example

use loro::{LoroDoc, IdSpan};

let doc = LoroDoc::new();
doc.set_peer_id(0).unwrap();
doc.get_text("text").insert(0, "a").unwrap();
doc.commit();
let doc_clone = doc.clone();
let _sub = doc.subscribe_pre_commit(Box::new(move |e| {
    let changes = doc_clone.export_json_in_id_span(IdSpan::new(
        0,
        0,
        e.change_meta.id.counter + e.change_meta.len as i32,
    ));
    // 2 because commit one and the uncommit one
    assert_eq!(changes.len(), 2);
    true
}));
doc.get_text("text").insert(0, "b").unwrap();
let changes = doc.export_json_in_id_span(IdSpan::new(0, 0, 2));
assert_eq!(changes.len(), 1);
doc.commit();
// change merged
assert_eq!(changes.len(), 1);

pub fn frontiers_to_vv(&self, frontiers: &Frontiers) -> Option<VersionVector>

Convert Frontiers into VersionVector

Returns None if the frontiers are not included by this doc’s OpLog.

Example

use loro::LoroDoc;
let doc = LoroDoc::new();
let f = doc.state_frontiers();
let vv = doc.frontiers_to_vv(&f);
assert!(vv.is_some());

pub fn minimize_frontiers(&self, frontiers: &Frontiers) -> Result<Frontiers, ID>

Minimize the frontiers by removing the unnecessary entries.

Returns Err(ID) if any frontier is not included by this doc’s history.

Example

use loro::LoroDoc;
let doc = LoroDoc::new();
let f = doc.state_frontiers();
let _minimized = doc.minimize_frontiers(&f).unwrap();

pub fn vv_to_frontiers(&self, vv: &VersionVector) -> Frontiers

Convert VersionVector into Frontiers

pub fn with_oplog<R>(&self, f: impl FnOnce(&OpLog) -> R) -> R

Access the OpLog.

NOTE: The API in OpLog is unstable. Keep the closure short; avoid calling methods that might re-enter the document while holding the lock.

pub fn with_state<R>(&self, f: impl FnOnce(&mut DocState) -> R) -> R

Access the DocState.

NOTE: The API in DocState is unstable. Keep the closure short; avoid calling methods that might re-enter the document while holding the lock.

pub fn oplog_vv(&self) -> VersionVector

Get the VersionVector version of OpLog

pub fn state_vv(&self) -> VersionVector

Get the VersionVector version of DocState

pub fn shallow_since_vv(&self) -> ImVersionVector

The doc only contains the history since this version

This is empty if the doc is not shallow.

The ops included by the shallow history start version vector are not in the doc.

pub fn shallow_since_frontiers(&self) -> Frontiers

The doc only contains the history since this version

This is empty if the doc is not shallow.

The ops included by the shallow history start frontiers are not in the doc.

pub fn len_ops(&self) -> usize

Get the total number of operations in the OpLog

pub fn len_changes(&self) -> usize

Get the total number of changes in the OpLog

pub fn get_value(&self) -> LoroValue

Get the shallow value of the document.

pub fn get_deep_value(&self) -> LoroValue

Get the entire state of the current DocState

pub fn get_deep_value_with_id(&self) -> LoroValue

Get the entire state of the current DocState with container id

pub fn oplog_frontiers(&self) -> Frontiers

Get the Frontiers version of OpLog.

pub fn state_frontiers(&self) -> Frontiers

Get the Frontiers version of DocState.

When detached or during checkout, state_frontiers() may differ from oplog_frontiers(). Learn more about Frontiers.

Example

use loro::LoroDoc;
let doc = LoroDoc::new();
let before = doc.state_frontiers();
doc.get_text("t").insert(0, "x").unwrap();
let after = doc.state_frontiers();
assert_ne!(before, after);

pub fn peer_id(&self) -> PeerID

Get the PeerID

pub fn set_peer_id(&self, peer: PeerID) -> LoroResult<()>

Change the PeerID

Pitfalls:

• Never reuse the same PeerID across concurrent writers (multiple tabs/devices). Duplicate PeerIDs can produce conflicting OpIDs and corrupt the document.
• Do not assign a fixed PeerID to a user or device without strict single-ownership locking. Prefer the default random PeerID per process/session.

pub fn subscribe( &self, container_id: &ContainerID, callback: Subscriber, ) -> Subscription

Subscribe the events of a container.

The callback will be invoked after a transaction that change the container. Returns a subscription that can be used to unsubscribe.

The events will be emitted after a transaction is committed. A transaction is committed when:

• doc.commit() is called.
• doc.export(mode) is called.
• doc.import(data) is called.
• doc.checkout(version) is called.

Example

let doc = LoroDoc::new();
let text = doc.get_text("text");
let ran = Arc::new(AtomicBool::new(false));
let ran2 = ran.clone();
let sub = doc.subscribe(
    &text.id(),
    Arc::new(move |event| {
        assert!(event.triggered_by.is_local());
        for event in event.events {
            let delta = event.diff.as_text().unwrap();
            let d = TextDelta::Insert {
                insert: "123".into(),
                attributes: Default::default(),
            };
            assert_eq!(delta, &vec![d]);
            ran2.store(true, std::sync::atomic::Ordering::Relaxed);
        }
    }),
);
text.insert(0, "123").unwrap();
doc.commit();
assert!(ran.load(std::sync::atomic::Ordering::Relaxed));
// unsubscribe
sub.unsubscribe();

pub fn subscribe_root(&self, callback: Subscriber) -> Subscription

Subscribe all the events.

The callback will be invoked when any part of the loro_internal::DocState is changed. Returns a subscription that can be used to unsubscribe.

The events will be emitted after a transaction is committed. A transaction is committed when:

• doc.commit() is called.
• doc.export(mode) is called.
• doc.import(data) is called.
• doc.checkout(version) is called.

pub fn subscribe_local_update( &self, callback: LocalUpdateCallback, ) -> Subscription

Subscribe to local document updates.

The callback receives encoded update bytes whenever local changes are committed. This is useful for syncing changes to other document instances or persisting updates.

Auto-unsubscription: If the callback returns false, the subscription will be automatically removed, providing a convenient way to implement one-time or conditional subscriptions in Rust.

Parameters

• callback: Function that receives &Vec<u8> (encoded updates) and returns bool
  • Return true to keep the subscription active
  • Return false to automatically unsubscribe

Example

use loro::LoroDoc;
use std::sync::{Arc, Mutex};

let doc = LoroDoc::new();
let updates = Arc::new(Mutex::new(Vec::new()));
let updates_clone = updates.clone();
let count = Arc::new(Mutex::new(0));
let count_clone = count.clone();

// Subscribe and collect first 3 updates, then auto-unsubscribe
let sub = doc.subscribe_local_update(Box::new(move |bytes| {
    updates_clone.lock().unwrap().push(bytes.clone());
    let mut c = count_clone.lock().unwrap();
    *c += 1;
    *c < 3  // Auto-unsubscribe after 3 updates
}));

doc.get_text("text").insert(0, "hello").unwrap();
doc.commit();

pub fn subscribe_peer_id_change( &self, callback: PeerIdUpdateCallback, ) -> Subscription

Subscribe to peer ID changes in the document.

The callback is triggered whenever the document’s peer ID is modified. This is useful for tracking identity changes and updating related state accordingly.

Auto-unsubscription: If the callback returns false, the subscription will be automatically removed, providing a convenient way to implement one-time or conditional subscriptions in Rust.

Parameters

• callback: Function that receives &ID (the new peer ID) and returns bool
  • Return true to keep the subscription active
  • Return false to automatically unsubscribe

Example

use loro::LoroDoc;
use std::sync::{Arc, Mutex};

let doc = LoroDoc::new();
let peer_changes = Arc::new(Mutex::new(Vec::new()));
let changes_clone = peer_changes.clone();

let sub = doc.subscribe_peer_id_change(Box::new(move |new_peer_id| {
    changes_clone.lock().unwrap().push(*new_peer_id);
    true  // Keep subscription active
}));

doc.set_peer_id(42).unwrap();
doc.set_peer_id(100).unwrap();

pub fn check_state_correctness_slow(&self)

Check the correctness of the document state by comparing it with the state calculated by applying all the history.

pub fn get_by_path(&self, path: &[Index]) -> Option<ValueOrContainer>

Get the handler by the path.

pub fn get_by_str_path(&self, path: &str) -> Option<ValueOrContainer>

Get the handler by the string path.

The path can be specified in different ways depending on the container type:

For Tree:

1. Using node IDs: tree/{node_id}/property
2. Using indices: tree/0/1/property

For List and MovableList:

• Using indices: list/0 or list/1/property

For Map:

• Using keys: map/key or map/nested/property

For tree structures, index-based paths follow depth-first traversal order. The indices start from 0 and represent the position of a node among its siblings.

Examples

let doc = LoroDoc::new();

// Tree example
let tree = doc.get_tree("tree");
let root = tree.create(None).unwrap();
tree.get_meta(root).unwrap().insert("name", "root").unwrap();
// Access tree by ID or index
let name1 = doc.get_by_str_path(&format!("tree/{}/name", root)).unwrap().into_value().unwrap();
let name2 = doc.get_by_str_path("tree/0/name").unwrap().into_value().unwrap();
assert_eq!(name1, name2);

// List example
let list = doc.get_list("list");
list.insert(0, "first").unwrap();
list.insert(1, "second").unwrap();
// Access list by index
let item = doc.get_by_str_path("list/0");
assert_eq!(item.unwrap().into_value().unwrap().into_string().unwrap(), "first".into());

// Map example
let map = doc.get_map("map");
map.insert("key", "value").unwrap();
// Access map by key
let value = doc.get_by_str_path("map/key");
assert_eq!(value.unwrap().into_value().unwrap().into_string().unwrap(), "value".into());

// MovableList example
let mlist = doc.get_movable_list("mlist");
mlist.insert(0, "item").unwrap();
// Access movable list by index
let item = doc.get_by_str_path("mlist/0");
assert_eq!(item.unwrap().into_value().unwrap().into_string().unwrap(), "item".into());

pub fn get_cursor_pos( &self, cursor: &Cursor, ) -> Result<PosQueryResult, CannotFindRelativePosition>

Get the absolute position of the given cursor.

Example

let doc = LoroDoc::new();
let text = &doc.get_text("text");
text.insert(0, "01234").unwrap();
let pos = text.get_cursor(5, Default::default()).unwrap();
assert_eq!(doc.get_cursor_pos(&pos).unwrap().current.pos, 5);
text.insert(0, "01234").unwrap();
assert_eq!(doc.get_cursor_pos(&pos).unwrap().current.pos, 10);
text.delete(0, 10).unwrap();
assert_eq!(doc.get_cursor_pos(&pos).unwrap().current.pos, 0);
text.insert(0, "01234").unwrap();
assert_eq!(doc.get_cursor_pos(&pos).unwrap().current.pos, 5);

pub fn inner(&self) -> &InnerLoroDoc

Get the inner LoroDoc ref.

pub fn has_history_cache(&self) -> bool

Whether the history cache is built.

pub fn free_history_cache(&self)

Free the history cache that is used for making checkout faster.

If you use checkout that switching to an old/concurrent version, the history cache will be built. You can free it by calling this method.

pub fn free_diff_calculator(&self)

Free the cached diff calculator that is used for checkout.

pub fn compact_change_store(&self)

Encoded all ops and history cache to bytes and store them in the kv store.

This will free up the memory that used by parsed ops

pub fn export(&self, mode: ExportMode<'_>) -> Result<Vec<u8>, LoroEncodeError>

Export the document in the given mode.

Common modes:

• ExportMode::Snapshot: full state + history
• ExportMode::all_updates(): all known ops
• [ExportMode::updates(&VersionVector)]: ops since a specific version
• [ExportMode::shallow_snapshot(..)]: GC’d snapshot starting at frontiers
• [ExportMode::updates_in_range(..)]: ops in specific ID spans

Important notes:

• Auto-commit: export finalizes the current transaction before producing bytes.
• Shallow snapshots: peers cannot import updates from before the shallow start.
• Performance: exporting fresh snapshots periodically can reduce import time for new peers.

Examples

use loro::{ExportMode, LoroDoc};

let doc = LoroDoc::new();
doc.get_text("text").insert(0, "Hello").unwrap();

// 1) Full snapshot
let snapshot = doc.export(ExportMode::Snapshot).unwrap();

// 2) All updates
let all = doc.export(ExportMode::all_updates()).unwrap();

// 3) Updates from another peer’s version vector
let vv = doc.oplog_vv();
let delta = doc.export(ExportMode::updates(&vv)).unwrap();
assert!(!delta.is_empty());

pub fn analyze(&self) -> DocAnalysis

Analyze the container info of the doc

This is used for development and debugging. It can be slow.

pub fn get_path_to_container( &self, id: &ContainerID, ) -> Option<Vec<(ContainerID, Index)>>

Get the path from the root to the container

pub fn get_pending_txn_len(&self) -> usize

Get the number of operations in the pending transaction.

The pending transaction is the one that is not committed yet. It will be committed after calling doc.commit(), doc.export(mode) or doc.checkout(version).

pub fn travel_change_ancestors( &self, ids: &[ID], f: &mut dyn FnMut(ChangeMeta) -> ControlFlow<()>, ) -> Result<(), ChangeTravelError>

Traverses the ancestors of the Change containing the given ID, including itself.

This method visits all ancestors in causal order, from the latest to the oldest, based on their Lamport timestamps.

Arguments

• ids - The IDs of the Change to start the traversal from.
• f - A mutable function that is called for each ancestor. It can return ControlFlow::Break(()) to stop the traversal.

pub fn is_shallow(&self) -> bool

Check if the doc contains the full history.

pub fn get_changed_containers_in( &self, id: ID, len: usize, ) -> FxHashSet<ContainerID>

Gets container IDs modified in the given ID range.

Pitfalls:

• This method will implicitly commit the current transaction to ensure the change range is finalized.

This method can be used in conjunction with doc.travel_change_ancestors() to traverse the history and identify all changes that affected specific containers.

Arguments

• id - The starting ID of the change range
• len - The length of the change range to check

pub fn find_id_spans_between( &self, from: &Frontiers, to: &Frontiers, ) -> VersionVectorDiff

Find the operation id spans that between the from version and the to version.

Useful for exporting just the changes in a range, e.g., in response to a subscription.

Example

use loro::LoroDoc;
let doc = LoroDoc::new();
let a = doc.state_frontiers();
doc.get_text("t").insert(0, "x").unwrap();
doc.commit();
let b = doc.state_frontiers();
let spans = doc.find_id_spans_between(&a, &b);
assert!(!spans.forward.is_empty());

pub fn revert_to(&self, version: &Frontiers) -> LoroResult<()>

Revert the current document state back to the target version

Internally, it will generate a series of local operations that can revert the current doc to the target version. It will calculate the diff between the current state and the target state, and apply the diff to the current state.

Pitfalls:

• The target frontiers must be included by the document’s history. If the document is shallow and the target is before the shallow start, revert will fail.

Example

use loro::LoroDoc;
let doc = LoroDoc::new();
let t = doc.get_text("text");
t.insert(0, "Hello").unwrap();
let v0 = doc.state_frontiers();
t.insert(5, ", world").unwrap();
doc.commit();
doc.revert_to(&v0).unwrap();
assert_eq!(t.to_string(), "Hello");

pub fn apply_diff(&self, diff: DiffBatch) -> LoroResult<()>

Apply a diff to the current document state.

Internally, it will apply the diff to the current state.

pub fn diff(&self, a: &Frontiers, b: &Frontiers) -> LoroResult<DiffBatch>

Calculate the diff between two versions.

Example

use loro::{LoroDoc};
let doc = LoroDoc::new();
let t = doc.get_text("text");
let a = doc.state_frontiers();
t.insert(0, "a").unwrap();
let b = doc.state_frontiers();
let diff = doc.diff(&a, &b).unwrap();
assert!(diff.iter().next().is_some());

pub fn has_container(&self, container_id: &ContainerID) -> bool

Check if the doc contains the target container.

A root container always exists, while a normal container exists if it has ever been created on the doc.

Examples

use loro::{LoroDoc, LoroText, LoroList, ExportMode};

let doc = LoroDoc::new();
doc.set_peer_id(1);
let map = doc.get_map("map");
map.insert_container("text", LoroText::new()).unwrap();
map.insert_container("list", LoroList::new()).unwrap();

// Root map container exists
assert!(doc.has_container(&"cid:root-map:Map".try_into().unwrap()));
// Text container exists
assert!(doc.has_container(&"cid:0@1:Text".try_into().unwrap()));
// List container exists
assert!(doc.has_container(&"cid:1@1:List".try_into().unwrap()));

let doc2 = LoroDoc::new();
// Containers exist as long as the history or doc state includes them
doc.detach();
doc2.import(&doc.export(ExportMode::all_updates()).unwrap()).unwrap();
assert!(doc2.has_container(&"cid:root-map:Map".try_into().unwrap()));
assert!(doc2.has_container(&"cid:0@1:Text".try_into().unwrap()));
assert!(doc2.has_container(&"cid:1@1:List".try_into().unwrap()));

pub fn subscribe_first_commit_from_peer( &self, callback: FirstCommitFromPeerCallback, ) -> Subscription

Subscribe to the first commit from a peer. Operations performed on the LoroDoc within this callback will be merged into the current commit.

Subscribe to the first commit event from each peer.

The callback is triggered only once per peer when they make their first commit to the document locally. This is particularly useful for managing peer-to-user mappings or initialization logic.

Auto-unsubscription: If the callback returns false, the subscription will be automatically removed, providing a convenient way to implement one-time or conditional subscriptions in Rust.

Parameters

• callback: Function that receives &FirstCommitFromPeerPayload and returns bool
  • Return true to keep the subscription active
  • Return false to automatically unsubscribe

Use Cases

• Initialize peer-specific data structures
• Map peer IDs to user information

Example

use loro::LoroDoc;
use std::sync::{Arc, Mutex};

let doc = LoroDoc::new();
doc.set_peer_id(0).unwrap();

let new_peers = Arc::new(Mutex::new(Vec::new()));
let peers_clone = new_peers.clone();
let peer_count = Arc::new(Mutex::new(0));
let count_clone = peer_count.clone();

// Track first 5 new peers, then auto-unsubscribe
let sub = doc.subscribe_first_commit_from_peer(Box::new(move |payload| {
    peers_clone.lock().unwrap().push(payload.peer);
    let mut count = count_clone.lock().unwrap();
    *count += 1;
    *count < 5  // Auto-unsubscribe after tracking 5 peers
}));

// This will trigger the callback for peer 0
doc.get_text("text").insert(0, "hello").unwrap();
doc.commit();

// Switch to a new peer and commit - triggers callback again
doc.set_peer_id(1).unwrap();
doc.get_text("text").insert(0, "world").unwrap();
doc.commit();

pub fn subscribe_pre_commit(&self, callback: PreCommitCallback) -> Subscription

Subscribe to pre-commit events.

The callback is triggered when changes are about to be committed but before they’re applied to the OpLog. This allows you to modify commit metadata such as timestamps and messages, or perform validation before changes are finalized.

Auto-unsubscription: If the callback returns false, the subscription will be automatically removed, providing a convenient way to implement one-time or conditional subscriptions in Rust.

Pitfall: commit() can be triggered implicitly by import, export, and checkout. This hook still runs for those commits, which is helpful for annotating metadata even for implicit commits.

Parameters

• callback: Function that receives &PreCommitCallbackPayload and returns bool
  • Return true to keep the subscription active
  • Return false to automatically unsubscribe
• The payload contains:
  • change_meta: Metadata about the commit
  • modifier: Interface to modify commit properties

Use Cases

• Add commit message prefixes or formatting
• Adjust timestamps for consistent ordering
• Log or audit commit operations
• Implement commit validation or approval workflows

Example

use loro::LoroDoc;
use std::sync::{Arc, Mutex};

let doc = LoroDoc::new();
let commit_count = Arc::new(Mutex::new(0));
let count_clone = commit_count.clone();

// Add timestamps and auto-unsubscribe after 5 commits
let sub = doc.subscribe_pre_commit(Box::new(move |payload| {
    // Add a prefix to commit messages
    let new_message = format!("Auto: {}", payload.change_meta.message());
    payload.modifier.set_message(&new_message);

    let mut count = count_clone.lock().unwrap();
    *count += 1;
    *count < 5  // Auto-unsubscribe after 5 commits
}));

doc.get_text("text").insert(0, "hello").unwrap();
doc.commit();

pub fn delete_root_container(&self, cid: ContainerID)

Delete all content from a root container and hide it from the document.

When a root container is empty and hidden:

• It won’t show up in get_deep_value() results
• It won’t be included in document snapshots

Only works on root containers (containers without parents).

pub fn set_hide_empty_root_containers(&self, hide: bool)

Set whether to hide empty root containers.

Example

use loro::LoroDoc;

let doc = LoroDoc::new();
let map = doc.get_map("map");
dbg!(doc.get_deep_value()); // {"map": {}}
doc.set_hide_empty_root_containers(true);
dbg!(doc.get_deep_value()); // {}

Trait Implementations

impl Clone for LoroDoc

fn clone(&self) -> Self

This creates a reference clone, not a deep clone. The cloned doc will share the same underlying doc as the original one.

For deep clone, please use the .fork() method.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LoroDoc

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for LoroDoc

fn default() -> Self

Returns the “default value” for a type.