loro-repo 0.18.5 → 0.19.1

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,88 @@ 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
+ - Rooms can be joined before ANY transport is registered (offline-first
101
+ startup): the join resolves as a pending room whose classic surface reads
102
+ `"disconnected"`, and it attaches automatically when the first transport
103
+ is added. Only `joinEphemeralRoom` requires a registered transport.
104
+ - Room handles returned by `joinMetaRoom` / `joinDocRoom` /
105
+ `joinFlockDocRoom` expose stable per-transport subscriptions via
106
+ `subscription(transportId)` / `subscriptions()`. A handle survives
107
+ `removeTransport`/`addTransport` cycles: it reports `"detached"` while its
108
+ transport is absent and resumes live statuses after re-attach.
109
+ - The classic single-value members (`status`, `onStatusChange`, …) keep
110
+ working while exactly one transport is routed; with several routed
111
+ transports they throw instead of merging — there is deliberately no API
112
+ that aggregates multiple transports' room statuses into one value.
113
+ - One transport's failure never affects another's subscription state, join
114
+ lifecycle, or the doc's ability to import from healthy transports. Room
115
+ attaches and one-shot sync pipelines run concurrently per transport, so a
116
+ hanging transport cannot stall a healthy one's convergence, and an
117
+ aborted `sync()` settles even while one transport is hung. Adapters
118
+ always receive the one shared meta Flock instance (their session and
119
+ durable-cursor persistence are keyed on it); concurrent meta syncs stay
120
+ independent because CRDT imports commute and cache hydration runs on a
121
+ single local-only path.
122
+ - `join*Room` resolves as soon as ONE routed transport has attached (or the
123
+ route is empty/pending); the remaining transports keep attaching in the
124
+ background, observable via their per-transport subscriptions. It rejects
125
+ only when every routed registered transport failed to attach.
126
+ - `repo.transportRooms(transportId)` enumerates every live room involving a
127
+ transport together with its stable per-transport subscription.
128
+ - `repo.sync()` resolves with a `RepoSyncReport` listing per-transport
129
+ results (`report.ok` is a convenience aggregate). A partial failure
130
+ resolves with `ok: false`; the call rejects only when every attempted
131
+ transport failed.
132
+ - `repo.reconnect({ transportIds? })` targets all or specific transports, and
133
+ ephemeral rooms go to the transport registered with `{ ephemeral: true }`.
134
+
53
135
  ## Built-in adapters
54
136
 
55
137
  - `BroadcastChannelTransportAdapter` (`src/transport/broadcast-channel.ts`)