loro-repo 0.20.0 → 0.20.3

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 (50) hide show
  1. package/README.md +118 -16
  2. package/dist/flock-persistence-journal.cjs +156 -0
  3. package/dist/flock-persistence-journal.cjs.map +1 -0
  4. package/dist/flock-persistence-journal.js +145 -0
  5. package/dist/flock-persistence-journal.js.map +1 -0
  6. package/dist/flock-snapshot.cjs +3 -3
  7. package/dist/flock-snapshot.cjs.map +1 -1
  8. package/dist/flock-snapshot.js +3 -3
  9. package/dist/flock-snapshot.js.map +1 -1
  10. package/dist/index.cjs +101 -163
  11. package/dist/index.cjs.map +1 -1
  12. package/dist/index.d.cts +10 -2
  13. package/dist/index.d.ts +10 -2
  14. package/dist/index.js +103 -166
  15. package/dist/index.js.map +1 -1
  16. package/dist/storage/filesystem.cjs +2 -2
  17. package/dist/storage/filesystem.cjs.map +1 -1
  18. package/dist/storage/filesystem.d.cts +1 -1
  19. package/dist/storage/filesystem.d.ts +1 -1
  20. package/dist/storage/filesystem.js +2 -2
  21. package/dist/storage/filesystem.js.map +1 -1
  22. package/dist/storage/indexeddb.cjs +383 -70
  23. package/dist/storage/indexeddb.cjs.map +1 -1
  24. package/dist/storage/indexeddb.d.cts +51 -6
  25. package/dist/storage/indexeddb.d.ts +51 -6
  26. package/dist/storage/indexeddb.js +382 -71
  27. package/dist/storage/indexeddb.js.map +1 -1
  28. package/dist/storage/sqlite.cjs +18 -1
  29. package/dist/storage/sqlite.cjs.map +1 -1
  30. package/dist/storage/sqlite.d.cts +3 -2
  31. package/dist/storage/sqlite.d.ts +2 -1
  32. package/dist/storage/sqlite.js +18 -1
  33. package/dist/storage/sqlite.js.map +1 -1
  34. package/dist/transport/broadcast-channel.d.cts +1 -1
  35. package/dist/transport/broadcast-channel.d.ts +1 -1
  36. package/dist/transport/streams.cjs +46 -26
  37. package/dist/transport/streams.cjs.map +1 -1
  38. package/dist/transport/streams.d.cts +33 -5
  39. package/dist/transport/streams.d.ts +32 -4
  40. package/dist/transport/streams.js +47 -27
  41. package/dist/transport/streams.js.map +1 -1
  42. package/dist/transport/websocket.d.cts +1 -1
  43. package/dist/transport/websocket.d.ts +1 -1
  44. package/dist/types.cjs +37 -0
  45. package/dist/types.cjs.map +1 -1
  46. package/dist/types.d.cts +95 -12
  47. package/dist/types.d.ts +95 -12
  48. package/dist/types.js +32 -1
  49. package/dist/types.js.map +1 -1
  50. package/package.json +1 -1
package/README.md CHANGED
@@ -148,6 +148,67 @@ Key points:
148
148
  - `FileSystemStorageAdaptor` (`src/storage/filesystem.ts`)
149
149
  - `SqliteRepoStore` (`src/storage/sqlite.ts`, Node.js only)
150
150
 
151
+ ## Classifying storage failures
152
+
153
+ `IndexedDBStorageAdaptor` wraps backend failures in a `RepoStorageError`
154
+ carrying a stable `code`, so callers do not have to pattern-match browser error
155
+ text (which differs across engines, versions, and UI locales). Misusing the
156
+ adaptor — an unsupported payload type, a call after `close()` — still throws a
157
+ plain `Error`: those are bugs in the caller, not storage failures.
158
+
159
+ ```ts
160
+ import { RepoStorageError } from "loro-repo";
161
+
162
+ try {
163
+ await repo.flush();
164
+ } catch (error) {
165
+ if (error instanceof RepoStorageError) {
166
+ switch (error.code) {
167
+ case "quota":
168
+ // Out of disk / origin quota. Retrying will keep failing until space
169
+ // is freed — tell the user, and stop accepting writes.
170
+ break;
171
+ case "unavailable":
172
+ // The store is not usable right now: connection closing, backing
173
+ // store unreachable, open blocked by another connection, or the
174
+ // context is not allowed to use IndexedDB (sandboxed iframe,
175
+ // opaque origin).
176
+ break;
177
+ case "unknown":
178
+ break;
179
+ }
180
+ }
181
+ }
182
+ ```
183
+
184
+ `error.cause` is the original `DOMException` and `error.causeName` is its
185
+ `name` (`"QuotaExceededError"`, `"InvalidStateError"`, …), which the wrapped
186
+ `message` does not include.
187
+
188
+ Three caveats worth knowing:
189
+
190
+ - **`code` is best-effort for two error names.** `QuotaExceededError` and
191
+ `SecurityError` mean one thing each, so the name alone classifies them.
192
+ `InvalidStateError` and `UnknownError` are overloaded, so the adaptor also
193
+ probes the message — and that text is Chromium's. On other engines those two
194
+ fall back to `"unknown"` rather than being guessed into an actionable bucket.
195
+ - **Background persistence logs, it does not throw.** Debounced auto-saves
196
+ report failures through `console.error` and stay dirty for the next attempt.
197
+ To act on a `code`, `await repo.flush()` (or a load) where the error reaches
198
+ you.
199
+ - **Loading never fails for a write-related reason.** Folding queued updates
200
+ back into a snapshot is an optimization; if that write fails, the document is
201
+ still returned and the updates stay queued for the next load. The compaction
202
+ entry points (`compactMeta`, `compactFlockDoc`) are the opposite: the write
203
+ *is* the request, so they reject.
204
+
205
+ A failed *open* is retried on the next call, so a transient `blocked` (another
206
+ tab still holding the previous version) does not permanently disable the
207
+ adaptor. A *live* connection that has started failing is a different matter: the
208
+ adaptor deliberately does **not** reopen it on its own, because a reopen usually
209
+ fails for the same reason and silent self-healing makes it harder for an
210
+ application to fail closed. That recovery is the caller's decision.
211
+
151
212
  ## Per-room Streams payload protection
152
213
 
153
214
  `StreamsTransportAdapter` can select one streams-crdt provider config for each
@@ -234,13 +295,57 @@ protected-payload boundary and `payloadProtectionRequired` guard. No 0.12.x
234
295
  encryption compatibility shim is retained; the adapter passes the published
235
296
  0.15 opaque `streamUrl` transport target directly.
236
297
 
298
+ ## Replica-bound Streams checkpoints (IndexedDB)
299
+
300
+ For browser Flock rooms, let the repo's IndexedDB storage own checkpoints:
301
+
302
+ ```ts
303
+ import { LoroRepo } from "loro-repo";
304
+ import { IndexedDBStorageAdaptor } from "loro-repo/storage/indexeddb";
305
+ import {
306
+ StreamsTransportAdapter,
307
+ createRepoStreamsPersistence,
308
+ } from "loro-repo/transport/streams";
309
+
310
+ const repo = await LoroRepo.create({
311
+ storageAdapter: new IndexedDBStorageAdaptor({ dbName: "workspace-42" }),
312
+ });
313
+
314
+ await repo.addTransport(
315
+ "streams",
316
+ new StreamsTransportAdapter({
317
+ bucketId: "your-bucket",
318
+ auth: yourAuthProvider,
319
+ persistence: createRepoStreamsPersistence(repo),
320
+ }),
321
+ );
322
+ ```
323
+
324
+ The storage adapter restores each Meta/named Flock snapshot, update log and
325
+ Streams checkpoint from one capture transaction. Existing generations use a
326
+ readonly transaction; a missing generation is created while recapturing the
327
+ resource in one readwrite transaction. A live Flock only sees the cursor
328
+ captured with its own restored bytes, even when another tab writes a newer
329
+ cursor to the same database later. Strict Flock data commits precede the strict
330
+ checkpoint transaction, while LoroDoc body writes retain normal IndexedDB
331
+ durability. Named Flock
332
+ deletion removes its checkpoint record with the data and invalidates outstanding
333
+ cursor stores. Version changes from another tab are handled by reopening the
334
+ database before subsequent checkpoint mutations.
335
+
336
+ LoroDoc persistence keeps its existing storage path. Its cursor is memory-only
337
+ in the example above. Pass `{ documentRemoteCursorStore }` as the factory's
338
+ second argument when an application explicitly wants its existing LoroDoc
339
+ cursor behavior; this does not extend the Flock recovery guarantee to LoroDoc.
340
+
237
341
  ## SQLite storage (Node.js / Electron)
