loro-repo 0.16.11 → 0.18.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 +127 -0
- package/dist/index.cjs +862 -42
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +21 -2
- package/dist/index.d.ts +21 -2
- package/dist/index.js +862 -42
- package/dist/index.js.map +1 -1
- package/dist/storage/filesystem.cjs +79 -14
- package/dist/storage/filesystem.cjs.map +1 -1
- package/dist/storage/filesystem.d.cts +15 -1
- package/dist/storage/filesystem.d.ts +15 -1
- package/dist/storage/filesystem.js +79 -14
- package/dist/storage/filesystem.js.map +1 -1
- package/dist/storage/indexeddb.cjs +151 -39
- package/dist/storage/indexeddb.cjs.map +1 -1
- package/dist/storage/indexeddb.d.cts +16 -1
- package/dist/storage/indexeddb.d.ts +16 -1
- package/dist/storage/indexeddb.js +151 -39
- package/dist/storage/indexeddb.js.map +1 -1
- package/dist/storage/sqlite.cjs +449 -0
- package/dist/storage/sqlite.cjs.map +1 -0
- package/dist/storage/sqlite.d.cts +98 -0
- package/dist/storage/sqlite.d.ts +98 -0
- package/dist/storage/sqlite.js +445 -0
- package/dist/storage/sqlite.js.map +1 -0
- package/dist/transport/broadcast-channel.cjs +131 -0
- package/dist/transport/broadcast-channel.cjs.map +1 -1
- package/dist/transport/broadcast-channel.d.cts +8 -1
- package/dist/transport/broadcast-channel.d.ts +8 -1
- package/dist/transport/broadcast-channel.js +131 -0
- package/dist/transport/broadcast-channel.js.map +1 -1
- package/dist/transport/streams.cjs +188 -0
- package/dist/transport/streams.cjs.map +1 -1
- package/dist/transport/streams.d.cts +27 -1
- package/dist/transport/streams.d.ts +27 -1
- package/dist/transport/streams.js +188 -0
- package/dist/transport/streams.js.map +1 -1
- package/dist/transport/websocket.cjs +196 -0
- package/dist/transport/websocket.cjs.map +1 -1
- package/dist/transport/websocket.d.cts +23 -2
- package/dist/transport/websocket.d.ts +23 -2
- package/dist/transport/websocket.js +196 -0
- package/dist/transport/websocket.js.map +1 -1
- package/dist/types.d.cts +129 -1
- package/dist/types.d.ts +129 -1
- package/package.json +21 -3
package/README.md
CHANGED
|
@@ -56,6 +56,133 @@ await repo.unloadDoc("note:welcome");
|
|
|
56
56
|
- `WebSocketTransportAdapter` (`src/transport/websocket.ts`)
|
|
57
57
|
- `IndexedDBStorageAdaptor` (`src/storage/indexeddb.ts`)
|
|
58
58
|
- `FileSystemStorageAdaptor` (`src/storage/filesystem.ts`)
|
|
59
|
+
- `SqliteRepoStore` (`src/storage/sqlite.ts`, Node.js only)
|
|
60
|
+
|
|
61
|
+
## SQLite storage (Node.js / Electron)
|
|
62
|
+
|
|
63
|
+
`SqliteRepoStore` packs everything a repo needs into a single SQLite database
|
|
64
|
+
file and is the recommended Node-side storage when the streams transport is in
|
|
65
|
+
use. Compared to `FileSystemStorageAdaptor`, it avoids creating many small
|
|
66
|
+
files for incremental updates, and it lets remote-cursor advances become
|
|
67
|
+
single-row `UPDATE`s instead of rewriting a large JSON blob.
|
|
68
|
+
|
|
69
|
+
A single `SqliteRepoStore` instance exposes two adapters that share one
|
|
70
|
+
database connection:
|
|
71
|
+
|
|
72
|
+
- `store.storage` — a `StorageAdapter` for doc snapshots, doc updates, and
|
|
73
|
+
metadata (Flock) snapshots/updates.
|
|
74
|
+
- `store.cursorStore` — a `RemoteCursorStore` for the streams transport's
|
|
75
|
+
`remoteCursorStore` option.
|
|
76
|
+
|
|
77
|
+
```ts
|
|
78
|
+
import { LoroRepo } from "loro-repo";
|
|
79
|
+
import { SqliteRepoStore } from "loro-repo/storage/sqlite";
|
|
80
|
+
import { StreamsTransportAdapter } from "loro-repo/transport/streams";
|
|
81
|
+
|
|
82
|
+
const store = new SqliteRepoStore({ path: "./data/repo.db" });
|
|
83
|
+
|
|
84
|
+
const repo = await LoroRepo.create({
|
|
85
|
+
storageAdapter: store.storage,
|
|
86
|
+
transportAdapter: new StreamsTransportAdapter({
|
|
87
|
+
bucketId: "your-bucket",
|
|
88
|
+
auth: yourAuthProvider,
|
|
89
|
+
remoteCursorStore: store.cursorStore,
|
|
90
|
+
// Required when `remoteCursorStore` persists across restarts. Both hooks
|
|
91
|
+
// run inside `beforeRemoteCursorSave`, so the local doc / Flock state is
|
|
92
|
+
// durable *before* the cursor advances. Skipping them risks a crash that
|
|
93
|
+
// leaves the cursor pointing past data that was never persisted locally.
|
|
94
|
+
onPersistDoc: async (docId, doc) => {
|
|
95
|
+
await store.storage.save({
|
|
96
|
+
type: "doc-snapshot",
|
|
97
|
+
docId,
|
|
98
|
+
snapshot: doc.export({ mode: "snapshot" }),
|
|
99
|
+
});
|
|
100
|
+
},
|
|
101
|
+
onPersistMeta: async (flock) => {
|
|
102
|
+
await store.storage.save({
|
|
103
|
+
type: "meta-snapshot",
|
|
104
|
+
snapshot: flock.exportFile(),
|
|
105
|
+
});
|
|
106
|
+
},
|
|
107
|
+
}),
|
|
108
|
+
});
|
|
109
|
+
|
|
110
|
+
// Shutdown
|
|
111
|
+
await repo.destroy();
|
|
112
|
+
store.close();
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
> ⚠️ `onPersistDoc` and `onPersistMeta` are not optional when you wire a
|
|
116
|
+
> durable `remoteCursorStore`. The streams transport advances cursors only
|
|
117
|
+
> after `beforeRemoteCursorSave` resolves; if local persistence does not run
|
|
118
|
+
> there, a crash can leave SQLite with stale doc/meta state while the cursor
|
|
119
|
+
> resumes after data that was never applied locally. The `InMemoryRemoteCursorStore`
|
|
120
|
+
> default is the only configuration where omitting the hooks is safe, since
|
|
121
|
+
> the cursor itself is lost on restart.
|
|
122
|
+
|
|
123
|
+
`SqliteRepoStoreOptions`:
|
|
124
|
+
|
|
125
|
+
| Option | Default | Description |
|
|
126
|
+
| --- | --- | --- |
|
|
127
|
+
| `path` | `":memory:"` | SQLite file path. Use `":memory:"` for an ephemeral store. |
|
|
128
|
+
| `database` | — | Pass a pre-constructed `better-sqlite3` `Database` to share a connection; the caller owns its lifetime. |
|
|
129
|
+
| `tablePrefix` | `""` | Optional prefix for all table names, useful when multiple repos share one database. |
|
|
130
|
+
| `wal` | `true` | Enables `journal_mode=WAL` + `synchronous=NORMAL` for fast, durable writes. |
|
|
131
|
+
|
|
132
|
+
The schema (created on first use) is:
|
|
133
|
+
|
|
134
|
+
```
|
|
135
|
+
docs (doc_id PK, snapshot, updated_at, snapshot_digest)
|
|
136
|
+
doc_updates (id, doc_id, update_data, created_at)
|
|
137
|
+
meta_snapshot (id=1, snapshot, updated_at)
|
|
138
|
+
meta_updates (id, update_data, created_at)
|
|
139
|
+
remote_cursors (stream_url PK, next_offset, server_lower_bound_version, updated_at_ms)
|
|
140
|
+
```
|
|
141
|
+
|
|
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.
|
|
145
|
+
|
|
146
|
+
### Backups in WAL mode
|
|
147
|
+
|
|
148
|
+
With the default `wal: true`, SQLite writes to two sidecar files alongside
|
|
149
|
+
the main DB: `<path>-wal` and `<path>-shm`. Recent writes may live only in
|
|
150
|
+
the WAL until a checkpoint runs. If you copy the database file out for
|
|
151
|
+
backup, also copy both sidecars **or** force a checkpoint first — pass a
|
|
152
|
+
pre-constructed `Database` via the `database` option so your code keeps
|
|
153
|
+
access to the connection and can call `pragma("wal_checkpoint(TRUNCATE)")`
|
|
154
|
+
before snapshotting. Otherwise the `.db`-only copy can miss recent writes.
|
|
155
|
+
|
|
156
|
+
### Installation
|
|
157
|
+
|
|
158
|
+
`better-sqlite3` is declared as an **optional** peer dependency. Install it
|
|
159
|
+
explicitly in projects that want SQLite storage, along with `@types/better-sqlite3`
|
|
160
|
+
for TypeScript users (the runtime package ships no `.d.ts` of its own and the
|
|
161
|
+
published `loro-repo/storage/sqlite` types reference it):
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
pnpm add better-sqlite3
|
|
165
|
+
pnpm add -D @types/better-sqlite3
|
|
166
|
+
# or: npm install better-sqlite3 && npm install -D @types/better-sqlite3
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
#### Node version compatibility
|
|
170
|
+
|
|
171
|
+
`loro-repo` itself supports Node ≥ 18. `better-sqlite3` versions matter:
|
|
172
|
+
|
|
173
|
+
| Node version | Use `better-sqlite3` |
|
|
174
|
+
| --- | --- |
|
|
175
|
+
| 18.x | `^11` (v11 is the last line that supports Node 18) |
|
|
176
|
+
| ≥ 20 | `^11` or `^12` |
|
|
177
|
+
|
|
178
|
+
If you're on Node 18, install `better-sqlite3@^11` explicitly — picking up v12
|
|
179
|
+
will fail at runtime with an unsupported-Node error. The `loro-repo`
|
|
180
|
+
implementation only uses APIs present in both lines, so either works.
|
|
181
|
+
|
|
182
|
+
Browsers should keep using `IndexedDBStorageAdaptor` (see the previous
|
|
183
|
+
section). The `loro-repo/storage/sqlite` entry is the only place that imports
|
|
184
|
+
`better-sqlite3`, so importing the main package or any other adapter never
|
|
185
|
+
pulls native bindings into a browser bundle.
|
|
59
186
|
|
|
60
187
|
## Core API surface
|
|
61
188
|
|