Crate loro

Loro

Make your JSON data collaborative and version-controlled

Loro is a high-performance CRDTs framework offering Rust, JavaScript and Swift APIs.

Designed for local-first software, it enables effortless collaboration in app states.

Examples

Map/List/Text

use loro::{LoroDoc, LoroList, LoroText, LoroValue, ToJson};
use serde_json::json;

let doc = LoroDoc::new();
let map = doc.get_map("map");
map.insert("key", "value").unwrap();
map.insert("true", true).unwrap();
map.insert("null", LoroValue::Null).unwrap();
map.insert("deleted", LoroValue::Null).unwrap();
map.delete("deleted").unwrap();
let list = map.insert_container("list", LoroList::new()).unwrap();
list.insert(0, "List").unwrap();
list.insert(1, 9).unwrap();
let text = map.insert_container("text", LoroText::new()).unwrap();
text.insert(0, "Hello world!").unwrap();
assert_eq!(
    doc.get_deep_value().to_json_value(),
    json!({
        "map": {
            "key": "value",
            "true": true,
            "null": null,
            "list": ["List", 9],
            "text": "Hello world!"
        }
    })
);

Rich Text

use loro::{ExpandType, LoroDoc, ToJson};
use serde_json::json;

let doc = LoroDoc::new();
let text = doc.get_text("text");
text.insert(0, "Hello world!").unwrap();
text.mark(0..5, "bold", true).unwrap();
assert_eq!(
    text.get_richtext_value().to_json_value(),
    json!([
        { "insert": "Hello", "attributes": {"bold": true} },
        { "insert": " world!" },
    ])
);
text.unmark(3..5, "bold").unwrap();
assert_eq!(
    text.get_richtext_value().to_json_value(),
    json!([
          { "insert": "Hel", "attributes": {"bold": true} },
          { "insert": "lo world!" },
    ])
);

Sync

use loro::{LoroDoc, ToJson, ExpandType};
use serde_json::json;

let doc = LoroDoc::new();
let text = doc.get_text("text");
text.insert(0, "Hello world!").unwrap();
let bytes = doc.export_from(&Default::default());
let doc_b = LoroDoc::new();
doc_b.import(&bytes).unwrap();
assert_eq!(doc.get_deep_value(), doc_b.get_deep_value());
let text_b = doc_b.get_text("text");
text_b
    .mark(0..5, "bold", true)
    .unwrap();
doc.import(&doc_b.export_from(&doc.oplog_vv())).unwrap();
assert_eq!(
    text.get_richtext_value().to_json_value(),
    json!([
        { "insert": "Hello", "attributes": {"bold": true} },
        { "insert": " world!" },
    ])
);

Save

use loro::LoroDoc;

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

let new_doc = LoroDoc::new();
new_doc.import(&snapshot).unwrap();
assert_eq!(new_doc.get_deep_value(), doc.get_deep_value());

Re-exports

pub use loro_kv_store as kv_store;

Modules

awareness

cursor

event

Loro event handling.

json

sync

undo

Macros

loro_value

A macro for creating LoroValue. It works just like the json! macro in serde_json.

Structs

ChangeMeta

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

ChangeModifier

CommitOptions

Options for configuring a commit operation.

Configure

CounterSpan

This struct supports reverse repr: from can be less than to. We need this because it’ll make merging deletions easier.

DocAnalysis

FirstCommitFromPeerPayload

The payload of the first commit from a peer callback.

FractionalIndex

FrontiersNotIncluded

ID

It’s the unique ID of an Op represented by PeerID and Counter.

IdLp

It’s the unique ID of an Op represented by PeerID and Lamport clock. It’s used to define the total order of Ops.

IdSpan

This struct supports reverse repr: CounterSpan’s from can be less than to. But we should use it conservatively. We need this because it’ll make merging deletions easier.

ImVersionVector

Immutable version vector

ImportBlobMetadata

ImportStatus

InnerUndoManager

UndoManager is responsible for managing undo/redo from the current peer’s perspective.

InternalString

JsonChange

JsonFutureOpWrapper

JsonOp

JsonSchema

LoroBinaryValue

LoroDoc

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

LoroList

LoroList container. It’s used to model array.

LoroListValue

LoroMap

LoroMap container.

LoroMapValue

LoroMovableList

LoroMovableList container

LoroStringValue

LoroText

LoroText container. It’s used to model plaintext/richtext.

LoroTree

LoroTree container. It’s used to model movable trees.

LoroUnknown

Unknown container.

MemKvStore

PreCommitCallbackPayload

The payload of the pre commit callback.

StyleConfig

StyleConfigMap

Subscription

A handle to a subscription created by GPUI. When dropped, the subscription is cancelled and the callback will no longer be invoked.

TreeDeltaItem

The semantic action in movable tree.

TreeDiff

TreeDiffItem

TreeID

Each node of movable tree has a unique TreeID generated by Loro.

TreeNode

A tree node in the LoroTree.

UndoItemMeta

The metadata of an undo item.

UndoManager

UndoManager can be used to undo and redo the changes made to the document with a certain peer.

UpdateOptions

Options for controlling the text update behavior.

VersionRange

VersionVector

VersionVector is a map from PeerID to Counter. Its a right-open interval.

VersionVectorDiff

Enums

CannotFindRelativePosition

ChangeTravelError

Container

All the CRDT containers supported by Loro.

ContainerID

ContainerID includes the Op’s ID and the type. So it’s impossible to have the same ContainerID with conflict ContainerType.

ContainerType

EncodedBlobMode

EventTriggerKind

The kind of the event trigger.

ExpandType

Whether to expand the style when inserting new text around it.

ExportMode

The mode of the export.

Frontiers

Frontiers representation.

Index

JsonFutureOp

JsonListOp

JsonMapOp

JsonMovableListOp

JsonOpContent

JsonTextOp

JsonTreeOp

LoroEncodeError

LoroError

LoroTreeError

LoroValue

LoroValue is used to represents the state of CRDT at a given version.

TextDelta

TreeExternalDiff

TreeParentId

UndoOrRedo

UpdateTimeoutError

ValueOrContainer

It’s a type that can be either a value or a container.

Constants

LORO_VERSION

The version of the loro crate

Traits

ApplyDiff

ContainerTrait

The common trait for all the containers. It’s used internally, you can’t implement it directly.

IntoContainerId

KvStore

ToJson

Functions

to_value

Type Aliases

Counter

If it’s the nth Op of a peer, the counter will be n.

FirstCommitFromPeerCallback

The callback of the first commit from a peer.

Lamport

It’s the Lamport clock

LocalUpdateCallback

The callback of the local update.

LoroResult

OnPop

OnPush

When a undo/redo item is pushed, the undo manager will call the on_push callback to get the meta data of the undo item. The returned cursors will be recorded for a new pushed undo item.

PeerID

Unique id for each peer. It’s a random u64 by default.

PeerIdUpdateCallback

The callback of the peer id change. The second argument is the next counter for the peer.

PreCommitCallback

Timestamp