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 +82 -0
- package/dist/index.cjs +961 -254
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +64 -7
- package/dist/index.d.ts +64 -7
- package/dist/index.js +959 -255
- package/dist/index.js.map +1 -1
- package/dist/storage/filesystem.d.cts +1 -1
- package/dist/storage/filesystem.d.ts +1 -1
- package/dist/storage/indexeddb.d.cts +1 -1
- package/dist/storage/indexeddb.d.ts +1 -1
- package/dist/storage/sqlite.d.cts +1 -1
- package/dist/storage/sqlite.d.ts +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 +192 -7
- package/dist/types.d.ts +192 -7
- package/package.json +1 -1
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`)
|