This PR introduces support for retrieving and querying cursors.
## Motivation
Using "index" to denote cursor positions can be unstable, as positions may shift with document edits. To reliably represent a position or range within a document, it is more effective to leverage the unique ID of each item/character in a List CRDT or Text CRDT.
## Updating Cursors
Loro optimizes State metadata by not storing the IDs of deleted elements. This approach, while efficient, complicates tracking cursor positions since they rely on these IDs for precise locations within the document. The solution recalculates position by replaying relevant history to update stable positions accurately. To minimize the performance impact of history replay, the system updates cursor info to reference only the IDs of currently present elements, thereby reducing the need for replay.
Each position has a "Side" information, indicating the actual cursor position is on the left, right, or directly in the center of the target ID.
Note: In JavaScript, the offset returned when querying a Stable Position is based on the UTF-16 index.
# Example
```ts
const loro = new Loro();
const list = loro.getList("list");
list.insert(0, "a");
const pos0 = list.getStablePos(0);
list.insert(1, "b");
{
const ans = loro.queryStablePos(pos0!);
expect(ans.offset).toEqual(0);
expect(ans.side).toEqual(0);
expect(ans.update).toBeUndefined();
}
list.insert(0, "c");
{
const ans = loro.queryStablePos(pos0!);
expect(ans.offset).toEqual(1);
expect(ans.side).toEqual(0);
expect(ans.update).toBeUndefined();
}
list.delete(1, 1);
{
const ans = loro.queryStablePos(pos0!);
expect(ans.offset).toEqual(1);
expect(ans.side).toEqual(-1);
expect(ans.update).toBeDefined();
}
```
* feat: access elem by path
* fix: parse tree node index by str
* fix: reuse treeid try_from
* chore: rename methods on lib.rs
---------
Co-authored-by: Leon Zhao <leeeon233@gmail.com>
This PR includes a BREAKING CHANGE.
It enables you to create containers before attaching them to the document, making the API more intuitive and straightforward.
A container can be either attached to a document or detached. When it's detached, its history/state does not persist. You can attach a container to a document by inserting it into an attached container. Once a container is attached, its state, along with all of its descendants's states, will be recreated in the document. After attaching, the container and its descendants, will each have their corresponding "attached" version of themselves?
When a detached container x is attached to a document, you can use x.getAttached() to obtain the corresponding attached container.
* refactor: include start_id in seq delete span
* Add size benchmark example (#276)
* test: add size bench example
* chore: update lock file
* refactor: optimize encoding
* perf: make revert ops with the size of m O(m)
* fix: delete span with id merge rule
* fix: fix several bugs related to delete span id
* refactor: encoding container id
* fix: container indexing when merged ops in encoding
* chore: add compress encode size for draw example
* fix: do not need cids in encoding
* chore: change name containerIdx to containerType in encoding
* fix: avoid enter invalid richtext state
* fix: only include the style when the doc contains both style start and style end
* fix: iter_range err in richtext state
* fix: richtext state iter range
* fix: iter range err
* fix: iter range
* chore: rm log
* fix: iter range
* fix: get affected range
* fix: return err if given checkout target is invalid
* refactor(wasm): extract VersionVector class and fix inconsistent PeerID in wasm
* fix: example type err
* fix: binding err
* fix: peer id repr should be consistent
* test: update tests
* refactor: use rich text style config
* chore: rm log
* feat: support config text style in wasm
* feat: overlapped styles
* chore: add warning style key cannot contain ':'
* test: refine test case for richtext
* test: refine test
* refactor: rm txn.abort and related undo behavior
* perf: simplify richtext state when there is not styles
* perf: reduce text cost when there is no style
* chore: refine logs
* perf: remove cid in states to reduce mem overhead
* refactor: reduce mem overhead by using a compacter mapvalue
* refactor: rm the box inside richtext state
This pull request fixes an issue in the Tracker module where only the target span was forwarded during forwarding instead of forwarding all content from vv to the target opid. This resulted in errors in current_vv. The issue is resolved by updating the forward function in the Tracker module to include the entire range of content to be forwarded.
It also fixed the inconsistent issue in richtext between style anchors and style ranges.
---------
Co-authored-by: leeeon233 <leeeon233@gmail.com>
* refactor: make container states can get their ids
* test: add utils to test consistency between the current states and diff calc
* test: add state diff calc consistency check
This PR implements a new encode schema that is more extendible and more compact. It’s also simpler and takes less binary size and maintaining effort. It is inspired by the [Automerge Encoding Format](https://automerge.org/automerge-binary-format-spec/).
The main motivation is the extensibility. When we integrate a new CRDT algorithm, we don’t want to make a breaking change to the encoding or keep multiple versions of the encoding schema in the code, as it will make our WASM size much larger. We need a stable and extendible encoding schema for our v1.0 version.
This PR also exposes the ops that compose the current container state. For example, now you can make a query about which operation a certain character quickly. This behavior is required in the new snapshot encoding, so it’s included in this PR.
# Encoding Schema
## Header
The header has 22 bytes.
- (0-4 bytes) Magic Bytes: The encoding starts with `loro` as magic bytes.
- (4-20 bytes) Checksum: MD5 checksum of the encoded data, including the header starting from 20th bytes. The checksum is encoded as a 16-byte array. The `checksum` and `magic bytes` fields are trimmed when calculating the checksum.
- (20-21 bytes) Encoding Method (2 bytes, big endian): Multiple encoding methods are available for a specific encoding version.
## Encode Mode: Updates
In this approach, only ops, specifically their historical record, are encoded, while document states are excluded.
Like Automerge's format, we employ columnar encoding for operations and changes.
Previously, operations were ordered by their Operation ID (OpId) before columnar encoding. However, sorting operations based on their respective containers initially enhance compression potential.
## Encode Mode: Snapshot
This mode simultaneously captures document state and historical data. Upon importing a snapshot into a new document, initialization occurs directly from the snapshot, bypassing the need for CRDT-based recalculations.
Unlike previous snapshot encoding methods, the current binary output in snapshot mode is compatible with the updates mode. This enhances the efficiency of importing snapshots into non-empty documents, where initialization via snapshot is infeasible.
Additionally, when feasible, we leverage the sequence of operations to construct state snapshots. In CRDTs, deducing the specific ops constituting the current container state is feasible. These ops are tagged in relation to the container, facilitating direct state reconstruction from them. This approach, pioneered by Automerge, significantly improves compression efficiency.
