/ README.md
README.md
1 <p align="center"> 2 <a href="https://loro.dev"> 3 <picture> 4 <img src="./docs/Loro.svg" width="200"/> 5 </picture> 6 </a> 7 </p> 8 <h1 align="center"> 9 <a href="https://loro.dev" alt="loro-site">Loro</a> 10 </h1> 11 <p align="center"> 12 <b>Make your JSON data collaborative and version-controlled 🦜</b> 13 </p> 14 <p align="center"> 15 <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> 16 </p> 17 <p align="center"> 18 <a href="https://loro.dev/docs"> 19 <b>Documentation</b> 20 </a> 21 | 22 <a href="https://loro.dev/docs/tutorial/get_started"> 23 <b>Getting Started</b> 24 </a> 25 | 26 <a href="https://docs.rs/loro"> 27 <b>Rust Doc</b> 28 </a> 29 </p> 30 <p align="center"> 31 <a aria-label="X" href="https://x.com/loro_dev" target="_blank"> 32 <img alt="" src="https://img.shields.io/badge/Twitter-black?style=for-the-badge&logo=Twitter"> 33 </a> 34 <a aria-label="Discord-Link" href="https://discord.gg/tUsBSVfqzf" target="_blank"> 35 <img alt="" src="https://img.shields.io/badge/Discord-black?style=for-the-badge&logo=discord"> 36 </a> 37 <a aria-label="Gurubase" href="https://gurubase.io/g/loro" target="_blank"> 38 <img alt="" src="https://img.shields.io/badge/Ask%20Loro%20Guru-000000?style=for-the-badge"> 39 </a> 40 </p> 41 42 https://github.com/loro-dev/loro/assets/18425020/fe246c47-a120-44b3-91d4-1e7232a5b4ac 43 44 <h4 align="center"> 45 ✨ Loro 1.0 is out! Read the <a href="https://loro.dev/blog/v1.0">announcement</a>. 46 </h4> 47 48 Loro is a [CRDTs(Conflict-free Replicated Data Types)](https://crdt.tech/) library that makes building [local-first][local-first] and collaborative apps easier. You can now use it in Rust, JS (via WASM), and Swift. 49 50 # Features 51 52 **Features Provided by CRDTs** 53 54 - P2P Synchronization 55 - Automatic Merging 56 - Local Availability 57 - Scalability 58 - Delta Updates 59 60 **Supported CRDT Algorithms** 61 62 - 📝 Text Editing with [Fugue] 63 - 📙 [Rich Text CRDT](https://loro.dev/blog/loro-richtext) 64 - 🌲 [Moveable Tree](https://loro.dev/docs/tutorial/tree) 65 - 🚗 [Moveable List](https://loro.dev/docs/tutorial/list) 66 - 🗺️ [Last-Write-Wins Map](https://loro.dev/docs/tutorial/map) 67 68 **Advanced Features in Loro** 69 70 - 🚀 [Fast Document Loading](https://loro.dev/blog/v1.0) 71 - ⏱️ Fast [Time Travel](https://loro.dev/docs/tutorial/time_travel) Through History 72 - 🏛️ [Version Control with Real-Time Collaboration](https://loro.dev/blog/v1.0#version-control) 73 - 📦 [Shallow Snapshot](https://loro.dev/docs/advanced/shallow_snapshot) that Works like Git Shallow Clone 74 75 https://github.com/user-attachments/assets/68e0017a-4987-4f71-b2cf-4ed28a210987 76 77 > In this example, we demonstrate importing an entire Loro codebase into a Loro-powered 78 > version controller, preserving the complete Git DAG history while enabling fast version switching. 79 80 # Example 81 82 [](https://stackblitz.com/edit/loro-basic-test?file=test%2Floro-sync.test.ts) 83 84 ```ts 85 import { expect, test } from "vitest"; 86 import { LoroDoc, LoroList } from "loro-crdt"; 87 88 test("sync example", () => { 89 // Sync two docs with two rounds of exchanges 90 91 // Initialize document A 92 const docA = new LoroDoc(); 93 const listA: LoroList = docA.getList("list"); 94 listA.insert(0, "A"); 95 listA.insert(1, "B"); 96 listA.insert(2, "C"); 97 98 // Export all updates from docA 99 const bytes: Uint8Array = docA.export({ mode: "update" }); 100 101 // Simulate sending `bytes` across the network to another peer, B 102 103 const docB = new LoroDoc(); 104 // Peer B imports the updates from A 105 docB.import(bytes); 106 107 // B's state matches A's state 108 expect(docB.toJSON()).toStrictEqual({ 109 list: ["A", "B", "C"], 110 }); 111 112 // Get the current version of docB 113 const version = docB.oplogVersion(); 114 115 // Simulate editing at B: delete item 'B' 116 const listB: LoroList = docB.getList("list"); 117 listB.delete(1, 1); 118 119 // Export the updates from B since the last sync point 120 const bytesB: Uint8Array = docB.export({ mode: "update", from: version }); 121 122 // Simulate sending `bytesB` back across the network to A 123 124 // A imports the updates from B 125 docA.import(bytesB); 126 127 // A has the same state as B 128 expect(docA.toJSON()).toStrictEqual({ 129 list: ["A", "C"], 130 }); 131 }); 132 ``` 133 134 # DevTools 135 136 ## Loro Inspector 137 138 You can use the [Loro Inspector](https://inspector.loro.dev) to inspect the state and history of a Loro document. 139 140 https://github.com/user-attachments/assets/ceeb7450-80ce-42f2-aef4-2e08fa2d1f1b 141 142 # Bindings 143 144 You can find bindings for other programming languages in [loro-ffi](https://github.com/loro-dev/loro-ffi). 145 146 # Blog 147 148 - [Loro 1.0](https://loro.dev/blog/v1.0) 149 - [Movable tree CRDTs and Loro's implementation](https://loro.dev/blog/movable-tree) 150 - [Introduction to Loro's Rich Text CRDT](https://loro.dev/blog/loro-richtext) 151 - [Loro: Reimagine State Management with CRDTs](https://loro.dev/blog/loro-now-open-source) 152 153 # Credits 154 155 Loro draws inspiration from the innovative work of the following projects and individuals: 156 157 - [Diamond-types](https://github.com/josephg/diamond-types): The [Event Graph Walker (Eg-walker)](https://loro.dev/docs/advanced/event_graph_walker) algorithm from @josephg has been adapted to reduce the computation and space usage of CRDTs. 158 - [Automerge](https://github.com/automerge/automerge): Their use of columnar encoding for CRDTs has informed our strategies for efficient data encoding. 159 - [Yjs](https://github.com/yjs/yjs): We have incorporated a similar algorithm for effectively merging collaborative editing operations, thanks to their pioneering work. 160 - [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. 161 - [Martin Kleppmann](https://martin.kleppmann.com/): His work on CRDTs has significantly influenced our comprehension of the field. 162 163 [local-first]: https://www.inkandswitch.com/local-first/ 164 [Fugue]: https://arxiv.org/abs/2305.00583