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.
- package/README.md +118 -16
- package/dist/flock-persistence-journal.cjs +156 -0
- package/dist/flock-persistence-journal.cjs.map +1 -0
- package/dist/flock-persistence-journal.js +145 -0
- package/dist/flock-persistence-journal.js.map +1 -0
- package/dist/flock-snapshot.cjs +3 -3
- package/dist/flock-snapshot.cjs.map +1 -1
- package/dist/flock-snapshot.js +3 -3
- package/dist/flock-snapshot.js.map +1 -1
- package/dist/index.cjs +101 -163
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +10 -2
- package/dist/index.d.ts +10 -2
- package/dist/index.js +103 -166
- package/dist/index.js.map +1 -1
- package/dist/storage/filesystem.cjs +2 -2
- package/dist/storage/filesystem.cjs.map +1 -1
- package/dist/storage/filesystem.d.cts +1 -1
- package/dist/storage/filesystem.d.ts +1 -1
- package/dist/storage/filesystem.js +2 -2
- package/dist/storage/filesystem.js.map +1 -1
- package/dist/storage/indexeddb.cjs +383 -70
- package/dist/storage/indexeddb.cjs.map +1 -1
- package/dist/storage/indexeddb.d.cts +51 -6
- package/dist/storage/indexeddb.d.ts +51 -6
- package/dist/storage/indexeddb.js +382 -71
- package/dist/storage/indexeddb.js.map +1 -1
- package/dist/storage/sqlite.cjs +18 -1
- package/dist/storage/sqlite.cjs.map +1 -1
- package/dist/storage/sqlite.d.cts +3 -2
- package/dist/storage/sqlite.d.ts +2 -1
- package/dist/storage/sqlite.js +18 -1
- package/dist/storage/sqlite.js.map +1 -1
- package/dist/transport/broadcast-channel.d.cts +1 -1
- package/dist/transport/broadcast-channel.d.ts +1 -1
- package/dist/transport/streams.cjs +46 -26
- package/dist/transport/streams.cjs.map +1 -1
- package/dist/transport/streams.d.cts +33 -5
- package/dist/transport/streams.d.ts +32 -4
- package/dist/transport/streams.js +47 -27
- package/dist/transport/streams.js.map +1 -1
- package/dist/transport/websocket.d.cts +1 -1
- package/dist/transport/websocket.d.ts +1 -1
- package/dist/types.cjs +37 -0
- package/dist/types.cjs.map +1 -1
- package/dist/types.d.cts +95 -12
- package/dist/types.d.ts +95 -12
- package/dist/types.js +32 -1
- package/dist/types.js.map +1 -1
- 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
|
|
240
|
-
file
|
|
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
|
-
//
|
|
273
|
-
//
|
|
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
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
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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"}
|
package/dist/flock-snapshot.cjs
CHANGED
|
@@ -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.
|
|
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.
|
|
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.
|
|
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":"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"}
|
|
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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"}
|
package/dist/flock-snapshot.js
CHANGED
|
@@ -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.
|
|
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.
|
|
133
|
+
flock.recoverImportFile(bytes);
|
|
134
134
|
return {
|
|
135
135
|
flock,
|
|
136
136
|
format: "file"
|
|
137
137
|
};
|
|
138
138
|
}
|
|
139
139
|
return {
|
|
140
|
-
flock: Flock.
|
|
140
|
+
flock: Flock.recoverFromFile(bytes).flock,
|
|
141
141
|
format: "file"
|
|
142
142
|
};
|
|
143
143
|
}
|