@optimystic/db-core 1.5.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (157) hide show
  1. package/README.md +336 -336
  2. package/dist/src/cluster/structs.d.ts +37 -0
  3. package/dist/src/cluster/structs.d.ts.map +1 -1
  4. package/dist/src/cluster/structs.js +13 -0
  5. package/dist/src/cluster/structs.js.map +1 -1
  6. package/dist/src/collection/collection.d.ts +44 -4
  7. package/dist/src/collection/collection.d.ts.map +1 -1
  8. package/dist/src/collection/collection.js +95 -14
  9. package/dist/src/collection/collection.js.map +1 -1
  10. package/dist/src/log/log.d.ts +41 -8
  11. package/dist/src/log/log.d.ts.map +1 -1
  12. package/dist/src/log/log.js +15 -10
  13. package/dist/src/log/log.js.map +1 -1
  14. package/dist/src/testing/test-transactor.d.ts +36 -0
  15. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  16. package/dist/src/testing/test-transactor.js +49 -0
  17. package/dist/src/testing/test-transactor.js.map +1 -1
  18. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  19. package/dist/src/transaction/coordinator.js +26 -9
  20. package/dist/src/transaction/coordinator.js.map +1 -1
  21. package/package.json +1 -1
  22. package/src/blocks/block-store.ts +31 -31
  23. package/src/blocks/block-types.ts +11 -11
  24. package/src/blocks/index.ts +5 -5
  25. package/src/blocks/structs.ts +17 -17
  26. package/src/btree/btree.ts +872 -872
  27. package/src/btree/independent-trunk.ts +53 -53
  28. package/src/btree/index.ts +5 -5
  29. package/src/btree/key-range.ts +15 -15
  30. package/src/btree/keyset.ts +6 -6
  31. package/src/btree/nodes.ts +25 -25
  32. package/src/btree/path.ts +37 -37
  33. package/src/btree/tree-block.ts +11 -11
  34. package/src/btree/trunk.ts +14 -14
  35. package/src/chain/chain-nodes.ts +26 -26
  36. package/src/chain/chain.ts +349 -349
  37. package/src/chain/index.ts +3 -3
  38. package/src/cluster/i-cluster.ts +6 -6
  39. package/src/cluster/index.ts +3 -3
  40. package/src/cluster/structs.ts +38 -0
  41. package/src/cohort-topic/addressing.ts +120 -120
  42. package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
  43. package/src/cohort-topic/antidos/index.ts +5 -5
  44. package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
  45. package/src/cohort-topic/antidos/replay-guard.ts +146 -146
  46. package/src/cohort-topic/antidos/topic-budget.ts +160 -160
  47. package/src/cohort-topic/antiflood/index.ts +2 -2
  48. package/src/cohort-topic/antiflood/invariants.ts +108 -108
  49. package/src/cohort-topic/antiflood/jitter.ts +117 -117
  50. package/src/cohort-topic/coldstart.ts +237 -237
  51. package/src/cohort-topic/dmax.ts +88 -88
  52. package/src/cohort-topic/gossip/bus.ts +254 -254
  53. package/src/cohort-topic/gossip/index.ts +3 -3
  54. package/src/cohort-topic/gossip/records.ts +45 -45
  55. package/src/cohort-topic/gossip/view.ts +91 -91
  56. package/src/cohort-topic/index.ts +20 -20
  57. package/src/cohort-topic/load/barometer.ts +134 -134
  58. package/src/cohort-topic/load/index.ts +1 -1
  59. package/src/cohort-topic/member-engine.ts +430 -430
  60. package/src/cohort-topic/membership/index.ts +3 -3
  61. package/src/cohort-topic/membership/publisher.ts +163 -163
  62. package/src/cohort-topic/membership/source.ts +41 -41
  63. package/src/cohort-topic/ports.ts +157 -157
  64. package/src/cohort-topic/promotion.ts +477 -477
  65. package/src/cohort-topic/registration/bytes.ts +37 -37
  66. package/src/cohort-topic/registration/handoff.ts +154 -154
  67. package/src/cohort-topic/registration/index.ts +6 -6
  68. package/src/cohort-topic/registration/renewal.ts +495 -495
  69. package/src/cohort-topic/registration/sharding.ts +61 -61
  70. package/src/cohort-topic/registration/store.ts +81 -81
  71. package/src/cohort-topic/registration/types.ts +91 -91
  72. package/src/cohort-topic/ring-hash.ts +50 -50
  73. package/src/cohort-topic/service.ts +416 -416
  74. package/src/cohort-topic/sig/index.ts +2 -2
  75. package/src/cohort-topic/sig/payloads.ts +59 -59
  76. package/src/cohort-topic/sig/threshold.ts +64 -64
  77. package/src/cohort-topic/tiers.ts +74 -74
  78. package/src/cohort-topic/traffic.ts +233 -233
  79. package/src/cohort-topic/walk.ts +326 -326
  80. package/src/cohort-topic/willingness.ts +237 -237
  81. package/src/cohort-topic/wire/index.ts +18 -18
  82. package/src/cohort-topic/wire/payloads.ts +126 -126
  83. package/src/collection/action.ts +48 -48
  84. package/src/collection/collection-type-registry.ts +37 -37
  85. package/src/collection/collection.ts +2203 -2118
  86. package/src/collection/index.ts +4 -4
  87. package/src/collections/diary/index.ts +2 -2
  88. package/src/collections/diary/struct.ts +3 -3
  89. package/src/collections/index.ts +2 -2
  90. package/src/collections/tree/collection-trunk.ts +25 -25
  91. package/src/collections/tree/index.ts +2 -2
  92. package/src/collections/tree/readme.md +55 -55
  93. package/src/log/index.ts +2 -2
  94. package/src/log/log.ts +304 -268
  95. package/src/log/struct.ts +165 -165
  96. package/src/matchmaking/capability-filter.ts +45 -45
  97. package/src/matchmaking/config.ts +98 -98
  98. package/src/matchmaking/index.ts +21 -21
  99. package/src/matchmaking/multi-cohort-seeker.ts +234 -234
  100. package/src/matchmaking/provider.ts +123 -123
  101. package/src/matchmaking/query-eval.ts +105 -105
  102. package/src/matchmaking/seeker-walk.ts +127 -127
  103. package/src/matchmaking/seeker.ts +86 -86
  104. package/src/matchmaking/topic-anchor.ts +90 -90
  105. package/src/matchmaking/voting-quorum.ts +394 -394
  106. package/src/network/i-peer-network.ts +25 -25
  107. package/src/network/repo-protocol.ts +13 -13
  108. package/src/network/types.ts +37 -37
  109. package/src/reactivity/backfill.ts +220 -220
  110. package/src/reactivity/backpressure.ts +191 -191
  111. package/src/reactivity/checkpoint.ts +308 -308
  112. package/src/reactivity/config.ts +172 -172
  113. package/src/reactivity/dedupe.ts +132 -132
  114. package/src/reactivity/forwarder.ts +87 -87
  115. package/src/reactivity/index.ts +34 -34
  116. package/src/reactivity/notification.ts +123 -123
  117. package/src/reactivity/policy.ts +79 -79
  118. package/src/reactivity/push-state.ts +310 -310
  119. package/src/reactivity/recover.ts +153 -153
  120. package/src/reactivity/replay-buffer.ts +141 -141
  121. package/src/reactivity/resume.ts +549 -549
  122. package/src/reactivity/rotation.ts +415 -415
  123. package/src/reactivity/subscriber.ts +132 -132
  124. package/src/reactivity/subscription.ts +66 -66
  125. package/src/reactivity/topic-anchor.ts +71 -71
  126. package/src/reactivity/verify.ts +73 -73
  127. package/src/reactivity/wire-validate.ts +13 -13
  128. package/src/testing/async-wait.ts +65 -65
  129. package/src/testing/index.ts +2 -2
  130. package/src/testing/test-transactor.ts +62 -0
  131. package/src/transaction/actions-engine.ts +68 -68
  132. package/src/transaction/coordinator.ts +28 -11
  133. package/src/transaction/index.ts +52 -52
  134. package/src/transaction/operations-hash.ts +196 -196
  135. package/src/transaction/read-dependency-collector.ts +78 -78
  136. package/src/transaction/session.ts +238 -238
  137. package/src/transaction/transaction.ts +442 -442
  138. package/src/transaction/validator.ts +197 -197
  139. package/src/transactor/block-floors.ts +126 -126
  140. package/src/transactor/index.ts +6 -6
  141. package/src/transactor/network-transactor.ts +1545 -1545
  142. package/src/transform/atomic-proxy.ts +92 -92
  143. package/src/transform/cache-source.ts +370 -370
  144. package/src/transform/helpers.ts +164 -164
  145. package/src/transform/index.ts +7 -7
  146. package/src/transform/struct.ts +21 -21
  147. package/src/utility/actor.ts +62 -62
  148. package/src/utility/backoff.ts +95 -95
  149. package/src/utility/batch-coordinator.ts +191 -191
  150. package/src/utility/ensured.ts +32 -32
  151. package/src/utility/groupby.ts +18 -18
  152. package/src/utility/hash-string.ts +14 -14
  153. package/src/utility/is-record-empty.ts +5 -5
  154. package/src/utility/latches.ts +42 -42
  155. package/src/utility/lru-map.ts +60 -60
  156. package/src/utility/nameof.ts +7 -7
  157. package/src/utility/pending.ts +43 -43
