From c3eec8d00f3264df4bb8392122a976e61fa84fcf Mon Sep 17 00:00:00 2001 From: Zixuan Chen Date: Fri, 10 Jan 2025 14:45:27 +0800 Subject: [PATCH] Extract the section of persistence --- pages/docs/tutorial/_meta.json | 1 + pages/docs/tutorial/encoding.md | 40 +----------------------------- pages/docs/tutorial/persistence.md | 37 +++++++++++++++++++++++++++ 3 files changed, 39 insertions(+), 39 deletions(-) create mode 100644 pages/docs/tutorial/persistence.md diff --git a/pages/docs/tutorial/_meta.json b/pages/docs/tutorial/_meta.json index 7cf7c2c..d573d38 100644 --- a/pages/docs/tutorial/_meta.json +++ b/pages/docs/tutorial/_meta.json @@ -10,6 +10,7 @@ "version": "Version", "event": "Event Handling", "encoding": "Export Mode", + "persistence": "Persistence", "cursor": "Cursor", "time_travel": "Time Travel" } diff --git a/pages/docs/tutorial/encoding.md b/pages/docs/tutorial/encoding.md index 4b3cf82..1db7d8a 100644 --- a/pages/docs/tutorial/encoding.md +++ b/pages/docs/tutorial/encoding.md @@ -119,45 +119,7 @@ Note: When using shallow snapshots, you cannot import updates that are concurrent to the snapshot's start version. For details, see [shallow snapshot](/docs/advanced/shallow_snapshot). -## Best Practices for Persisting Loro Documents - -The simplest approach is to use full snapshots for both import and export -operations. Here's how it works: - -1. Import the entire snapshot when loading the document. -2. Export a complete snapshot when saving changes. -3. Implement a debounce or throttle mechanism to trigger snapshot saves after a - certain number of edits. - -This method simplifies initial application development but has a drawback: user -edits are not immediately saved. Let's explore how to quickly save each user -edit while minimizing resource consumption. - -### Balancing Quick Saves and Resource Efficiency - -To achieve both quick saves and resource efficiency: - -- Use `Snapshot` to periodically store the entire document. -- Use `Updates Encoding` to export delta updates frequently (e.g., after each - keystroke or with debounce/throttle). Store these binary data in fast-write - storage like user disks or a key-value database. This ensures quick saves with - low resource cost. -- When loading a document, import the snapshot and all related updates to get - the latest version. -- After importing, export a new snapshot to replace the old one and remove - imported updates for faster future loading. -- If your `LoroDoc` has grown large and older history can be safely recycled, - use `Shallow Snapshot Encoding` to reduce snapshot size. You can archive the - history before the shallow snapshot's start version in cold storage. - -For collaboration, the binary data generated by snapshot/updates can be -transmitted through any medium, such as WebRTC, WebSocket, or HTTP. - -The strong eventual consistency in CRDTs ensures that peers with identical sets -of operations will converge to the same document state, obviating concerns about -the order, duplication, or timing of operation delivery. - -## Loro's Snapshot Format +## Loro's Snapshot File Format To support lazy loading capabilities, we referenced common storage formats in databases, introduced a simple LSM engine, and abstracted the encoding results diff --git a/pages/docs/tutorial/persistence.md b/pages/docs/tutorial/persistence.md new file mode 100644 index 0000000..118fdbc --- /dev/null +++ b/pages/docs/tutorial/persistence.md @@ -0,0 +1,37 @@ +## Best Practices for Persisting Loro Documents + +The simplest approach is to use full snapshots for both import and export +operations. Here's how it works: + +1. Import the entire snapshot when loading the document. +2. Export a complete snapshot when saving changes. +3. Implement a debounce or throttle mechanism to trigger snapshot saves after a + certain number of edits. + +This method simplifies initial application development but has a drawback: user +edits are not immediately saved. Let's explore how to quickly save each user +edit while minimizing resource consumption. + +### Balancing Quick Saves and Resource Efficiency + +To achieve both quick saves and resource efficiency: + +- Use [`Snapshot Encoding`](./encoding#snapshot-encoding) to periodically store the entire document. +- Use [`Updates Encoding`](./encoding#updates-encoding) to export delta updates frequently (e.g., after each + keystroke or with debounce/throttle). Store these binary data in fast-write + storage like user disks or a key-value database. This ensures quick saves with + low resource cost. +- When loading a document, import the snapshot and all related updates to get + the latest version. +- After importing, export a new snapshot to replace the old one and remove + imported updates for faster future loading. +- If your `LoroDoc` has grown large and older history can be safely recycled, + use `Shallow Snapshot Encoding` to reduce snapshot size. You can archive the + history before the shallow snapshot's start version in cold storage. + +For collaboration, the binary data generated by snapshot/updates can be +transmitted through any medium, such as WebRTC, WebSocket, or HTTP. + +The strong eventual consistency in CRDTs ensures that peers with identical sets +of operations will converge to the same document state, obviating concerns about +the order, duplication, or timing of operation delivery.