@optimystic/db-p2p-storage-web 1.15.0 → 1.16.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 CHANGED
@@ -4,8 +4,8 @@ IndexedDB-backed storage backend for Optimystic browser peers. Provides:
4
4
 
5
5
  - **`IndexedDBRawStorage`** — implements `IRawStorage` so a browser node persists
6
6
  block metadata, revisions, pending transactions, committed transactions,
7
- commit proofs, and
8
- materialized blocks across page reloads.
7
+ commit proofs, and materialized blocks across page reloads, each group of
8
+ writes journaled and applied as one transaction.
9
9
  - **`IndexedDBKVStore`** — implements `IKVStore` for the persistent transaction
10
10
  state used to recover crashed two-phase commits.
11
11
  - **`loadOrCreateBrowserPeerKey`** — generates an Ed25519 libp2p private key on
@@ -14,7 +14,8 @@ IndexedDB-backed storage backend for Optimystic browser peers. Provides:
14
14
 
15
15
  This package is browser-only — it imports no Node built-ins. Counterparts:
16
16
 
17
- - `@optimystic/db-p2p-storage-rn` — React Native (MMKV)
17
+ - `@optimystic/db-p2p-storage-rn` — React Native (LevelDB)
18
+ - `@optimystic/db-p2p-storage-ns` — NativeScript (SQLite)
18
19
  - `@optimystic/db-p2p-storage-fs` — Node filesystem
19
20
 
20
21
  ## Install
@@ -57,14 +58,27 @@ The same `IDBPDatabase` handle is shared by all three consumers — IndexedDB
57
58
  permits concurrent transactions across disjoint object stores, so the storage
58
59
  layer parallelises naturally.
59
60
 
61
+ Close the storage and the key-value store before the handle, and the handle last:
62
+
63
+ ```ts
64
+ await rawStorage.close(); // applies what it still holds, disarms its timers
65
+ await kvStore.close(); // commits what it still holds, disarms its timer
66
+ db.close();
67
+ ```
68
+
69
+ Neither `close()` closes the shared handle. A write a store still holds when the
70
+ handle is closed under it is lost, and a timer it still has armed would fire on
71
+ a closed handle.
72
+
60
73
  ## Persistence semantics
61
74
 
62
75
  The package opens a single IndexedDB database (`optimystic` by default) with
63
- seven object stores. `IndexedDBRawStorage` is a thin shell over the shared
64
- `KvRawStorage` kernel driven by an `IndexedDBStoreDriver`: the kernel owns all
65
- JSON/UTF-8 serialization, so the six block-storage stores now hold opaque
66
- kernel-encoded `Uint8Array` bytes rather than live objects. The keys and the
67
- logical types the kernel decodes them back into are unchanged:
76
+ eight object stores. `IndexedDBRawStorage` is the shared `KvRawStorage` kernel
77
+ over a `WriteGroupDriver` over a `JournalBatchBackend` over an
78
+ `IndexedDBJournalStore`: the kernel owns all JSON/UTF-8 serialization, so the
79
+ six block-storage stores hold opaque kernel-encoded `Uint8Array` bytes rather
80
+ than live objects. The keys and the logical types the kernel decodes them back
81
+ into are unchanged from earlier builds, so data written by one reads unchanged:
68
82
 
69
83
  | Store | Key | Stored value | Decoded (logical) type |
70
84
  |----------------|----------------------|--------------|------------------------|
@@ -74,24 +88,92 @@ logical types the kernel decodes them back into are unchanged:
74
88
  | `transactions` | `[blockId, actionId]`| `Uint8Array` | `Transform` |
75
89
  | `proofs` | `[blockId, rev]` | `Uint8Array` | `BlockCommitProof` |
76
90
  | `materialized` | `[blockId, actionId]`| `Uint8Array` | `IBlock` |
91
+ | `journal` | `seq` (a number), or `'applied-through'` | a `JournalRecord` by structured clone, or the number of the last record applied | — (owned by `IndexedDBJournalStore`) |
77
92
  | `kv` | `key` | `string` or `Uint8Array` | — (not kernel-backed) |
78
93
 
79
94
  `listRevisions` and `listPendingTransactions` use real IndexedDB range cursors
80
95
  — never `getAllKeys()` + JS filter — so list latency stays bounded as the store
81
- grows. `promotePendingTransaction` runs as a single `readwrite` transaction
82
- spanning `pending` and `transactions`, so the move is atomic across crashes.
96
+ grows. `promotePendingTransaction` records two entries of one write group — the
97
+ committed row's put and the pending row's delete — applied in that group's
98
+ transaction, so the move is atomic across crashes.
83
99
 
84
100
  `getApproximateBytesUsed()` returns `(await navigator.storage.estimate()).usage`,
85
101
  which is **per-origin**, not per-database. That is adequate for `StorageMonitor`
86
102
  — which uses the figure as an advisory ring-selection input — but is not a
87
103
  precise per-database accounting.
88
104
 