238
342
 
239
- `SqliteRepoStore` packs everything a repo needs into a single SQLite database
240
- file and is the recommended Node-side storage when the streams transport is in
241
- use. Compared to `FileSystemStorageAdaptor`, it avoids creating many small
343
+ `SqliteRepoStore` packs repo data and cursor rows into a single SQLite database
344
+ file. Compared to `FileSystemStorageAdaptor`, it avoids creating many small
242
345
  files for incremental updates, and it lets remote-cursor advances become
243
- single-row `UPDATE`s instead of rewriting a large JSON blob.
346
+ single-row `UPDATE`s instead of rewriting a large JSON blob. It currently
347
+ provides ordered cursor persistence, not the atomic Flock recovery capability
348
+ described above.
244
349
 
245
350
  A single `SqliteRepoStore` instance exposes two adapters that share one
246
351
  database connection:
@@ -269,9 +374,8 @@ await repo.addTransport(
269
374
  new StreamsTransportAdapter({
270
375
  bucketId: "your-bucket",
271
376
  auth: yourAuthProvider,
272
- // Binds the durable cursor store to the repo's durability barriers: the
273
- // cursor only advances after the covered doc / Flock / meta state is
274
- // durably written through `store.storage`.
377
+ // Compatibility path: this guarantees data-before-cursor ordering, but
378
+ // SqliteRepoStore does not atomically restore a Flock and checkpoint.
275
379
  persistence: createRepoStreamsPersistence(repo, store.cursorStore),
276
380
  }),
277
381
  );
@@ -281,15 +385,13 @@ await repo.destroy();
281
385
  store.close();
