loro-repo 0.18.5 → 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`)