Skip to content

Commit

Permalink
Extract the section of persistence
Browse files Browse the repository at this point in the history
  • Loading branch information
zxch3n committed Jan 10, 2025
1 parent 6e5ff32 commit c3eec8d
Show file tree
Hide file tree
Showing 3 changed files with 39 additions and 39 deletions.
1 change: 1 addition & 0 deletions pages/docs/tutorial/_meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
"version": "Version",
"event": "Event Handling",
"encoding": "Export Mode",
"persistence": "Persistence",
"cursor": "Cursor",
"time_travel": "Time Travel"
}
40 changes: 1 addition & 39 deletions pages/docs/tutorial/encoding.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
37 changes: 37 additions & 0 deletions pages/docs/tutorial/persistence.md
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit c3eec8d

Please sign in to comment.