DOCSEARCHbyAlgolia
Submit Docs

Loro CRDT Library

repository·main·Indexed 26 days ago

https://github.com/loro-dev/loro

A Conflict-free Replicated Data Types (CRDTs) library for building local-first, collaborative applications. It supports Rust, JavaScript (via WASM and a pure TypeScript implementation in loro.js), and Swift. Loro provides automatic merging, P2P synchronization, and version control for data types including text, rich text, trees, lists, and maps. Key features include time travel, shallow snapshots, and incremental updates via VersionVectors.

Tokens
69.7K
Snippets
142
Records
386
Agent score
91%

What's inside Loro

  1. Overview of Moonbit Loro Codec

    main
    The Moonbit Loro Codec provides an implementation of the Loro binary encoding format using the Moonbit language. This codec is designed to be compatible with the Loro encoding specification (documented in docs/encoding.md of the main repository) and aims for end-to-end interoperability between Rust and Moonbit implementations.

  2. Overview of Loro CRDT Library

    main

    Loro is a Conflict-free Replicated Data Types (CRDTs) library designed for building local-first and collaborative applications. It supports Rust, JavaScript (via WASM), and Swift.

    Key features include:

    • CRDT Capabilities: P2P synchronization, automatic merging, local availability, scalability, and delta updates.
    • Supported Data Types: Text editing (Fugue), Rich Text, Moveable Trees, Moveable Lists, and Last-Write-Wins Maps.
    • Advanced Functionality: Fast document loading, time travel through history, version control with real-time collaboration, and shallow snapshots (similar to Git shallow clones).

  3. Overview of loro-crdt-map

    main
    The loro-crdt-map package provides WebAssembly source maps for the loro-crdt package. These source maps are split into different targets: bundler, nodejs, and web. They are hosted on unpkg to allow browsers and development tools to load them on demand via the sourceMappingURL metadata embedded in loro_wasm_bg.wasm, preventing the main npm distribution from becoming bloated.

  6. Overview of Moonbit implementation for Loro encoding

    main
    This directory contains the implementation plan, key specifications, and testing/acceptance strategies for implementing the Loro binary encoding format (as described in docs/encoding.md) using Moonbit. The implementation focuses on ensuring cross-language interoperability between Rust and Moonbit.

  7. Understand Loro performance tradeoffs and limitations

    main

    When designing systems with Loro, keep the following architectural tradeoffs in mind:

    • Optimization Focus: Loro is optimized for local editing, automatic merging, history preservation, and version control.
    • Consistency Model: Loro provides strong eventual consistency, meaning peers will converge once they have received the same set of operations.
    • Missing Features: Loro does not natively provide central locking, serializable transactions, or write-time authorization.
    • Invariants: Hard invariants (e.g., account balances, permissions, or bookings) must be validated at the application or server level, as they cannot be guaranteed solely by the CRDT merge process.

  8. Understand loro.js compatibility and limitations

    main

    loro.js is an experimental TypeScript implementation designed for wire and API compatibility with the Rust loro-crdt package.

    Key Compatibility Notes:

    • Wire Compatibility: Encoded updates and snapshots are wire-compatible, but byte layouts are not canonical (TypeScript output may differ byte-for-byte from Rust).
    • Legacy Support: Legacy/outdated Loro update and snapshot modes are not decoded. Use a current Loro release to migrate them first.
    • Snapshot Importing: Importing a snapshot into a document with existing history is less complete than importing into a new document or using LoroDoc.fromSnapshot().
    • Ordering: diff() preserves parent-before-child ordering, but independent containers at the same depth may appear in a different order than Rust's internal hash-map iteration.
    • Undo/Redo: UndoManager uses ID-span-based semantic undo for sequence edits and common map/tree/counter changes. Style-only rich-text edits and movable-list move/set undo use simplified behavior.
    • JSONPath: subscribeJsonpath() uses broad invalidation and may produce false positives.

    Recommendation: Treat the package as experimental when handling data from untrusted or older clients.

  9. Understand RLE (Run Length Encoding) in Loro

    main

    Loro utilizes Run Length Encoding (RLE) not only for data encoding but also within its internal vec and tree structures. This allows elements to be merged, sliced, and assigned lengths.

    • Atom Element: An element with a length of 1 that cannot be sliced.
    • Rle Trait: The Rle trait is used to express these capabilities. The following types implement the Rle trait:
      • Op
      • Change
      • Elements inside RleTree

  10. Understand the Loro Rust crate architecture merge plan

    main

    Loro is transitioning from a split architecture (crates/loro as a public facade and crates/loro-internal as the engine) into a single canonical crate named loro.

    Key architectural changes include:

    • Single Crate: loro will become the sole published Rust crate for the core implementation.
    • Unified Types: Consolidation of LoroDoc, container/value, diff, and event surfaces to remove runtime overhead caused by facade-to-engine conversions.
    • Compatibility: The transition follows a compatibility-first approach, ensuring that LoroDoc::new() preserves current auto-commit behaviors and that loro-wasm remains functional.

    Developers using loro-wasm or low-level internal APIs should prepare for a migration as loro-internal is phased out in favor of loro.

  11. Understand Moonbit Change and Op Data Structures

    main
    The Moonbit side of the project uses specific Change and Op data structures designed for re-encoding (decode $\rightarrow$ encode) and testing (Golden tests). These structures are intended to carry the core semantics of ChangeBlock (metadata + sequence of operations) and are designed to be serializable into stable JSON for comparison with Rust-side outputs.

  12. Determine if Loro is suitable for your use case

    main

    Loro is a CRDT framework designed for local-first applications that prioritize eventual consistency over strict coordination.

    Use Loro when building:

    • Collaborative text and structured documents.
    • Offline-first applications that synchronize later.
    • Multi-device sync where eventual consistency is acceptable.
    • Apps requiring complete history, time travel, or version checkpoints.

    Avoid Loro for:

    • Financial or accounting invariants.
    • Exclusive ownership, booking, or locking semantics.
    • Authorization decisions that must be enforced at write time.
    • Arbitrary graph-shaped or non-JSON-like data (unless using an adaptation layer).