282
386
  ```
283
387
 
284
- > ⚠️ A durable cursor store must arrive together with its durability
285
- > barriers, which is what the `persistence` bundle enforces: the streams
286
- > transport advances a cursor only after the matching `persist*` barrier
287
- > resolves, so a crash can never leave the cursor pointing past state that
288
- > was never written locally. Configuring a durable store without a barrier
289
- > for a lane (the failure mode the deprecated `remoteCursorStore` +
290
- > `onPersist*` options allowed) is now rejected at that lane's first
291
- > join/sync. Sessions that genuinely keep nothing across restarts should say
292
- > so with `persistence: { mode: "ephemeral" }`.
388
+ The two-argument factory is deprecated for Flock rooms because a separate
389
+ cursor store cannot prove that a newly loaded in-memory replica contains the
390
+ checkpointed state. It retains data-before-cursor ordering for compatibility.
391
+ SQLite, filesystem and custom stores must implement the optional atomic
392
+ replica-loading capability before they can use the no-argument safe factory.
393
+ Sessions that keep nothing across restarts can use `persistence: { mode:
394
+ "ephemeral" }`.
293
395
 
294
396
  `SqliteRepoStoreOptions`:
295
397
 
@@ -0,0 +1,156 @@
1
+ const require_flock_snapshot = require('./flock-snapshot.cjs');
2
+
3
+ //#region src/internal/flock-persistence-journal.ts
4
+ const journalKey = Symbol.for("loro-repo.flock-persistence-journal.v1");
5
+ const MAX_EXACT_PAYLOAD_SAVE_ATTEMPTS = 3;
6
+ function versionsEqual(left, right) {
7
+ const leftPeers = Object.keys(left);
8
+ const rightPeers = Object.keys(right);
9
+ if (leftPeers.length !== rightPeers.length) return false;
10
+ return leftPeers.every((peer) => {
11
+ const a = left[peer];
12
+ const b = right[peer];
13
+ return a?.physicalTime === b?.physicalTime && a?.logicalCounter === b?.logicalCounter;
14
+ });
15
+ }
16
+ /** Pending exact records and received payloads, acknowledged only after save. */
17
+ var FlockPersistenceJournal = class {
18
+ keys = /* @__PURE__ */ new Set();
19
+ payloads = [];
20
+ unsubscribe;
21
+ remoteKeys;
22
+ constructor(flock, onDirty) {
23
+ this.flock = flock;
24
+ this.onDirty = onDirty;
25
+ flock[journalKey] = this;
26
+ this.unsubscribe = flock.subscribe((batch) => {
27
+ const keys = batch.source !== "local" && this.remoteKeys ? this.remoteKeys : this.keys;
28
+ for (const event of batch.events) keys.add(JSON.stringify(event.key));
29
+ if (keys === this.keys && batch.events.length) this.onDirty();
30
+ });
31
+ }
32
+ get hasPending() {
33
+ return this.keys.size > 0 || this.payloads.length > 0;
34
+ }
35
+ async receive(payloads, apply) {
36
+ const copies = payloads.filter((bytes) => bytes.length > 0).map((bytes) => bytes.slice());
37
+ let result;
38
+ const previousKeys = this.remoteKeys;
39
+ const remoteKeys = /* @__PURE__ */ new Set();
40
+ const previousVersion = this.flock.version();
41
+ this.remoteKeys = remoteKeys;
42
+ try {
43
+ result = apply();
44
+ } catch (error) {
45
+ this.retainChangedKeys(remoteKeys);
46
+ throw error;
47
+ } finally {
48
+ this.remoteKeys = previousKeys;
49
+ }
50
+ let outcome;
51
+ try {
52
+ outcome = await result;
53
+ } catch (error) {
54
+ this.retainChangedKeys(remoteKeys);
55
+ throw error;
56
+ }
57
+ if (remoteKeys.size > 0 || !versionsEqual(previousVersion, this.flock.version())) {
58
+ this.payloads.push(...copies.map((bytes) => ({
59
+ bytes,
60
+ failures: 0
61
+ })));
62
+ if (copies.length) this.onDirty();
63
+ }
64
+ return outcome;
65
+ }
66
+ retainChangedKeys(keys) {
67
+ for (const key of keys) this.keys.add(key);
68
+ if (keys.size) this.onDirty();
69
+ }
70
+ /** Called within the owner's serialized persistence queue. */
71
+ async flush(save) {
72
+ this.flock.commit();
73
+ while (this.hasPending) {
74
+ if (this.keys.size) await this.stageChangedKeys();
75
+ const payload = this.payloads[0];
76
+ try {
77
+ await save(payload.bytes);
78
+ } catch (exactError) {
79
+ payload.failures += 1;
80
+ if (payload.failures < MAX_EXACT_PAYLOAD_SAVE_ATTEMPTS) throw exactError;
81
+ const coveredPayloads = this.payloads.length;
82
+ const snapshot = await require_flock_snapshot.exportFlockFileSnapshot(this.flock);
83
+ try {
84
+ await save(snapshot);
85
+ } catch (snapshotError) {
86
+ throw new AggregateError([exactError, snapshotError], "Failed to persist a Flock update and its snapshot fallback");
87
+ }
88
+ this.payloads.splice(0, coveredPayloads);
89
+ continue;
90
+ }
91
+ this.payloads.shift();
92
+ }
93
+ }
94
+ async stageChangedKeys() {
95
+ const capturedKeys = [...this.keys];
96
+ for (const key of capturedKeys) this.keys.delete(key);
97
+ try {
98
+ const bundle = {
99
+ version: 0,
100
+ entries: {}
101
+ };
102
+ let useSnapshot = false;
103
+ for (const key of capturedKeys) {
104
+ let entry;
105
+ try {
106
+ entry = this.flock.getEntry(JSON.parse(key));
107
+ } catch {
108
+ useSnapshot = true;
109
+ break;
110
+ }
111
+ if (!entry) {
112
+ useSnapshot = true;
113
+ break;
114
+ }
115
+ const { physicalTime, logicalCounter, peerId } = entry.clock;
116
+ bundle.entries[key] = {
117
+ c: `${physicalTime},${logicalCounter},${peerId}`,
118
+ ...entry.data === void 0 ? {} : { d: entry.data },
119
+ ...Object.keys(entry.metadata).length ? { m: entry.metadata } : {}
120
+ };
121
+ }
122
+ const bytes = useSnapshot ? await require_flock_snapshot.exportFlockFileSnapshot(this.flock) : require_flock_snapshot.encodeMetaJsonUpdate(bundle);
123
+ this.payloads.push({
124
+ bytes,
125
+ failures: 0
126
+ });
127
+ } catch (error) {
128
+ for (const key of capturedKeys) this.keys.add(key);
129
+ throw error;
130
+ }
131
+ }
132
+ destroy() {
133
+ this.unsubscribe();
134
+ if (this.flock[journalKey] === this) delete this.flock[journalKey];
135
+ }
136
+ };
137
+ /** Preserve plaintext CRDT bytes at the public Streams adapter boundary. */
138
+ async function receiveFlockPayloads(flock, payloads, apply) {
139
+ const journal = flock[journalKey];
140
+ return journal ? journal.receive(payloads, apply) : await apply();
141
+ }
142
+
143
+ //#endregion
144
+ Object.defineProperty(exports, 'FlockPersistenceJournal', {
145
+ enumerable: true,
146
+ get: function () {
147
+ return FlockPersistenceJournal;
148
+ }
149
+ });
150
+ Object.defineProperty(exports, 'receiveFlockPayloads', {
151
+ enumerable: true,
152
+ get: function () {
153
+ return receiveFlockPayloads;
154
+ }
155
+ });
156
+ //# sourceMappingURL=flock-persistence-journal.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"flock-persistence-journal.cjs","names":["flock: Flock","onDirty: () => void","result: T","outcome: Awaited<T>","exportFlockFileSnapshot","bundle: ExportBundle","encodeMetaJsonUpdate"],"sources":["../src/internal/flock-persistence-journal.ts"],"sourcesContent":["import type {\n ExportBundle,\n Flock,\n KeyPart,\n VersionVector,\n} from \"@loro-dev/flock-wasm\";\nimport { encodeMetaJsonUpdate } from \"../storage/meta-snapshot\";\nimport { exportFlockFileSnapshot } from \"./flock-snapshot\";\n\n// The repo and transport are separate package entry points (and may use\n// different ESM/CJS module instances). Attach the journal to the replica,\n// rather than relying on a module-local WeakMap shared by both entry points.\nconst journalKey = Symbol.for(\"loro-repo.flock-persistence-journal.v1\");\ntype JournalledFlock = Flock & { [journalKey]?: FlockPersistenceJournal };\n\ninterface PendingPayload {\n readonly bytes: Uint8Array;\n failures: number;\n}\n\nconst MAX_EXACT_PAYLOAD_SAVE_ATTEMPTS = 3;\n\nfunction versionsEqual(left: VersionVector, right: VersionVector): boolean {\n const leftPeers = Object.keys(left);\n const rightPeers = Object.keys(right);\n if (leftPeers.length !== rightPeers.length) return false;\n return leftPeers.every((peer) => {\n const a = left[peer];\n const b = right[peer];\n return (\n a?.physicalTime === b?.physicalTime &&\n a?.logicalCounter === b?.logicalCounter\n );\n });\n}\n\n/** Pending exact records and received payloads, acknowledged only after save. */\nexport class FlockPersistenceJournal {\n private readonly keys = new Set<string>();\n private readonly payloads: PendingPayload[] = [];\n private readonly unsubscribe: () => void;\n private remoteKeys?: Set<string>;\n\n constructor(\n private readonly flock: Flock,\n private readonly onDirty: () => void,\n ) {\n (flock as JournalledFlock)[journalKey] = this;\n this.unsubscribe = flock.subscribe((batch) => {\n // Local commits can be emitted by beforeImport(), even inside a remote\n // import. They must survive alongside the received payload.\n const keys =\n batch.source !== \"local\" && this.remoteKeys ? this.remoteKeys : this.keys;\n for (const event of batch.events) {\n keys.add(JSON.stringify(event.key));\n }\n if (keys === this.keys && batch.events.length) this.onDirty();\n });\n }\n\n get hasPending(): boolean {\n return this.keys.size > 0 || this.payloads.length > 0;\n }\n\n async receive<T>(\n payloads: readonly Uint8Array[],\n apply: () => T,\n ): Promise<Awaited<T>> {\n const copies = payloads\n .filter((bytes) => bytes.length > 0)\n .map((bytes) => bytes.slice());\n // Existing Flock adapter imports are synchronous. Only suppress their\n // synchronous remote events; unrelated work after an await is observable.\n let result: T;\n const previousKeys = this.remoteKeys;\n const remoteKeys = new Set<string>();\n const previousVersion = this.flock.version();\n this.remoteKeys = remoteKeys;\n try {\n result = apply();\n } catch (error) {\n // A batch import can partially succeed before throwing. Retain its\n // accepted records without persisting a possibly malformed payload.\n this.retainChangedKeys(remoteKeys);\n throw error;\n } finally {\n this.remoteKeys = previousKeys;\n }\n let outcome: Awaited<T>;\n try {\n outcome = await result;\n } catch (error) {\n this.retainChangedKeys(remoteKeys);\n throw error;\n }\n // Streams can echo an append back to its producer, and a bootstrap can\n // repeat state already hydrated locally. Flock emits no remote events in\n // either case, so there is no newly accepted state to journal. A genuine\n // same-VV hole does emit the missing key and still records the exact\n // received bytes.\n if (\n remoteKeys.size > 0 ||\n !versionsEqual(previousVersion, this.flock.version())\n ) {\n this.payloads.push(...copies.map((bytes) => ({ bytes, failures: 0 })));\n if (copies.length) this.onDirty();\n }\n return outcome;\n }\n\n private retainChangedKeys(keys: ReadonlySet<string>): void {\n for (const key of keys) this.keys.add(key);\n if (keys.size) this.onDirty();\n }\n\n /** Called within the owner's serialized persistence queue. */\n async flush(save: (update: Uint8Array) => Promise<void>): Promise<void> {\n this.flock.commit();\n while (this.hasPending) {\n if (this.keys.size) {\n await this.stageChangedKeys();\n }\n\n const payload = this.payloads[0]!;\n try {\n await save(payload.bytes);\n } catch (exactError) {\n payload.failures += 1;\n // One failing barrier must still block its remote cursor. Repeated\n // barriers retry the exact bytes up to a bounded count before using\n // the mergeable full-state fallback below.\n if (payload.failures < MAX_EXACT_PAYLOAD_SAVE_ATTEMPTS) {\n throw exactError;\n }\n // A storage adapter can reject one otherwise accepted encoding\n // forever. A full file is another mergeable representation of the\n // current CRDT state, so it can safely cover that queue item. Never\n // advance past the item unless this fallback itself is durable.\n // The exported file covers every payload that was queued when the\n // export began, not just the failing head. Payloads received while\n // the incremental export or save awaits are appended after this\n // boundary and must remain pending.\n const coveredPayloads = this.payloads.length;\n const snapshot = await exportFlockFileSnapshot(this.flock);\n try {\n await save(snapshot);\n } catch (snapshotError) {\n throw new AggregateError(\n [exactError, snapshotError],\n \"Failed to persist a Flock update and its snapshot fallback\",\n );\n }\n this.payloads.splice(0, coveredPayloads);\n continue;\n }\n\n // New imports/local changes during the awaits remain behind this item.\n this.payloads.shift();\n }\n }\n\n private async stageChangedKeys(): Promise<void> {\n const capturedKeys = [...this.keys];\n for (const key of capturedKeys) this.keys.delete(key);\n try {\n const bundle: ExportBundle = { version: 0, entries: {} };\n let useSnapshot = false;\n for (const key of capturedKeys) {\n let entry;\n try {\n entry = this.flock.getEntry(JSON.parse(key) as KeyPart[]);\n } catch {\n useSnapshot = true;\n break;\n }\n if (!entry) {\n useSnapshot = true;\n break;\n }\n const { physicalTime, logicalCounter, peerId } = entry.clock;\n bundle.entries[key] = {\n c: `${physicalTime},${logicalCounter},${peerId}`,\n ...(entry.data === undefined ? {} : { d: entry.data }),\n ...(Object.keys(entry.metadata).length ? { m: entry.metadata } : {}),\n };\n }\n const bytes = useSnapshot\n ? await exportFlockFileSnapshot(this.flock)\n : encodeMetaJsonUpdate(bundle);\n this.payloads.push({ bytes, failures: 0 });\n } catch (error) {\n // The current state has not been represented in the payload queue.\n // Restore the captured markers without disturbing newer events.\n for (const key of capturedKeys) this.keys.add(key);\n throw error;\n }\n }\n\n destroy(): void {\n this.unsubscribe();\n if ((this.flock as JournalledFlock)[journalKey] === this) {\n delete (this.flock as JournalledFlock)[journalKey];\n }\n }\n}\n\n/** Preserve plaintext CRDT bytes at the public Streams adapter boundary. */\nexport async function receiveFlockPayloads<T>(\n flock: Flock,\n payloads: readonly Uint8Array[],\n apply: () => T,\n): Promise<Awaited<T>> {\n const journal = (flock as JournalledFlock)[journalKey];\n return journal ? journal.receive(payloads, apply) : await apply();\n}\n"],"mappings":"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"}
@@ -0,0 +1,145 @@
1
+ import { r as encodeMetaJsonUpdate, t as exportFlockFileSnapshot } from "./flock-snapshot.js";
2
+
3
+ //#region src/internal/flock-persistence-journal.ts
4
+ const journalKey = Symbol.for("loro-repo.flock-persistence-journal.v1");
5
+ const MAX_EXACT_PAYLOAD_SAVE_ATTEMPTS = 3;
6
+ function versionsEqual(left, right) {
7
+ const leftPeers = Object.keys(left);
8
+ const rightPeers = Object.keys(right);
9
+ if (leftPeers.length !== rightPeers.length) return false;
10
+ return leftPeers.every((peer) => {
11
+ const a = left[peer];
12
+ const b = right[peer];
13
+ return a?.physicalTime === b?.physicalTime && a?.logicalCounter === b?.logicalCounter;
14
+ });
15
+ }
16
+ /** Pending exact records and received payloads, acknowledged only after save. */
17
+ var FlockPersistenceJournal = class {
18
+ keys = /* @__PURE__ */ new Set();
19
+ payloads = [];
20
+ unsubscribe;
21
+ remoteKeys;
22
+ constructor(flock, onDirty) {
23
+ this.flock = flock;
24
+ this.onDirty = onDirty;
25
+ flock[journalKey] = this;
26
+ this.unsubscribe = flock.subscribe((batch) => {
27
+ const keys = batch.source !== "local" && this.remoteKeys ? this.remoteKeys : this.keys;
28
+ for (const event of batch.events) keys.add(JSON.stringify(event.key));
29
+ if (keys === this.keys && batch.events.length) this.onDirty();
30
+ });
31
+ }
32
+ get hasPending() {
33
+ return this.keys.size > 0 || this.payloads.length > 0;
34
+ }
35
+ async receive(payloads, apply) {
36
+ const copies = payloads.filter((bytes) => bytes.length > 0).map((bytes) => bytes.slice());
37
+ let result;
38
+ const previousKeys = this.remoteKeys;
39
+ const remoteKeys = /* @__PURE__ */ new Set();
40
+ const previousVersion = this.flock.version();
41
+ this.remoteKeys = remoteKeys;
42
+ try {
43
+ result = apply();
44
+ } catch (error) {
45
+ this.retainChangedKeys(remoteKeys);
46
+ throw error;
47
+ } finally {
48
+ this.remoteKeys = previousKeys;
49
+ }
50
+ let outcome;
51
+ try {
52
+ outcome = await result;
53
+ } catch (error) {
54
+ this.retainChangedKeys(remoteKeys);
55
+ throw error;
56
+ }
57
+ if (remoteKeys.size > 0 || !versionsEqual(previousVersion, this.flock.version())) {
58
+ this.payloads.push(...copies.map((bytes) => ({
59
+ bytes,
60
+ failures: 0
61
+ })));
62
+ if (copies.length) this.onDirty();
63
+ }
64
+ return outcome;
65
+ }
66
+ retainChangedKeys(keys) {
67
+ for (const key of keys) this.keys.add(key);
68
+ if (keys.size) this.onDirty();
69
+ }
70
+ /** Called within the owner's serialized persistence queue. */
71
+ async flush(save) {
72
+ this.flock.commit();
73
+ while (this.hasPending) {
74
+ if (this.keys.size) await this.stageChangedKeys();
75
+ const payload = this.payloads[0];
76
+ try {
77
+ await save(payload.bytes);
78
+ } catch (exactError) {
79
+ payload.failures += 1;
80
+ if (payload.failures < MAX_EXACT_PAYLOAD_SAVE_ATTEMPTS) throw exactError;
81
+ const coveredPayloads = this.payloads.length;
82
+ const snapshot = await exportFlockFileSnapshot(this.flock);
83
+ try {
84
+ await save(snapshot);
85
+ } catch (snapshotError) {
86
+ throw new AggregateError([exactError, snapshotError], "Failed to persist a Flock update and its snapshot fallback");
87
+ }
88
+ this.payloads.splice(0, coveredPayloads);
89
+ continue;
90
+ }
91
+ this.payloads.shift();
92
+ }
93
+ }
94
+ async stageChangedKeys() {
95
+ const capturedKeys = [...this.keys];
96
+ for (const key of capturedKeys) this.keys.delete(key);
97
+ try {
98
+ const bundle = {
99
+ version: 0,
100
+ entries: {}
101
+ };
102
+ let useSnapshot = false;
103
+ for (const key of capturedKeys) {
104
+ let entry;
105
+ try {
106
+ entry = this.flock.getEntry(JSON.parse(key));
107
+ } catch {
108
+ useSnapshot = true;
109
+ break;
110
+ }
111
+ if (!entry) {
112
+ useSnapshot = true;
113
+ break;
114
+ }
115
+ const { physicalTime, logicalCounter, peerId } = entry.clock;
116
+ bundle.entries[key] = {
117
+ c: `${physicalTime},${logicalCounter},${peerId}`,
118
+ ...entry.data === void 0 ? {} : { d: entry.data },
119
+ ...Object.keys(entry.metadata).length ? { m: entry.metadata } : {}
120
+ };
121
+ }
122
+ const bytes = useSnapshot ? await exportFlockFileSnapshot(this.flock) : encodeMetaJsonUpdate(bundle);
123
+ this.payloads.push({
124
+ bytes,
125
+ failures: 0
126
+ });
127
+ } catch (error) {
128
+ for (const key of capturedKeys) this.keys.add(key);
129
+ throw error;
130
+ }
131
+ }
132
+ destroy() {
133
+ this.unsubscribe();
134
+ if (this.flock[journalKey] === this) delete this.flock[journalKey];
135
+ }
136
+ };
137
+ /** Preserve plaintext CRDT bytes at the public Streams adapter boundary. */
138
+ async function receiveFlockPayloads(flock, payloads, apply) {
139
+ const journal = flock[journalKey];
140
+ return journal ? journal.receive(payloads, apply) : await apply();
141
+ }
142
+
143
+ //#endregion
144
+ export { receiveFlockPayloads as n, FlockPersistenceJournal as t };
145
+ //# sourceMappingURL=flock-persistence-journal.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"flock-persistence-journal.js","names":["flock: Flock","onDirty: () => void","result: T","outcome: Awaited<T>","bundle: ExportBundle"],"sources":["../src/internal/flock-persistence-journal.ts"],"sourcesContent":["import type {\n ExportBundle,\n Flock,\n KeyPart,\n VersionVector,\n} from \"@loro-dev/flock-wasm\";\nimport { encodeMetaJsonUpdate } from \"../storage/meta-snapshot\";\nimport { exportFlockFileSnapshot } from \"./flock-snapshot\";\n\n// The repo and transport are separate package entry points (and may use\n// different ESM/CJS module instances). Attach the journal to the replica,\n// rather than relying on a module-local WeakMap shared by both entry points.\nconst journalKey = Symbol.for(\"loro-repo.flock-persistence-journal.v1\");\ntype JournalledFlock = Flock & { [journalKey]?: FlockPersistenceJournal };\n\ninterface PendingPayload {\n readonly bytes: Uint8Array;\n failures: number;\n}\n\nconst MAX_EXACT_PAYLOAD_SAVE_ATTEMPTS = 3;\n\nfunction versionsEqual(left: VersionVector, right: VersionVector): boolean {\n const leftPeers = Object.keys(left);\n const rightPeers = Object.keys(right);\n if (leftPeers.length !== rightPeers.length) return false;\n return leftPeers.every((peer) => {\n const a = left[peer];\n const b = right[peer];\n return (\n a?.physicalTime === b?.physicalTime &&\n a?.logicalCounter === b?.logicalCounter\n );\n });\n}\n\n/** Pending exact records and received payloads, acknowledged only after save. */\nexport class FlockPersistenceJournal {\n private readonly keys = new Set<string>();\n private readonly payloads: PendingPayload[] = [];\n private readonly unsubscribe: () => void;\n private remoteKeys?: Set<string>;\n\n constructor(\n private readonly flock: Flock,\n private readonly onDirty: () => void,\n ) {\n (flock as JournalledFlock)[journalKey] = this;\n this.unsubscribe = flock.subscribe((batch) => {\n // Local commits can be emitted by beforeImport(), even inside a remote\n // import. They must survive alongside the received payload.\n const keys =\n batch.source !== \"local\" && this.remoteKeys ? this.remoteKeys : this.keys;\n for (const event of batch.events) {\n keys.add(JSON.stringify(event.key));\n }\n if (keys === this.keys && batch.events.length) this.onDirty();\n });\n }\n\n get hasPending(): boolean {\n return this.keys.size > 0 || this.payloads.length > 0;\n }\n\n async receive<T>(\n payloads: readonly Uint8Array[],\n apply: () => T,\n ): Promise<Awaited<T>> {\n const copies = payloads\n .filter((bytes) => bytes.length > 0)\n .map((bytes) => bytes.slice());\n // Existing Flock adapter imports are synchronous. Only suppress their\n // synchronous remote events; unrelated work after an await is observable.\n let result: T;\n const previousKeys = this.remoteKeys;\n const remoteKeys = new Set<string>();\n const previousVersion = this.flock.version();\n this.remoteKeys = remoteKeys;\n try {\n result = apply();\n } catch (error) {\n // A batch import can partially succeed before throwing. Retain its\n // accepted records without persisting a possibly malformed payload.\n this.retainChangedKeys(remoteKeys);\n throw error;\n } finally {\n this.remoteKeys = previousKeys;\n }\n let outcome: Awaited<T>;\n try {\n outcome = await result;\n } catch (error) {\n this.retainChangedKeys(remoteKeys);\n throw error;\n }\n // Streams can echo an append back to its producer, and a bootstrap can\n // repeat state already hydrated locally. Flock emits no remote events in\n // either case, so there is no newly accepted state to journal. A genuine\n // same-VV hole does emit the missing key and still records the exact\n // received bytes.\n if (\n remoteKeys.size > 0 ||\n !versionsEqual(previousVersion, this.flock.version())\n ) {\n this.payloads.push(...copies.map((bytes) => ({ bytes, failures: 0 })));\n if (copies.length) this.onDirty();\n }\n return outcome;\n }\n\n private retainChangedKeys(keys: ReadonlySet<string>): void {\n for (const key of keys) this.keys.add(key);\n if (keys.size) this.onDirty();\n }\n\n /** Called within the owner's serialized persistence queue. */\n async flush(save: (update: Uint8Array) => Promise<void>): Promise<void> {\n this.flock.commit();\n while (this.hasPending) {\n if (this.keys.size) {\n await this.stageChangedKeys();\n }\n\n const payload = this.payloads[0]!;\n try {\n await save(payload.bytes);\n } catch (exactError) {\n payload.failures += 1;\n // One failing barrier must still block its remote cursor. Repeated\n // barriers retry the exact bytes up to a bounded count before using\n // the mergeable full-state fallback below.\n if (payload.failures < MAX_EXACT_PAYLOAD_SAVE_ATTEMPTS) {\n throw exactError;\n }\n // A storage adapter can reject one otherwise accepted encoding\n // forever. A full file is another mergeable representation of the\n // current CRDT state, so it can safely cover that queue item. Never\n // advance past the item unless this fallback itself is durable.\n // The exported file covers every payload that was queued when the\n // export began, not just the failing head. Payloads received while\n // the incremental export or save awaits are appended after this\n // boundary and must remain pending.\n const coveredPayloads = this.payloads.length;\n const snapshot = await exportFlockFileSnapshot(this.flock);\n try {\n await save(snapshot);\n } catch (snapshotError) {\n throw new AggregateError(\n [exactError, snapshotError],\n \"Failed to persist a Flock update and its snapshot fallback\",\n );\n }\n this.payloads.splice(0, coveredPayloads);\n continue;\n }\n\n // New imports/local changes during the awaits remain behind this item.\n this.payloads.shift();\n }\n }\n\n private async stageChangedKeys(): Promise<void> {\n const capturedKeys = [...this.keys];\n for (const key of capturedKeys) this.keys.delete(key);\n try {\n const bundle: ExportBundle = { version: 0, entries: {} };\n let useSnapshot = false;\n for (const key of capturedKeys) {\n let entry;\n try {\n entry = this.flock.getEntry(JSON.parse(key) as KeyPart[]);\n } catch {\n useSnapshot = true;\n break;\n }\n if (!entry) {\n useSnapshot = true;\n break;\n }\n const { physicalTime, logicalCounter, peerId } = entry.clock;\n bundle.entries[key] = {\n c: `${physicalTime},${logicalCounter},${peerId}`,\n ...(entry.data === undefined ? {} : { d: entry.data }),\n ...(Object.keys(entry.metadata).length ? { m: entry.metadata } : {}),\n };\n }\n const bytes = useSnapshot\n ? await exportFlockFileSnapshot(this.flock)\n : encodeMetaJsonUpdate(bundle);\n this.payloads.push({ bytes, failures: 0 });\n } catch (error) {\n // The current state has not been represented in the payload queue.\n // Restore the captured markers without disturbing newer events.\n for (const key of capturedKeys) this.keys.add(key);\n throw error;\n }\n }\n\n destroy(): void {\n this.unsubscribe();\n if ((this.flock as JournalledFlock)[journalKey] === this) {\n delete (this.flock as JournalledFlock)[journalKey];\n }\n }\n}\n\n/** Preserve plaintext CRDT bytes at the public Streams adapter boundary. */\nexport async function receiveFlockPayloads<T>(\n flock: Flock,\n payloads: readonly Uint8Array[],\n apply: () => T,\n): Promise<Awaited<T>> {\n const journal = (flock as JournalledFlock)[journalKey];\n return journal ? journal.receive(payloads, apply) : await apply();\n}\n"],"mappings":"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"}
@@ -116,7 +116,7 @@ function hydrateMetaSnapshots(legacy, updates) {
116
116
  if (merged.format === "json") loadedJsonUpdate = true;
117
117
  } else {
118
118
  baseUpdateIndex = updates.findIndex((bytes) => isFlockFile(bytes));
119
- if (baseUpdateIndex >= 0) flock = __loro_dev_flock_wasm.Flock.fromFile(updates[baseUpdateIndex]);
119
+ if (baseUpdateIndex >= 0) flock = __loro_dev_flock_wasm.Flock.recoverFromFile(updates[baseUpdateIndex]).flock;
120
120
  }
121
121
  for (let index = 0; index < updates.length; index += 1) {
122
122
  if (index === baseUpdateIndex) continue;
@@ -132,14 +132,14 @@ function hydrateMetaSnapshots(legacy, updates) {
132
132
  function mergeMetaSnapshot(flock, bytes) {
133
133
  if (isFlockFile(bytes)) {
134
134
  if (flock) {
135
- flock.importFile(bytes);
135
+ flock.recoverImportFile(bytes);
136
136
  return {
137
137
  flock,
138
138
  format: "file"
139
139
  };
140
140
  }
141
141
  return {
142
- flock: __loro_dev_flock_wasm.Flock.fromFile(bytes),
142
+ flock: __loro_dev_flock_wasm.Flock.recoverFromFile(bytes).flock,
143
143
  format: "file"
144
144
  };
145
145
  }
@@ -1 +1 @@
1
- {"version":3,"file":"flock-snapshot.cjs","names":["CURRENT_SNAPSHOT_FORMAT: PersistedFormatId","flock: Flock | undefined","Flock"],"sources":["../src/storage/format.ts","../src/storage/meta-snapshot.ts","../src/internal/flock-snapshot.ts"],"sourcesContent":["/**\n * Persisted-format identification, in one place.\n *\n * ## Why this module exists\n *\n * Every persisted format this package reads is identified by sniffing:\n * magic bytes for Flock files, \"does it parse as JSON\" for update bundles,\n * a literal file name for the Filesystem adapter's full snapshot, a key\n * prefix for IndexedDB's queue layout. There has never been an explicit\n * version stamp, and each storage adapter grew its own copy of the\n * \"is this layout current?\" decision. Those copies are not equivalent —\n * one checks a legacy queue key, another compares a file name, a third\n * skips Flock-doc JSON entirely — which is exactly where a future format\n * change would silently diverge.\n *\n * Detection stays sniff-based, because that is what already-written data\n * supports: bytes on disk today carry no version field, and inventing one\n * cannot retroactively apply to them. What this module adds is a single\n * definition of each format, one shared \"needs rewriting\" predicate, and an\n * explicit version constant that new writers can stamp going forward.\n *\n * ## Format registry\n *\n * | id | encoding | written today |\n * |---------------|---------------------------------|---------------|\n * | `flock-v1` | Flock file, `FLOK` magic | no (read-only)|\n * | `flock-v2` | Flock file, `FLK2` magic | yes |\n * | `json-bundle` | UTF-8 JSON `ExportBundle` | yes (updates) |\n *\n * `flock-v1` is retained deliberately: it is the on-disk shape of data\n * written by older versions, and dropping the reader would make that data\n * unreadable rather than merely stale.\n */\n\nconst FLOCK_FILE_MAGIC_LENGTH = 4;\nconst FLOCK_FILE_MAGIC_V1 = [0x46, 0x4c, 0x4f, 0x4b]; // \"FLOK\"\nconst FLOCK_FILE_MAGIC_V2 = [0x46, 0x4c, 0x4b, 0x32]; // \"FLK2\"\n\n/**\n * Formats this package can read.\n *\n * `\"unknown\"` is reported rather than guessed: a caller that cannot\n * identify bytes should surface that, not assume the newest shape.\n */\nexport type PersistedFormatId =\n | \"flock-v1\"\n | \"flock-v2\"\n | \"json-bundle\"\n | \"unknown\";\n\n/**\n * Format new full snapshots are written in.\n *\n * Bump this together with a reader for the previous value, never instead of\n * one — the compatibility window is the whole point.\n */\nexport const CURRENT_SNAPSHOT_FORMAT: PersistedFormatId = \"flock-v2\";\n\n/**\n * Formats whose readers must keep working for already-persisted data.\n *\n * Listed explicitly so removing one is a visible decision rather than a\n * side effect of tidying a branch that \"looks dead\".\n */\nexport const SUPPORTED_READ_FORMATS: ReadonlyArray<PersistedFormatId> = [\n \"flock-v1\",\n \"flock-v2\",\n \"json-bundle\",\n];\n\nfunction matchesMagic(bytes: Uint8Array, magic: readonly number[]): boolean {\n for (let i = 0; i < magic.length; i += 1) {\n if (bytes[i] !== magic[i]) return false;\n }\n return true;\n}\n\n/**\n * Identifies persisted bytes.\n *\n * Anything without a recognized Flock magic is treated as a JSON bundle,\n * matching how the hydration path has always behaved; `\"unknown\"` is\n * reserved for input too short to classify at all.\n */\nexport function detectPersistedFormat(bytes: Uint8Array): PersistedFormatId {\n // Too short to carry a magic header, and too short to be any bundle this\n // package writes — say so rather than defaulting it into a format whose\n // reader would then fail on it.\n if (bytes.length < FLOCK_FILE_MAGIC_LENGTH) return \"unknown\";\n if (matchesMagic(bytes, FLOCK_FILE_MAGIC_V2)) return \"flock-v2\";\n if (matchesMagic(bytes, FLOCK_FILE_MAGIC_V1)) return \"flock-v1\";\n return \"json-bundle\";\n}\n\n/** Whether `bytes` is a Flock file snapshot in any supported version. */\nexport function isFlockFile(bytes: Uint8Array): boolean {\n const format = detectPersistedFormat(bytes);\n return format === \"flock-v1\" || format === \"flock-v2\";\n}\n\n/** Whether `bytes` is written in the format new snapshots use. */\nexport function isCurrentSnapshotFormat(bytes: Uint8Array): boolean {\n return detectPersistedFormat(bytes) === CURRENT_SNAPSHOT_FORMAT;\n}\n\n/**\n * Inputs to the shared \"should this metadata layout be rewritten?\" decision.\n *\n * Each storage adapter supplies what it can observe; the policy itself lives\n * here so the three adapters cannot drift apart on it.\n */\nexport interface MetaLayoutState {\n /** The base snapshot as loaded, if any. */\n readonly snapshot?: Uint8Array;\n /** Number of queued update records sitting alongside the snapshot. */\n readonly queuedUpdates: number;\n /** True when hydration had to parse a JSON bundle as a full snapshot. */\n readonly loadedJsonUpdate: boolean;\n /**\n * True when the adapter found data in a layout it no longer writes —\n * IndexedDB's single `\"queue\"` key, the Filesystem adapter's `meta.json`.\n */\n readonly legacyLayout?: boolean;\n}\n\n/**\n * Whether the persisted metadata layout should be rewritten into the current\n * one on load.\n *\n * Rewriting is what stops old formats from lingering and being re-parsed on\n * every start. Missing a case does not corrupt anything, but it does mean\n * paying the legacy parse cost forever — which is why the decision is one\n * shared function rather than three lookalikes.\n */\nexport function metaLayoutNeedsRewrite(state: MetaLayoutState): boolean {\n if (state.legacyLayout) return true;\n if (state.loadedJsonUpdate) return true;\n if (state.queuedUpdates > 0) return true;\n if (state.snapshot !== undefined && !isCurrentSnapshotFormat(state.snapshot)) {\n return true;\n }\n return false;\n}\n","import { Flock, type ExportBundle } from \"@loro-dev/flock-wasm\";\n\nimport { isFlockFile } from \"./format\";\n\nexport { isFlockFile };\n\nconst textEncoder = new TextEncoder();\nconst textDecoder = new TextDecoder();\n\ntype SnapshotFormat = \"file\" | \"json\";\n\ninterface MergeResult {\n flock: Flock;\n format: SnapshotFormat;\n}\n\nexport interface HydrateMetaSnapshotResult {\n flock: Flock | undefined;\n loadedJsonUpdate: boolean;\n}\n\nexport function encodeMetaJsonUpdate(bundle: ExportBundle): Uint8Array {\n return textEncoder.encode(JSON.stringify(bundle));\n}\n\nexport function hydrateMetaSnapshots(\n legacy: Uint8Array | undefined,\n updates: readonly Uint8Array[],\n): HydrateMetaSnapshotResult {\n let loadedJsonUpdate = false;\n let baseUpdateIndex = -1;\n let flock: Flock | undefined;\n\n if (legacy) {\n const merged = mergeMetaSnapshot(flock, legacy);\n flock = merged.flock;\n if (merged.format === \"json\") {\n loadedJsonUpdate = true;\n }\n } else {\n baseUpdateIndex = updates.findIndex((bytes) => isFlockFile(bytes));\n if (baseUpdateIndex >= 0) {\n flock = Flock.fromFile(updates[baseUpdateIndex] as Uint8Array);\n }\n }\n\n for (let index = 0; index < updates.length; index += 1) {\n if (index === baseUpdateIndex) continue;\n const merged = mergeMetaSnapshot(flock, updates[index] as Uint8Array);\n flock = merged.flock;\n if (merged.format === \"json\") {\n loadedJsonUpdate = true;\n }\n }\n\n return { flock, loadedJsonUpdate };\n}\n\nfunction mergeMetaSnapshot(\n flock: Flock | undefined,\n bytes: Uint8Array,\n): MergeResult {\n if (isFlockFile(bytes)) {\n if (flock) {\n flock.importFile(bytes);\n return { flock, format: \"file\" };\n }\n return { flock: Flock.fromFile(bytes), format: \"file\" };\n }\n\n const bundle = JSON.parse(textDecoder.decode(bytes)) as ExportBundle;\n if (flock) {\n flock.importJson(bundle);\n return { flock, format: \"json\" };\n }\n const hydrated = new Flock();\n hydrated.importJson(bundle);\n return { flock: hydrated, format: \"json\" };\n}\n","import type { Flock } from \"@loro-dev/flock-wasm\";\n\nexport const DEFAULT_FLOCK_FILE_EXPORT_BUDGET_MS = 8;\n\nexport interface ExportFlockFileSnapshotOptions {\n readonly budgetMs?: number;\n readonly signal?: AbortSignal;\n}\n\ntype FlockWithIncrementalFileExport = Flock & {\n exportFileV2Incremental?: (\n options?: ExportFlockFileSnapshotOptions,\n ) => Promise<Uint8Array>;\n};\n\ntype FlockWithIsEmpty = Flock & {\n isEmpty?: () => boolean;\n};\n\nexport async function exportFlockFileSnapshot(\n flock: Flock,\n options: ExportFlockFileSnapshotOptions = {},\n): Promise<Uint8Array> {\n const exportIncremental = (flock as FlockWithIncrementalFileExport)\n .exportFileV2Incremental;\n if (typeof exportIncremental === \"function\") {\n return exportIncremental.call(flock, {\n budgetMs: options.budgetMs ?? DEFAULT_FLOCK_FILE_EXPORT_BUDGET_MS,\n signal: options.signal,\n });\n }\n return flock.exportFile();\n}\n\nexport function hasVisibleRows(flock: Flock): boolean {\n const isEmpty = (flock as FlockWithIsEmpty).isEmpty;\n if (typeof isEmpty === \"function\") {\n return !isEmpty.call(flock);\n }\n\n const rows = flock.scan({});\n for (const row of rows) {\n if (row.value !== undefined) return true;\n }\n return false;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,MAAM,0BAA0B;AAChC,MAAM,sBAAsB;CAAC;CAAM;CAAM;CAAM;CAAK;AACpD,MAAM,sBAAsB;CAAC;CAAM;CAAM;CAAM;CAAK;;;;;;;AAoBpD,MAAaA,0BAA6C;AAc1D,SAAS,aAAa,OAAmB,OAAmC;AAC1E,MAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK,EACrC,KAAI,MAAM,OAAO,MAAM,GAAI,QAAO;AAEpC,QAAO;;;;;;;;;AAUT,SAAgB,sBAAsB,OAAsC;AAI1E,KAAI,MAAM,SAAS,wBAAyB,QAAO;AACnD,KAAI,aAAa,OAAO,oBAAoB,CAAE,QAAO;AACrD,KAAI,aAAa,OAAO,oBAAoB,CAAE,QAAO;AACrD,QAAO;;;AAIT,SAAgB,YAAY,OAA4B;CACtD,MAAM,SAAS,sBAAsB,MAAM;AAC3C,QAAO,WAAW,cAAc,WAAW;;;AAI7C,SAAgB,wBAAwB,OAA4B;AAClE,QAAO,sBAAsB,MAAM,KAAK;;;;;;;;;;;AAgC1C,SAAgB,uBAAuB,OAAiC;AACtE,KAAI,MAAM,aAAc,QAAO;AAC/B,KAAI,MAAM,iBAAkB,QAAO;AACnC,KAAI,MAAM,gBAAgB,EAAG,QAAO;AACpC,KAAI,MAAM,aAAa,UAAa,CAAC,wBAAwB,MAAM,SAAS,CAC1E,QAAO;AAET,QAAO;;;;;ACvIT,MAAM,cAAc,IAAI,aAAa;AACrC,MAAM,cAAc,IAAI,aAAa;AAcrC,SAAgB,qBAAqB,QAAkC;AACrE,QAAO,YAAY,OAAO,KAAK,UAAU,OAAO,CAAC;;AAGnD,SAAgB,qBACd,QACA,SAC2B;CAC3B,IAAI,mBAAmB;CACvB,IAAI,kBAAkB;CACtB,IAAIC;AAEJ,KAAI,QAAQ;EACV,MAAM,SAAS,kBAAkB,OAAO,OAAO;AAC/C,UAAQ,OAAO;AACf,MAAI,OAAO,WAAW,OACpB,oBAAmB;QAEhB;AACL,oBAAkB,QAAQ,WAAW,UAAU,YAAY,MAAM,CAAC;AAClE,MAAI,mBAAmB,EACrB,SAAQC,4BAAM,SAAS,QAAQ,iBAA+B;;AAIlE,MAAK,IAAI,QAAQ,GAAG,QAAQ,QAAQ,QAAQ,SAAS,GAAG;AACtD,MAAI,UAAU,gBAAiB;EAC/B,MAAM,SAAS,kBAAkB,OAAO,QAAQ,OAAqB;AACrE,UAAQ,OAAO;AACf,MAAI,OAAO,WAAW,OACpB,oBAAmB;;AAIvB,QAAO;EAAE;EAAO;EAAkB;;AAGpC,SAAS,kBACP,OACA,OACa;AACb,KAAI,YAAY,MAAM,EAAE;AACtB,MAAI,OAAO;AACT,SAAM,WAAW,MAAM;AACvB,UAAO;IAAE;IAAO,QAAQ;IAAQ;;AAElC,SAAO;GAAE,OAAOA,4BAAM,SAAS,MAAM;GAAE,QAAQ;GAAQ;;CAGzD,MAAM,SAAS,KAAK,MAAM,YAAY,OAAO,MAAM,CAAC;AACpD,KAAI,OAAO;AACT,QAAM,WAAW,OAAO;AACxB,SAAO;GAAE;GAAO,QAAQ;GAAQ;;CAElC,MAAM,WAAW,IAAIA,6BAAO;AAC5B,UAAS,WAAW,OAAO;AAC3B,QAAO;EAAE,OAAO;EAAU,QAAQ;EAAQ;;;;;AC3E5C,MAAa,sCAAsC;AAiBnD,eAAsB,wBACpB,OACA,UAA0C,EAAE,EACvB;CACrB,MAAM,oBAAqB,MACxB;AACH,KAAI,OAAO,sBAAsB,WAC/B,QAAO,kBAAkB,KAAK,OAAO;EACnC,UAAU,QAAQ,YAAY;EAC9B,QAAQ,QAAQ;EACjB,CAAC;AAEJ,QAAO,MAAM,YAAY;;AAG3B,SAAgB,eAAe,OAAuB;CACpD,MAAM,UAAW,MAA2B;AAC5C,KAAI,OAAO,YAAY,WACrB,QAAO,CAAC,QAAQ,KAAK,MAAM;CAG7B,MAAM,OAAO,MAAM,KAAK,EAAE,CAAC;AAC3B,MAAK,MAAM,OAAO,KAChB,KAAI,IAAI,UAAU,OAAW,QAAO;AAEtC,QAAO"}
1
+ {"version":3,"file":"flock-snapshot.cjs","names":["CURRENT_SNAPSHOT_FORMAT: PersistedFormatId","flock: Flock | undefined","Flock"],"sources":["../src/storage/format.ts","../src/storage/meta-snapshot.ts","../src/internal/flock-snapshot.ts"],"sourcesContent":["/**\n * Persisted-format identification, in one place.\n *\n * ## Why this module exists\n *\n * Every persisted format this package reads is identified by sniffing:\n * magic bytes for Flock files, \"does it parse as JSON\" for update bundles,\n * a literal file name for the Filesystem adapter's full snapshot, a key\n * prefix for IndexedDB's queue layout. There has never been an explicit\n * version stamp, and each storage adapter grew its own copy of the\n * \"is this layout current?\" decision. Those copies are not equivalent —\n * one checks a legacy queue key, another compares a file name, a third\n * skips Flock-doc JSON entirely — which is exactly where a future format\n * change would silently diverge.\n *\n * Detection stays sniff-based, because that is what already-written data\n * supports: bytes on disk today carry no version field, and inventing one\n * cannot retroactively apply to them. What this module adds is a single\n * definition of each format, one shared \"needs rewriting\" predicate, and an\n * explicit version constant that new writers can stamp going forward.\n *\n * ## Format registry\n *\n * | id | encoding | written today |\n * |---------------|---------------------------------|---------------|\n * | `flock-v1` | Flock file, `FLOK` magic | no (read-only)|\n * | `flock-v2` | Flock file, `FLK2` magic | yes |\n * | `json-bundle` | UTF-8 JSON `ExportBundle` | yes (updates) |\n *\n * `flock-v1` is retained deliberately: it is the on-disk shape of data\n * written by older versions, and dropping the reader would make that data\n * unreadable rather than merely stale.\n */\n\nconst FLOCK_FILE_MAGIC_LENGTH = 4;\nconst FLOCK_FILE_MAGIC_V1 = [0x46, 0x4c, 0x4f, 0x4b]; // \"FLOK\"\nconst FLOCK_FILE_MAGIC_V2 = [0x46, 0x4c, 0x4b, 0x32]; // \"FLK2\"\n\n/**\n * Formats this package can read.\n *\n * `\"unknown\"` is reported rather than guessed: a caller that cannot\n * identify bytes should surface that, not assume the newest shape.\n */\nexport type PersistedFormatId =\n | \"flock-v1\"\n | \"flock-v2\"\n | \"json-bundle\"\n | \"unknown\";\n\n/**\n * Format new full snapshots are written in.\n *\n * Bump this together with a reader for the previous value, never instead of\n * one — the compatibility window is the whole point.\n */\nexport const CURRENT_SNAPSHOT_FORMAT: PersistedFormatId = \"flock-v2\";\n\n/**\n * Formats whose readers must keep working for already-persisted data.\n *\n * Listed explicitly so removing one is a visible decision rather than a\n * side effect of tidying a branch that \"looks dead\".\n */\nexport const SUPPORTED_READ_FORMATS: ReadonlyArray<PersistedFormatId> = [\n \"flock-v1\",\n \"flock-v2\",\n \"json-bundle\",\n];\n\nfunction matchesMagic(bytes: Uint8Array, magic: readonly number[]): boolean {\n for (let i = 0; i < magic.length; i += 1) {\n if (bytes[i] !== magic[i]) return false;\n }\n return true;\n}\n\n/**\n * Identifies persisted bytes.\n *\n * Anything without a recognized Flock magic is treated as a JSON bundle,\n * matching how the hydration path has always behaved; `\"unknown\"` is\n * reserved for input too short to classify at all.\n */\nexport function detectPersistedFormat(bytes: Uint8Array): PersistedFormatId {\n // Too short to carry a magic header, and too short to be any bundle this\n // package writes — say so rather than defaulting it into a format whose\n // reader would then fail on it.\n if (bytes.length < FLOCK_FILE_MAGIC_LENGTH) return \"unknown\";\n if (matchesMagic(bytes, FLOCK_FILE_MAGIC_V2)) return \"flock-v2\";\n if (matchesMagic(bytes, FLOCK_FILE_MAGIC_V1)) return \"flock-v1\";\n return \"json-bundle\";\n}\n\n/** Whether `bytes` is a Flock file snapshot in any supported version. */\nexport function isFlockFile(bytes: Uint8Array): boolean {\n const format = detectPersistedFormat(bytes);\n return format === \"flock-v1\" || format === \"flock-v2\";\n}\n\n/** Whether `bytes` is written in the format new snapshots use. */\nexport function isCurrentSnapshotFormat(bytes: Uint8Array): boolean {\n return detectPersistedFormat(bytes) === CURRENT_SNAPSHOT_FORMAT;\n}\n\n/**\n * Inputs to the shared \"should this metadata layout be rewritten?\" decision.\n *\n * Each storage adapter supplies what it can observe; the policy itself lives\n * here so the three adapters cannot drift apart on it.\n */\nexport interface MetaLayoutState {\n /** The base snapshot as loaded, if any. */\n readonly snapshot?: Uint8Array;\n /** Number of queued update records sitting alongside the snapshot. */\n readonly queuedUpdates: number;\n /** True when hydration had to parse a JSON bundle as a full snapshot. */\n readonly loadedJsonUpdate: boolean;\n /**\n * True when the adapter found data in a layout it no longer writes —\n * IndexedDB's single `\"queue\"` key, the Filesystem adapter's `meta.json`.\n */\n readonly legacyLayout?: boolean;\n}\n\n/**\n * Whether the persisted metadata layout should be rewritten into the current\n * one on load.\n *\n * Rewriting is what stops old formats from lingering and being re-parsed on\n * every start. Missing a case does not corrupt anything, but it does mean\n * paying the legacy parse cost forever — which is why the decision is one\n * shared function rather than three lookalikes.\n */\nexport function metaLayoutNeedsRewrite(state: MetaLayoutState): boolean {\n if (state.legacyLayout) return true;\n if (state.loadedJsonUpdate) return true;\n if (state.queuedUpdates > 0) return true;\n if (state.snapshot !== undefined && !isCurrentSnapshotFormat(state.snapshot)) {\n return true;\n }\n return false;\n}\n","import { Flock, type ExportBundle } from \"@loro-dev/flock-wasm\";\n\nimport { isFlockFile } from \"./format\";\n\nexport { isFlockFile };\n\nconst textEncoder = new TextEncoder();\nconst textDecoder = new TextDecoder();\n\ntype SnapshotFormat = \"file\" | \"json\";\n\ninterface MergeResult {\n flock: Flock;\n format: SnapshotFormat;\n}\n\nexport interface HydrateMetaSnapshotResult {\n flock: Flock | undefined;\n loadedJsonUpdate: boolean;\n}\n\nexport function encodeMetaJsonUpdate(bundle: ExportBundle): Uint8Array {\n return textEncoder.encode(JSON.stringify(bundle));\n}\n\nexport function hydrateMetaSnapshots(\n legacy: Uint8Array | undefined,\n updates: readonly Uint8Array[],\n): HydrateMetaSnapshotResult {\n let loadedJsonUpdate = false;\n let baseUpdateIndex = -1;\n let flock: Flock | undefined;\n\n if (legacy) {\n const merged = mergeMetaSnapshot(flock, legacy);\n flock = merged.flock;\n if (merged.format === \"json\") {\n loadedJsonUpdate = true;\n }\n } else {\n baseUpdateIndex = updates.findIndex((bytes) => isFlockFile(bytes));\n if (baseUpdateIndex >= 0) {\n // A remote bootstrap may contain recoverable corrupt entries. Build a\n // canonical, hydratable base from the accepted subset instead of\n // retaining an object produced by the compatibility import path.\n flock = Flock.recoverFromFile(\n updates[baseUpdateIndex] as Uint8Array,\n ).flock;\n }\n }\n\n for (let index = 0; index < updates.length; index += 1) {\n if (index === baseUpdateIndex) continue;\n const merged = mergeMetaSnapshot(flock, updates[index] as Uint8Array);\n flock = merged.flock;\n if (merged.format === \"json\") {\n loadedJsonUpdate = true;\n }\n }\n\n return { flock, loadedJsonUpdate };\n}\n\nfunction mergeMetaSnapshot(\n flock: Flock | undefined,\n bytes: Uint8Array,\n): MergeResult {\n if (isFlockFile(bytes)) {\n if (flock) {\n flock.recoverImportFile(bytes);\n return { flock, format: \"file\" };\n }\n return { flock: Flock.recoverFromFile(bytes).flock, format: \"file\" };\n }\n\n const bundle = JSON.parse(textDecoder.decode(bytes)) as ExportBundle;\n if (flock) {\n flock.importJson(bundle);\n return { flock, format: \"json\" };\n }\n const hydrated = new Flock();\n hydrated.importJson(bundle);\n return { flock: hydrated, format: \"json\" };\n}\n","import type { Flock } from \"@loro-dev/flock-wasm\";\n\nexport const DEFAULT_FLOCK_FILE_EXPORT_BUDGET_MS = 8;\n\nexport interface ExportFlockFileSnapshotOptions {\n readonly budgetMs?: number;\n readonly signal?: AbortSignal;\n}\n\ntype FlockWithIncrementalFileExport = Flock & {\n exportFileV2Incremental?: (\n options?: ExportFlockFileSnapshotOptions,\n ) => Promise<Uint8Array>;\n};\n\ntype FlockWithIsEmpty = Flock & {\n isEmpty?: () => boolean;\n};\n\nexport async function exportFlockFileSnapshot(\n flock: Flock,\n options: ExportFlockFileSnapshotOptions = {},\n): Promise<Uint8Array> {\n const exportIncremental = (flock as FlockWithIncrementalFileExport)\n .exportFileV2Incremental;\n if (typeof exportIncremental === \"function\") {\n return exportIncremental.call(flock, {\n budgetMs: options.budgetMs ?? DEFAULT_FLOCK_FILE_EXPORT_BUDGET_MS,\n signal: options.signal,\n });\n }\n return flock.exportFile();\n}\n\nexport function hasVisibleRows(flock: Flock): boolean {\n const isEmpty = (flock as FlockWithIsEmpty).isEmpty;\n if (typeof isEmpty === \"function\") {\n return !isEmpty.call(flock);\n }\n\n const rows = flock.scan({});\n for (const row of rows) {\n if (row.value !== undefined) return true;\n }\n return false;\n}\n"],"mappings":"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"}
@@ -114,7 +114,7 @@ function hydrateMetaSnapshots(legacy, updates) {
114
114
  if (merged.format === "json") loadedJsonUpdate = true;
115
115
  } else {
116
116
  baseUpdateIndex = updates.findIndex((bytes) => isFlockFile(bytes));
117
- if (baseUpdateIndex >= 0) flock = Flock.fromFile(updates[baseUpdateIndex]);
117
+ if (baseUpdateIndex >= 0) flock = Flock.recoverFromFile(updates[baseUpdateIndex]).flock;
118
118
  }
119
119
  for (let index = 0; index < updates.length; index += 1) {
120
120
  if (index === baseUpdateIndex) continue;
@@ -130,14 +130,14 @@ function hydrateMetaSnapshots(legacy, updates) {
130
130
  function mergeMetaSnapshot(flock, bytes) {
131
131
  if (isFlockFile(bytes)) {
132
132
  if (flock) {
133
- flock.importFile(bytes);
133
+ flock.recoverImportFile(bytes);
134
134
  return {
135
135
  flock,
136
136
  format: "file"
137
137
  };
138
138
  }
139
139
  return {
140
- flock: Flock.fromFile(bytes),
140
+ flock: Flock.recoverFromFile(bytes).flock,
141
141
  format: "file"
142
142
  };
143
143
  }