@@ -1,872 +1,872 @@
1
- import { Path, PathBranch } from "./path.js";
2
- import type { ITreeTrunk, KeyRange, getTrunkFunc } from "./index.js";
3
- import type { BlockId, BlockStore } from "../blocks/index.js";
4
- import { apply, get } from "../blocks/index.js";
5
- import { TreeLeafBlockType, TreeBranchBlockType, entries$, nodes$, partitions$ } from "./nodes.js";
6
- import type { BranchNode, ITreeNode, LeafNode } from "./nodes.js";
7
- import type { TreeBlock } from "./tree-block.js";
8
- import { AtomicProxy, type AtomicScope } from "../transform/atomic-proxy.js";
9
-
10
- export const NodeCapacity = 64;
11
-
12
- /**
13
- * Represents a lightweight B+(ish)Tree (data at leaves, but no linked list of leaves).
14
- * Allows for efficient storage and retrieval of data in a sorted manner.
15
- * @template TEntry The type of entries stored in the B-tree.
16
- * @template TKey The type of keys used for indexing the entries. This might be an element of TEntry, or TEntry itself.
17
- */
18
- export class BTree<TKey, TEntry> {
19
- protected _version = 0; // only for path invalidation
20
- private _proxy?: AtomicProxy<ITreeNode>;
21
-
22
- /**
23
- * @param [compare=(a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0] a comparison function for keys. The default uses < and > operators.
24
- * @param [keyFromEntry=(entry: TEntry) => entry as unknown as TKey] a function to extract the key from an entry. The default assumes the key is the entry itself.
25
- */
26
- constructor(
27
- public readonly store: BlockStore<ITreeNode>,
28
- public readonly trunk: ITreeTrunk,
29
- public readonly keyFromEntry = (entry: TEntry) => entry as unknown as TKey,
30
- public readonly compare = (a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0 as number,
31
- public readonly nodeCapacity = NodeCapacity,
32
- ) {
33
- }
34
-
35
- private atomic<T>(fn: (scope?: AtomicScope) => Promise<T>, parent?: AtomicScope): Promise<T> {
36
- return this._proxy ? this._proxy.atomic(fn, parent) : fn(parent);
37
- }
38
-
39
- static createRoot(
40
- store: BlockStore<ITreeNode>
41
- ) {
42
- return newLeafNode(store, []);
43
- }
44
-
45
- static create<TKey, TEntry>(
46
- store: BlockStore<ITreeNode | TreeBlock>,
47
- createTrunk: getTrunkFunc,
48
- keyFromEntry = (entry: TEntry) => entry as unknown as TKey,
49
- // `as number` so the inferred param type is a comparator returning any number, matching the
50
- // constructor above — without it the default narrows to `-1 | 0 | 1` and a perfectly valid
51
- // `(a, b) => a - b` comparator is rejected here but accepted there.
52
- compare = (a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0 as number,
53
- nodeCapacity = NodeCapacity,
54
- newId?: BlockId,
55
- ) {
56
- const proxy = new AtomicProxy(store);
57
- const root = BTree.createRoot(proxy as BlockStore<TreeBlock>);
58
- proxy.insert(root);
59
- const trunk = createTrunk(proxy as BlockStore<TreeBlock>, root.header.id, newId);
60
- const tree = new BTree(proxy, trunk, keyFromEntry, compare, nodeCapacity);
61
- tree._proxy = proxy;
62
- return tree;
63
- }
64
-
65
- /** @returns a path to the first entry (on = false if no entries) */
66
- async first(): Promise<Path<TKey, TEntry>> {
67
- return await this.getFirst(await this.trunk.get());
68
- }
69
-
70
- /** @returns a path to the last entry (on = false if no entries) */
71
- async last(): Promise<Path<TKey, TEntry>> {
72
- return await this.getLast(await this.trunk.get());
73
- }
74
-
75
- /** Attempts to find the given key
76
- * @returns Path to the key or the "crack" before it. If `on` is true on the resulting path, the key was found.
77
- * If `on` is false, next() and prior() can attempt to move to the nearest match.
78
- * @param navigate when true, the interior descent nodes are captured as droppable `navigation`
79
- * reads (see {@link getPath}). DEFAULT false: `find` returns a Path a caller may use to seed a
80
- * range scan (`ascending`/`next`), whose result depends on tree shape, so its structural reads
81
- * must stay retained. Only {@link get} — a point lookup with no such escape — opts in. */
82
- async find(key: TKey, navigate = false): Promise<Path<TKey, TEntry>> {
83
- return await this.getPath(await this.trunk.get(), key, navigate);
84
- }
85
-
86
- /** Retrieves the entry for the given key.
87
- * Use find instead for a path to the key, the nearest match, or as a basis for navigation.
88
- * @returns the entry for the given key if found; undefined otherwise. */
89
- async get(key: TKey): Promise<TEntry | undefined> {
90
- // Value-of-key point lookup: the result depends ONLY on the terminal leaf's content, so the
91
- // interior descent nodes are pure navigation and are dropped from the OCC conflict set. The
92
- // returned Path is consumed by `at` and discarded — it never seeds a scan — so navigate=true
93
- // is safe here (unlike the public `find`).
94
- return this.at(await this.find(key, /* navigate */ true));
95
- }
96
-
97
- /** @returns the entry for the given path if on an entry; undefined otherwise. */
98
- at(path: Path<TKey, TEntry>): TEntry | undefined {
99
- this.validatePath(path);
100
- return path.on ? this.getEntry(path) : undefined;
101
- }
102
-
103
- /** Iterates based on the given range
104
- * WARNING: mutation during iteration will result in an exception
105
- */
106
- async *range(range: KeyRange<TKey>): AsyncIterableIterator<Path<TKey, TEntry>> {
107
- const startPath = range.first
108
- ? await this.findFirst(range)
109
- : (range.isAscending ? await this.first() : await this.last());
110
- const endPath = range.last
111
- ? await this.findLast(range)
112
- : (range.isAscending ? await this.last() : await this.first());
113
- // If the tree is empty or endPath is not on an entry, return early
114
- if (!endPath.on) {
115
- return;
116
- }
117
- const endKey = this.keyFromPath(endPath);
118
- const iterable = range.isAscending
119
- ? this.internalAscending(startPath)
120
- : this.internalDescending(startPath);
121
- const iter = iterable[Symbol.asyncIterator]();
122
- const ascendingFactor = range.isAscending ? 1 : -1;
123
- for await (let path of iter) {
124
- if (!path.on || this.compare(
125
- this.keyFromPath(path),
126
- endKey
127
- ) * ascendingFactor > 0) {
128
- break;
129
- }
130
- yield path;
131
- }
132
- }
133
-
134
- /** @returns true if the given path remains valid; false if the tree has been mutated, invalidating the path. */
135
- isValid(path: Path<TKey, TEntry>) {
136
- return path.version === this._version;
137
- }
138
-
139
- /** Bump the version so every Path handed out before now reports invalid (see {@link isValid}).
140
- * Needed when the tree's data was mutated through a DIFFERENT store binding than this instance —
141
- * e.g. the tree collection's action handler writes through a per-action Atomic store, so this
142
- * read-side btree never sees the mutation and must be told to invalidate outstanding paths. */
143
- invalidatePaths() {
144
- ++this._version;
145
- }
146
-
147
- /**
148
- * Adds a value to the tree. Be sure to check the result, as the tree does not allow duplicate keys.
149
- * Added entries are frozen to ensure immutability
150
- * @returns path to the new (on = true) or conflicting (on = false) row. */
151
- async insert(entry: TEntry): Promise<Path<TKey, TEntry>> {
152
- return this.atomic(async () => {
153
- Object.freeze(entry); // Ensure immutability
154
- const path = await this.internalInsert(entry);
155
- if (path.on) {
156
- path.version = ++this._version;
157
- }
158
- return path;
159
- });
160
- }
161
-
162
- /** Updates the entry at the given path to the given value. Deletes and inserts if the key changes.
163
- * @returns path to resulting entry and whether it was an update (as opposed to an insert).
164
- * * on = true if update/insert succeeded.
165
- * * wasUpdate = true if updated; false if inserted.
166
- * * Returned path is on entry
167
- * * on = false if update/insert failed.
168
- * * wasUpdate = true, given path is not on an entry
169
- * * else newEntry's new key already present; returned path is "near" existing entry */
170
- async updateAt(path: Path<TKey, TEntry>, newEntry: TEntry, parent?: AtomicScope): Promise<[path: Path<TKey, TEntry>, wasUpdate: boolean]> {
171
- return this.atomic(async () => {
172
- this.validatePath(path);
173
- if (path.on) {
174
- Object.freeze(newEntry);
175
- }
176
- const result = await this.internalUpdate(path, newEntry);
177
- if (result[0].on) {
178
- result[0].version = ++this._version;
179
- }
180
- return result;
181
- }, parent);
182
- }
183
-
184
- /** Inserts the entry if it doesn't exist, or updates it if it does.
185
- * The entry is frozen to ensure immutability.
186
- * @returns path to the new entry. on = true if existing; on = false if new. */
187
- async upsert(entry: TEntry): Promise<Path<TKey, TEntry>> {
188
- return this.atomic(async () => {
189
- const path = await this.find(this.keyFromEntry(entry));
190
- Object.freeze(entry);
191
- if (path.on) {
192
- this.updateEntry(path, entry);
193
- } else {
194
- await this.internalInsertAt(path, entry);
195
- }
196
- path.version = ++this._version;
197
- return path;
198
- });
199
- }
200
-
201
- /** Inserts or updates depending on the existence of the given key, using callbacks to generate the new value.
202
- * @param newEntry the new entry to insert if the key doesn't exist.
203
- * @param getUpdated a callback to generate an updated entry if the key does exist. WARNING: mutation in this callback will cause merge to error.
204
- * @returns path to new entry and whether an update or insert attempted.
205
- * If getUpdated callback returns a row that is already present, the resulting path will not be on. */
206
- async merge(newEntry: TEntry, getUpdated: (existing: TEntry) => TEntry): Promise<[path: Path<TKey, TEntry>, wasUpdate: boolean]> {
207
- return this.atomic(async (scope) => {
208
- const newKey = this.keyFromEntry(newEntry);
209
- const path = await this.find(newKey);
210
- if (path.on) {
211
- // Thread this scope into updateAt so the nested call joins this atomic batch
212
- // (reuses the tracker) rather than opening/committing a second scope.
213
- const result = await this.updateAt(path, getUpdated(this.getEntry(path)), scope); // Don't use internalUpdate - need to freeze and check for mutation
214
- // Note: updateAt already increments version, so don't double-increment here
215
- return result;
216
- } else {
217
- await this.internalInsertAt(path, Object.freeze(newEntry));
218
- path.on = true;
219
- path.version = ++this._version;
220
- return [path, false];
221
- }
222
- });
223
- }
224
-
225
- /** Deletes the entry at the given path.
226
- * The on property of the path will be cleared.
227
- * @returns true if the delete succeeded (the key was found); false otherwise.
228
- */
229
- async deleteAt(path: Path<TKey, TEntry>): Promise<boolean> {
230
- return this.atomic(async () => {
231
- this.validatePath(path);
232
- const result = await this.internalDelete(path);
233
- if (result) {
234
- ++this._version;
235
- }
236
- return result;
237
- });
238
- }
239
-
240
- async drop() { // Node: only when a root treeBlock
241
- return this.atomic(async () => {
242
- const root = await this.trunk.get();
243
- for await (const id of this.nodeIds(root)) {
244
- this.store.delete(id);
245
- }
246
- });
247
- }
248
-
249
- /** Iterates forward starting from the path location (inclusive) to the end.
250
- * WARNING: mutation during iteration will result in an exception.
251
- */
252
- ascending(path: Path<TKey, TEntry>): AsyncIterableIterator<Path<TKey, TEntry>> {
253
- this.validatePath(path);
254
- return this.internalAscending(path.clone());
255
- }
256
-
257
- /** Iterates backward starting from the path location (inclusive) to the end.
258
- * WARNING: mutation during iteration will result in an exception
259
- */
260
- descending(path: Path<TKey, TEntry>): AsyncIterableIterator<Path<TKey, TEntry>> {
261
- this.validatePath(path);
262
- return this.internalDescending(path.clone());
263
- }
264
-
265
- /** Computed (not stored) count. Computes the sum using leaf-node lengths. O(n/af) where af is average fill.
266
- * @param from if provided, the count will start from the given path (inclusive). If ascending is false,
267
- * the count will start from the end of the tree. Ascending is true by default.
268
- */
269
- async getCount(from?: { path: Path<TKey, TEntry>, ascending?: boolean }): Promise<number> {
270
- let result = 0;
271
- const path = from ? from.path.clone() : await this.first();
272
- if (from?.ascending ?? true) {
273
- while (path.on) {
274
- result += path.leafNode.entries.length - path.leafIndex;
275
- path.leafIndex = path.leafNode.entries.length - 1;
276
- await this.internalNext(path);
277
- }
278
- } else {
279
- while (path.on) {
280
- result += path.leafIndex + 1;
281
- path.leafIndex = 0;
282
- await this.internalPrior(path);
283
- }
284
- }
285
- return result;
286
- }
287
-
288
- /** @returns a path one step forward. on will be true if the path hasn't hit the end. */
289
- async next(path: Path<TKey, TEntry>): Promise<Path<TKey, TEntry>> {
290
- const newPath = path.clone();
291
- await this.moveNext(newPath);
292
- return newPath;
293
- }
294
-
295
- /** Attempts to advance the given path one step forward. (mutates the path) */
296
- async moveNext(path: Path<TKey, TEntry>) {
297
- this.validatePath(path);
298
- await this.internalNext(path);
299
- }
300
-
301
- /** @returns a path one step backward. on will be true if the path hasn't hit the end. */
302
- async prior(path: Path<TKey, TEntry>): Promise<Path<TKey, TEntry>> {
303
- const newPath = path.clone();
304
- await this.movePrior(newPath);
305
- return newPath;
306
- }
307
-
308
- /** Attempts to advance the given path one step backwards. (mutates the path) */
309
- async movePrior(path: Path<TKey, TEntry>) {
310
- this.validatePath(path);
311
- await this.internalPrior(path);
312
- }
313
-
314
- /** @remarks Assumes the path is "on" */
315
- protected keyFromPath(path: Path<TKey, TEntry>): TKey {
316
- return this.keyFromEntry(path.leafNode.entries[path.leafIndex]!);
317
- }
318
-
319
- private async *internalAscending(path: Path<TKey, TEntry>): AsyncIterableIterator<Path<TKey, TEntry>> {
320
- this.validatePath(path);
321
- while (path.on) {
322
- yield path;
323
- await this.moveNext(path); // Not internal - re-check after yield
324
- }
325
- }
326
-
327
- private async *internalDescending(path: Path<TKey, TEntry>): AsyncIterableIterator<Path<TKey, TEntry>> {
328
- this.validatePath(path);
329
- while (path.on) {
330
- yield path;
331
- await this.movePrior(path); // Not internal - re-check after yield
332
- }
333
- }
334
-
335
- private async findFirst(range: KeyRange<TKey>) { // Assumes range.first is defined
336
- const startPath = await this.find(range.first!.key)
337
- if (!startPath.on || (range.first && !range.first.inclusive)) {
338
- if (range.isAscending) {
339
- await this.internalNext(startPath);
340
- } else {
341
- await this.internalPrior(startPath);
342
- }
343
- }
344
- return startPath;
345
- }
346
-
347
- private async findLast(range: KeyRange<TKey>) { // Assumes range.last is defined
348
- const endPath = await this.find(range.last!.key)
349
- if (!endPath.on || (range.last && !range.last.inclusive)) {
350
- if (range.isAscending) {
351
- await this.internalPrior(endPath);
352
- } else {
353
- await this.internalNext(endPath);
354
- }
355
- }
356
- return endPath;
357
- }
358
-
359
- /** Descend from `node` toward `key`, building the path. When `navigate` is true this is a point
360
- * lookup (from {@link get}): each interior branch read below the root is captured as a droppable
361
- * `navigation` read, and the terminal leaf is upgraded back to a retained `value` read — the
362
- * result depends only on the leaf, and any concurrent restructuring that would change the result
363
- * also bumps the leaf's revision (Theorem 5), so the interior reads are redundant. When false
364
- * (find/range/scan/write descents) every read stays `value` (retained). */
365
- protected async getPath(node: ITreeNode, key: TKey, navigate = false): Promise<Path<TKey, TEntry>> {
366
- if (node.header.type === TreeLeafBlockType) {
367
- const leaf = node as LeafNode<TEntry>;
368
- if (navigate) {
369
- // The leaf ends a point-lookup descent: its content is the load-bearing VALUE read.
370
- // Its parent fetched it as `navigation` (a child's type is unknown before reading);
371
- // upgrade it (value-wins) so it is retained while the interior nodes above are dropped.
372
- this.markReadValue(leaf.header.id);
373
- }
374
- const [on, index] = this.indexOfEntry(leaf.entries, key);
375
- return new Path<TKey, TEntry>([], leaf, index, on, this._version);
376
- } else {
377
- const branch = node as BranchNode<TKey>;
378
- const index = this.indexOfKey(branch.partitions, key);
379
- const child = await get(this.store, branch.nodes[index]!, navigate ? 'navigation' : 'value');
380
- const path = await this.getPath(child, key, navigate);
381
- path.branches.unshift(new PathBranch(branch, index));
382
- return path;
383
- }
384
- }
385
-
386
- /** Upgrade a captured read of `id` to a retained `value` read via the store chain's read
387
- * collector (duck-typed — a no-op for stores without one, e.g. test doubles or log-walk
388
- * caches). Used by a point lookup to pin its terminal leaf. */
389
- private markReadValue(id: BlockId) {
390
- (this.store as { markReadValue?: (id: BlockId) => void }).markReadValue?.(id);
391
- }
392
-
393
- private indexOfEntry(entries: TEntry[], key: TKey): [on: boolean, index: number] {
394
- let lo = 0;
395
- let hi = entries.length - 1;
396
- let split = 0;
397
- let result = -1;
398
-
399
- while (lo <= hi) {
400
- split = (lo + hi) >>> 1;
401
- result = this.compare(key, this.keyFromEntry(entries[split]!));
402
-
403
- if (result === 0)
404
- return [true, split];
405
- else if (result < 0)
406
- hi = split - 1;
407
- else
408
- lo = split + 1;
409
- }
410
-
411
- return [false, lo];
412
- }
413
-
414
- protected indexOfKey(keys: TKey[], key: TKey): number {
415
- let lo = 0;
416
- let hi = keys.length - 1;
417
- let split = 0;
418
- let result = -1;
419
-
420
- while (lo <= hi) {
421
- split = (lo + hi) >>> 1;
422
- result = this.compare(key, keys[split]!);
423
-
424
- if (result === 0)
425
- return split + 1; // +1 because taking right partition
426
- else if (result < 0)
427
- hi = split - 1;
428
- else
429
- lo = split + 1;
430
- }
431
-
432
- return lo;
433
- }
434
-
435
- private async internalNext(path: Path<TKey, TEntry>) {
436
- if (!path.on) { // Attempt to move off of crack
437
- path.on = path.branches.every(branch => branch.index >= 0 && branch.index < branch.node.nodes.length)
438
- && path.leafIndex >= 0 && path.leafIndex < path.leafNode.entries.length;
439
- if (path.on || path.leafIndex < path.leafNode.entries.length) {
440
- return; // got on an entry, or an interior crack — nothing to advance into
441
- }
442
- // end-of-leaf crack (leafIndex === entries.length): fall through to branch-popping leaf-advance
443
- } else if (path.leafIndex < path.leafNode.entries.length - 1) {
444
- ++path.leafIndex;
445
- path.on = true;
446
- return;
447
- }
448
- // on the last entry of the leaf, or off an end-of-leaf crack: advance into the next leaf
449
- let popCount = 0;
450
- let found = false;
451
- const last = path.branches.length - 1;
452
- while (popCount <= last && !found) {
453
- const branch = path.branches[last - popCount]!;
454
- if (branch.index === branch.node.partitions.length) // last node in branch
455
- ++popCount;
456
- else
457
- found = true;
458
- }
459
-
460
- if (!found) {
461
- path.leafIndex = path.leafNode.entries.length; // after last row = end crack
462
- path.on = false;
463
- } else {
464
- path.branches.splice(-popCount, popCount);
465
- const branch = path.branches.at(-1)!;
466
- ++branch.index;
467
- await this.moveToFirst(await get(this.store, branch.node.nodes[branch.index]!), path);
468
- }
469
- }
470
-
471
- private async internalPrior(path: Path<TKey, TEntry>) {
472
- this.validatePath(path);
473
- if (path.leafIndex <= 0) {
474
- let popCount = 0;
475
- let opening = false;
476
- const last = path.branches.length - 1;
477
- while (popCount <= last && !opening) {
478
- const branch = path.branches[last - popCount]!;
479
- if (branch.index === 0) // first node in branch
480
- ++popCount;
481
- else
482
- opening = true;
483
- }
484
-
485
- if (!opening) {
486
- path.leafIndex = 0;
487
- path.on = false;
488
- } else {
489
- path.branches.splice(-popCount, popCount);
490
- const branch = path.branches.at(-1)!;
491
- --branch.index;
492
- await this.moveToLast(await get(this.store, branch.node.nodes[branch.index]!), path);
493
- }
494
- }
495
- else {
496
- --path.leafIndex;
497
- path.on = true;
498
- }
499
- }
500
-
501
- private async internalUpdate(path: Path<TKey, TEntry>, newEntry: TEntry): Promise<[path: Path<TKey, TEntry>, wasUpdate: boolean]> {
502
- if (path.on) {
503
- const oldKey = this.keyFromPath(path);
504
- const newKey = this.keyFromEntry(newEntry);
505
- if (this.compare(oldKey, newKey) !== 0) { // if key changed, delete and re-insert
506
- let newPath = await this.internalInsert(newEntry)
507
- if (newPath.on) { // insert succeeded
508
- await this.internalDelete(await this.find(oldKey)); // Re-find - the prior insert invalidated the path
509
- newPath = await this.find(newKey); // Re-find- delete invalidated path
510
- }
511
- return [newPath, false];
512
- } else {
513
- this.updateEntry(path, newEntry);
514
- }
515
- }
516
- return [path, true];
517
- }
518
-
519
- protected async internalDelete(path: Path<TKey, TEntry>): Promise<boolean> {
520
- if (path.on) {
521
- apply(this.store, path.leafNode, [entries$, path.leafIndex, 1, []]);
522
- if (path.branches.length > 0) { // Only worry about underflows, balancing, etc. if not root
523
- if (path.leafIndex === 0 && path.leafNode.entries.length > 0) { // If we deleted index 0 and leaf is not empty, update branches with new key
524
- const pathBranch = path.branches.at(-1)!;
525
- this.updatePartition(pathBranch.index, path, path.branches.length - 1,
526
- this.keyFromPath(path));
527
- }
528
- const newRoot = await this.rebalanceLeaf(path, path.branches.length);
529
- if (newRoot) {
530
- await this.trunk.set(newRoot);
531
- }
532
- }
533
- path.on = false;
534
- return true;
535
- } else {
536
- return false;
537
- }
538
- }
539
-
540
- private async internalInsert(entry: TEntry): Promise<Path<TKey, TEntry>> {
541
- const path = await this.find(this.keyFromEntry(entry));
542
- if (path.on) {
543
- path.on = false;
544
- return path;
545
- }
546
- await this.internalInsertAt(path, entry);
547
- path.on = true;
548
- return path;
549
- }
550
-
551
- private async internalInsertAt(path: Path<TKey, TEntry>, entry: TEntry) {
552
- let split = this.leafInsert(path, entry);
553
- let branchIndex = path.branches.length - 1;
554
- while (split && branchIndex >= 0) {
555
- split = await this.branchInsert(path, branchIndex, split);
556
- --branchIndex;
557
- }
558
- if (split) {
559
- const newBranch = newBranchNode(this.store, [split.key], [await this.trunk.getId(), split.right.header.id]);
560
- this.store.insert(newBranch);
561
- await this.trunk.set(newBranch);
562
- path.branches.unshift(new PathBranch(newBranch, split.indexDelta));
563
- }
564
- }
565
-
566
- /** Starting from the given node, recursively working down to the leaf, build onto the path based on the beginning-most entry. */
567
- private async moveToFirst(node: ITreeNode, path: Path<TKey, TEntry>) {
568
- if (node.header.type === TreeLeafBlockType) {
569
- const leaf = node as LeafNode<TEntry>;
570
- path.leafNode = leaf;
571
- path.leafIndex = 0;
572
- path.on = leaf.entries.length > 0;
573
- } else {
574
- path.branches.push(new PathBranch(node as BranchNode<TKey>, 0));
575
- await this.moveToFirst(await get(this.store, (node as BranchNode<TKey>).nodes[0]!), path);
576
- }
577
- }
578
-
579
- /** Starting from the given node, recursively working down to the leaf, build onto the path based on the end-most entry. */
580
- private async moveToLast(node: ITreeNode, path: Path<TKey, TEntry>) {
581
- if (node.header.type === TreeLeafBlockType) {
582
- const leaf = node as LeafNode<TEntry>;
583
- const count = leaf.entries.length;
584
- path.leafNode = leaf;
585
- path.on = count > 0;
586
- path.leafIndex = count > 0 ? count - 1 : 0;
587
- } else {
588
- const branch = node as BranchNode<TKey>;
589
- const pathBranch = new PathBranch(branch, branch.partitions.length);
590
- path.branches.push(pathBranch);
591
- await this.moveToLast(await get(this.store, branch.nodes[pathBranch.index]!), path);
592
- }
593
- }
594
-
595
- /** Construct a path based on the first-most edge of the given. */
596
- private async getFirst(node: ITreeNode): Promise<Path<TKey, TEntry>> {
597
- if (node.header.type === TreeLeafBlockType) {
598
- const leaf = node as LeafNode<TEntry>;
599
- return new Path<TKey, TEntry>([], leaf, 0, leaf.entries.length > 0, this._version)
600
- } else {
601
- const branch = node as BranchNode<TKey>;
602
- const path = await this.getFirst(await get(this.store, branch.nodes[0]!));
603
- path.branches.unshift(new PathBranch(branch, 0));
604
- return path;
605
- }
606
- }
607
-
608
- /** Construct a path based on the last-most edge of the given node */
609
- private async getLast(node: ITreeNode): Promise<Path<TKey, TEntry>> {
610
- if (node.header.type === TreeLeafBlockType) {
611
- const leaf = node as LeafNode<TEntry>;
612
- const count = leaf.entries.length;
613
- return new Path<TKey, TEntry>([], leaf, count > 0 ? count - 1 : 0, count > 0, this._version);
614
- } else {
615
- const branch = node as BranchNode<TKey>;
616
- const index = branch.nodes.length - 1;
617
- const path = await this.getLast(await get(this.store, branch.nodes[index]!));
618
- path.branches.unshift(new PathBranch(branch, index));
619
- return path;
620
- }
621
- }
622
-
623
- private leafInsert(path: Path<TKey, TEntry>, entry: TEntry): Split<TKey> | undefined {
624
- const { leafNode: leaf, leafIndex: index } = path;
625
- if (leaf.entries.length < this.nodeCapacity) { // No split needed
626
- apply(this.store, leaf, [entries$, index, 0, [entry]]);
627
- return undefined;
628
- }
629
- // Full. Split needed
630
-
631
- const midIndex = (leaf.entries.length + 1) >>> 1;
632
- const newEntries = leaf.entries.slice(midIndex);
633
-
634
- // New node
635
- if (index >= midIndex) { // Put the new entry directly rather than log an insert
636
- newEntries.splice(index - midIndex, 0, entry);
637
- }
638
- const newLeaf = newLeafNode(this.store, newEntries);
639
- this.store.insert(newLeaf);
640
-
641
- // Delete entries from old node
642
- apply(this.store, leaf, [entries$, midIndex, leaf.entries.length - midIndex, []]);
643
-
644
- if (index < midIndex) { // Insert new entry into old node
645
- apply(this.store, leaf, [entries$, index, 0, [entry]]);
646
- } else {
647
- path.leafNode = newLeaf;
648
- path.leafIndex -= midIndex;
649
- }
650
-
651
- return new Split<TKey>(this.keyFromEntry(newEntries[0]!), newLeaf, index < midIndex ? 0 : 1);
652
- }
653
-
654
- private async branchInsert(path: Path<TKey, TEntry>, branchIndex: number, split: Split<TKey>): Promise<Split<TKey> | undefined> {
655
- const pathBranch = path.branches[branchIndex]!;
656
- const { index: splitIndex, node } = pathBranch;
657
- pathBranch.index += split.indexDelta;
658
- if (node.nodes.length < this.nodeCapacity) { // no split needed
659
- apply(this.store, node, [partitions$, splitIndex, 0, [split.key]]);
660
- apply(this.store, node, [nodes$, splitIndex + 1, 0, [split.right.header.id]]);
661
- return undefined;
662
- }
663
- // Full. Split needed
664
-
665
- const midIndex = (node.nodes.length + 1) >>> 1;
666
- const newPartitions = node.partitions.slice(midIndex);
667
- const newNodes = node.nodes.slice(midIndex);
668
- const delta = pathBranch.index < midIndex ? 0 : 1;
669
-
670
- // New node
671
- if (delta) { // If split is on new, add it before the split to avoid logging an insert
672
- pathBranch.index -= midIndex;
673
- newPartitions.splice(pathBranch.index, 0, split.key);
674
- newNodes.splice(pathBranch.index + 1, 0, split.right.header.id);
675
- }
676
- const newBranch = newBranchNode(this.store, newPartitions, newNodes);
677
- this.store.insert(newBranch);
678
-
679
- // Delete partitions and nodes
680
- const newPartition = node.partitions[midIndex - 1]!;
681
- apply(this.store, node, [partitions$, midIndex - 1, newPartitions.length + 1, []]);
682
- apply(this.store, node, [nodes$, midIndex, newNodes.length, []]);
683
-
684
- if (pathBranch.index < midIndex) { // Insert into old node
685
- apply(this.store, node, [partitions$, splitIndex, 0, [split.key]]);
686
- apply(this.store, node, [nodes$, splitIndex + 1, 0, [split.right.header.id]]);
687
- }
688
-
689
- return new Split<TKey>(newPartition, newBranch, delta);
690
- }
691
-
692
- protected async rebalanceLeaf(path: Path<TKey, TEntry>, depth: number): Promise<ITreeNode | undefined> {
693
- if (depth === 0 || path.leafNode.entries.length >= (this.nodeCapacity >>> 1)) {
694
- return undefined;
695
- }
696
-
697
- const leaf = path.leafNode;
698
- const parent = path.branches.at(depth - 1)!;
699
- const pIndex = parent.index;
700
- const pNode = parent.node;
701
-
702
- const rightSibId = pNode.nodes[pIndex + 1];
703
- const rightSib = rightSibId ? (await get(this.store, rightSibId)) as LeafNode<TEntry> : undefined;
704
- if (rightSib && rightSib.entries.length > (this.nodeCapacity >>> 1)) { // Attempt to borrow from right sibling
705
- const entry = rightSib.entries[0]!;
706
- apply(this.store, rightSib, [entries$, 0, 1, []]);
707
- apply(this.store, leaf, [entries$, leaf.entries.length, 0, [entry]]);
708
- this.updatePartition(pIndex + 1, path, depth - 1, this.keyFromEntry(rightSib.entries[0]!));
709
- return undefined;
710
- }
711
-
712
- const leftSibId = pNode.nodes[pIndex - 1];
713
- const leftSib = leftSibId ? (await get(this.store, leftSibId)) as LeafNode<TEntry> : undefined;
714
- if (leftSib && leftSib.entries.length > (this.nodeCapacity >>> 1)) { // Attempt to borrow from left sibling
715
- const entry = leftSib.entries[leftSib.entries.length - 1]!;
716
- apply(this.store, leftSib, [entries$, leftSib.entries.length - 1, 1, []]);
717
- apply(this.store, leaf, [entries$, 0, 0, [entry]]);
718
- this.updatePartition(pIndex, path, depth - 1, this.keyFromEntry(entry));
719
- path.leafIndex += 1;
720
- return undefined;
721
- }
722
-
723
- if (rightSib && rightSib.entries.length + leaf.entries.length <= this.nodeCapacity) { // Attempt to merge right sibling into leaf (right sib deleted)
724
- apply(this.store, leaf, [entries$, leaf.entries.length, 0, rightSib.entries]);
725
- this.deletePartition(pNode, pIndex);
726
- if (pIndex === 0) { // 0th node of parent, update parent key
727
- this.updatePartition(pIndex, path, depth - 1, this.keyFromEntry(leaf.entries[0]!));
728
- }
729
- this.store.delete(rightSib.header.id);
730
- return await this.rebalanceBranch(path, depth - 1);
731
- }
732
-
733
- if (leftSib && leftSib.entries.length + leaf.entries.length <= this.nodeCapacity) { // Attempt to merge into left sibling (leaf deleted)
734
- // NOTE: this fixes leafIndex, but the parent-branch index up the path is left pointing at
735
- // the now-deleted leaf's old slot (same tolerated-staleness class as rebalanceBranch's
736
- // left-merge, part c). Harmless today because deleteAt version-bumps and abandons the
737
- // returned path. A future path-reuse consumer must audit BOTH left-merge sites, not just
738
- // rebalanceBranch.
739
- path.leafNode = leftSib;
740
- path.leafIndex += leftSib.entries.length;
741
- apply(this.store, leftSib, [entries$, leftSib.entries.length, 0, leaf.entries]);
742
- this.deletePartition(pNode, pIndex - 1);
743
- this.store.delete(leaf.header.id);
744
- return await this.rebalanceBranch(path, depth - 1);
745
- }
746
- }
747
-
748
- protected async rebalanceBranch(path: Path<TKey, TEntry>, depth: number): Promise<ITreeNode | undefined> {
749
- const pathBranch = path.branches[depth]!;
750
- const branch = pathBranch.node;
751
- if (depth === 0 && branch.partitions.length === 0) { // last node... collapse child into root
752
- return path.branches[depth + 1]?.node ?? path.leafNode;
753
- }
754
-
755
- if (depth === 0 || (branch.nodes.length >= this.nodeCapacity >>> 1)) {
756
- return undefined;
757
- }
758
-
759
- const parent = path.branches.at(depth - 1)!;
760
- const pIndex = parent.index;
761
- const pNode = parent.node;
762
-
763
- const rightSibId = pNode.nodes[pIndex + 1];
764
- const rightSib = rightSibId ? (await get(this.store, rightSibId)) as BranchNode<TKey> : undefined;
765
- if (rightSib && rightSib.nodes.length > (this.nodeCapacity >>> 1)) { // Attempt to borrow from right sibling
766
- const node = rightSib.nodes[0]!;
767
- const rightKey = rightSib.partitions[0]!;
768
- this.insertPartition(branch, branch.partitions.length, pNode.partitions[pIndex]!, node);
769
- this.deletePartition(rightSib, 0, 0);
770
- this.updatePartition(pIndex + 1, path, depth - 1, rightKey);
771
- return undefined;
772
- }
773
-
774
- const leftSibId = pNode.nodes[pIndex - 1];
775
- const leftSib = leftSibId ? (await get(this.store, leftSibId)) as BranchNode<TKey> : undefined;
776
- if (leftSib && leftSib.nodes.length > (this.nodeCapacity >>> 1)) { // Attempt to borrow from left sibling
777
- const node = leftSib.nodes[leftSib.nodes.length - 1]!;
778
- const pKey = leftSib.partitions[leftSib.partitions.length - 1]!;
779
- this.insertPartition(branch, 0, pNode.partitions[pIndex - 1]!, node, 0);
780
- this.deletePartition(leftSib, leftSib.partitions.length - 1);
781
- pathBranch.index += 1;
782
- this.updatePartition(pIndex, path, depth - 1, pKey);
783
- return undefined;
784
- }
785
-
786
- if (rightSib && rightSib.nodes.length + branch.nodes.length <= this.nodeCapacity) { // Attempt to merge right sibling into self
787
- const pKey = pNode.partitions[pIndex]!;
788
- this.deletePartition(pNode, pIndex);
789
- apply(this.store, branch, [partitions$, branch.partitions.length, 0, [pKey]]);
790
- apply(this.store, branch, [partitions$, branch.partitions.length, 0, rightSib.partitions]);
791
- apply(this.store, branch, [nodes$, branch.nodes.length, 0, rightSib.nodes]);
792
- this.store.delete(rightSib.header.id);
793
- return this.rebalanceBranch(path, depth - 1);
794
- }
795
-
796
- if (leftSib && leftSib.nodes.length + branch.nodes.length <= this.nodeCapacity) { // Attempt to merge self into left sibling
797
- const leftLen = leftSib.nodes.length; // capture BEFORE the appends below shift it (see leaf path at rebalanceLeaf)
798
- const pKey = pNode.partitions[pIndex - 1]!;
799
- this.deletePartition(pNode, pIndex - 1);
800
- apply(this.store, leftSib, [partitions$, leftSib.partitions.length, 0, [pKey]]);
801
- apply(this.store, leftSib, [partitions$, leftSib.partitions.length, 0, branch.partitions]);
802
- apply(this.store, leftSib, [nodes$, leftSib.nodes.length, 0, branch.nodes]);
803
- pathBranch.node = leftSib;
804
- pathBranch.index += leftLen; // branch's children now sit after leftSib's original children
805
- this.store.delete(branch.header.id);
806
- return this.rebalanceBranch(path, depth - 1);
807
- }
808
- }
809
-
810
- protected updatePartition(nodeIndex: number, path: Path<TKey, TEntry>, depth: number, newKey: TKey) {
811
- const pathBranch = path.branches[depth]!;
812
- if (nodeIndex > 0) { // Only affects this branch; just update the partition key
813
- apply(this.store, pathBranch.node, [partitions$, nodeIndex - 1, 1, [newKey]]);
814
- } else if (depth !== 0) {
815
- this.updatePartition(path.branches[depth - 1]!.index, path, depth - 1, newKey);
816
- }
817
- }
818
-
819
- protected insertPartition(branch: BranchNode<TKey>, index: number, key: TKey, node: BlockId, nodeOffset = 1) {
820
- apply(this.store, branch, [partitions$, index, 0, [key]]);
821
- apply(this.store, branch, [nodes$, index + nodeOffset, 0, [node]]);
822
- }
823
-
824
- protected deletePartition(branch: BranchNode<TKey>, index: number, nodeOffset = 1) {
825
- apply(this.store, branch, [partitions$, index, 1, []]);
826
- apply(this.store, branch, [nodes$, index + nodeOffset, 1, []]);
827
- }
828
-
829
- private validatePath(path: Path<TKey, TEntry>) {
830
- if (!this.isValid(path)) {
831
- throw new Error("Path is invalid due to mutation of the tree");
832
- }
833
- }
834
-
835
- /** Iterates every node ID below and including the given node. */
836
- private async *nodeIds(node: ITreeNode): AsyncIterableIterator<BlockId> {
837
- // TODO: This would be much more efficient if we avoided iterating into leaf nodes
838
- if (node.header.type === TreeBranchBlockType) {
839
- const subNodes = await Promise.all((node as BranchNode<TKey>).nodes.map(id => get(this.store, id)));
840
- for (let subNode of subNodes) {
841
- yield* this.nodeIds(subNode);
842
- }
843
- }
844
- yield node.header.id;
845
- }
846
-
847
- protected getEntry(path: Path<TKey, TEntry>): TEntry {
848
- return path.leafNode.entries[path.leafIndex]!;
849
- }
850
-
851
- protected updateEntry(path: Path<TKey, TEntry>, entry: TEntry) {
852
- apply(this.store, path.leafNode, [entries$, path.leafIndex, 1, [entry]]);
853
- }
854
- }
855
-
856
- class Split<TKey> {
857
- constructor(
858
- public key: TKey,
859
- public right: ITreeNode,
860
- public indexDelta: number
861
- ) { }
862
- }
863
-
864
- function newLeafNode<TEntry>(store: BlockStore<ITreeNode>, entries: TEntry[]): LeafNode<TEntry> {
865
- const header = store.createBlockHeader(TreeLeafBlockType);
866
- return { header, entries };
867
- }
868
-
869
- function newBranchNode<TKey>(store: BlockStore<ITreeNode>, partitions: TKey[], nodes: BlockId[]): BranchNode<TKey> {
870
- const header = store.createBlockHeader(TreeBranchBlockType);
871
- return { header, partitions, nodes };
872
- }
1
+ import { Path, PathBranch } from "./path.js";
2
+ import type { ITreeTrunk, KeyRange, getTrunkFunc } from "./index.js";
3
+ import type { BlockId, BlockStore } from "../blocks/index.js";
4
+ import { apply, get } from "../blocks/index.js";
5
+ import { TreeLeafBlockType, TreeBranchBlockType, entries$, nodes$, partitions$ } from "./nodes.js";
6
+ import type { BranchNode, ITreeNode, LeafNode } from "./nodes.js";
7
+ import type { TreeBlock } from "./tree-block.js";
8
+ import { AtomicProxy, type AtomicScope } from "../transform/atomic-proxy.js";
9
+
10
+ export const NodeCapacity = 64;
11
+
12
+ /**
13
+ * Represents a lightweight B+(ish)Tree (data at leaves, but no linked list of leaves).
14
+ * Allows for efficient storage and retrieval of data in a sorted manner.
15
+ * @template TEntry The type of entries stored in the B-tree.
16
+ * @template TKey The type of keys used for indexing the entries. This might be an element of TEntry, or TEntry itself.
17
+ */
18
+ export class BTree<TKey, TEntry> {
19
+ protected _version = 0; // only for path invalidation
20
+ private _proxy?: AtomicProxy<ITreeNode>;
21
+
22
+ /**
23
+ * @param [compare=(a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0] a comparison function for keys. The default uses < and > operators.
24
+ * @param [keyFromEntry=(entry: TEntry) => entry as unknown as TKey] a function to extract the key from an entry. The default assumes the key is the entry itself.
25
+ */
26
+ constructor(
27
+ public readonly store: BlockStore<ITreeNode>,
28
+ public readonly trunk: ITreeTrunk,
29
+ public readonly keyFromEntry = (entry: TEntry) => entry as unknown as TKey,
30
+ public readonly compare = (a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0 as number,
31
+ public readonly nodeCapacity = NodeCapacity,
32
+ ) {
33
+ }
34
+
35
+ private atomic<T>(fn: (scope?: AtomicScope) => Promise<T>, parent?: AtomicScope): Promise<T> {
36
+ return this._proxy ? this._proxy.atomic(fn, parent) : fn(parent);
37
+ }
38
+
39
+ static createRoot(
40
+ store: BlockStore<ITreeNode>
41
+ ) {
42
+ return newLeafNode(store, []);
43
+ }
44
+
45
+ static create<TKey, TEntry>(
46
+ store: BlockStore<ITreeNode | TreeBlock>,
47
+ createTrunk: getTrunkFunc,
48
+ keyFromEntry = (entry: TEntry) => entry as unknown as TKey,
49
+ // `as number` so the inferred param type is a comparator returning any number, matching the
50
+ // constructor above — without it the default narrows to `-1 | 0 | 1` and a perfectly valid
51
+ // `(a, b) => a - b` comparator is rejected here but accepted there.
52
+ compare = (a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0 as number,
53
+ nodeCapacity = NodeCapacity,
54
+ newId?: BlockId,
55
+ ) {
56
+ const proxy = new AtomicProxy(store);
57
+ const root = BTree.createRoot(proxy as BlockStore<TreeBlock>);
58
+ proxy.insert(root);
59
+ const trunk = createTrunk(proxy as BlockStore<TreeBlock>, root.header.id, newId);
60
+ const tree = new BTree(proxy, trunk, keyFromEntry, compare, nodeCapacity);
61
+ tree._proxy = proxy;
62
+ return tree;
63
+ }
64
+
65
+ /** @returns a path to the first entry (on = false if no entries) */
66
+ async first(): Promise<Path<TKey, TEntry>> {
67
+ return await this.getFirst(await this.trunk.get());
68
+ }
69
+
70
+ /** @returns a path to the last entry (on = false if no entries) */
71
+ async last(): Promise<Path<TKey, TEntry>> {
72
+ return await this.getLast(await this.trunk.get());
73
+ }
74
+
75
+ /** Attempts to find the given key
76
+ * @returns Path to the key or the "crack" before it. If `on` is true on the resulting path, the key was found.
77
+ * If `on` is false, next() and prior() can attempt to move to the nearest match.
78
+ * @param navigate when true, the interior descent nodes are captured as droppable `navigation`
79
+ * reads (see {@link getPath}). DEFAULT false: `find` returns a Path a caller may use to seed a
80
+ * range scan (`ascending`/`next`), whose result depends on tree shape, so its structural reads
81
+ * must stay retained. Only {@link get} — a point lookup with no such escape — opts in. */
82
+ async find(key: TKey, navigate = false): Promise<Path<TKey, TEntry>> {
83
+ return await this.getPath(await this.trunk.get(), key, navigate);
84
+ }
85
+
86
+ /** Retrieves the entry for the given key.
87
+ * Use find instead for a path to the key, the nearest match, or as a basis for navigation.
88
+ * @returns the entry for the given key if found; undefined otherwise. */
89
+ async get(key: TKey): Promise<TEntry | undefined> {
90
+ // Value-of-key point lookup: the result depends ONLY on the terminal leaf's content, so the
91
+ // interior descent nodes are pure navigation and are dropped from the OCC conflict set. The
92
+ // returned Path is consumed by `at` and discarded — it never seeds a scan — so navigate=true
93
+ // is safe here (unlike the public `find`).
94
+ return this.at(await this.find(key, /* navigate */ true));
95
+ }
96
+
97
+ /** @returns the entry for the given path if on an entry; undefined otherwise. */
98
+ at(path: Path<TKey, TEntry>): TEntry | undefined {
99
+ this.validatePath(path);
100
+ return path.on ? this.getEntry(path) : undefined;
101
+ }
102
+
103
+ /** Iterates based on the given range
104
+ * WARNING: mutation during iteration will result in an exception
105
+ */
106
+ async *range(range: KeyRange<TKey>): AsyncIterableIterator<Path<TKey, TEntry>> {
107
+ const startPath = range.first
108
+ ? await this.findFirst(range)
109
+ : (range.isAscending ? await this.first() : await this.last());
110
+ const endPath = range.last
111
+ ? await this.findLast(range)
112
+ : (range.isAscending ? await this.last() : await this.first());
113
+ // If the tree is empty or endPath is not on an entry, return early
114
+ if (!endPath.on) {
115
+ return;
116
+ }
117
+ const endKey = this.keyFromPath(endPath);
118
+ const iterable = range.isAscending
119
+ ? this.internalAscending(startPath)
120
+ : this.internalDescending(startPath);
121
+ const iter = iterable[Symbol.asyncIterator]();
122
+ const ascendingFactor = range.isAscending ? 1 : -1;
123
+ for await (let path of iter) {
124
+ if (!path.on || this.compare(
125
+ this.keyFromPath(path),
126
+ endKey
127
+ ) * ascendingFactor > 0) {
128
+ break;
129
+ }
130
+ yield path;
131
+ }
132
+ }
133
+
134
+ /** @returns true if the given path remains valid; false if the tree has been mutated, invalidating the path. */
135
+ isValid(path: Path<TKey, TEntry>) {
136
+ return path.version === this._version;
137
+ }
138
+
139
+ /** Bump the version so every Path handed out before now reports invalid (see {@link isValid}).
140
+ * Needed when the tree's data was mutated through a DIFFERENT store binding than this instance —
141
+ * e.g. the tree collection's action handler writes through a per-action Atomic store, so this
142
+ * read-side btree never sees the mutation and must be told to invalidate outstanding paths. */
143
+ invalidatePaths() {
144
+ ++this._version;
145
+ }
146
+
147
+ /**
148
+ * Adds a value to the tree. Be sure to check the result, as the tree does not allow duplicate keys.
149
+ * Added entries are frozen to ensure immutability
150
+ * @returns path to the new (on = true) or conflicting (on = false) row. */
151
+ async insert(entry: TEntry): Promise<Path<TKey, TEntry>> {
152
+ return this.atomic(async () => {
153
+ Object.freeze(entry); // Ensure immutability
154
+ const path = await this.internalInsert(entry);
155
+ if (path.on) {
156
+ path.version = ++this._version;
157
+ }
158
+ return path;
159
+ });
160
+ }
161
+
162
+ /** Updates the entry at the given path to the given value. Deletes and inserts if the key changes.
163
+ * @returns path to resulting entry and whether it was an update (as opposed to an insert).
164
+ * * on = true if update/insert succeeded.
165
+ * * wasUpdate = true if updated; false if inserted.
166
+ * * Returned path is on entry
167
+ * * on = false if update/insert failed.
168
+ * * wasUpdate = true, given path is not on an entry
169
+ * * else newEntry's new key already present; returned path is "near" existing entry */
170
+ async updateAt(path: Path<TKey, TEntry>, newEntry: TEntry, parent?: AtomicScope): Promise<[path: Path<TKey, TEntry>, wasUpdate: boolean]> {
171
+ return this.atomic(async () => {
172
+ this.validatePath(path);
173
+ if (path.on) {
174
+ Object.freeze(newEntry);
175
+ }
176
+ const result = await this.internalUpdate(path, newEntry);
177
+ if (result[0].on) {
178
+ result[0].version = ++this._version;
179
+ }
180
+ return result;
181
+ }, parent);
182
+ }
183
+
184
+ /** Inserts the entry if it doesn't exist, or updates it if it does.
185
+ * The entry is frozen to ensure immutability.
186
+ * @returns path to the new entry. on = true if existing; on = false if new. */
187
+ async upsert(entry: TEntry): Promise<Path<TKey, TEntry>> {
188
+ return this.atomic(async () => {
189
+ const path = await this.find(this.keyFromEntry(entry));
190
+ Object.freeze(entry);
191
+ if (path.on) {
192
+ this.updateEntry(path, entry);
193
+ } else {
194
+ await this.internalInsertAt(path, entry);
195
+ }
196
+ path.version = ++this._version;
197
+ return path;
198
+ });
199
+ }
200
+
201
+ /** Inserts or updates depending on the existence of the given key, using callbacks to generate the new value.
202
+ * @param newEntry the new entry to insert if the key doesn't exist.
203
+ * @param getUpdated a callback to generate an updated entry if the key does exist. WARNING: mutation in this callback will cause merge to error.
204
+ * @returns path to new entry and whether an update or insert attempted.
205
+ * If getUpdated callback returns a row that is already present, the resulting path will not be on. */
206
+ async merge(newEntry: TEntry, getUpdated: (existing: TEntry) => TEntry): Promise<[path: Path<TKey, TEntry>, wasUpdate: boolean]> {
207
+ return this.atomic(async (scope) => {
208
+ const newKey = this.keyFromEntry(newEntry);
209
+ const path = await this.find(newKey);
210
+ if (path.on) {
211
+ // Thread this scope into updateAt so the nested call joins this atomic batch
212
+ // (reuses the tracker) rather than opening/committing a second scope.
213
+ const result = await this.updateAt(path, getUpdated(this.getEntry(path)), scope); // Don't use internalUpdate - need to freeze and check for mutation
214
+ // Note: updateAt already increments version, so don't double-increment here
215
+ return result;
216
+ } else {
217
+ await this.internalInsertAt(path, Object.freeze(newEntry));
218
+ path.on = true;
219
+ path.version = ++this._version;
220
+ return [path, false];
221
+ }
222
+ });
223
+ }
224
+
225
+ /** Deletes the entry at the given path.
226
+ * The on property of the path will be cleared.
227
+ * @returns true if the delete succeeded (the key was found); false otherwise.
228
+ */
229
+ async deleteAt(path: Path<TKey, TEntry>): Promise<boolean> {
230
+ return this.atomic(async () => {
231
+ this.validatePath(path);
232
+ const result = await this.internalDelete(path);
233
+ if (result) {
234
+ ++this._version;
235
+ }
236
+ return result;
237
+ });
238
+ }
239
+
240
+ async drop() { // Node: only when a root treeBlock
241
+ return this.atomic(async () => {
242
+ const root = await this.trunk.get();
243
+ for await (const id of this.nodeIds(root)) {
244
+ this.store.delete(id);
245
+ }
246
+ });
247
+ }
248
+
249
+ /** Iterates forward starting from the path location (inclusive) to the end.
250
+ * WARNING: mutation during iteration will result in an exception.
251
+ */
252
+ ascending(path: Path<TKey, TEntry>): AsyncIterableIterator<Path<TKey, TEntry>> {
253
+ this.validatePath(path);
254
+ return this.internalAscending(path.clone());
255
+ }
256
+
257
+ /** Iterates backward starting from the path location (inclusive) to the end.
258
+ * WARNING: mutation during iteration will result in an exception
259
+ */
260
+ descending(path: Path<TKey, TEntry>): AsyncIterableIterator<Path<TKey, TEntry>> {
261
+ this.validatePath(path);
262
+ return this.internalDescending(path.clone());
263
+ }
264
+
265
+ /** Computed (not stored) count. Computes the sum using leaf-node lengths. O(n/af) where af is average fill.
266
+ * @param from if provided, the count will start from the given path (inclusive). If ascending is false,
267
+ * the count will start from the end of the tree. Ascending is true by default.
268
+ */
269
+ async getCount(from?: { path: Path<TKey, TEntry>, ascending?: boolean }): Promise<number> {
270
+ let result = 0;
271
+ const path = from ? from.path.clone() : await this.first();
272
+ if (from?.ascending ?? true) {
273
+ while (path.on) {
274
+ result += path.leafNode.entries.length - path.leafIndex;
275
+ path.leafIndex = path.leafNode.entries.length - 1;
276
+ await this.internalNext(path);
277
+ }
278
+ } else {
279
+ while (path.on) {
280
+ result += path.leafIndex + 1;
281
+ path.leafIndex = 0;
282
+ await this.internalPrior(path);
283
+ }
284
+ }
285
+ return result;
286
+ }
287
+
288
+ /** @returns a path one step forward. on will be true if the path hasn't hit the end. */
289
+ async next(path: Path<TKey, TEntry>): Promise<Path<TKey, TEntry>> {
290
+ const newPath = path.clone();
291
+ await this.moveNext(newPath);
292
+ return newPath;
293
+ }
294
+
295
+ /** Attempts to advance the given path one step forward. (mutates the path) */
296
+ async moveNext(path: Path<TKey, TEntry>) {
297
+ this.validatePath(path);
298
+ await this.internalNext(path);
299
+ }
300
+
301
+ /** @returns a path one step backward. on will be true if the path hasn't hit the end. */
302
+ async prior(path: Path<TKey, TEntry>): Promise<Path<TKey, TEntry>> {
303
+ const newPath = path.clone();
304
+ await this.movePrior(newPath);
305
+ return newPath;
306
+ }
307
+
308
+ /** Attempts to advance the given path one step backwards. (mutates the path) */
309
+ async movePrior(path: Path<TKey, TEntry>) {
310
+ this.validatePath(path);
311
+ await this.internalPrior(path);
312
+ }
313
+
314
+ /** @remarks Assumes the path is "on" */
315
+ protected keyFromPath(path: Path<TKey, TEntry>): TKey {
316
+ return this.keyFromEntry(path.leafNode.entries[path.leafIndex]!);
317
+ }
318
+
319
+ private async *internalAscending(path: Path<TKey, TEntry>): AsyncIterableIterator<Path<TKey, TEntry>> {
320
+ this.validatePath(path);
321
+ while (path.on) {
322
+ yield path;
323
+ await this.moveNext(path); // Not internal - re-check after yield
324
+ }
325
+ }
326
+
327
+ private async *internalDescending(path: Path<TKey, TEntry>): AsyncIterableIterator<Path<TKey, TEntry>> {
328
+ this.validatePath(path);
329
+ while (path.on) {
330
+ yield path;
331
+ await this.movePrior(path); // Not internal - re-check after yield
332
+ }
333
+ }
334
+
335
+ private async findFirst(range: KeyRange<TKey>) { // Assumes range.first is defined
336
+ const startPath = await this.find(range.first!.key)
337
+ if (!startPath.on || (range.first && !range.first.inclusive)) {
338
+ if (range.isAscending) {
339
+ await this.internalNext(startPath);
340
+ } else {
341
+ await this.internalPrior(startPath);
342
+ }
343
+ }
344
+ return startPath;
345
+ }
346
+
347
+ private async findLast(range: KeyRange<TKey>) { // Assumes range.last is defined
348
+ const endPath = await this.find(range.last!.key)
349
+ if (!endPath.on || (range.last && !range.last.inclusive)) {
350
+ if (range.isAscending) {
351
+ await this.internalPrior(endPath);
352
+ } else {
353
+ await this.internalNext(endPath);
354
+ }
355
+ }
356
+ return endPath;
357
+ }
358
+
359
+ /** Descend from `node` toward `key`, building the path. When `navigate` is true this is a point
360
+ * lookup (from {@link get}): each interior branch read below the root is captured as a droppable
361
+ * `navigation` read, and the terminal leaf is upgraded back to a retained `value` read — the
362
+ * result depends only on the leaf, and any concurrent restructuring that would change the result
363
+ * also bumps the leaf's revision (Theorem 5), so the interior reads are redundant. When false
364
+ * (find/range/scan/write descents) every read stays `value` (retained). */
365
+ protected async getPath(node: ITreeNode, key: TKey, navigate = false): Promise<Path<TKey, TEntry>> {
366
+ if (node.header.type === TreeLeafBlockType) {
367
+ const leaf = node as LeafNode<TEntry>;
368
+ if (navigate) {
369
+ // The leaf ends a point-lookup descent: its content is the load-bearing VALUE read.
370
+ // Its parent fetched it as `navigation` (a child's type is unknown before reading);
371
+ // upgrade it (value-wins) so it is retained while the interior nodes above are dropped.
372
+ this.markReadValue(leaf.header.id);
373
+ }
374
+ const [on, index] = this.indexOfEntry(leaf.entries, key);
375
+ return new Path<TKey, TEntry>([], leaf, index, on, this._version);
376
+ } else {
377
+ const branch = node as BranchNode<TKey>;
378
+ const index = this.indexOfKey(branch.partitions, key);
379
+ const child = await get(this.store, branch.nodes[index]!, navigate ? 'navigation' : 'value');
380
+ const path = await this.getPath(child, key, navigate);
381
+ path.branches.unshift(new PathBranch(branch, index));
382
+ return path;
383
+ }
384
+ }
385
+
386
+ /** Upgrade a captured read of `id` to a retained `value` read via the store chain's read
387
+ * collector (duck-typed — a no-op for stores without one, e.g. test doubles or log-walk
388
+ * caches). Used by a point lookup to pin its terminal leaf. */
389
+ private markReadValue(id: BlockId) {
390
+ (this.store as { markReadValue?: (id: BlockId) => void }).markReadValue?.(id);
391
+ }
392
+
393
+ private indexOfEntry(entries: TEntry[], key: TKey): [on: boolean, index: number] {
394
+ let lo = 0;
395
+ let hi = entries.length - 1;
396
+ let split = 0;
397
+ let result = -1;
398
+
399
+ while (lo <= hi) {
400
+ split = (lo + hi) >>> 1;
401
+ result = this.compare(key, this.keyFromEntry(entries[split]!));
402
+
403
+ if (result === 0)
404
+ return [true, split];
405
+ else if (result < 0)
406
+ hi = split - 1;
407
+ else
408
+ lo = split + 1;
409
+ }
410
+
411
+ return [false, lo];
412
+ }
413
+
414
+ protected indexOfKey(keys: TKey[], key: TKey): number {
415
+ let lo = 0;
416
+ let hi = keys.length - 1;
417
+ let split = 0;
418
+ let result = -1;
419
+
420
+ while (lo <= hi) {
421
+ split = (lo + hi) >>> 1;
422
+ result = this.compare(key, keys[split]!);
423
+
424
+ if (result === 0)
425
+ return split + 1; // +1 because taking right partition
426
+ else if (result < 0)
427
+ hi = split - 1;
428
+ else
429
+ lo = split + 1;
430
+ }
431
+
432
+ return lo;
433
+ }
434
+
435
+ private async internalNext(path: Path<TKey, TEntry>) {
436
+ if (!path.on) { // Attempt to move off of crack
437
+ path.on = path.branches.every(branch => branch.index >= 0 && branch.index < branch.node.nodes.length)
438
+ && path.leafIndex >= 0 && path.leafIndex < path.leafNode.entries.length;
439
+ if (path.on || path.leafIndex < path.leafNode.entries.length) {
440
+ return; // got on an entry, or an interior crack — nothing to advance into
441
+ }
442
+ // end-of-leaf crack (leafIndex === entries.length): fall through to branch-popping leaf-advance
443
+ } else if (path.leafIndex < path.leafNode.entries.length - 1) {
444
+ ++path.leafIndex;
445
+ path.on = true;
446
+ return;
447
+ }
448
+ // on the last entry of the leaf, or off an end-of-leaf crack: advance into the next leaf
449
+ let popCount = 0;
450
+ let found = false;
451
+ const last = path.branches.length - 1;
452
+ while (popCount <= last && !found) {
453
+ const branch = path.branches[last - popCount]!;
454
+ if (branch.index === branch.node.partitions.length) // last node in branch
455
+ ++popCount;
456
+ else
457
+ found = true;
458
+ }
459
+
460
+ if (!found) {
461
+ path.leafIndex = path.leafNode.entries.length; // after last row = end crack
462
+ path.on = false;
463
+ } else {
464
+ path.branches.splice(-popCount, popCount);
465
+ const branch = path.branches.at(-1)!;
466
+ ++branch.index;
467
+ await this.moveToFirst(await get(this.store, branch.node.nodes[branch.index]!), path);
468
+ }
469
+ }
470
+
471
+ private async internalPrior(path: Path<TKey, TEntry>) {
472
+ this.validatePath(path);
473
+ if (path.leafIndex <= 0) {
474
+ let popCount = 0;
475
+ let opening = false;
476
+ const last = path.branches.length - 1;
477
+ while (popCount <= last && !opening) {
478
+ const branch = path.branches[last - popCount]!;
479
+ if (branch.index === 0) // first node in branch
480
+ ++popCount;
481
+ else
482
+ opening = true;
483
+ }
484
+
485
+ if (!opening) {
486
+ path.leafIndex = 0;
487
+ path.on = false;
488
+ } else {
489
+ path.branches.splice(-popCount, popCount);
490
+ const branch = path.branches.at(-1)!;
491
+ --branch.index;
492
+ await this.moveToLast(await get(this.store, branch.node.nodes[branch.index]!), path);
493
+ }
494
+ }
495
+ else {
496
+ --path.leafIndex;
497
+ path.on = true;
498
+ }
499
+ }
500
+
501
+ private async internalUpdate(path: Path<TKey, TEntry>, newEntry: TEntry): Promise<[path: Path<TKey, TEntry>, wasUpdate: boolean]> {
502
+ if (path.on) {
503
+ const oldKey = this.keyFromPath(path);
504
+ const newKey = this.keyFromEntry(newEntry);
505
+ if (this.compare(oldKey, newKey) !== 0) { // if key changed, delete and re-insert
506
+ let newPath = await this.internalInsert(newEntry)
507
+ if (newPath.on) { // insert succeeded
508
+ await this.internalDelete(await this.find(oldKey)); // Re-find - the prior insert invalidated the path
509
+ newPath = await this.find(newKey); // Re-find- delete invalidated path
510
+ }
511
+ return [newPath, false];
512
+ } else {
513
+ this.updateEntry(path, newEntry);
514
+ }
515
+ }
516
+ return [path, true];
517
+ }
518
+
519
+ protected async internalDelete(path: Path<TKey, TEntry>): Promise<boolean> {
520
+ if (path.on) {
521
+ apply(this.store, path.leafNode, [entries$, path.leafIndex, 1, []]);
522
+ if (path.branches.length > 0) { // Only worry about underflows, balancing, etc. if not root
523
+ if (path.leafIndex === 0 && path.leafNode.entries.length > 0) { // If we deleted index 0 and leaf is not empty, update branches with new key
524
+ const pathBranch = path.branches.at(-1)!;
525
+ this.updatePartition(pathBranch.index, path, path.branches.length - 1,
526
+ this.keyFromPath(path));
527
+ }
528
+ const newRoot = await this.rebalanceLeaf(path, path.branches.length);
529
+ if (newRoot) {
530
+ await this.trunk.set(newRoot);
531
+ }
532
+ }
533
+ path.on = false;
534
+ return true;
535
+ } else {
536
+ return false;
537
+ }
538
+ }
539
+
540
+ private async internalInsert(entry: TEntry): Promise<Path<TKey, TEntry>> {
541
+ const path = await this.find(this.keyFromEntry(entry));
542
+ if (path.on) {
543
+ path.on = false;
544
+ return path;
545
+ }
546
+ await this.internalInsertAt(path, entry);
547
+ path.on = true;
548
+ return path;
549
+ }
550
+
551
+ private async internalInsertAt(path: Path<TKey, TEntry>, entry: TEntry) {
552
+ let split = this.leafInsert(path, entry);
553
+ let branchIndex = path.branches.length - 1;
554
+ while (split && branchIndex >= 0) {
555
+ split = await this.branchInsert(path, branchIndex, split);
556
+ --branchIndex;
557
+ }
558
+ if (split) {
559
+ const newBranch = newBranchNode(this.store, [split.key], [await this.trunk.getId(), split.right.header.id]);
560
+ this.store.insert(newBranch);
561
+ await this.trunk.set(newBranch);
562
+ path.branches.unshift(new PathBranch(newBranch, split.indexDelta));
563
+ }
564
+ }
565
+
566
+ /** Starting from the given node, recursively working down to the leaf, build onto the path based on the beginning-most entry. */
567
+ private async moveToFirst(node: ITreeNode, path: Path<TKey, TEntry>) {
568
+ if (node.header.type === TreeLeafBlockType) {
569
+ const leaf = node as LeafNode<TEntry>;
570
+ path.leafNode = leaf;
571
+ path.leafIndex = 0;
572
+ path.on = leaf.entries.length > 0;
573
+ } else {
574
+ path.branches.push(new PathBranch(node as BranchNode<TKey>, 0));
575
+ await this.moveToFirst(await get(this.store, (node as BranchNode<TKey>).nodes[0]!), path);
576
+ }
577
+ }
578
+
579
+ /** Starting from the given node, recursively working down to the leaf, build onto the path based on the end-most entry. */
580
+ private async moveToLast(node: ITreeNode, path: Path<TKey, TEntry>) {
581
+ if (node.header.type === TreeLeafBlockType) {
582
+ const leaf = node as LeafNode<TEntry>;
583
+ const count = leaf.entries.length;
584
+ path.leafNode = leaf;
585
+ path.on = count > 0;
586
+ path.leafIndex = count > 0 ? count - 1 : 0;
587
+ } else {
588
+ const branch = node as BranchNode<TKey>;
589
+ const pathBranch = new PathBranch(branch, branch.partitions.length);
590
+ path.branches.push(pathBranch);
591
+ await this.moveToLast(await get(this.store, branch.nodes[pathBranch.index]!), path);
592
+ }
593
+ }
594
+
595
+ /** Construct a path based on the first-most edge of the given. */
596
+ private async getFirst(node: ITreeNode): Promise<Path<TKey, TEntry>> {
597
+ if (node.header.type === TreeLeafBlockType) {
598
+ const leaf = node as LeafNode<TEntry>;
599
+ return new Path<TKey, TEntry>([], leaf, 0, leaf.entries.length > 0, this._version)
600
+ } else {
601
+ const branch = node as BranchNode<TKey>;
602
+ const path = await this.getFirst(await get(this.store, branch.nodes[0]!));
603
+ path.branches.unshift(new PathBranch(branch, 0));
604
+ return path;
605
+ }
606
+ }
607
+
608
+ /** Construct a path based on the last-most edge of the given node */
609
+ private async getLast(node: ITreeNode): Promise<Path<TKey, TEntry>> {
610
+ if (node.header.type === TreeLeafBlockType) {
611
+ const leaf = node as LeafNode<TEntry>;
612
+ const count = leaf.entries.length;
613
+ return new Path<TKey, TEntry>([], leaf, count > 0 ? count - 1 : 0, count > 0, this._version);
614
+ } else {
615
+ const branch = node as BranchNode<TKey>;
616
+ const index = branch.nodes.length - 1;
617
+ const path = await this.getLast(await get(this.store, branch.nodes[index]!));
618
+ path.branches.unshift(new PathBranch(branch, index));
619
+ return path;
620
+ }
621
+ }
622
+
623
+ private leafInsert(path: Path<TKey, TEntry>, entry: TEntry): Split<TKey> | undefined {
624
+ const { leafNode: leaf, leafIndex: index } = path;
625
+ if (leaf.entries.length < this.nodeCapacity) { // No split needed
626
+ apply(this.store, leaf, [entries$, index, 0, [entry]]);
627
+ return undefined;
628
+ }
629
+ // Full. Split needed
630
+
631
+ const midIndex = (leaf.entries.length + 1) >>> 1;
632
+ const newEntries = leaf.entries.slice(midIndex);
633
+
634
+ // New node
635
+ if (index >= midIndex) { // Put the new entry directly rather than log an insert
636
+ newEntries.splice(index - midIndex, 0, entry);
637
+ }
638
+ const newLeaf = newLeafNode(this.store, newEntries);
639
+ this.store.insert(newLeaf);
640
+
641
+ // Delete entries from old node
642
+ apply(this.store, leaf, [entries$, midIndex, leaf.entries.length - midIndex, []]);
643
+
644
+ if (index < midIndex) { // Insert new entry into old node
645
+ apply(this.store, leaf, [entries$, index, 0, [entry]]);
646
+ } else {
647
+ path.leafNode = newLeaf;
648
+ path.leafIndex -= midIndex;
649
+ }
650
+
651
+ return new Split<TKey>(this.keyFromEntry(newEntries[0]!), newLeaf, index < midIndex ? 0 : 1);
652
+ }
653
+
654
+ private async branchInsert(path: Path<TKey, TEntry>, branchIndex: number, split: Split<TKey>): Promise<Split<TKey> | undefined> {
655
+ const pathBranch = path.branches[branchIndex]!;
656
+ const { index: splitIndex, node } = pathBranch;
657
+ pathBranch.index += split.indexDelta;
658
+ if (node.nodes.length < this.nodeCapacity) { // no split needed
659
+ apply(this.store, node, [partitions$, splitIndex, 0, [split.key]]);
660
+ apply(this.store, node, [nodes$, splitIndex + 1, 0, [split.right.header.id]]);
661
+ return undefined;
662
+ }
663
+ // Full. Split needed
664
+
665
+ const midIndex = (node.nodes.length + 1) >>> 1;
666
+ const newPartitions = node.partitions.slice(midIndex);
667
+ const newNodes = node.nodes.slice(midIndex);
668
+ const delta = pathBranch.index < midIndex ? 0 : 1;
669
+
670
+ // New node
671
+ if (delta) { // If split is on new, add it before the split to avoid logging an insert
672
+ pathBranch.index -= midIndex;
673
+ newPartitions.splice(pathBranch.index, 0, split.key);
674
+ newNodes.splice(pathBranch.index + 1, 0, split.right.header.id);
675
+ }
676
+ const newBranch = newBranchNode(this.store, newPartitions, newNodes);
677
+ this.store.insert(newBranch);
678
+
679
+ // Delete partitions and nodes
680
+ const newPartition = node.partitions[midIndex - 1]!;
681
+ apply(this.store, node, [partitions$, midIndex - 1, newPartitions.length + 1, []]);
682
+ apply(this.store, node, [nodes$, midIndex, newNodes.length, []]);
683
+
684
+ if (pathBranch.index < midIndex) { // Insert into old node
685
+ apply(this.store, node, [partitions$, splitIndex, 0, [split.key]]);
686
+ apply(this.store, node, [nodes$, splitIndex + 1, 0, [split.right.header.id]]);
687
+ }
688
+
689
+ return new Split<TKey>(newPartition, newBranch, delta);
690
+ }
691
+
692
+ protected async rebalanceLeaf(path: Path<TKey, TEntry>, depth: number): Promise<ITreeNode | undefined> {
693
+ if (depth === 0 || path.leafNode.entries.length >= (this.nodeCapacity >>> 1)) {
694
+ return undefined;
695
+ }
696
+
697
+ const leaf = path.leafNode;
698
+ const parent = path.branches.at(depth - 1)!;
699
+ const pIndex = parent.index;
700
+ const pNode = parent.node;
701
+
702
+ const rightSibId = pNode.nodes[pIndex + 1];
703
+ const rightSib = rightSibId ? (await get(this.store, rightSibId)) as LeafNode<TEntry> : undefined;
704
+ if (rightSib && rightSib.entries.length > (this.nodeCapacity >>> 1)) { // Attempt to borrow from right sibling
705
+ const entry = rightSib.entries[0]!;
706
+ apply(this.store, rightSib, [entries$, 0, 1, []]);
707
+ apply(this.store, leaf, [entries$, leaf.entries.length, 0, [entry]]);
708
+ this.updatePartition(pIndex + 1, path, depth - 1, this.keyFromEntry(rightSib.entries[0]!));
709
+ return undefined;
710
+ }
711
+
712
+ const leftSibId = pNode.nodes[pIndex - 1];
713
+ const leftSib = leftSibId ? (await get(this.store, leftSibId)) as LeafNode<TEntry> : undefined;
714
+ if (leftSib && leftSib.entries.length > (this.nodeCapacity >>> 1)) { // Attempt to borrow from left sibling
715
+ const entry = leftSib.entries[leftSib.entries.length - 1]!;
716
+ apply(this.store, leftSib, [entries$, leftSib.entries.length - 1, 1, []]);
717
+ apply(this.store, leaf, [entries$, 0, 0, [entry]]);
718
+ this.updatePartition(pIndex, path, depth - 1, this.keyFromEntry(entry));
719
+ path.leafIndex += 1;
720
+ return undefined;
721
+ }
722
+
723
+ if (rightSib && rightSib.entries.length + leaf.entries.length <= this.nodeCapacity) { // Attempt to merge right sibling into leaf (right sib deleted)
724
+ apply(this.store, leaf, [entries$, leaf.entries.length, 0, rightSib.entries]);
725
+ this.deletePartition(pNode, pIndex);
726
+ if (pIndex === 0) { // 0th node of parent, update parent key
727
+ this.updatePartition(pIndex, path, depth - 1, this.keyFromEntry(leaf.entries[0]!));
728
+ }
729
+ this.store.delete(rightSib.header.id);
730
+ return await this.rebalanceBranch(path, depth - 1);
731
+ }
732
+
733
+ if (leftSib && leftSib.entries.length + leaf.entries.length <= this.nodeCapacity) { // Attempt to merge into left sibling (leaf deleted)
734
+ // NOTE: this fixes leafIndex, but the parent-branch index up the path is left pointing at
735
+ // the now-deleted leaf's old slot (same tolerated-staleness class as rebalanceBranch's
736
+ // left-merge, part c). Harmless today because deleteAt version-bumps and abandons the
737
+ // returned path. A future path-reuse consumer must audit BOTH left-merge sites, not just
738
+ // rebalanceBranch.
739
+ path.leafNode = leftSib;
740
+ path.leafIndex += leftSib.entries.length;
741
+ apply(this.store, leftSib, [entries$, leftSib.entries.length, 0, leaf.entries]);
742
+ this.deletePartition(pNode, pIndex - 1);
743
+ this.store.delete(leaf.header.id);
744
+ return await this.rebalanceBranch(path, depth - 1);
745
+ }
746
+ }
747
+
748
+ protected async rebalanceBranch(path: Path<TKey, TEntry>, depth: number): Promise<ITreeNode | undefined> {
749
+ const pathBranch = path.branches[depth]!;
750
+ const branch = pathBranch.node;
751
+ if (depth === 0 && branch.partitions.length === 0) { // last node... collapse child into root
752
+ return path.branches[depth + 1]?.node ?? path.leafNode;
753
+ }
754
+
755
+ if (depth === 0 || (branch.nodes.length >= this.nodeCapacity >>> 1)) {
756
+ return undefined;
757
+ }
758
+
759
+ const parent = path.branches.at(depth - 1)!;
760
+ const pIndex = parent.index;
761
+ const pNode = parent.node;
762
+
763
+ const rightSibId = pNode.nodes[pIndex + 1];
764
+ const rightSib = rightSibId ? (await get(this.store, rightSibId)) as BranchNode<TKey> : undefined;
765
+ if (rightSib && rightSib.nodes.length > (this.nodeCapacity >>> 1)) { // Attempt to borrow from right sibling
766
+ const node = rightSib.nodes[0]!;
767
+ const rightKey = rightSib.partitions[0]!;
768
+ this.insertPartition(branch, branch.partitions.length, pNode.partitions[pIndex]!, node);
769
+ this.deletePartition(rightSib, 0, 0);
770
+ this.updatePartition(pIndex + 1, path, depth - 1, rightKey);
771
+ return undefined;
772
+ }
773
+
774
+ const leftSibId = pNode.nodes[pIndex - 1];
775
+ const leftSib = leftSibId ? (await get(this.store, leftSibId)) as BranchNode<TKey> : undefined;
776
+ if (leftSib && leftSib.nodes.length > (this.nodeCapacity >>> 1)) { // Attempt to borrow from left sibling
777
+ const node = leftSib.nodes[leftSib.nodes.length - 1]!;
778
+ const pKey = leftSib.partitions[leftSib.partitions.length - 1]!;
779
+ this.insertPartition(branch, 0, pNode.partitions[pIndex - 1]!, node, 0);
780
+ this.deletePartition(leftSib, leftSib.partitions.length - 1);
781
+ pathBranch.index += 1;
782
+ this.updatePartition(pIndex, path, depth - 1, pKey);
783
+ return undefined;
784
+ }
785
+
786
+ if (rightSib && rightSib.nodes.length + branch.nodes.length <= this.nodeCapacity) { // Attempt to merge right sibling into self
787
+ const pKey = pNode.partitions[pIndex]!;
788
+ this.deletePartition(pNode, pIndex);
789
+ apply(this.store, branch, [partitions$, branch.partitions.length, 0, [pKey]]);
790
+ apply(this.store, branch, [partitions$, branch.partitions.length, 0, rightSib.partitions]);
791
+ apply(this.store, branch, [nodes$, branch.nodes.length, 0, rightSib.nodes]);
792
+ this.store.delete(rightSib.header.id);
793
+ return this.rebalanceBranch(path, depth - 1);
794
+ }
795
+
796
+ if (leftSib && leftSib.nodes.length + branch.nodes.length <= this.nodeCapacity) { // Attempt to merge self into left sibling
797
+ const leftLen = leftSib.nodes.length; // capture BEFORE the appends below shift it (see leaf path at rebalanceLeaf)
798
+ const pKey = pNode.partitions[pIndex - 1]!;
799
+ this.deletePartition(pNode, pIndex - 1);
800
+ apply(this.store, leftSib, [partitions$, leftSib.partitions.length, 0, [pKey]]);
801
+ apply(this.store, leftSib, [partitions$, leftSib.partitions.length, 0, branch.partitions]);
802
+ apply(this.store, leftSib, [nodes$, leftSib.nodes.length, 0, branch.nodes]);
803
+ pathBranch.node = leftSib;
804
+ pathBranch.index += leftLen; // branch's children now sit after leftSib's original children
805
+ this.store.delete(branch.header.id);
806
+ return this.rebalanceBranch(path, depth - 1);
807
+ }
808
+ }
809
+
810
+ protected updatePartition(nodeIndex: number, path: Path<TKey, TEntry>, depth: number, newKey: TKey) {
811
+ const pathBranch = path.branches[depth]!;
812
+ if (nodeIndex > 0) { // Only affects this branch; just update the partition key
813
+ apply(this.store, pathBranch.node, [partitions$, nodeIndex - 1, 1, [newKey]]);
814
+ } else if (depth !== 0) {
815
+ this.updatePartition(path.branches[depth - 1]!.index, path, depth - 1, newKey);
816
+ }
817
+ }
818
+
819
+ protected insertPartition(branch: BranchNode<TKey>, index: number, key: TKey, node: BlockId, nodeOffset = 1) {
820
+ apply(this.store, branch, [partitions$, index, 0, [key]]);
821
+ apply(this.store, branch, [nodes$, index + nodeOffset, 0, [node]]);
822
+ }
823
+
824
+ protected deletePartition(branch: BranchNode<TKey>, index: number, nodeOffset = 1) {
825
+ apply(this.store, branch, [partitions$, index, 1, []]);
826
+ apply(this.store, branch, [nodes$, index + nodeOffset, 1, []]);
827
+ }
828
+
829
+ private validatePath(path: Path<TKey, TEntry>) {
830
+ if (!this.isValid(path)) {
831
+ throw new Error("Path is invalid due to mutation of the tree");
832
+ }
833
+ }
834
+
835
+ /** Iterates every node ID below and including the given node. */
836
+ private async *nodeIds(node: ITreeNode): AsyncIterableIterator<BlockId> {
837
+ // TODO: This would be much more efficient if we avoided iterating into leaf nodes
838
+ if (node.header.type === TreeBranchBlockType) {
839
+ const subNodes = await Promise.all((node as BranchNode<TKey>).nodes.map(id => get(this.store, id)));
840
+ for (let subNode of subNodes) {
841
+ yield* this.nodeIds(subNode);
842
+ }
843
+ }
844
+ yield node.header.id;
845
+ }
846
+
847
+ protected getEntry(path: Path<TKey, TEntry>): TEntry {
848
+ return path.leafNode.entries[path.leafIndex]!;
849
+ }
850
+
851
+ protected updateEntry(path: Path<TKey, TEntry>, entry: TEntry) {
852
+ apply(this.store, path.leafNode, [entries$, path.leafIndex, 1, [entry]]);
853
+ }
854
+ }
855
+
856
+ class Split<TKey> {
857
+ constructor(
858
+ public key: TKey,
859
+ public right: ITreeNode,
860
+ public indexDelta: number
861
+ ) { }
862
+ }
863
+
864
+ function newLeafNode<TEntry>(store: BlockStore<ITreeNode>, entries: TEntry[]): LeafNode<TEntry> {
865
+ const header = store.createBlockHeader(TreeLeafBlockType);
866
+ return { header, entries };
867
+ }
868
+
869
+ function newBranchNode<TKey>(store: BlockStore<ITreeNode>, partitions: TKey[], nodes: BlockId[]): BranchNode<TKey> {
870
+ const header = store.createBlockHeader(TreeBranchBlockType);
871
+ return { header, partitions, nodes };
872
+ }