105
+ ## Durability
106
+
107
+ A write resolves into memory and is served from there; `flush()` hands every
108
+ write made since the last flush to the journal backend as **one group**, so a
109
+ group lands whole or not at all. IndexedDB can make one transaction durable
110
+ (`durability: 'strict'`: the transaction completes only once the browser has
111
+ put it on the disk) but promises nothing about the order relaxed transactions
112
+ reach the disk, so the backend journals rather than committing groups directly:
113
+
114
+ - a strict `flush()` (no `withinMs`, or 0) applies the group — and every group
115
+ journaled and not yet applied — as one strict transaction over the six data
116
+ stores and `journal`, and resolves once that transaction has completed;
117
+ - a relaxed `flush({ withinMs })` — what a node uses for a write its cohort
118
+ also holds, see [storage.md §How long a write may wait for its sync](../db-p2p/docs/storage.md#how-long-a-write-may-wait-for-its-sync) —
119
+ appends the group as one journal record in one relaxed transaction on
120
+ `journal` alone and resolves; one strict apply by the earliest deadline, or a
121
+ strict flush before then, applies every record appended since the last apply,
122
+ in order, and deletes them. `whenDurable()` resolves once the groups flushed
123
+ so far are applied.
124
+
125
+ Every apply carries every byte it applies, and the backend applies one at a
126
+ time, so what a power cut leaves is a prefix of the groups: a journal record the
127
+ browser did not keep is a missing number, and recovery at the next open applies
128
+ the consecutive run before it and discards everything after it (details in
129
+ [storage.md §6, *The journal backend*](../db-p2p/docs/storage.md#6-a-write-survives-a-crash-once-a-flush-called-after-it-has-resolved)).
130
+
131
+ Whether a transaction can be strict is the browser's: `IndexedDBRawStorage`
132
+ reports `durability: 'power-loss'` where the browser honours the option (Chrome
133
+ 83+, and Firefox and Safari in their current releases, detected once at
134
+ construction by `supportsStrictDurability`), and `'process-crash'` where it
135
+ ignores it. In the latter the backend journals nothing and applies each group
136
+ at once as one relaxed transaction, and the node's start-up line says such a
137
+ store cannot keep the window.
138
+
139
+ What a crash loses, with strict transactions:
140
+
141
+ | Crash | Lost |
142
+ |---|---|
143
+ | the tab, or the browser's process | a group not yet flushed, still in memory; nothing a flush has resolved for: a completed transaction survives the page, so a journaled group is applied at the next open |
144
+ | a power cut or operating-system crash | at most the groups still inside their window, always the most recent ones, each whole; nothing a strict flush has resolved for, and nothing once the window has passed |
145
+
146
+ Without strict transactions the first row holds and the second does not: a
147
+ power cut may lose any write the operating system has not written out, and may
148
+ keep a later group while losing an earlier one.
149
+
150
+ Two things sit outside this. Browser storage can be **evicted** under storage
151
+ pressure, which loses the whole database, unless the page holds persistent
152
+ storage (`navigator.storage.persist()`); that is the host's decision and the
153
+ backend cannot tell the difference between eviction and a database that was
154
+ never written. And two tabs over one database run two nodes over one store,
155
+ which [storage.md §5](../db-p2p/docs/storage.md#5-a-store-is-owned-by-exactly-one-process)
156
+ forbids and nothing here enforces.
157
+
158
+ A failed transaction latches the storage: every later write, flush and
159
+ `whenDurable()` rejects with `StoreFailedError` until the page reopens the store
160
+ (rule 5 of the flush contract,
161
+ [storage.md §6](../db-p2p/docs/storage.md#6-a-write-survives-a-crash-once-a-flush-called-after-it-has-resolved)).
162
+
163
+ `IndexedDBKVStore` writes through a `WriteGroup` over its keys the same way:
164
+ `set` and `delete` resolve into memory, and `flush()` commits everything since
165
+ the last flush as one `readwrite` transaction on `kv`, strict where the browser
166
+ supports it — every flush of this store is strict, so nothing of it is ever
167
+ journaled. `whenDurable()` and `close()` are the group's.
168
+
89
169
  ## Identity
90
170
 
91
171
  `loadOrCreateBrowserPeerKey(db, keyName?)` writes the libp2p private key as
92
172
  raw protobuf bytes (`Uint8Array`) under `keyName` in the `kv` store
93
- (default `peer-private-key`). IndexedDB stores typed arrays natively, so no
94
- base64 round-trip is needed. To rotate the identity, delete that one key:
173
+ (default `peer-private-key`), in one transaction that is strict where the
174
+ browser supports it, so a power cut right after first start cannot give the
175
+ node a different peer id next time. IndexedDB stores typed arrays natively, so
176
+ no base64 round-trip is needed. To rotate the identity, delete that one key:
95
177
 
96
178
  ```ts
97
179
  await db.delete('kv', 'peer-private-key');
@@ -107,4 +189,11 @@ indexedDB.deleteDatabase('optimystic');
107
189
 
108
190
  `yarn test` runs the spec suite under [`fake-indexeddb`](https://www.npmjs.com/package/fake-indexeddb)
109
191
  in Node so CI doesn't need a real browser. Production code only uses the
110
- IndexedDB W3C API, so fake-indexeddb is a faithful behavioural surrogate.
192
+ IndexedDB W3C API, so fake-indexeddb is a faithful behavioural surrogate — with
193
+ one gap: it has no disk, so it keeps the durability a transaction asked for and
194
+ does nothing with it, and does not advertise the option on
195
+ `IDBTransaction.prototype`. The tests pass `strictDurability: true` to take the
196
+ path a strict-capable browser takes, and check which durability each
197
+ transaction asked for, not what a disk did. That a strict transaction survives
198
+ a power cut rests on the browser; a device, or a manual check in one, is the
199
+ only real test of it.
package/dist/src/db.d.ts CHANGED
@@ -1,11 +1,18 @@
1
1
  import { type DBSchema, type IDBPDatabase } from 'idb';
2
2
  import type { ActionId, BlockId } from '@optimystic/db-core';
3
+ import type { JournalRecord } from '@optimystic/db-p2p';
4
+ /**
5
+ * The key of the applied-through mark in the `journal` store. A string, where every record's key
6
+ * is a number: IndexedDB orders numbers before strings, so a key range over the numbers never
7
+ * reaches the mark.
8
+ */
9
+ export declare const JOURNAL_MARK_KEY = "applied-through";
3
10
  /**
4
11
  * IndexedDB schema for the Optimystic browser storage backend.
5
12
  *
6
13
  * The six block-storage stores keep their original object stores and compound
7
- * array keys, but their values are now opaque `Uint8Array` blobs: the shared
8
- * `KvRawStorage` kernel owns JSON (de)serialization, so `IndexedDBStoreDriver`
14
+ * array keys, but their values are opaque `Uint8Array` blobs: the shared
15
+ * `KvRawStorage` kernel owns JSON (de)serialization, so `IndexedDBJournalStore`
9
16
  * only ever hands IndexedDB kernel-encoded bytes. IndexedDB stores a
10
17
  * `Uint8Array` natively via structured clone and returns a `Uint8Array`, so the
11
18
  * bytes round-trip without a codec here.
@@ -20,7 +27,11 @@ import type { ActionId, BlockId } from '@optimystic/db-core';
20
27
  * as `revisions`, deliberately NOT the action keyspace (an action id is caller-chosen,
21
28
  * so no reserved id could be relied on).
22
29
  * - `materialized`: materialized block bytes keyed by `[blockId, actionId]`. Deleting
23
- * the row is a driver `delete`, not a stored `undefined`.
30
+ * the row is an entry of a write group with no value, not a stored `undefined`.
31
+ * - `journal`: the write groups appended and not yet applied to the six stores above, each a
32
+ * `JournalRecord` stored by structured clone under its `seq` (no codec: the record's keys are
33
+ * plain objects and its values `Uint8Array`s), and under {@link JOURNAL_MARK_KEY} the number of
34
+ * the last record applied. `IndexedDBJournalStore` owns both; nothing else touches the store.
24
35
  * - `kv`: a generic string keyspace shared by `IndexedDBKVStore` and the
25
36
  * identity helper. Identity keys are stored as raw `Uint8Array` blobs (under
26
37
  * a separate logical store from string-only `IKVStore` data, but the same
@@ -51,13 +62,17 @@ export interface OptimysticWebDB extends DBSchema {
51
62
  key: [BlockId, ActionId];
52
63
  value: Uint8Array;
53
64
  };
65
+ journal: {
66
+ key: number | typeof JOURNAL_MARK_KEY;
67
+ value: JournalRecord | number;
68
+ };
54
69
  kv: {
55
70
  key: string;
56
71
  value: string | Uint8Array;
57
72
  };
58
73
  }
59
74
  export declare const DEFAULT_DB_NAME = "optimystic";
60
- export declare const DEFAULT_DB_VERSION = 2;
75
+ export declare const DEFAULT_DB_VERSION = 3;
61
76
  export type OptimysticWebDBHandle = IDBPDatabase<OptimysticWebDB>;
62
77
  /**
63
78
  * Opens (and creates if necessary) the Optimystic IndexedDB database used by
@@ -1 +1 @@
1
- {"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,KAAK,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,eAAgB,SAAQ,QAAQ;IAChD,QAAQ,EAAE;QACT,GAAG,EAAE,OAAO,CAAC;QACb,KAAK,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,SAAS,EAAE;QACV,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACvB,KAAK,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,OAAO,EAAE;QACR,GAAG,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzB,KAAK,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,YAAY,EAAE;QACb,GAAG,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzB,KAAK,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,MAAM,EAAE;QACP,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACvB,KAAK,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,YAAY,EAAE;QACb,GAAG,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzB,KAAK,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,EAAE,EAAE;QACH,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC;KAC3B,CAAC;CACF;AAED,eAAO,MAAM,eAAe,eAAe,CAAC;AAG5C,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,MAAM,MAAM,qBAAqB,GAAG,YAAY,CAAC,eAAe,CAAC,CAAC;AAElE;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACxC,IAAI,GAAE,MAAwB,EAC9B,OAAO,GAAE,MAA2B,GAClC,OAAO,CAAC,qBAAqB,CAAC,CA0BhC"}
1
+ {"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,KAAK,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,eAAgB,SAAQ,QAAQ;IAChD,QAAQ,EAAE;QACT,GAAG,EAAE,OAAO,CAAC;QACb,KAAK,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,SAAS,EAAE;QACV,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACvB,KAAK,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,OAAO,EAAE;QACR,GAAG,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzB,KAAK,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,YAAY,EAAE;QACb,GAAG,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzB,KAAK,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,MAAM,EAAE;QACP,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACvB,KAAK,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,YAAY,EAAE;QACb,GAAG,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzB,KAAK,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,OAAO,EAAE;QACR,GAAG,EAAE,MAAM,GAAG,OAAO,gBAAgB,CAAC;QACtC,KAAK,EAAE,aAAa,GAAG,MAAM,CAAC;KAC9B,CAAC;IACF,EAAE,EAAE;QACH,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC;KAC3B,CAAC;CACF;AAED,eAAO,MAAM,eAAe,eAAe,CAAC;AAK5C,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,MAAM,MAAM,qBAAqB,GAAG,YAAY,CAAC,eAAe,CAAC,CAAC;AAElE;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACxC,IAAI,GAAE,MAAwB,EAC9B,OAAO,GAAE,MAA2B,GAClC,OAAO,CAAC,qBAAqB,CAAC,CA6BhC"}
package/dist/src/db.js CHANGED
@@ -1,8 +1,16 @@
1
1
  import { openDB } from 'idb';
2
+ /**
3
+ * The key of the applied-through mark in the `journal` store. A string, where every record's key
4
+ * is a number: IndexedDB orders numbers before strings, so a key range over the numbers never
5
+ * reaches the mark.
6
+ */
7
+ export const JOURNAL_MARK_KEY = 'applied-through';
2
8
  export const DEFAULT_DB_NAME = 'optimystic';
3
- // Bumped to 2 when the `proofs` object store was added. The `upgrade` hook is guarded
4
- // by `objectStoreNames.contains`, so an existing v1 database gains only the new store.
5
- export const DEFAULT_DB_VERSION = 2;
9
+ // Bumped to 2 when the `proofs` object store was added and to 3 for `journal`. The `upgrade` hook
10
+ // is guarded by `objectStoreNames.contains`, so an existing database gains only the stores it
11
+ // lacks (backlog `debt-indexeddb-version-upgrade-is-untested-and-unhandled` owns testing that, and
12
+ // the open that another tab's older connection blocks).
13
+ export const DEFAULT_DB_VERSION = 3;
6
14
  /**
7
15
  * Opens (and creates if necessary) the Optimystic IndexedDB database used by
8
16
  * `IndexedDBRawStorage`, `IndexedDBKVStore`, and `loadOrCreateBrowserPeerKey`.
@@ -31,6 +39,9 @@ export async function openOptimysticWebDb(name = DEFAULT_DB_NAME, version = DEFA
31
39
  if (!db.objectStoreNames.contains('materialized')) {
32
40
  db.createObjectStore('materialized');
33
41
  }
42
+ if (!db.objectStoreNames.contains('journal')) {
43
+ db.createObjectStore('journal');
44
+ }
34
45
  if (!db.objectStoreNames.contains('kv')) {
35
46
  db.createObjectStore('kv');
36
47
  }
@@ -1 +1 @@
1
- {"version":3,"file":"db.js","sourceRoot":"","sources":["../../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAoC,MAAM,KAAK,CAAC;AA4D/D,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC;AAC5C,sFAAsF;AACtF,uFAAuF;AACvF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAIpC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACxC,OAAe,eAAe,EAC9B,UAAkB,kBAAkB;IAEpC,OAAO,MAAM,CAAkB,IAAI,EAAE,OAAO,EAAE;QAC7C,OAAO,CAAC,EAAE;YACT,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC/C,EAAE,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC;YAClC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;gBAChD,EAAE,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;YACnC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC9C,EAAE,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;YACjC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;gBACnD,EAAE,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC;YACtC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC7C,EAAE,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;YAChC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;gBACnD,EAAE,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC;YACtC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzC,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;YAC5B,CAAC;QACF,CAAC;KACD,CAAC,CAAC;AACJ,CAAC"}
1
+ {"version":3,"file":"db.js","sourceRoot":"","sources":["../../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAoC,MAAM,KAAK,CAAC;AAI/D;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;AAmElD,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC;AAC5C,kGAAkG;AAClG,8FAA8F;AAC9F,mGAAmG;AACnG,wDAAwD;AACxD,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAIpC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACxC,OAAe,eAAe,EAC9B,UAAkB,kBAAkB;IAEpC,OAAO,MAAM,CAAkB,IAAI,EAAE,OAAO,EAAE;QAC7C,OAAO,CAAC,EAAE;YACT,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC/C,EAAE,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC;YAClC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;gBAChD,EAAE,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;YACnC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC9C,EAAE,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;YACjC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;gBACnD,EAAE,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC;YACtC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC7C,EAAE,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;YAChC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;gBACnD,EAAE,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC;YACtC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC9C,EAAE,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;YACjC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzC,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;YAC5B,CAAC;QACF,CAAC;KACD,CAAC,CAAC;AACJ,CAAC"}
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Whether this runtime's IndexedDB honours `IDBTransactionOptions.durability`. A browser that does
3
+ * exposes the durability a transaction was given as `IDBTransaction.durability`, an accessor on
4
+ * the prototype (Chrome 83+, and Firefox and Safari in their current releases); one that does not
5
+ * ignores the option and commits every transaction at its default, which current browsers treat
6
+ * as relaxed. Asked once per store, at construction, since a store's `durability` never changes
7
+ * over its life.
8
+ *
9
+ * `fake-indexeddb` keeps the durability a transaction asked for as an own property of the
10
+ * transaction and puts nothing on the prototype, so under it this answers false and the tests
11
+ * override it with `strictDurability: true`.
12
+ */
13
+ export declare function supportsStrictDurability(): boolean;
14
+ /** The option every store of this package takes: whether the transactions that must reach the disk ask for strict durability. */
15
+ export interface IndexedDBDurabilityOptions {
16
+ /**
17
+ * Whether a transaction that must survive a power cut asks for `durability: 'strict'`. Defaults to
18
+ * {@link supportsStrictDurability}. Tests set it, since `fake-indexeddb` honours the option
19
+ * without advertising it; a host has no reason to.
20
+ */
21
+ readonly strictDurability?: boolean;
22
+ }
23
+ export declare function resolveStrictDurability(options: IndexedDBDurabilityOptions): boolean;
24
+ /**
25
+ * The durability a transaction asks for: `'strict'` for one that must be on the disk before it
26
+ * completes, where the browser supports it, and `'relaxed'` otherwise — what every current
27
+ * browser's default already is, and what a browser without the option does whatever is asked.
28
+ */
29
+ export declare function transactionDurability(strict: boolean): IDBTransactionDurability;
30
+ //# sourceMappingURL=durability.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"durability.d.ts","sourceRoot":"","sources":["../../src/durability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED,iIAAiI;AACjI,MAAM,WAAW,0BAA0B;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAEpF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,wBAAwB,CAE/E"}
@@ -0,0 +1,27 @@
1
+ /**
2
+ * Whether this runtime's IndexedDB honours `IDBTransactionOptions.durability`. A browser that does
3
+ * exposes the durability a transaction was given as `IDBTransaction.durability`, an accessor on
4
+ * the prototype (Chrome 83+, and Firefox and Safari in their current releases); one that does not
5
+ * ignores the option and commits every transaction at its default, which current browsers treat
6
+ * as relaxed. Asked once per store, at construction, since a store's `durability` never changes
7
+ * over its life.
8
+ *
9
+ * `fake-indexeddb` keeps the durability a transaction asked for as an own property of the
10
+ * transaction and puts nothing on the prototype, so under it this answers false and the tests
11
+ * override it with `strictDurability: true`.
12
+ */
13
+ export function supportsStrictDurability() {
14
+ return typeof IDBTransaction !== 'undefined' && 'durability' in IDBTransaction.prototype;
15
+ }
16
+ export function resolveStrictDurability(options) {
17
+ return options.strictDurability ?? supportsStrictDurability();
18
+ }
19
+ /**
20
+ * The durability a transaction asks for: `'strict'` for one that must be on the disk before it
21
+ * completes, where the browser supports it, and `'relaxed'` otherwise — what every current
22
+ * browser's default already is, and what a browser without the option does whatever is asked.
23
+ */
24
+ export function transactionDurability(strict) {
25
+ return strict ? 'strict' : 'relaxed';
26
+ }
27
+ //# sourceMappingURL=durability.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"durability.js","sourceRoot":"","sources":["../../src/durability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,wBAAwB;IACvC,OAAO,OAAO,cAAc,KAAK,WAAW,IAAI,YAAY,IAAI,cAAc,CAAC,SAAS,CAAC;AAC1F,CAAC;AAYD,MAAM,UAAU,uBAAuB,CAAC,OAAmC;IAC1E,OAAO,OAAO,CAAC,gBAAgB,IAAI,wBAAwB,EAAE,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAe;IACpD,OAAO,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;AACtC,CAAC"}
@@ -1,9 +1,12 @@
1
1
  import type { PrivateKey } from '@libp2p/interface';
2
2
  import type { OptimysticWebDBHandle } from './db.js';
3
+ import { type IndexedDBDurabilityOptions } from './durability.js';
3
4
  export declare const DEFAULT_PEER_KEY_NAME = "peer-private-key";
4
5
  /**
5
6
  * Loads the persisted browser peer's libp2p private key, or generates a fresh
6
- * Ed25519 key on first call and persists it.
7
+ * Ed25519 key on first call and persists it in one transaction that is strict
8
+ * where the browser supports it, so a power cut right after first start cannot
9
+ * give the node a different peer id next time. An existing key is read as it is.
7
10
  *
8
11
  * Stores the key as raw protobuf bytes (a `Uint8Array`) under `keyName` in the
9
12
  * `kv` object store. IndexedDB stores typed arrays natively — no base64 round-trip.
@@ -11,5 +14,5 @@ export declare const DEFAULT_PEER_KEY_NAME = "peer-private-key";
11
14
  * The returned `PrivateKey` can be passed directly to `createLibp2pNode({ privateKey })`,
12
15
  * giving a browser peer a stable, reload-surviving identity.
13
16
  */
14
- export declare function loadOrCreateBrowserPeerKey(db: OptimysticWebDBHandle, keyName?: string): Promise<PrivateKey>;
17
+ export declare function loadOrCreateBrowserPeerKey(db: OptimysticWebDBHandle, keyName?: string, options?: IndexedDBDurabilityOptions): Promise<PrivateKey>;
15
18
  //# sourceMappingURL=identity.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/identity.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAErD,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD;;;;;;;;;GASG;AACH,wBAAsB,0BAA0B,CAC/C,EAAE,EAAE,qBAAqB,EACzB,OAAO,GAAE,MAA8B,GACrC,OAAO,CAAC,UAAU,CAAC,CASrB"}
1
+ {"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/identity.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAkD,KAAK,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAElH,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,wBAAsB,0BAA0B,CAC/C,EAAE,EAAE,qBAAqB,EACzB,OAAO,GAAE,MAA8B,EACvC,OAAO,GAAE,0BAA+B,GACtC,OAAO,CAAC,UAAU,CAAC,CAUrB"}
@@ -1,8 +1,11 @@
1
1
  import { generateKeyPair, privateKeyFromProtobuf, privateKeyToProtobuf } from '@libp2p/crypto/keys';
2
+ import { resolveStrictDurability, transactionDurability } from './durability.js';
2
3
  export const DEFAULT_PEER_KEY_NAME = 'peer-private-key';
3
4
  /**
4
5
  * Loads the persisted browser peer's libp2p private key, or generates a fresh
5
- * Ed25519 key on first call and persists it.
6
+ * Ed25519 key on first call and persists it in one transaction that is strict
7
+ * where the browser supports it, so a power cut right after first start cannot
8
+ * give the node a different peer id next time. An existing key is read as it is.
6
9
  *
7
10
  * Stores the key as raw protobuf bytes (a `Uint8Array`) under `keyName` in the
8
11
  * `kv` object store. IndexedDB stores typed arrays natively — no base64 round-trip.
@@ -10,14 +13,15 @@ export const DEFAULT_PEER_KEY_NAME = 'peer-private-key';
10
13
  * The returned `PrivateKey` can be passed directly to `createLibp2pNode({ privateKey })`,
11
14
  * giving a browser peer a stable, reload-surviving identity.
12
15
  */
13
- export async function loadOrCreateBrowserPeerKey(db, keyName = DEFAULT_PEER_KEY_NAME) {
16
+ export async function loadOrCreateBrowserPeerKey(db, keyName = DEFAULT_PEER_KEY_NAME, options = {}) {
14
17
  const stored = await db.get('kv', keyName);
15
18
  if (stored instanceof Uint8Array) {
16
19
  return privateKeyFromProtobuf(stored);
17
20
  }
18
21
  const key = await generateKeyPair('Ed25519');
19
22
  const bytes = privateKeyToProtobuf(key);
20
- await db.put('kv', bytes, keyName);
23
+ const tx = db.transaction('kv', 'readwrite', { durability: transactionDurability(resolveStrictDurability(options)) });
24
+ await Promise.all([tx.store.put(bytes, keyName), tx.done]);
21
25
  return key;
22
26
  }
23
27
  //# sourceMappingURL=identity.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAIpG,MAAM,CAAC,MAAM,qBAAqB,GAAG,kBAAkB,CAAC;AAExD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC/C,EAAyB,EACzB,UAAkB,qBAAqB;IAEvC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC3C,IAAI,MAAM,YAAY,UAAU,EAAE,CAAC;QAClC,OAAO,sBAAsB,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,eAAe,CAAC,SAAS,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,GAAG,CAAC;AACZ,CAAC"}
1
+ {"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGpG,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAmC,MAAM,iBAAiB,CAAC;AAElH,MAAM,CAAC,MAAM,qBAAqB,GAAG,kBAAkB,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC/C,EAAyB,EACzB,UAAkB,qBAAqB,EACvC,UAAsC,EAAE;IAExC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC3C,IAAI,MAAM,YAAY,UAAU,EAAE,CAAC;QAClC,OAAO,sBAAsB,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,eAAe,CAAC,SAAS,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE,UAAU,EAAE,qBAAqB,CAAC,uBAAuB,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACtH,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3D,OAAO,GAAG,CAAC;AACZ,CAAC"}
@@ -1,4 +1,5 @@
1
1
  export * from './db.js';
2
+ export * from './durability.js';
2
3
  export * from './indexeddb-storage.js';
3
4
  export * from './indexeddb-kv-store.js';
4
5
  export * from './identity.js';
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,eAAe,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,eAAe,CAAC"}
package/dist/src/index.js CHANGED
@@ -1,4 +1,5 @@
1
1
  export * from './db.js';
2
+ export * from './durability.js';
2
3
  export * from './indexeddb-storage.js';
3
4
  export * from './indexeddb-kv-store.js';
4
5
  export * from './identity.js';
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,eAAe,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,eAAe,CAAC"}
@@ -1,20 +1,43 @@
1
- import type { IKVStore } from '@optimystic/db-p2p';
1
+ import { type FlushOptions, type IKVStore, type WriteGroupOptions } from '@optimystic/db-p2p';
2
2
  import type { OptimysticWebDBHandle } from './db.js';
3
+ import { type IndexedDBDurabilityOptions } from './durability.js';
4
+ /** The write group's options (`idleFlushMs`, `maxUnsyncedBytes`, the test-only `setTimer`), and whether to ask for strict transactions. */
5
+ export type IndexedDBKVStoreOptions = WriteGroupOptions & IndexedDBDurabilityOptions;
3
6
  /**
4
7
  * IndexedDB-backed `IKVStore` adapter for browser peers.
5
8
  *
6
- * Stored keys are namespaced with `prefix` so the `kv` object store can be
7
- * shared with the identity helper without collisions. `list(prefix)` uses a
8
- * range-bounded key cursor — never `getAllKeys()` — so a large `kv` store
9
- * does not pay an O(n) JS-side filter cost.
9
+ * Stored keys are namespaced with `prefix` so the `kv` object store can be shared with the identity
10
+ * helper without collisions. `list(prefix)` uses a range-bounded key cursor — never `getAllKeys()` —
11
+ * so a large `kv` store does not pay an O(n) JS-side filter cost.
12
+ *
13
+ * Writes go through a {@link WriteGroup} over the plain keys, as `FileKVStore` does: a `set` or
14
+ * `delete` resolves into memory, served from there to `get` and `list`, and `flush()` commits
15
+ * everything written since the last flush as ONE `readwrite` transaction on `kv`, strict where the
16
+ * browser supports it (`supportsStrictDurability`), so the writes are on the disk before the flush
17
+ * resolves. Every flush the node makes of this store is strict, and so is the group's own idle
18
+ * flush, so there is no relaxed path to journal: a flush given a window is treated as strict, as a
19
+ * store that cannot defer a sync treats every window. A failed commit latches the store, after which
20
+ * every write and flush throws `StoreFailedError` (rule 5 of the flush contract on
21
+ * `RawStoreDriver.flush`); reads keep serving the overlay.
10
22
  */
11
23
  export declare class IndexedDBKVStore implements IKVStore {
12
24
  private readonly db;
13
25
  private readonly prefix;
14
- constructor(db: OptimysticWebDBHandle, prefix?: string);
26
+ private readonly group;
27
+ private readonly strict;
28
+ constructor(db: OptimysticWebDBHandle, prefix?: string, options?: IndexedDBKVStoreOptions);
15
29
  get(key: string): Promise<string | undefined>;
16
30
  set(key: string, value: string): Promise<void>;
17
31
  delete(key: string): Promise<void>;
32
+ /** Every key under `prefix`: the store's, plus those written and not yet flushed, less those deleted and not yet flushed. */
18
33
  list(prefix: string): Promise<string[]>;
34
+ /** Make every write resolved before this call durable: one transaction, strict where supported, whatever `options.withinMs` says. The contract is `RawStoreDriver.flush`'s. */
35
+ flush(options?: FlushOptions): Promise<void>;
36
+ /** Resolves once every write covered by a flush that resolved before this call is durable; `RawStoreDriver.whenDurable`'s contract. */
37
+ whenDurable(): Promise<void>;
38
+ /** Flush what is still held and disarm the idle timer. The host closes the shared handle after this resolves. */
39
+ close(): Promise<void>;
40
+ private commit;
41
+ private listStored;
19
42
  }
20
43
  //# sourceMappingURL=indexeddb-kv-store.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"indexeddb-kv-store.d.ts","sourceRoot":"","sources":["../../src/indexeddb-kv-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAErD;;;;;;;GAOG;AACH,qBAAa,gBAAiB,YAAW,QAAQ;IAE/C,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,EAAE,EAAE,qBAAqB,EACzB,MAAM,GAAE,MAA0B;IAG9C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAK7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAkB7C"}
1
+ {"version":3,"file":"indexeddb-kv-store.d.ts","sourceRoot":"","sources":["../../src/indexeddb-kv-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,KAAK,YAAY,EAAE,KAAK,QAAQ,EAAwB,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACrJ,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAkD,KAAK,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAElH,2IAA2I;AAC3I,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,GAAG,0BAA0B,CAAC;AAQrF;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,gBAAiB,YAAW,QAAQ;IAK/C,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IALxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;gBAGf,EAAE,EAAE,qBAAqB,EACzB,MAAM,GAAE,MAA0B,EACnD,OAAO,GAAE,uBAA4B;IAUhC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAO7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,6HAA6H;IACvH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAY7C,+KAA+K;IAC/K,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C,uIAAuI;IACvI,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,iHAAiH;IACjH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAIR,MAAM;YAUN,UAAU;CAkBxB"}
@@ -1,29 +1,91 @@
1
+ import { WriteGroup } from '@optimystic/db-p2p';
2
+ import { resolveStrictDurability, transactionDurability } from './durability.js';
3
+ const encoder = new TextEncoder();
4
+ // Built on first use rather than at module load, like every other `TextDecoder` in library source
5
+ // (see NO_MODULE_SCOPE_TEXT_DECODER in eslint.config.js).
6
+ let decoderInstance;
7
+ const decoder = () => decoderInstance ??= new TextDecoder();
1
8
  /**
2
9
  * IndexedDB-backed `IKVStore` adapter for browser peers.
3
10
  *
4
- * Stored keys are namespaced with `prefix` so the `kv` object store can be
5
- * shared with the identity helper without collisions. `list(prefix)` uses a
6
- * range-bounded key cursor — never `getAllKeys()` — so a large `kv` store
7
- * does not pay an O(n) JS-side filter cost.
11
+ * Stored keys are namespaced with `prefix` so the `kv` object store can be shared with the identity
12
+ * helper without collisions. `list(prefix)` uses a range-bounded key cursor — never `getAllKeys()` —
13
+ * so a large `kv` store does not pay an O(n) JS-side filter cost.
14
+ *
15
+ * Writes go through a {@link WriteGroup} over the plain keys, as `FileKVStore` does: a `set` or
16
+ * `delete` resolves into memory, served from there to `get` and `list`, and `flush()` commits
17
+ * everything written since the last flush as ONE `readwrite` transaction on `kv`, strict where the
18
+ * browser supports it (`supportsStrictDurability`), so the writes are on the disk before the flush
19
+ * resolves. Every flush the node makes of this store is strict, and so is the group's own idle
20
+ * flush, so there is no relaxed path to journal: a flush given a window is treated as strict, as a
21
+ * store that cannot defer a sync treats every window. A failed commit latches the store, after which
22
+ * every write and flush throws `StoreFailedError` (rule 5 of the flush contract on
23
+ * `RawStoreDriver.flush`); reads keep serving the overlay.
8
24
  */
9
25
  export class IndexedDBKVStore {
10
26
  db;
11
27
  prefix;
12
- constructor(db, prefix = 'optimystic:txn:') {
28
+ group;
29
+ strict;
30
+ constructor(db, prefix = 'optimystic:txn:', options = {}) {
13
31
  this.db = db;
14
32
  this.prefix = prefix;
33
+ this.strict = resolveStrictDurability(options);
34
+ this.group = new WriteGroup(key => key, {
35
+ commit: entries => this.commit(entries),
36
+ // Every commit is as durable as this store can make it when it resolves, so nothing is ever owed a sync.
37
+ sync: () => Promise.resolve(),
38
+ }, options);
15
39
  }
16
40
  async get(key) {
41
+ const held = this.group.lookup(key);
42
+ if (held !== undefined)
43
+ return held === null ? undefined : decoder().decode(held);
17
44
  const value = await this.db.get('kv', this.prefix + key);
18
45
  return typeof value === 'string' ? value : undefined;
19
46
  }
20
47
  async set(key, value) {
21
- await this.db.put('kv', value, this.prefix + key);
48
+ this.group.put(key, encoder.encode(value));
22
49
  }
23
50
  async delete(key) {
24
- await this.db.delete('kv', this.prefix + key);
51
+ this.group.delete(key);
25
52
  }
53
+ /** Every key under `prefix`: the store's, plus those written and not yet flushed, less those deleted and not yet flushed. */
26
54
  async list(prefix) {
55
+ // Taken before awaiting the store: a commit resolving meanwhile drops entries from the overlay
56
+ // that the listing below may have been taken without.
57
+ const held = [...this.group.entries()].filter(([key]) => key.startsWith(prefix));
58
+ const keys = new Set(await this.listStored(prefix));
59
+ for (const [key, value] of held) {
60
+ if (value === null)
61
+ keys.delete(key);
62
+ else
63
+ keys.add(key);
64
+ }
65
+ return [...keys];
66
+ }
67
+ /** Make every write resolved before this call durable: one transaction, strict where supported, whatever `options.withinMs` says. The contract is `RawStoreDriver.flush`'s. */
68
+ flush(options) {
69
+ return this.group.flush(options);
70
+ }
71
+ /** Resolves once every write covered by a flush that resolved before this call is durable; `RawStoreDriver.whenDurable`'s contract. */
72
+ whenDurable() {
73
+ return this.group.whenDurable();
74
+ }
75
+ /** Flush what is still held and disarm the idle timer. The host closes the shared handle after this resolves. */
76
+ close() {
77
+ return this.group.close();
78
+ }
79
+ async commit(entries) {
80
+ const tx = this.db.transaction('kv', 'readwrite', { durability: transactionDurability(this.strict) });
81
+ // Queued synchronously and awaited together with the transaction: IndexedDB commits a transaction that is left idle.
82
+ const requests = entries.map(({ key, value }) => value === undefined
83
+ ? tx.store.delete(this.prefix + key)
84
+ : tx.store.put(decoder().decode(value), this.prefix + key));
85
+ await Promise.all([...requests, tx.done]);
86
+ return { durable: Promise.resolve() };
87
+ }
88
+ async listStored(prefix) {
27
89
  const fullPrefix = this.prefix + prefix;
28
90
  // '￿' is the highest BMP code unit; appending it produces a string
29
91
  // that is >= every string starting with `fullPrefix`. IndexedDB compares
@@ -1 +1 @@
1
- {"version":3,"file":"indexeddb-kv-store.js","sourceRoot":"","sources":["../../src/indexeddb-kv-store.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,MAAM,OAAO,gBAAgB;IAEV;IACA;IAFlB,YACkB,EAAyB,EACzB,SAAiB,iBAAiB;QADlC,OAAE,GAAF,EAAE,CAAuB;QACzB,WAAM,GAAN,MAAM,CAA4B;IACjD,CAAC;IAEJ,KAAK,CAAC,GAAG,CAAC,GAAW;QACpB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;QACzD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACtD,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAa;QACnC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;IACnD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACvB,MAAM,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;IAC/C,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAc;QACxB,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACxC,mEAAmE;QACnE,yEAAyE;QACzE,wDAAwD;QACxD,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,UAAU,EAAE,UAAU,GAAG,GAAG,CAAC,CAAC;QAC9D,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACjD,MAAM,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,IAAI,GAAa,EAAE,CAAC;QAC1B,IAAI,MAAM,GAAG,MAAM,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAC9C,OAAO,MAAM,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,MAAM,CAAC,GAAa,CAAC;YACrC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;YAC7C,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;QAClC,CAAC;QACD,MAAM,EAAE,CAAC,IAAI,CAAC;QACd,OAAO,IAAI,CAAC;IACb,CAAC;CACD"}
1
+ {"version":3,"file":"indexeddb-kv-store.js","sourceRoot":"","sources":["../../src/indexeddb-kv-store.ts"],"names":[],"mappings":"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"}