loro-repo 0.19.0 → 0.20.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +126 -33
- package/dist/flock-snapshot.cjs +88 -4
- package/dist/flock-snapshot.cjs.map +1 -1
- package/dist/flock-snapshot.js +83 -5
- package/dist/flock-snapshot.js.map +1 -1
- package/dist/index.cjs +1217 -212
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +148 -30
- package/dist/index.d.ts +148 -30
- package/dist/index.js +1207 -206
- package/dist/index.js.map +1 -1
- package/dist/storage/filesystem.cjs +13 -5
- 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 +14 -6
- package/dist/storage/filesystem.js.map +1 -1
- package/dist/storage/indexeddb.cjs +6 -9
- package/dist/storage/indexeddb.cjs.map +1 -1
- package/dist/storage/indexeddb.d.cts +1 -1
- package/dist/storage/indexeddb.d.ts +1 -1
- package/dist/storage/indexeddb.js +7 -10
- package/dist/storage/indexeddb.js.map +1 -1
- package/dist/storage/sqlite.cjs +6 -4
- package/dist/storage/sqlite.cjs.map +1 -1
- package/dist/storage/sqlite.d.cts +1 -1
- package/dist/storage/sqlite.d.ts +1 -1
- package/dist/storage/sqlite.js +7 -5
- 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 +1115 -159
- package/dist/transport/streams.cjs.map +1 -1
- package/dist/transport/streams.d.cts +369 -15
- package/dist/transport/streams.d.ts +369 -15
- package/dist/transport/streams.js +1113 -161
- 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 +94 -0
- package/dist/types.cjs.map +1 -0
- package/dist/types.d.cts +455 -20
- package/dist/types.d.ts +455 -20
- package/dist/types.js +64 -0
- package/dist/types.js.map +1 -0
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -43,9 +43,16 @@ await repo.unloadDoc("note:welcome");
|
|
|
43
43
|
## Using the API
|
|
44
44
|
|
|
45
45
|
- **Create a repo** with `await LoroRepo.create<Meta>({ transportAdapter?, storageAdapter? })`.
|
|
46
|
-
- **
|
|
46
|
+
- **Add transports later** with `await repo.addTransport(id, adapter, options?)`.
|
|
47
47
|
- **Check adapter availability** via `repo.hasTransport()` and `repo.hasStorage()`.
|
|
48
48
|
- **Choose sync lanes** using `repo.sync({ scope: "meta" | "doc" | "full", docIds? })`.
|
|
49
|
+
The default is `"meta"` — metadata is bounded, document bodies are not, so
|
|
50
|
+
pulling bodies is opt-in. Passing `docIds`/`flockDocIds` widens the scope on
|
|
51
|
+
its own. Bodies planned automatically skip soft-deleted documents and are
|
|
52
|
+
released after the sync unless `retainLoadedDocs` says otherwise.
|
|
53
|
+
- **Acquire replicas** with `repo.acquireDoc(id)` / `repo.acquireFlockDoc(id)`
|
|
54
|
+
when a document is used across awaits; the lease keeps the repository from
|
|
55
|
+
evicting it, and must be `release()`d.
|
|
49
56
|
- **Work with docs** through `openPersistedDoc`, `openDetachedDoc`, `joinDocRoom`, `unloadDoc`, and `flush`.
|
|
50
57
|
- **React to changes** with `repo.watch(listener, { docIds, kinds, metadataFields, by })`.
|
|
51
58
|
- **Shutdown cleanly** by calling `await repo.destroy()`.
|
|
@@ -91,12 +98,17 @@ await repo.removeTransport("cloud");
|
|
|
91
98
|
Key points:
|
|
92
99
|
|
|
93
100
|
- `addTransport(id, adapter, options?)` / `removeTransport(id, { close? })`
|
|
94
|
-
register and unregister named transports; `
|
|
95
|
-
|
|
101
|
+
register and unregister named transports; the `transportAdapter`
|
|
102
|
+
construction option registers a single transport under
|
|
103
|
+
`DEFAULT_TRANSPORT_ID`.
|
|
96
104
|
- `resolveRoomTransports({ kind: "meta" | "doc" | "flock-doc", id })` decides
|
|
97
105
|
which transports join each room. It may return ids that are not registered
|
|
98
106
|
yet (they attach when added) or an empty list (the room stays pending until
|
|
99
107
|
a later `refreshTransportRoutes()`).
|
|
108
|
+
- Rooms can be joined before ANY transport is registered (offline-first
|
|
109
|
+
startup): the join resolves as a pending room whose classic surface reads
|
|
110
|
+
`"disconnected"`, and it attaches automatically when the first transport
|
|
111
|
+
is added. Only `joinEphemeralRoom` requires a registered transport.
|
|
100
112
|
- Room handles returned by `joinMetaRoom` / `joinDocRoom` /
|
|
101
113
|
`joinFlockDocRoom` expose stable per-transport subscriptions via
|
|
102
114
|
`subscription(transportId)` / `subscriptions()`. A handle survives
|
|
@@ -136,6 +148,92 @@ Key points:
|
|
|
136
148
|
- `FileSystemStorageAdaptor` (`src/storage/filesystem.ts`)
|
|
137
149
|
- `SqliteRepoStore` (`src/storage/sqlite.ts`, Node.js only)
|
|
138
150
|
|
|
151
|
+
## Per-room Streams payload protection
|
|
152
|
+
|
|
153
|
+
`StreamsTransportAdapter` can select one streams-crdt provider config for each
|
|
154
|
+
durable room. The resolver receives only logical room identity:
|
|
155
|
+
|
|
156
|
+
- Meta Flock: `{ kind: "meta" }`
|
|
157
|
+
- Loro document: `{ kind: "doc", docId }`
|
|
158
|
+
- named Flock document: `{ kind: "flock", flockDocId }`
|
|
159
|
+
|
|
160
|
+
The resolver never receives the Durable Streams bucket or stream ID. The
|
|
161
|
+
adapter privately maps its structured `{ bucketId, streamId }` address to the
|
|
162
|
+
opaque `streamUrl` expected by streams-crdt. That URL is transport routing, not
|
|
163
|
+
cryptographic identity. The provider returned for a logical room owns key
|
|
164
|
+
lookup and AEAD implementation, while the adapter always binds
|
|
165
|
+
streams-crdt's envelope AAD to a caller-supplied stable application namespace
|
|
166
|
+
plus the logical room identity. The binding is versioned, domain-separated,
|
|
167
|
+
and length-prefixed; it never contains the bucket, stream ID, or URL.
|
|
168
|
+
|
|
169
|
+
```ts
|
|
170
|
+
const transport = new StreamsTransportAdapter({
|
|
171
|
+
bucketId: "workspace-data",
|
|
172
|
+
metaStreamId: "workspace:123:meta",
|
|
173
|
+
docStreamId: (docId) => `workspace:123:doc:${docId}`,
|
|
174
|
+
flockDocStreamId: (flockDocId) => `workspace:123:flock:${flockDocId}`,
|
|
175
|
+
auth: yourAuthProvider,
|
|
176
|
+
// Stable application/workspace identity, not a physical stream route.
|
|
177
|
+
payloadProtectionNamespace: "acme-notes/workspace-123",
|
|
178
|
+
payloadProtection: (room) => ({
|
|
179
|
+
mode: "protected",
|
|
180
|
+
config: lodyCrypto.providerConfigForRoom(room),
|
|
181
|
+
}),
|
|
182
|
+
});
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Once `payloadProtection` is present, the resolver is total. Every room must
|
|
186
|
+
return either `{ mode: "protected", config }` or `{ mode: "plaintext" }`.
|
|
187
|
+
Returning `undefined`, throwing, or returning an invalid selection fails that
|
|
188
|
+
room before a `StreamsCrdt` is created. Protected selections also set upstream
|
|
189
|
+
`payloadProtectionRequired` and force `readPolicy: "encrypted-only"` plus
|
|
190
|
+
`writePolicy: "encrypt"`. A protected config cannot opt into
|
|
191
|
+
`allow-plaintext` reads or plaintext writes. Use the honest top-level
|
|
192
|
+
`{ mode: "plaintext" }` selection for a public room. Omit `payloadProtection`
|
|
193
|
+
entirely to preserve the existing plaintext API and wire behavior.
|
|
194
|
+
|
|
195
|
+
The resolved config and the provider instance used by `seal()` are fixed for
|
|
196
|
+
one room session. In particular, `seal()` must keep using that session's write
|
|
197
|
+
epoch; it must not switch dynamically through a mutable vault handle. `open()`
|
|
198
|
+
may use the opaque authenticated header to look up historical read keys.
|
|
199
|
+
|
|
200
|
+
To replace the write provider safely without recreating the whole repo, the
|
|
201
|
+
application owns a grouped barrier:
|
|
202
|
+
|
|
203
|
+
1. stop producing writes for the affected room set;
|
|
204
|
+
2. await one `Promise.all` of `waitUntilSynced()` for every active subscription;
|
|
205
|
+
3. only after every wait succeeds, unsubscribe every lease in that set;
|
|
206
|
+
4. await `restartRoomSessions(rooms)` to join any in-progress teardown, then
|
|
207
|
+
update the application-owned config and rejoin.
|
|
208
|
+
|
|
209
|
+
The final live lease already starts that room's teardown, so
|
|
210
|
+
`restartRoomSessions` is not the atomic drain barrier. It refuses any room that
|
|
211
|
+
still has a live lease, pending live acquisition, or in-flight one-shot sync;
|
|
212
|
+
it also fences new joins and one-shot syncs until the selected teardown
|
|
213
|
+
completes. A successful return therefore leaves no old-generation session that
|
|
214
|
+
can reappear before the caller switches config. The restart preserves CRDT
|
|
215
|
+
state and remote cursors and makes the next sync/join call the resolver again.
|
|
216
|
+
If any `waitUntilSynced()` fails, keep all leases and the old write providers
|
|
217
|
+
in place; do not partially release the room set.
|
|
218
|
+
|
|
219
|
+
Use a non-owning provider handle into an application-owned vault. The adapter
|
|
220
|
+
wraps the provider only to add its logical-room AAD and fixed encrypted-only
|
|
221
|
+
policies. Resolver-configured one-shot sessions release that wrapper after each
|
|
222
|
+
operation, and live sessions release it after their final lease closes. The
|
|
223
|
+
adapter does not inspect or dispose provider state, and it never stores it in
|
|
224
|
+
repo metadata, documents, cursor storage, logs, or surfaced error causes.
|
|
225
|
+
|
|
226
|
+
The same protected `StreamsCrdt` instance handles updates, snapshots,
|
|
227
|
+
bootstrap/catch-up, and live reads. A protection failure therefore occurs before
|
|
228
|
+
CRDT import and before `beforeRemoteCursorSave`; the adapter keeps the existing
|
|
229
|
+
"persist CRDT state, then advance cursor" boundary. Each room owns an independent
|
|
230
|
+
instance, so one room's failure does not stop other rooms.
|
|
231
|
+
|
|
232
|
+
This API requires `@loro-dev/streams-crdt@^0.15.0`, specifically its common
|
|
233
|
+
protected-payload boundary and `payloadProtectionRequired` guard. No 0.12.x
|
|
234
|
+
encryption compatibility shim is retained; the adapter passes the published
|
|
235
|
+
0.15 opaque `streamUrl` transport target directly.
|
|
236
|
+
|
|
139
237
|
## SQLite storage (Node.js / Electron)
|
|
140
238
|
|
|
141
239
|
`SqliteRepoStore` packs everything a repo needs into a single SQLite database
|
|
@@ -150,53 +248,48 @@ database connection:
|
|
|
150
248
|
- `store.storage` — a `StorageAdapter` for doc snapshots, doc updates, and
|
|
151
249
|
metadata (Flock) snapshots/updates.
|
|
152
250
|
- `store.cursorStore` — a `RemoteCursorStore` for the streams transport's
|
|
153
|
-
`
|
|
251
|
+
`persistence` bundle.
|
|
154
252
|
|
|
155
253
|
```ts
|
|
156
254
|
import { LoroRepo } from "loro-repo";
|
|
157
255
|
import { SqliteRepoStore } from "loro-repo/storage/sqlite";
|
|
158
|
-
import {
|
|
256
|
+
import {
|
|
257
|
+
StreamsTransportAdapter,
|
|
258
|
+
createRepoStreamsPersistence,
|
|
259
|
+
} from "loro-repo/transport/streams";
|
|
159
260
|
|
|
160
261
|
const store = new SqliteRepoStore({ path: "./data/repo.db" });
|
|
161
262
|
|
|
162
263
|
const repo = await LoroRepo.create({
|
|
163
264
|
storageAdapter: store.storage,
|
|
164
|
-
|
|
265
|
+
});
|
|
266
|
+
|
|
267
|
+
await repo.addTransport(
|
|
268
|
+
"streams",
|
|
269
|
+
new StreamsTransportAdapter({
|
|
165
270
|
bucketId: "your-bucket",
|
|
166
271
|
auth: yourAuthProvider,
|
|
167
|
-
|
|
168
|
-
//
|
|
169
|
-
//
|
|
170
|
-
|
|
171
|
-
// leaves the cursor pointing past data that was never persisted locally.
|
|
172
|
-
onPersistDoc: async (docId, doc) => {
|
|
173
|
-
await store.storage.save({
|
|
174
|
-
type: "doc-snapshot",
|
|
175
|
-
docId,
|
|
176
|
-
snapshot: doc.export({ mode: "snapshot" }),
|
|
177
|
-
});
|
|
178
|
-
},
|
|
179
|
-
onPersistMeta: async (flock) => {
|
|
180
|
-
await store.storage.save({
|
|
181
|
-
type: "meta-snapshot",
|
|
182
|
-
snapshot: flock.exportFile(),
|
|
183
|
-
});
|
|
184
|
-
},
|
|
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`.
|
|
275
|
+
persistence: createRepoStreamsPersistence(repo, store.cursorStore),
|
|
185
276
|
}),
|
|
186
|
-
|
|
277
|
+
);
|
|
187
278
|
|
|
188
279
|
// Shutdown
|
|
189
280
|
await repo.destroy();
|
|
190
281
|
store.close();
|
|
191
282
|
```
|
|
192
283
|
|
|
193
|
-
> ⚠️
|
|
194
|
-
>
|
|
195
|
-
>
|
|
196
|
-
>
|
|
197
|
-
>
|
|
198
|
-
>
|
|
199
|
-
>
|
|
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" }`.
|
|
200
293
|
|
|
201
294
|
`SqliteRepoStoreOptions`:
|
|
202
295
|
|
|
@@ -294,7 +387,7 @@ pulls native bindings into a browser bundle.
|
|
|
294
387
|
- `await repo.upsertDocMeta(docId, patch)`
|
|
295
388
|
- `await repo.getDocMeta(docId)`
|
|
296
389
|
- `await repo.listDoc(query?)`
|
|
297
|
-
- `repo.getMeta()`
|
|
390
|
+
- `repo.getMeta()`
|
|
298
391
|
|
|
299
392
|
**Documents**
|
|
300
393
|
- `await repo.openPersistedDoc(docId)`
|
package/dist/flock-snapshot.cjs
CHANGED
|
@@ -2,9 +2,40 @@ const require_chunk = require('./chunk.cjs');
|
|
|
2
2
|
let __loro_dev_flock_wasm = require("@loro-dev/flock-wasm");
|
|
3
3
|
__loro_dev_flock_wasm = require_chunk.__toESM(__loro_dev_flock_wasm);
|
|
4
4
|
|
|
5
|
-
//#region src/storage/
|
|
6
|
-
|
|
7
|
-
|
|
5
|
+
//#region src/storage/format.ts
|
|
6
|
+
/**
|
|
7
|
+
* Persisted-format identification, in one place.
|
|
8
|
+
*
|
|
9
|
+
* ## Why this module exists
|
|
10
|
+
*
|
|
11
|
+
* Every persisted format this package reads is identified by sniffing:
|
|
12
|
+
* magic bytes for Flock files, "does it parse as JSON" for update bundles,
|
|
13
|
+
* a literal file name for the Filesystem adapter's full snapshot, a key
|
|
14
|
+
* prefix for IndexedDB's queue layout. There has never been an explicit
|
|
15
|
+
* version stamp, and each storage adapter grew its own copy of the
|
|
16
|
+
* "is this layout current?" decision. Those copies are not equivalent —
|
|
17
|
+
* one checks a legacy queue key, another compares a file name, a third
|
|
18
|
+
* skips Flock-doc JSON entirely — which is exactly where a future format
|
|
19
|
+
* change would silently diverge.
|
|
20
|
+
*
|
|
21
|
+
* Detection stays sniff-based, because that is what already-written data
|
|
22
|
+
* supports: bytes on disk today carry no version field, and inventing one
|
|
23
|
+
* cannot retroactively apply to them. What this module adds is a single
|
|
24
|
+
* definition of each format, one shared "needs rewriting" predicate, and an
|
|
25
|
+
* explicit version constant that new writers can stamp going forward.
|
|
26
|
+
*
|
|
27
|
+
* ## Format registry
|
|
28
|
+
*
|
|
29
|
+
* | id | encoding | written today |
|
|
30
|
+
* |---------------|---------------------------------|---------------|
|
|
31
|
+
* | `flock-v1` | Flock file, `FLOK` magic | no (read-only)|
|
|
32
|
+
* | `flock-v2` | Flock file, `FLK2` magic | yes |
|
|
33
|
+
* | `json-bundle` | UTF-8 JSON `ExportBundle` | yes (updates) |
|
|
34
|
+
*
|
|
35
|
+
* `flock-v1` is retained deliberately: it is the on-disk shape of data
|
|
36
|
+
* written by older versions, and dropping the reader would make that data
|
|
37
|
+
* unreadable rather than merely stale.
|
|
38
|
+
*/
|
|
8
39
|
const FLOCK_FILE_MAGIC_LENGTH = 4;
|
|
9
40
|
const FLOCK_FILE_MAGIC_V1 = [
|
|
10
41
|
70,
|
|
@@ -18,13 +49,60 @@ const FLOCK_FILE_MAGIC_V2 = [
|
|
|
18
49
|
75,
|
|
19
50
|
50
|
|
20
51
|
];
|
|
52
|
+
/**
|
|
53
|
+
* Format new full snapshots are written in.
|
|
54
|
+
*
|
|
55
|
+
* Bump this together with a reader for the previous value, never instead of
|
|
56
|
+
* one — the compatibility window is the whole point.
|
|
57
|
+
*/
|
|
58
|
+
const CURRENT_SNAPSHOT_FORMAT = "flock-v2";
|
|
21
59
|
function matchesMagic(bytes, magic) {
|
|
22
60
|
for (let i = 0; i < magic.length; i += 1) if (bytes[i] !== magic[i]) return false;
|
|
23
61
|
return true;
|
|
24
62
|
}
|
|
63
|
+
/**
|
|
64
|
+
* Identifies persisted bytes.
|
|
65
|
+
*
|
|
66
|
+
* Anything without a recognized Flock magic is treated as a JSON bundle,
|
|
67
|
+
* matching how the hydration path has always behaved; `"unknown"` is
|
|
68
|
+
* reserved for input too short to classify at all.
|
|
69
|
+
*/
|
|
70
|
+
function detectPersistedFormat(bytes) {
|
|
71
|
+
if (bytes.length < FLOCK_FILE_MAGIC_LENGTH) return "unknown";
|
|
72
|
+
if (matchesMagic(bytes, FLOCK_FILE_MAGIC_V2)) return "flock-v2";
|
|
73
|
+
if (matchesMagic(bytes, FLOCK_FILE_MAGIC_V1)) return "flock-v1";
|
|
74
|
+
return "json-bundle";
|
|
75
|
+
}
|
|
76
|
+
/** Whether `bytes` is a Flock file snapshot in any supported version. */
|
|
25
77
|
function isFlockFile(bytes) {
|
|
26
|
-
|
|
78
|
+
const format = detectPersistedFormat(bytes);
|
|
79
|
+
return format === "flock-v1" || format === "flock-v2";
|
|
27
80
|
}
|
|
81
|
+
/** Whether `bytes` is written in the format new snapshots use. */
|
|
82
|
+
function isCurrentSnapshotFormat(bytes) {
|
|
83
|
+
return detectPersistedFormat(bytes) === CURRENT_SNAPSHOT_FORMAT;
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* Whether the persisted metadata layout should be rewritten into the current
|
|
87
|
+
* one on load.
|
|
88
|
+
*
|
|
89
|
+
* Rewriting is what stops old formats from lingering and being re-parsed on
|
|
90
|
+
* every start. Missing a case does not corrupt anything, but it does mean
|
|
91
|
+
* paying the legacy parse cost forever — which is why the decision is one
|
|
92
|
+
* shared function rather than three lookalikes.
|
|
93
|
+
*/
|
|
94
|
+
function metaLayoutNeedsRewrite(state) {
|
|
95
|
+
if (state.legacyLayout) return true;
|
|
96
|
+
if (state.loadedJsonUpdate) return true;
|
|
97
|
+
if (state.queuedUpdates > 0) return true;
|
|
98
|
+
if (state.snapshot !== void 0 && !isCurrentSnapshotFormat(state.snapshot)) return true;
|
|
99
|
+
return false;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
//#endregion
|
|
103
|
+
//#region src/storage/meta-snapshot.ts
|
|
104
|
+
const textEncoder = new TextEncoder();
|
|
105
|
+
const textDecoder = new TextDecoder();
|
|
28
106
|
function encodeMetaJsonUpdate(bundle) {
|
|
29
107
|
return textEncoder.encode(JSON.stringify(bundle));
|
|
30
108
|
}
|
|
@@ -131,4 +209,10 @@ Object.defineProperty(exports, 'isFlockFile', {
|
|
|
131
209
|
return isFlockFile;
|
|
132
210
|
}
|
|
133
211
|
});
|
|
212
|
+
Object.defineProperty(exports, 'metaLayoutNeedsRewrite', {
|
|
213
|
+
enumerable: true,
|
|
214
|
+
get: function () {
|
|
215
|
+
return metaLayoutNeedsRewrite;
|
|
216
|
+
}
|
|
217
|
+
});
|
|
134
218
|
//# sourceMappingURL=flock-snapshot.cjs.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"flock-snapshot.cjs","names":["flock: Flock | undefined","Flock"],"sources":["../src/storage/meta-snapshot.ts","../src/internal/flock-snapshot.ts"],"sourcesContent":["import { Flock, type ExportBundle } from \"@loro-dev/flock-wasm\";\n\nconst textEncoder = new TextEncoder();\nconst textDecoder = new TextDecoder();\nconst FLOCK_FILE_MAGIC_LENGTH = 4;\n// Flock file snapshots are prefixed with a 4-byte magic header. The legacy v1\n// B+Tree page format uses \"FLOK\"; flock-wasm >=0.4.0 writes the canonical v2\n// format with \"FLK2\". `Flock.fromFile`/`importFile` read both, so we just need\n// to recognize either magic to distinguish a binary snapshot from a JSON bundle.\nconst FLOCK_FILE_MAGIC_V1 = [0x46, 0x4c, 0x4f, 0x4b]; // \"FLOK\"\nconst FLOCK_FILE_MAGIC_V2 = [0x46, 0x4c, 0x4b, 0x32]; // \"FLK2\"\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\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\nexport function isFlockFile(bytes: Uint8Array): boolean {\n return (\n bytes.length >= FLOCK_FILE_MAGIC_LENGTH &&\n (matchesMagic(bytes, FLOCK_FILE_MAGIC_V1) ||\n matchesMagic(bytes, FLOCK_FILE_MAGIC_V2))\n );\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":";;;;;AAEA,MAAM,cAAc,IAAI,aAAa;AACrC,MAAM,cAAc,IAAI,aAAa;AACrC,MAAM,0BAA0B;AAKhC,MAAM,sBAAsB;CAAC;CAAM;CAAM;CAAM;CAAK;AACpD,MAAM,sBAAsB;CAAC;CAAM;CAAM;CAAM;CAAK;AAcpD,SAAS,aAAa,OAAmB,OAAmC;AAC1E,MAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK,EACrC,KAAI,MAAM,OAAO,MAAM,GAAI,QAAO;AAEpC,QAAO;;AAGT,SAAgB,YAAY,OAA4B;AACtD,QACE,MAAM,UAAU,4BACf,aAAa,OAAO,oBAAoB,IACvC,aAAa,OAAO,oBAAoB;;AAI9C,SAAgB,qBAAqB,QAAkC;AACrE,QAAO,YAAY,OAAO,KAAK,UAAU,OAAO,CAAC;;AAGnD,SAAgB,qBACd,QACA,SAC2B;CAC3B,IAAI,mBAAmB;CACvB,IAAI,kBAAkB;CACtB,IAAIA;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;;;;;AC7F5C,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 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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"}
|
package/dist/flock-snapshot.js
CHANGED
|
@@ -1,8 +1,39 @@
|
|
|
1
1
|
import { Flock } from "@loro-dev/flock-wasm";
|
|
2
2
|
|
|
3
|
-
//#region src/storage/
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
//#region src/storage/format.ts
|
|
4
|
+
/**
|
|
5
|
+
* Persisted-format identification, in one place.
|
|
6
|
+
*
|
|
7
|
+
* ## Why this module exists
|
|
8
|
+
*
|
|
9
|
+
* Every persisted format this package reads is identified by sniffing:
|
|
10
|
+
* magic bytes for Flock files, "does it parse as JSON" for update bundles,
|
|
11
|
+
* a literal file name for the Filesystem adapter's full snapshot, a key
|
|
12
|
+
* prefix for IndexedDB's queue layout. There has never been an explicit
|
|
13
|
+
* version stamp, and each storage adapter grew its own copy of the
|
|
14
|
+
* "is this layout current?" decision. Those copies are not equivalent —
|
|
15
|
+
* one checks a legacy queue key, another compares a file name, a third
|
|
16
|
+
* skips Flock-doc JSON entirely — which is exactly where a future format
|
|
17
|
+
* change would silently diverge.
|
|
18
|
+
*
|
|
19
|
+
* Detection stays sniff-based, because that is what already-written data
|
|
20
|
+
* supports: bytes on disk today carry no version field, and inventing one
|
|
21
|
+
* cannot retroactively apply to them. What this module adds is a single
|
|
22
|
+
* definition of each format, one shared "needs rewriting" predicate, and an
|
|
23
|
+
* explicit version constant that new writers can stamp going forward.
|
|
24
|
+
*
|
|
25
|
+
* ## Format registry
|
|
26
|
+
*
|
|
27
|
+
* | id | encoding | written today |
|
|
28
|
+
* |---------------|---------------------------------|---------------|
|
|
29
|
+
* | `flock-v1` | Flock file, `FLOK` magic | no (read-only)|
|
|
30
|
+
* | `flock-v2` | Flock file, `FLK2` magic | yes |
|
|
31
|
+
* | `json-bundle` | UTF-8 JSON `ExportBundle` | yes (updates) |
|
|
32
|
+
*
|
|
33
|
+
* `flock-v1` is retained deliberately: it is the on-disk shape of data
|
|
34
|
+
* written by older versions, and dropping the reader would make that data
|
|
35
|
+
* unreadable rather than merely stale.
|
|
36
|
+
*/
|
|
6
37
|
const FLOCK_FILE_MAGIC_LENGTH = 4;
|
|
7
38
|
const FLOCK_FILE_MAGIC_V1 = [
|
|
8
39
|
70,
|
|
@@ -16,13 +47,60 @@ const FLOCK_FILE_MAGIC_V2 = [
|
|
|
16
47
|
75,
|
|
17
48
|
50
|
|
18
49
|
];
|
|
50
|
+
/**
|
|
51
|
+
* Format new full snapshots are written in.
|
|
52
|
+
*
|
|
53
|
+
* Bump this together with a reader for the previous value, never instead of
|
|
54
|
+
* one — the compatibility window is the whole point.
|
|
55
|
+
*/
|
|
56
|
+
const CURRENT_SNAPSHOT_FORMAT = "flock-v2";
|
|
19
57
|
function matchesMagic(bytes, magic) {
|
|
20
58
|
for (let i = 0; i < magic.length; i += 1) if (bytes[i] !== magic[i]) return false;
|
|
21
59
|
return true;
|
|
22
60
|
}
|
|
61
|
+
/**
|
|
62
|
+
* Identifies persisted bytes.
|
|
63
|
+
*
|
|
64
|
+
* Anything without a recognized Flock magic is treated as a JSON bundle,
|
|
65
|
+
* matching how the hydration path has always behaved; `"unknown"` is
|
|
66
|
+
* reserved for input too short to classify at all.
|
|
67
|
+
*/
|
|
68
|
+
function detectPersistedFormat(bytes) {
|
|
69
|
+
if (bytes.length < FLOCK_FILE_MAGIC_LENGTH) return "unknown";
|
|
70
|
+
if (matchesMagic(bytes, FLOCK_FILE_MAGIC_V2)) return "flock-v2";
|
|
71
|
+
if (matchesMagic(bytes, FLOCK_FILE_MAGIC_V1)) return "flock-v1";
|
|
72
|
+
return "json-bundle";
|
|
73
|
+
}
|
|
74
|
+
/** Whether `bytes` is a Flock file snapshot in any supported version. */
|
|
23
75
|
function isFlockFile(bytes) {
|
|
24
|
-
|
|
76
|
+
const format = detectPersistedFormat(bytes);
|
|
77
|
+
return format === "flock-v1" || format === "flock-v2";
|
|
78
|
+
}
|
|
79
|
+
/** Whether `bytes` is written in the format new snapshots use. */
|
|
80
|
+
function isCurrentSnapshotFormat(bytes) {
|
|
81
|
+
return detectPersistedFormat(bytes) === CURRENT_SNAPSHOT_FORMAT;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Whether the persisted metadata layout should be rewritten into the current
|
|
85
|
+
* one on load.
|
|
86
|
+
*
|
|
87
|
+
* Rewriting is what stops old formats from lingering and being re-parsed on
|
|
88
|
+
* every start. Missing a case does not corrupt anything, but it does mean
|
|
89
|
+
* paying the legacy parse cost forever — which is why the decision is one
|
|
90
|
+
* shared function rather than three lookalikes.
|
|
91
|
+
*/
|
|
92
|
+
function metaLayoutNeedsRewrite(state) {
|
|
93
|
+
if (state.legacyLayout) return true;
|
|
94
|
+
if (state.loadedJsonUpdate) return true;
|
|
95
|
+
if (state.queuedUpdates > 0) return true;
|
|
96
|
+
if (state.snapshot !== void 0 && !isCurrentSnapshotFormat(state.snapshot)) return true;
|
|
97
|
+
return false;
|
|
25
98
|
}
|
|
99
|
+
|
|
100
|
+
//#endregion
|
|
101
|
+
//#region src/storage/meta-snapshot.ts
|
|
102
|
+
const textEncoder = new TextEncoder();
|
|
103
|
+
const textDecoder = new TextDecoder();
|
|
26
104
|
function encodeMetaJsonUpdate(bundle) {
|
|
27
105
|
return textEncoder.encode(JSON.stringify(bundle));
|
|
28
106
|
}
|
|
@@ -99,5 +177,5 @@ function hasVisibleRows(flock) {
|
|
|
99
177
|
}
|
|
100
178
|
|
|
101
179
|
//#endregion
|
|
102
|
-
export { isFlockFile as a, hydrateMetaSnapshots as i, hasVisibleRows as n, encodeMetaJsonUpdate as r, exportFlockFileSnapshot as t };
|
|
180
|
+
export { isFlockFile as a, hydrateMetaSnapshots as i, hasVisibleRows as n, metaLayoutNeedsRewrite as o, encodeMetaJsonUpdate as r, exportFlockFileSnapshot as t };
|
|
103
181
|
//# sourceMappingURL=flock-snapshot.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"flock-snapshot.js","names":["flock: Flock | undefined"],"sources":["../src/storage/meta-snapshot.ts","../src/internal/flock-snapshot.ts"],"sourcesContent":["import { Flock, type ExportBundle } from \"@loro-dev/flock-wasm\";\n\nconst textEncoder = new TextEncoder();\nconst textDecoder = new TextDecoder();\nconst FLOCK_FILE_MAGIC_LENGTH = 4;\n// Flock file snapshots are prefixed with a 4-byte magic header. The legacy v1\n// B+Tree page format uses \"FLOK\"; flock-wasm >=0.4.0 writes the canonical v2\n// format with \"FLK2\". `Flock.fromFile`/`importFile` read both, so we just need\n// to recognize either magic to distinguish a binary snapshot from a JSON bundle.\nconst FLOCK_FILE_MAGIC_V1 = [0x46, 0x4c, 0x4f, 0x4b]; // \"FLOK\"\nconst FLOCK_FILE_MAGIC_V2 = [0x46, 0x4c, 0x4b, 0x32]; // \"FLK2\"\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\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\nexport function isFlockFile(bytes: Uint8Array): boolean {\n return (\n bytes.length >= FLOCK_FILE_MAGIC_LENGTH &&\n (matchesMagic(bytes, FLOCK_FILE_MAGIC_V1) ||\n matchesMagic(bytes, FLOCK_FILE_MAGIC_V2))\n );\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":";;;AAEA,MAAM,cAAc,IAAI,aAAa;AACrC,MAAM,cAAc,IAAI,aAAa;AACrC,MAAM,0BAA0B;AAKhC,MAAM,sBAAsB;CAAC;CAAM;CAAM;CAAM;CAAK;AACpD,MAAM,sBAAsB;CAAC;CAAM;CAAM;CAAM;CAAK;AAcpD,SAAS,aAAa,OAAmB,OAAmC;AAC1E,MAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK,EACrC,KAAI,MAAM,OAAO,MAAM,GAAI,QAAO;AAEpC,QAAO;;AAGT,SAAgB,YAAY,OAA4B;AACtD,QACE,MAAM,UAAU,4BACf,aAAa,OAAO,oBAAoB,IACvC,aAAa,OAAO,oBAAoB;;AAI9C,SAAgB,qBAAqB,QAAkC;AACrE,QAAO,YAAY,OAAO,KAAK,UAAU,OAAO,CAAC;;AAGnD,SAAgB,qBACd,QACA,SAC2B;CAC3B,IAAI,mBAAmB;CACvB,IAAI,kBAAkB;CACtB,IAAIA;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,SAAQ,MAAM,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,OAAO,MAAM,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,IAAI,OAAO;AAC5B,UAAS,WAAW,OAAO;AAC3B,QAAO;EAAE,OAAO;EAAU,QAAQ;EAAQ;;;;;AC7F5C,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.js","names":["CURRENT_SNAPSHOT_FORMAT: PersistedFormatId","flock: Flock | undefined"],"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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"}
|