Struct LoroDoc

pub struct LoroDoc { /* private fields */ }

LoroDoc is the entry for the whole document. When it’s dropped, all the associated [Handler]s 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.

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 set each timestamp manually when committing a change.

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

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.

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.

You need to config it if you use rich text mark method. Specifically, you need to config the expand property of each style.

Expand is used to specify the behavior of expanding when new text is inserted at the beginning or end of the style.

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.

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 to attach the DocState to the latest version of OpLog.

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, when you importing new updates, the loro_internal::DocState will not be changed.

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.

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.

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.

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.

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.

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.

pub fn commit_with(&self, options: CommitOptions)

Commit the cumulative auto commit transaction with custom configure.

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

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.

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 import(&self, bytes: &[u8]) -> Result<ImportStatus, LoroError>

Import updates/snapshot exported by LoroDoc::export_snapshot or LoroDoc::export_from.

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

Import updates/snapshot exported by LoroDoc::export_snapshot or LoroDoc::export_from.

It marks the import with a custom origin string. It can be used to track the import source in the generated events.

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

Import the json schema updates.

only supports backward compatibility but not forward compatibility.

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

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

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.

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 export_from(&self, vv: &VersionVector) -> Vec<u8>

👎Deprecated since 1.0.0: Use export with ExportMode::Updates instead

Export all the ops not included in the given VersionVector

pub fn export_snapshot(&self) -> Vec<u8>

👎Deprecated since 1.0.0: Use export with ExportMode::Snapshot instead

Export the current state and history of the document.

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

Convert Frontiers into VersionVector

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

Minimize the frontiers by removing the unnecessary entries.

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: Please be ware that the API in OpLog is unstable

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

Access the DocState.

NOTE: Please be ware that the API in DocState is unstable

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

Learn more about Frontiers

pub fn peer_id(&self) -> PeerID

Get the PeerID

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

Change the PeerID

NOTE: You need to make sure there is no chance two peer have the same PeerID. If it happens, the document will be corrupted.

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 the local update of the document.

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

Subscribe the peer id change of the document.

pub fn log_estimate_size(&self)

Estimate the size of the document states in memory.

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.

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.

NOTE: This method will implicitly commit.

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.

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.

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

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.

This is useful for managing the relationship between PeerID and user information. For example, you could store user names in a LoroMap using PeerID as the key and the UserID as the value.

Example

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

let doc = LoroDoc::new();
doc.set_peer_id(0).unwrap();
let p = Arc::new(Mutex::new(vec![]));
let p2 = Arc::clone(&p);
let sub = doc.subscribe_first_commit_from_peer(Box::new(move |e| {
    p2.try_lock().unwrap().push(e.peer);
    true
}));
doc.get_text("text").insert(0, "a").unwrap();
doc.commit();
doc.get_text("text").insert(0, "b").unwrap();
doc.commit();
doc.set_peer_id(1).unwrap();
doc.get_text("text").insert(0, "c").unwrap();
doc.commit();
sub.unsubscribe();
assert_eq!(p.try_lock().unwrap().as_slice(), &[0, 1]);

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

Subscribe to the pre-commit event.

The callback will be called when the changes are committed but not yet applied to the OpLog. You can modify the commit message and timestamp in the callback by ChangeModifier.

Example

use loro::LoroDoc;

let doc = LoroDoc::new();
let doc_clone = doc.clone();
let sub = doc.subscribe_pre_commit(Box::new(move |e| {
    e.modifier
     .set_timestamp(e.change_meta.timestamp + 1)
     .set_message(&format!("prefix\n{}", e.change_meta.message()));
    true
}));
doc.get_text("text").insert(0, "a").unwrap();
doc.commit();

Trait Implementations

impl Clone for LoroDoc

fn clone(&self) -> Self

Returns a copy of the value.

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.