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.
Files changed (46) hide show
  1. package/README.md +127 -0
  2. package/dist/index.cjs +862 -42
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +21 -2
  5. package/dist/index.d.ts +21 -2
  6. package/dist/index.js +862 -42
  7. package/dist/index.js.map +1 -1
  8. package/dist/storage/filesystem.cjs +79 -14
  9. package/dist/storage/filesystem.cjs.map +1 -1
  10. package/dist/storage/filesystem.d.cts +15 -1
  11. package/dist/storage/filesystem.d.ts +15 -1
  12. package/dist/storage/filesystem.js +79 -14
  13. package/dist/storage/filesystem.js.map +1 -1
  14. package/dist/storage/indexeddb.cjs +151 -39
  15. package/dist/storage/indexeddb.cjs.map +1 -1
  16. package/dist/storage/indexeddb.d.cts +16 -1
  17. package/dist/storage/indexeddb.d.ts +16 -1
  18. package/dist/storage/indexeddb.js +151 -39
  19. package/dist/storage/indexeddb.js.map +1 -1
  20. package/dist/storage/sqlite.cjs +449 -0
  21. package/dist/storage/sqlite.cjs.map +1 -0
  22. package/dist/storage/sqlite.d.cts +98 -0
  23. package/dist/storage/sqlite.d.ts +98 -0
  24. package/dist/storage/sqlite.js +445 -0
  25. package/dist/storage/sqlite.js.map +1 -0
  26. package/dist/transport/broadcast-channel.cjs +131 -0
  27. package/dist/transport/broadcast-channel.cjs.map +1 -1
  28. package/dist/transport/broadcast-channel.d.cts +8 -1
  29. package/dist/transport/broadcast-channel.d.ts +8 -1
  30. package/dist/transport/broadcast-channel.js +131 -0
  31. package/dist/transport/broadcast-channel.js.map +1 -1
  32. package/dist/transport/streams.cjs +188 -0
  33. package/dist/transport/streams.cjs.map +1 -1
  34. package/dist/transport/streams.d.cts +27 -1
  35. package/dist/transport/streams.d.ts +27 -1
  36. package/dist/transport/streams.js +188 -0
  37. package/dist/transport/streams.js.map +1 -1
  38. package/dist/transport/websocket.cjs +196 -0
  39. package/dist/transport/websocket.cjs.map +1 -1
  40. package/dist/transport/websocket.d.cts +23 -2
  41. package/dist/transport/websocket.d.ts +23 -2
  42. package/dist/transport/websocket.js +196 -0
  43. package/dist/transport/websocket.js.map +1 -1
  44. package/dist/types.d.cts +129 -1
  45. package/dist/types.d.ts +129 -1
  46. 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