loro/README.md

152 lines
7.1 KiB
Markdown
Raw Normal View History

2022-11-18 10:55:09 +00:00
<p align="center">
<a href="https://loro.dev">
<picture>
2023-02-08 02:54:44 +00:00
<img src="./docs/Loro.svg" width="200"/>
2022-11-18 10:55:09 +00:00
</picture>
</a>
</p>
2023-10-29 13:37:24 +00:00
<h1 align="center">
2023-11-11 08:28:05 +00:00
<a href="https://loro.dev" alt="loro-site">Loro</a>
2023-11-11 03:20:16 +00:00
</h1>
2023-11-11 02:57:47 +00:00
<p align="center">
2023-11-11 08:28:05 +00:00
<b>Reimagine state management with CRDTs 🦜</b><br/>
Make your app state synchronized and collaborative effortlessly.
2023-11-11 02:57:47 +00:00
</p>
2024-05-08 10:35:02 +00:00
<p align="center">
<a href="https://trendshift.io/repositories/4964" target="_blank"><img src="https://trendshift.io/api/badge/repositories/4964" alt="loro-dev%2Floro | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
</p>
<p align="center">
<a href="https://loro.dev/docs">
2024-05-08 10:41:30 +00:00
<b>Documentation</b>
2024-05-08 10:35:02 +00:00
</a>
|
<a href="https://loro.dev/docs/tutorial/get_started">
<b>Getting Started</b>
</a>
|
<a href="https://docs.rs/loro">
<b>Rust Doc</b>
</a>
</p>
2023-10-29 13:37:24 +00:00
<p align="center">
2023-10-30 14:00:49 +00:00
<a aria-label="X" href="https://x.com/loro_dev" target="_blank">
2023-10-29 13:37:24 +00:00
<img alt="" src="https://img.shields.io/badge/Twitter-black?style=for-the-badge&logo=Twitter">
</a>
2023-10-30 14:00:49 +00:00
<a aria-label="Discord-Link" href="https://discord.gg/tUsBSVfqzf" target="_blank">
2023-10-29 13:37:24 +00:00
<img alt="" src="https://img.shields.io/badge/Discord-black?style=for-the-badge&logo=discord">
</a>
</p>
2024-01-26 02:28:40 +00:00
https://github.com/loro-dev/loro/assets/18425020/fe246c47-a120-44b3-91d4-1e7232a5b4ac
2023-11-11 17:50:54 +00:00
2024-05-08 10:35:02 +00:00
> ⚠️ **Notice**: The current API and encoding schema of Loro are **experimental** and **subject to change**. You should not use it in production.
Loro is a [CRDTs(Conflict-free Replicated Data Types)](https://crdt.tech/) library that makes building [local-first apps][local-first] easier.
2022-10-03 09:35:44 +00:00
2024-05-08 10:41:30 +00:00
Loro is currently available for JavaScript (via WASM) and Rust developers.
2022-11-18 10:55:09 +00:00
2024-05-08 10:41:30 +00:00
Explore our vision in our blog: [**Reimagine State Management with CRDTs**](https://loro.dev/blog/loro-now-open-source).
2023-11-13 09:13:33 +00:00
2023-11-11 03:54:12 +00:00
# Features
2023-11-11 02:57:47 +00:00
2023-10-29 13:37:24 +00:00
## Supported CRDT Algorithms
2022-11-18 10:55:09 +00:00
2024-05-08 10:41:30 +00:00
- **Common Data Structures**: Includes `List` for ordered collections, LWW (Last Write Win) `Map` for key-value pairs, `Tree` for hierarchical data, and `Text` for rich text manipulation, enabling various applications.
2023-11-03 13:33:36 +00:00
- **Text Editing with Fugue**: Loro integrates [Fugue](https://arxiv.org/abs/2305.00583), a CRDT algorithm designed to minimize interleaving anomalies in concurrent text editing.
2024-05-08 10:35:02 +00:00
- **Peritext-like Rich Text CRDT**: Drawing inspiration from [Peritext](https://www.inkandswitch.com/peritext/), Loro manages rich text CRDTs that excel at merging concurrent rich text style edits, maintaining the original intent of users input as much as possible. Learn more in our blog [Introduction to Loro's Rich Text CRDT](https://loro.dev/blog/loro-richtext).
2023-11-03 13:33:36 +00:00
- **Moveable Tree**: For applications requiring directory-like data manipulation, Loro utilizes the algorithm from [*A Highly-Available Move Operation for Replicated Trees*](https://ieeexplore.ieee.org/document/9563274), which simplifies the process of moving hierarchical data structures.
2024-05-08 10:35:02 +00:00
- [**Moveable List**](https://loro.dev/docs/tutorial/list): Both `List` and `MovableList` utilize Fugue to achieve *maximal noninterleaving*. Additionally, `MovableList` uses the algorithm from [*Moving Elements in List CRDTs*](https://martin.kleppmann.com/2020/04/27/papoc-list-move.html) to implement the move operation.
2022-11-18 10:55:09 +00:00
2023-11-11 03:54:12 +00:00
## Advanced Features in Loro
2023-10-29 13:37:24 +00:00
- **Preserve Editing History**
- With Loro, you can track changes effortlessly as it records the editing history with low overhead.
2024-05-08 10:35:02 +00:00
- This feature is useful for audit trails, undo/redo functionality, and version control.
2023-10-29 13:37:24 +00:00
- **Time Travel Through History**
- It allows users to compare and merge manually when needed, although CRDTs typically resolve conflicts well.
2023-11-11 03:54:12 +00:00
- **High Performance**
- [See benchmarks](https://www.loro.dev/docs/performance).
2023-10-29 13:37:24 +00:00
> **Build time travel feature easily for large documents**.
https://github.com/loro-dev/loro/assets/18425020/ec2d20a3-3d8c-4483-a601-b200243c9792
2023-11-11 17:50:54 +00:00
2023-11-03 13:33:36 +00:00
## Features Provided by CRDTs
2023-10-29 13:37:24 +00:00
2023-11-11 03:54:12 +00:00
- **Decentralized Synchronization**: Loro allows your app's state synced via p2p connections.
- **Automatic Merging**: CRDTs guarantee strong eventual consistency by automating the merging of concurrent changes.
- **Local Availability**: Data can be persisted on users' devices, supporting offline functionality and real-time responsiveness.
2023-10-29 13:37:24 +00:00
- **Scalability**: Effortlessly scale your application horizontally thanks to the inherently distributed nature of CRDTs.
2023-11-11 03:54:12 +00:00
- **Delta Updates**
2022-11-18 10:55:09 +00:00
2024-05-08 10:35:02 +00:00
# Example
[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/edit/loro-basic-test?file=test%2Floro-sync.test.ts)
```ts
import { expect, test } from 'vitest';
import { Loro, LoroList } from 'loro-crdt';
/**
* Demonstrates synchronization of two documents with two rounds of exchanges.
*/
// Initialize document A
const docA = new Loro();
const listA: LoroList = docA.getList('list');
listA.insert(0, 'A');
listA.insert(1, 'B');
listA.insert(2, 'C');
// Export the state of document A as a byte array
const bytes: Uint8Array = docA.exportFrom();
// Simulate sending `bytes` across the network to another peer, B
const docB = new Loro();
// Peer B imports the updates from A
docB.import(bytes);
// Verify that B's state matches A's state
expect(docB.toJSON()).toStrictEqual({
list: ['A', 'B', 'C'],
});
2023-11-15 02:12:04 +00:00
2024-05-08 10:35:02 +00:00
// Get the current operation log version of document B
const version = docB.oplogVersion();
2023-11-15 13:07:00 +00:00
2024-05-08 10:35:02 +00:00
// Simulate editing at B: delete item 'B'
const listB: LoroList = docB.getList('list');
listB.delete(1, 1);
2023-11-15 02:12:04 +00:00
2024-05-08 10:35:02 +00:00
// Export the updates from B since the last synchronization point
const bytesB: Uint8Array = docB.exportFrom(version);
2023-11-15 02:12:04 +00:00
2024-05-08 10:35:02 +00:00
// Simulate sending `bytesB` back across the network to A
// A imports the updates from B
docA.import(bytesB);
2023-11-15 02:12:04 +00:00
2024-05-08 10:35:02 +00:00
// Verify that the list at A now matches the list at B after merging
expect(docA.toJSON()).toStrictEqual({
list: ['A', 'C'],
});
2023-11-15 02:12:04 +00:00
```
2022-11-18 10:55:09 +00:00
# Credits
2023-10-29 13:37:24 +00:00
Loro draws inspiration from the innovative work of the following projects and individuals:
- [Ink & Switch](https://inkandswitch.com/): The principles of Local-first Software have greatly influenced this project. The [Peritext](https://www.inkandswitch.com/peritext/) project has also shaped our approach to rich text CRDTs.
2024-05-06 10:22:09 +00:00
- [Diamond-types](https://github.com/josephg/diamond-types): The [Replayable Event Graph (REG)](https://loro.dev/docs/advanced/replayable_event_graph) algorithm from @josephg has been adapted to reduce the computation and space usage of CRDTs.
2023-10-29 13:37:24 +00:00
- [Automerge](https://github.com/automerge/automerge): Their use of columnar encoding for CRDTs has informed our strategies for efficient data encoding.
2024-05-06 10:22:09 +00:00
- [Yjs](https://github.com/yjs/yjs): We have incorporated a similar algorithm for effectively merging collaborative editing operations, thanks to their pioneering works.
2023-10-29 13:37:24 +00:00
- [Matthew Weidner](https://mattweidner.com/): His work on the [Fugue](https://arxiv.org/abs/2305.00583) algorithm has been invaluable, enhancing our text editing capabilities.
2024-05-06 10:22:09 +00:00
- [Martin Kleppmann](https://martin.kleppmann.com/): His work on CRDTs has significantly influenced our comprehension of the field.
2023-01-11 13:40:16 +00:00
2024-05-06 10:22:09 +00:00
2023-10-29 13:37:24 +00:00
[local-first]: https://www.inkandswitch.com/local-first/
[Fugue]: https://arxiv.org/abs/2305.00583
[Peritext]: https://www.inkandswitch.com/peritext/