Merge pull request #4 from loro-dev/docs-version

docs: refine docs about version and syncing

Author: zxch3n

pages/docs/advanced/doc_state_and_oplog.md

@@ -36,6 +36,41 @@ state, the version of DocState and the latest version recorded in OpLog may not
 always match. When they align, it is in an _attached_ state; otherwise, it's in
 a _detached_ state.
 
+```ts
+const doc = new LoroDoc();
+doc.setPeerId(1);
+doc.getText("text").insert(0, "Hello");
+const doc2 = doc.fork(); // create a fork of the doc
+console.log(doc.version().toJSON());
+// Map(1) { "1" => 5 }
+console.log(doc.oplogVersion().toJSON());
+// Map(1) { "1" => 5 }
+
+doc.checkout([{ peer: "1", counter: 1 }]);
+console.log(doc.version().toJSON());
+// Map(1) { "1" => 2 }
+console.log(doc.oplogVersion().toJSON());
+// Map(1) { "1" => 5 }
+
+doc2.setPeerId(2);
+doc2.getText("text").insert(5, "!");
+doc.import(doc2.export({ mode: "update" }));
+console.log(doc.version().toJSON());
+// Map(1) { "1" => 2 }
+console.log(doc.oplogVersion().toJSON());
+// Map(2) { "1" => 5, "2" => 1 }
+
+console.log(doc.isDetached()); // true
+doc.attach();
+console.log(doc.version().toJSON());
+// Map(2) { "1" => 5, "2" => 1 }
+console.log(doc.oplogVersion().toJSON());
+// Map(2) { "1" => 5, "2" => 1 }
+
+```
+
+![DocState and OpLog Detached Example](./images/version-4.png)
+
 The doc cannot be edited in the detached mode. Users must use `attach()` to
 return to the latest version to continue editing.
 

pages/docs/advanced/images/version-4.png

@@ -1,6 +1,7 @@
 {
   "get_started": "Getting Started",
   "loro_doc": "Loro Document",
+  "sync": "Sync",
   "text": "Text",
   "composition": "Composing CRDTs",
   "list": "List and Movable List",

pages/docs/tutorial/_meta.json

@@ -304,7 +304,7 @@ listB.delete(1, 1);
 // `version` is the version vector of another document
 const missingOps = docB.export({
   mode: "update",
-  from: docA.version(),
+  from: docA.oplogVersion(),
 });
 docA.import(missingOps);
 

pages/docs/tutorial/get_started.md

@@ -0,0 +1,73 @@
+## Sync
+
+Two documents with concurrent edits can be synchronized by just two message
+exchanges.
+
+Below is an example of synchronization between two documents:
+
+```ts
+const docA = new LoroDoc();
+const docB = new LoroDoc();
+const listA: LoroList = docA.getList("list");
+listA.insert(0, "A");
+listA.insert(1, "B");
+listA.insert(2, "C");
+// B import the ops from A
+const data: Uint8Array = docA.export({ mode: "update" });
+// The data can be sent to B through the network
+docB.import(data);
+expect(docB.toJSON()).toStrictEqual({
+  list: ["A", "B", "C"],
+});
+
+const listB: LoroList = docB.getList("list");
+listB.delete(1, 1);
+
+// `doc.export({mode: "update", from: version})` can encode all the ops from the version to the latest version
+// `version` is the version vector of another document
+const missingOps = docB.export({
+  mode: "update",
+  from: docA.oplogVersion(),
+});
+docA.import(missingOps);
+
+expect(docA.toJSON()).toStrictEqual({
+  list: ["A", "C"],
+});
+expect(docA.toJSON()).toStrictEqual(docB.toJSON());
+```
+
+## Real-time Collaboration
+
+Due to CRDT properties, document consistency is guaranteed when peers receive the same updates, regardless of order or duplicates.
+
+- First Sync: Initial synchronization between peers (done in the example above)
+- Real-time Sync (shown in the example below):
+  - Subscribe to local updates
+  - Broadcast updates directly to all the other peers
+  - No need for version comparison
+  - As long as updates reach all peers, consistency is maintained
+
+Example: 
+
+```ts 
+const docA = new LoroDoc();
+const docB = new LoroDoc();
+// Assume docA and docB finished the first sync
+
+docA.subscribeLocalUpdates((update) => {
+  // simulate sending update to docB
+  docB.import(update);
+});
+
+docB.subscribeLocalUpdates((update) => {
+  // simulate sending update to docA
+  docA.import(update);
+});
+
+docA.getText("text").insert(0, "Hello");
+docA.commit();
+await Promise.resolve(); // await the event to be emitted
+console.log(docB.toJSON());
+// { text: "Hello" }
+```

pages/docs/tutorial/sync.md

@@ -27,7 +27,7 @@ over time.
 Before this example will work, it is important that the edits made to the document
 have had [timestamp storage](/docs/advanced/timestamp) enabled:
 
-```ts
+```ts no_run
 doc.setRecordTimestamp(true);
 ```
 
@@ -40,7 +40,8 @@ intuition.
 The first step is to load our document. Here we assume that you have a snapshot from your database
 or API.
 
-```ts
+```ts no_run
+
 // Get the snapshot for your doc from your database / API
 let snapshot = fetchSnapshot();
 
@@ -52,7 +53,7 @@ doc.import(snapshot);
 Next we must collect and sort the timestamps for every change in the document. We want uesrs to be
 able to drag a slider to select a timestamp out of this list.
 
-```ts
+```ts no_run
 // Collect all changes from the document
 const changes = doc.getAllChanges();
 
@@ -113,7 +114,7 @@ const getFrontiersForTimestamp = (
 Finally, all we can get the index from our slider, get the timestamp from our list, and then
 checkout the calculated frontiers.
 
-```ts
+```ts no_run
 let sliderIdx = 3;
 const timestamp = timestamps[sliderIdx - 1];
 const frontiers = getFrontiersForTimestamp(changes, timestamp);