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 +102 -3
- package/dist/index.cjs +974 -269
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +59 -7
- package/dist/index.d.ts +59 -7
- package/dist/index.js +972 -270
- package/dist/index.js.map +1 -1
- package/dist/storage/filesystem.cjs +3 -0
- package/dist/storage/filesystem.cjs.map +1 -1
- package/dist/storage/filesystem.d.cts +2 -1
- package/dist/storage/filesystem.d.ts +2 -1
- package/dist/storage/filesystem.js +3 -0
- package/dist/storage/filesystem.js.map +1 -1
- package/dist/storage/indexeddb.cjs +3 -0
- package/dist/storage/indexeddb.cjs.map +1 -1
- package/dist/storage/indexeddb.d.cts +2 -1
- package/dist/storage/indexeddb.d.ts +2 -1
- package/dist/storage/indexeddb.js +3 -0
- package/dist/storage/indexeddb.js.map +1 -1
- package/dist/storage/sqlite.cjs +4 -0
- package/dist/storage/sqlite.cjs.map +1 -1
- package/dist/storage/sqlite.d.cts +2 -1
- package/dist/storage/sqlite.d.ts +2 -1
- package/dist/storage/sqlite.js +4 -0
- package/dist/storage/sqlite.js.map +1 -1
- package/dist/transport/broadcast-channel.d.cts +1 -1
- package/dist/transport/broadcast-channel.d.ts +1 -1
- package/dist/transport/streams.d.cts +1 -1
- package/dist/transport/streams.d.ts +1 -1
- package/dist/transport/websocket.d.cts +1 -1
- package/dist/transport/websocket.d.ts +1 -1
- package/dist/types.d.cts +205 -7
- package/dist/types.d.ts +205 -7
- package/package.json +2 -1
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
|
-
|
|
143
|
-
|
|
144
|
-
|
|
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
|
|