loro-repo 0.18.4 → 0.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -50,6 +50,84 @@ await repo.unloadDoc("note:welcome");
50
50
  - **React to changes** with `repo.watch(listener, { docIds, kinds, metadataFields, by })`.
51
51
  - **Shutdown cleanly** by calling `await repo.destroy()`.
52
52
 
53
+ ## Multiple transports
54
+
55
+ A repo can run several transports at once — e.g. a local IPC transport plus a
56
+ best-effort cloud transport. Each room joins every transport its route
57
+ selects, imports fan into the same doc from all of them (CRDT delivery is
58
+ idempotent and commutative), and **per-room statuses are never merged across
59
+ transports**: every (room, transport) pair keeps its own observable state.
60
+
61
+ ```ts
62
+ const repo = await LoroRepo.create({
63
+ // Optional routing policy; defaults to "all registered transports".
64
+ resolveRoomTransports: ({ kind, id }) => ({
65
+ transportIds: isLocallyOwned(id) ? ["local", "cloud"] : ["cloud"],
66
+ }),
67
+ });
68
+
69
+ await repo.addTransport("local", localAdapter);
70
+ // Hot-attach later (e.g. once authenticated); designate it for ephemeral rooms.
71
+ await repo.addTransport("cloud", cloudAdapter, { ephemeral: true });
72
+
73
+ const room = await repo.joinDocRoom("note:welcome");
74
+ room.subscription("local").status; // "joined" | ... | "detached"
75
+ room.subscription("cloud").onStatusChange((status) => { /* repair loop */ });
76
+
77
+ // Enumerate all of one transport's rooms (e.g. to find broken cloud rooms
78
+ // and repair them) without maintaining your own registry:
79
+ for (const { room: descriptor, subscription } of repo.transportRooms("cloud")) {
80
+ if (subscription.status === "error") void subscription.rejoin();
81
+ }
82
+
83
+ // Room ownership resolved asynchronously? Re-evaluate routes for live rooms:
84
+ await repo.refreshTransportRoutes();
85
+
86
+ // Hot-detach on sign-out; the handles above report "detached" and resume
87
+ // automatically after a later addTransport("cloud", ...).
88
+ await repo.removeTransport("cloud");
89
+ ```
90
+
91
+ Key points:
92
+
93
+ - `addTransport(id, adapter, options?)` / `removeTransport(id, { close? })`
94
+ register and unregister named transports; `setTransportAdapter(adapter)`
95
+ remains as sugar for a single transport under `DEFAULT_TRANSPORT_ID`.
96
+ - `resolveRoomTransports({ kind: "meta" | "doc" | "flock-doc", id })` decides
97
+ which transports join each room. It may return ids that are not registered
98
+ yet (they attach when added) or an empty list (the room stays pending until
99
+ a later `refreshTransportRoutes()`).
100
+ - Room handles returned by `joinMetaRoom` / `joinDocRoom` /
101
+ `joinFlockDocRoom` expose stable per-transport subscriptions via
102
+ `subscription(transportId)` / `subscriptions()`. A handle survives
103
+ `removeTransport`/`addTransport` cycles: it reports `"detached"` while its
104
+ transport is absent and resumes live statuses after re-attach.
105
+ - The classic single-value members (`status`, `onStatusChange`, …) keep
106
+ working while exactly one transport is routed; with several routed
107
+ transports they throw instead of merging — there is deliberately no API
108
+ that aggregates multiple transports' room statuses into one value.
109
+ - One transport's failure never affects another's subscription state, join
110
+ lifecycle, or the doc's ability to import from healthy transports. Room
111
+ attaches and one-shot sync pipelines run concurrently per transport, so a
112
+ hanging transport cannot stall a healthy one's convergence, and an
113
+ aborted `sync()` settles even while one transport is hung. Adapters
114
+ always receive the one shared meta Flock instance (their session and
115
+ durable-cursor persistence are keyed on it); concurrent meta syncs stay
116
+ independent because CRDT imports commute and cache hydration runs on a
117
+ single local-only path.
118
+ - `join*Room` resolves as soon as ONE routed transport has attached (or the
119
+ route is empty/pending); the remaining transports keep attaching in the
120
+ background, observable via their per-transport subscriptions. It rejects
121
+ only when every routed registered transport failed to attach.
122
+ - `repo.transportRooms(transportId)` enumerates every live room involving a
123
+ transport together with its stable per-transport subscription.
124
+ - `repo.sync()` resolves with a `RepoSyncReport` listing per-transport
125
+ results (`report.ok` is a convenience aggregate). A partial failure
126
+ resolves with `ok: false`; the call rejects only when every attempted
127
+ transport failed.
128
+ - `repo.reconnect({ transportIds? })` targets all or specific transports, and
129
+ ephemeral rooms go to the transport registered with `{ ephemeral: true }`.
130
+
53
131
  ## Built-in adapters
54
132
 
55
133
  - `BroadcastChannelTransportAdapter` (`src/transport/broadcast-channel.ts`)
@@ -134,14 +212,35 @@ The schema (created on first use) is:
134
212
  ```
135
213
  docs (doc_id PK, snapshot, updated_at, snapshot_digest)
136
214
  doc_updates (id, doc_id, update_data, created_at)
215
+ flock_docs (flock_doc_id PK, snapshot, updated_at, snapshot_digest)
216
+ flock_doc_updates (id, flock_doc_id, update_data, created_at)
137
217
  meta_snapshot (id=1, snapshot, updated_at)
138
218
  meta_updates (id, update_data, created_at)
139
219
  remote_cursors (stream_url PK, next_offset, server_lower_bound_version, updated_at_ms)
140
220
  ```
141
221
 
142
- `loadDoc` / `loadMeta` opportunistically compact replayed updates into a fresh
143
- snapshot inside a single transaction, mirroring the filesystem adapter's
144
- behaviour but without any file churn.
222
+ Post-sync Flock document persistence is version-vector based: no-op syncs do
223
+ not write, and changed state is appended as a JSON delta rather than a full
224
+ Flock file. Local changes that arrive while sync persistence is in flight are
225
+ queued behind that write and flushed from the last durable version. This keeps
226
+ storage growth proportional to new CRDT operations while preserving restart
227
+ convergence. Once a cached Flock document has accumulated 102400 persisted
228
+ delta bytes, the repo asks adapters that support compaction to consolidate
229
+ those updates. Configure this bound with
230
+ `flockDocCompactionByteThreshold` or set it to `0` to disable compaction. The
231
+ threshold-crossing delta save queues a coalesced per-document compaction rather
232
+ than awaiting the full snapshot export, so that sync can return once its delta
233
+ is durable. The adapter compaction starts on a later event-loop turn while
234
+ remaining serialized with later document persistence, and `flush()` /
235
+ `destroy()` drain the queued work.
236
+
237
+ `loadDoc` / `loadFlockDoc` / `loadMeta` opportunistically compact replayed
238
+ updates into a fresh snapshot inside a single transaction, mirroring the
239
+ filesystem adapter's behaviour but without any file churn. Existing databases
240
+ need no migration for delta-aware post-sync persistence; previously amplified
241
+ rows are compacted the next time that Flock document is loaded. Compaction is
242
+ driven by actual delta volume, not by time or sync count, so no-op syncs never
243
+ cause full snapshot exports.
145
244
 
146
245
  ### Backups in WAL mode
147
246