-
Notifications
You must be signed in to change notification settings - Fork 71
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add packages' repo and basic doc (#390)
* docs: update the pkg desc * chore: changeset
- Loading branch information
Showing
5 changed files
with
291 additions
and
6 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
--- | ||
"loro-wasm": patch | ||
"loro-crdt": patch | ||
--- | ||
|
||
Update pkg desc |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,141 @@ | ||
# Loro WASM | ||
<p align="center"> | ||
<a href="https://loro.dev"> | ||
<picture> | ||
<img src="./docs/Loro.svg" width="200"/> | ||
</picture> | ||
</a> | ||
</p> | ||
<h1 align="center"> | ||
<a href="https://loro.dev" alt="loro-site">Loro</a> | ||
</h1> | ||
<p align="center"> | ||
<b>Reimagine state management with CRDTs 🦜</b><br/> | ||
Make your app state synchronized and collaborative effortlessly. | ||
</p> | ||
<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"> | ||
<b>Documentation</b> | ||
</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> | ||
<p align="center"> | ||
<a aria-label="X" href="https://x.com/loro_dev" target="_blank"> | ||
<img alt="" src="https://img.shields.io/badge/Twitter-black?style=for-the-badge&logo=Twitter"> | ||
</a> | ||
<a aria-label="Discord-Link" href="https://discord.gg/tUsBSVfqzf" target="_blank"> | ||
<img alt="" src="https://img.shields.io/badge/Discord-black?style=for-the-badge&logo=discord"> | ||
</a> | ||
</p> | ||
|
||
Loro WASM is a WASM package of Loro. Learn more at https://loro.dev | ||
|
||
https://github.com/loro-dev/loro/assets/18425020/fe246c47-a120-44b3-91d4-1e7232a5b4ac | ||
|
||
|
||
> ⚠️ **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. It is currently available for JavaScript (via WASM) and Rust developers. | ||
|
||
Explore our vision in our blog: [**✨ Reimagine State Management with CRDTs**](https://loro.dev/blog/loro-now-open-source). | ||
|
||
# Features | ||
|
||
**Basic Features Provided by CRDTs** | ||
|
||
- P2P Synchronization | ||
- Automatic Merging | ||
- Local Availability | ||
- Scalability | ||
- Delta Updates | ||
|
||
**Supported CRDT Algorithms** | ||
|
||
- 📝 Text Editing with [Fugue] | ||
- 📙 [Peritext-like Rich Text CRDT](https://loro.dev/blog/loro-richtext) | ||
- 🌲 [Moveable Tree](https://loro.dev/docs/tutorial/tree) | ||
- 🚗 [Moveable List](https://loro.dev/docs/tutorial/list) | ||
- 🗺️ [Last-Write-Wins Map](https://loro.dev/docs/tutorial/map) | ||
- 🔄 [Replayable Event Graph](https://loro.dev/docs/advanced/replayable_event_graph) | ||
|
||
**Advanced Features in Loro** | ||
|
||
- 📖 Preserve Editing History in a [Replayable Event Graph](https://loro.dev/docs/advanced/replayable_event_graph) | ||
- ⏱️ Fast [Time Travel](https://loro.dev/docs/tutorial/time_travel) Through History | ||
|
||
https://github.com/loro-dev/loro/assets/18425020/ec2d20a3-3d8c-4483-a601-b200243c9792 | ||
|
||
# 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'], | ||
}); | ||
|
||
// Get the current operation log version of document B | ||
const version = docB.oplogVersion(); | ||
|
||
// Simulate editing at B: delete item 'B' | ||
const listB: LoroList = docB.getList('list'); | ||
listB.delete(1, 1); | ||
|
||
// Export the updates from B since the last synchronization point | ||
const bytesB: Uint8Array = docB.exportFrom(version); | ||
|
||
// Simulate sending `bytesB` back across the network to A | ||
// A imports the updates from B | ||
docA.import(bytesB); | ||
|
||
// Verify that the list at A now matches the list at B after merging | ||
expect(docA.toJSON()).toStrictEqual({ | ||
list: ['A', 'C'], | ||
}); | ||
``` | ||
|
||
# Credits | ||
|
||
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. | ||
- [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. | ||
- [Automerge](https://github.com/automerge/automerge): Their use of columnar encoding for CRDTs has informed our strategies for efficient data encoding. | ||
- [Yjs](https://github.com/yjs/yjs): We have incorporated a similar algorithm for effectively merging collaborative editing operations, thanks to their pioneering works. | ||
- [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. | ||
- [Martin Kleppmann](https://martin.kleppmann.com/): His work on CRDTs has significantly influenced our comprehension of the field. | ||
|
||
|
||
[local-first]: https://www.inkandswitch.com/local-first/ | ||
[Fugue]: https://arxiv.org/abs/2305.00583 | ||
[Peritext]: https://www.inkandswitch.com/peritext/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,8 +1,141 @@ | ||
# loro-crdt | ||
<p align="center"> | ||
<a href="https://loro.dev"> | ||
<picture> | ||
<img src="./docs/Loro.svg" width="200"/> | ||
</picture> | ||
</a> | ||
</p> | ||
<h1 align="center"> | ||
<a href="https://loro.dev" alt="loro-site">Loro</a> | ||
</h1> | ||
<p align="center"> | ||
<b>Reimagine state management with CRDTs 🦜</b><br/> | ||
Make your app state synchronized and collaborative effortlessly. | ||
</p> | ||
<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"> | ||
<b>Documentation</b> | ||
</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> | ||
<p align="center"> | ||
<a aria-label="X" href="https://x.com/loro_dev" target="_blank"> | ||
<img alt="" src="https://img.shields.io/badge/Twitter-black?style=for-the-badge&logo=Twitter"> | ||
</a> | ||
<a aria-label="Discord-Link" href="https://discord.gg/tUsBSVfqzf" target="_blank"> | ||
<img alt="" src="https://img.shields.io/badge/Discord-black?style=for-the-badge&logo=discord"> | ||
</a> | ||
</p> | ||
|
||
Loro CRDTs is a high-performance CRDT framework. | ||
|
||
It makes your app state synchronized, collaborative and maintainable effortlessly. | ||
https://github.com/loro-dev/loro/assets/18425020/fe246c47-a120-44b3-91d4-1e7232a5b4ac | ||
|
||
Learn more at https://loro.dev | ||
|
||
> ⚠️ **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. It is currently available for JavaScript (via WASM) and Rust developers. | ||
|
||
Explore our vision in our blog: [**✨ Reimagine State Management with CRDTs**](https://loro.dev/blog/loro-now-open-source). | ||
|
||
# Features | ||
|
||
**Basic Features Provided by CRDTs** | ||
|
||
- P2P Synchronization | ||
- Automatic Merging | ||
- Local Availability | ||
- Scalability | ||
- Delta Updates | ||
|
||
**Supported CRDT Algorithms** | ||
|
||
- 📝 Text Editing with [Fugue] | ||
- 📙 [Peritext-like Rich Text CRDT](https://loro.dev/blog/loro-richtext) | ||
- 🌲 [Moveable Tree](https://loro.dev/docs/tutorial/tree) | ||
- 🚗 [Moveable List](https://loro.dev/docs/tutorial/list) | ||
- 🗺️ [Last-Write-Wins Map](https://loro.dev/docs/tutorial/map) | ||
- 🔄 [Replayable Event Graph](https://loro.dev/docs/advanced/replayable_event_graph) | ||
|
||
**Advanced Features in Loro** | ||
|
||
- 📖 Preserve Editing History in a [Replayable Event Graph](https://loro.dev/docs/advanced/replayable_event_graph) | ||
- ⏱️ Fast [Time Travel](https://loro.dev/docs/tutorial/time_travel) Through History | ||
|
||
https://github.com/loro-dev/loro/assets/18425020/ec2d20a3-3d8c-4483-a601-b200243c9792 | ||
|
||
# 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'], | ||
}); | ||
|
||
// Get the current operation log version of document B | ||
const version = docB.oplogVersion(); | ||
|
||
// Simulate editing at B: delete item 'B' | ||
const listB: LoroList = docB.getList('list'); | ||
listB.delete(1, 1); | ||
|
||
// Export the updates from B since the last synchronization point | ||
const bytesB: Uint8Array = docB.exportFrom(version); | ||
|
||
// Simulate sending `bytesB` back across the network to A | ||
// A imports the updates from B | ||
docA.import(bytesB); | ||
|
||
// Verify that the list at A now matches the list at B after merging | ||
expect(docA.toJSON()).toStrictEqual({ | ||
list: ['A', 'C'], | ||
}); | ||
``` | ||
|
||
# Credits | ||
|
||
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. | ||
- [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. | ||
- [Automerge](https://github.com/automerge/automerge): Their use of columnar encoding for CRDTs has informed our strategies for efficient data encoding. | ||
- [Yjs](https://github.com/yjs/yjs): We have incorporated a similar algorithm for effectively merging collaborative editing operations, thanks to their pioneering works. | ||
- [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. | ||
- [Martin Kleppmann](https://martin.kleppmann.com/): His work on CRDTs has significantly influenced our comprehension of the field. | ||
|
||
|
||
[local-first]: https://www.inkandswitch.com/local-first/ | ||
[Fugue]: https://arxiv.org/abs/2305.00583 | ||
[Peritext]: https://www.inkandswitch.com/peritext/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters