@optimystic/db-core 1.18.0 → 1.19.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 +2 -1
- package/dist/src/blocks/helpers.d.ts +7 -0
- package/dist/src/blocks/helpers.d.ts.map +1 -1
- package/dist/src/blocks/helpers.js +7 -1
- package/dist/src/blocks/helpers.js.map +1 -1
- package/dist/src/btree/btree.d.ts +100 -4
- package/dist/src/btree/btree.d.ts.map +1 -1
- package/dist/src/btree/btree.js +252 -90
- package/dist/src/btree/btree.js.map +1 -1
- package/dist/src/btree/node-division.d.ts +37 -0
- package/dist/src/btree/node-division.d.ts.map +1 -0
- package/dist/src/btree/node-division.js +133 -0
- package/dist/src/btree/node-division.js.map +1 -0
- package/dist/src/chain/chain.d.ts +23 -0
- package/dist/src/chain/chain.d.ts.map +1 -1
- package/dist/src/chain/chain.js +43 -6
- package/dist/src/chain/chain.js.map +1 -1
- package/dist/src/collection/collection.d.ts +38 -5
- package/dist/src/collection/collection.d.ts.map +1 -1
- package/dist/src/collection/collection.js +126 -11
- package/dist/src/collection/collection.js.map +1 -1
- package/dist/src/collection/struct.d.ts +20 -0
- package/dist/src/collection/struct.d.ts.map +1 -1
- package/dist/src/collection/struct.js.map +1 -1
- package/dist/src/collections/tree/tree.d.ts.map +1 -1
- package/dist/src/collections/tree/tree.js +5 -3
- package/dist/src/collections/tree/tree.js.map +1 -1
- package/dist/src/log/log.d.ts +5 -1
- package/dist/src/log/log.d.ts.map +1 -1
- package/dist/src/log/log.js +7 -1
- package/dist/src/log/log.js.map +1 -1
- package/dist/src/network/block-size.d.ts +67 -0
- package/dist/src/network/block-size.d.ts.map +1 -0
- package/dist/src/network/block-size.js +82 -0
- package/dist/src/network/block-size.js.map +1 -0
- package/dist/src/network/index.d.ts +2 -0
- package/dist/src/network/index.d.ts.map +1 -1
- package/dist/src/network/index.js +2 -0
- package/dist/src/network/index.js.map +1 -1
- package/dist/src/network/struct.d.ts +13 -11
- package/dist/src/network/struct.d.ts.map +1 -1
- package/dist/src/network/struct.js.map +1 -1
- package/dist/src/network/transaction-size.d.ts +59 -0
- package/dist/src/network/transaction-size.d.ts.map +1 -0
- package/dist/src/network/transaction-size.js +74 -0
- package/dist/src/network/transaction-size.js.map +1 -0
- package/dist/src/reactivity/config.d.ts +8 -4
- package/dist/src/reactivity/config.d.ts.map +1 -1
- package/dist/src/reactivity/config.js +7 -3
- package/dist/src/reactivity/config.js.map +1 -1
- package/dist/src/reactivity/rotation.d.ts +9 -3
- package/dist/src/reactivity/rotation.d.ts.map +1 -1
- package/dist/src/reactivity/rotation.js +8 -2
- package/dist/src/reactivity/rotation.js.map +1 -1
- package/dist/src/testing/test-transactor.d.ts +2 -0
- package/dist/src/testing/test-transactor.d.ts.map +1 -1
- package/dist/src/testing/test-transactor.js +10 -0
- package/dist/src/testing/test-transactor.js.map +1 -1
- package/dist/src/transaction/coordinator.d.ts +72 -3
- package/dist/src/transaction/coordinator.d.ts.map +1 -1
- package/dist/src/transaction/coordinator.js +320 -146
- package/dist/src/transaction/coordinator.js.map +1 -1
- package/dist/src/transactor/change-notifier.d.ts +13 -4
- package/dist/src/transactor/change-notifier.d.ts.map +1 -1
- package/dist/src/transactor/change-notifier.js.map +1 -1
- package/dist/src/transactor/network-transactor.d.ts +57 -8
- package/dist/src/transactor/network-transactor.d.ts.map +1 -1
- package/dist/src/transactor/network-transactor.js +185 -24
- package/dist/src/transactor/network-transactor.js.map +1 -1
- package/dist/src/transactor/transactor.d.ts +14 -0
- package/dist/src/transactor/transactor.d.ts.map +1 -1
- package/dist/src/transform/digest.d.ts +20 -0
- package/dist/src/transform/digest.d.ts.map +1 -1
- package/dist/src/transform/digest.js +23 -3
- package/dist/src/transform/digest.js.map +1 -1
- package/package.json +1 -1
- package/src/blocks/helpers.ts +8 -1
- package/src/btree/btree.ts +266 -88
- package/src/btree/node-division.ts +155 -0
- package/src/chain/chain.ts +55 -6
- package/src/collection/collection.ts +135 -13
- package/src/collection/struct.ts +18 -0
- package/src/collections/tree/tree.ts +4 -2
- package/src/log/log.ts +7 -1
- package/src/network/block-size.ts +81 -0
- package/src/network/index.ts +2 -0
- package/src/network/struct.ts +15 -13
- package/src/network/transaction-size.ts +73 -0
- package/src/reactivity/config.ts +8 -4
- package/src/reactivity/rotation.ts +9 -3
- package/src/testing/test-transactor.ts +12 -0
- package/src/transaction/coordinator.ts +383 -154
- package/src/transactor/change-notifier.ts +13 -4
- package/src/transactor/network-transactor.ts +192 -29
- package/src/transactor/transactor.ts +16 -0
- package/src/transform/digest.ts +36 -3
package/src/btree/btree.ts
CHANGED
|
@@ -1,14 +1,20 @@
|
|
|
1
1
|
import { Path, PathBranch } from "./path.js";
|
|
2
2
|
import type { ITreeTrunk, KeyRange, getTrunkFunc } from "./index.js";
|
|
3
|
-
import type { BlockId, BlockStore } from "../blocks/index.js";
|
|
3
|
+
import type { BlockId, BlockOperation, BlockStore } from "../blocks/index.js";
|
|
4
4
|
import { apply, get } from "../blocks/index.js";
|
|
5
5
|
import { TreeLeafBlockType, TreeBranchBlockType, entries$, nodes$, partitions$ } from "./nodes.js";
|
|
6
6
|
import type { BranchNode, ITreeNode, LeafNode } from "./nodes.js";
|
|
7
7
|
import type { TreeBlock } from "./tree-block.js";
|
|
8
8
|
import { AtomicProxy, type AtomicScope } from "../transform/atomic-proxy.js";
|
|
9
|
+
import { jsonEncodedBytes } from "../network/transaction-size.js";
|
|
10
|
+
import { branchItemBytes, divideItems, emptyBranchBytes, emptyLeafBytes, leafItemBytes, runOf } from "./node-division.js";
|
|
9
11
|
|
|
10
12
|
export const NodeCapacity = 64;
|
|
11
13
|
|
|
14
|
+
/** One change to a leaf's `entries`, the splice `[entries$, index, deleteCount, [entry]]`: an insert
|
|
15
|
+
* at `index` (`deleteCount` 0) or the replacement of the entry there (`deleteCount` 1). */
|
|
16
|
+
type LeafEdit<TEntry> = { index: number; deleteCount: 0 | 1; entry: TEntry };
|
|
17
|
+
|
|
12
18
|
/**
|
|
13
19
|
* Represents a lightweight B+(ish)Tree (data at leaves, but no linked list of leaves).
|
|
14
20
|
* Allows for efficient storage and retrieval of data in a sorted manner.
|
|
@@ -29,6 +35,13 @@ export class BTree<TKey, TEntry> {
|
|
|
29
35
|
public readonly keyFromEntry = (entry: TEntry) => entry as unknown as TKey,
|
|
30
36
|
public readonly compare = (a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0 as number,
|
|
31
37
|
public readonly nodeCapacity = NodeCapacity,
|
|
38
|
+
/** When set, a node also splits once its JSON (`jsonEncodedBytes`) would pass this many bytes, and
|
|
39
|
+
* a borrow or merge that would take a node past it is refused. A node may exceed it only while
|
|
40
|
+
* holding the least a node holds — one entry for a leaf, two children for a branch — so a leaf is
|
|
41
|
+
* never larger than the entry that was written into it. Absent, nodes split by count alone and
|
|
42
|
+
* are never serialized to be measured. The tree collection sets it to `BLOCK_TARGET_BYTES`; see
|
|
43
|
+
* "Node size" in `docs/btree.md`. */
|
|
44
|
+
public readonly nodeTargetBytes?: number,
|
|
32
45
|
) {
|
|
33
46
|
}
|
|
34
47
|
|
|
@@ -52,12 +65,14 @@ export class BTree<TKey, TEntry> {
|
|
|
52
65
|
compare = (a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0 as number,
|
|
53
66
|
nodeCapacity = NodeCapacity,
|
|
54
67
|
newId?: BlockId,
|
|
68
|
+
/** See the constructor's `nodeTargetBytes`. */
|
|
69
|
+
nodeTargetBytes?: number,
|
|
55
70
|
) {
|
|
56
71
|
const proxy = new AtomicProxy(store);
|
|
57
72
|
const root = BTree.createRoot(proxy as BlockStore<TreeBlock>);
|
|
58
73
|
proxy.insert(root);
|
|
59
74
|
const trunk = createTrunk(proxy as BlockStore<TreeBlock>, root.header.id, newId);
|
|
60
|
-
const tree = new BTree(proxy, trunk, keyFromEntry, compare, nodeCapacity);
|
|
75
|
+
const tree = new BTree(proxy, trunk, keyFromEntry, compare, nodeCapacity, nodeTargetBytes);
|
|
61
76
|
tree._proxy = proxy;
|
|
62
77
|
return tree;
|
|
63
78
|
}
|
|
@@ -189,7 +204,7 @@ export class BTree<TKey, TEntry> {
|
|
|
189
204
|
const path = await this.find(this.keyFromEntry(entry));
|
|
190
205
|
Object.freeze(entry);
|
|
191
206
|
if (path.on) {
|
|
192
|
-
this.updateEntry(path, entry);
|
|
207
|
+
await this.updateEntry(path, entry);
|
|
193
208
|
} else {
|
|
194
209
|
await this.internalInsertAt(path, entry);
|
|
195
210
|
}
|
|
@@ -510,7 +525,7 @@ export class BTree<TKey, TEntry> {
|
|
|
510
525
|
}
|
|
511
526
|
return [newPath, false];
|
|
512
527
|
} else {
|
|
513
|
-
this.updateEntry(path, newEntry);
|
|
528
|
+
await this.updateEntry(path, newEntry);
|
|
514
529
|
}
|
|
515
530
|
}
|
|
516
531
|
return [path, true];
|
|
@@ -549,18 +564,43 @@ export class BTree<TKey, TEntry> {
|
|
|
549
564
|
}
|
|
550
565
|
|
|
551
566
|
private async internalInsertAt(path: Path<TKey, TEntry>, entry: TEntry) {
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
567
|
+
await this.applyLeafEdit(path, { index: path.leafIndex, deleteCount: 0, entry });
|
|
568
|
+
}
|
|
569
|
+
|
|
570
|
+
/** Apply `edit` to the path's leaf and absorb whatever splits it causes up the path: each parent
|
|
571
|
+
* that cannot take the new children splits in turn, and a split that reaches the root grows the
|
|
572
|
+
* tree by a level. The path follows the edited entry throughout. */
|
|
573
|
+
private async applyLeafEdit(path: Path<TKey, TEntry>, edit: LeafEdit<TEntry>) {
|
|
574
|
+
let overflow = this.leafEdit(path, edit);
|
|
575
|
+
for (let branchIndex = path.branches.length - 1; overflow && branchIndex >= 0; --branchIndex) {
|
|
576
|
+
overflow = await this.branchInsert(path, branchIndex, overflow);
|
|
577
|
+
}
|
|
578
|
+
while (overflow) {
|
|
579
|
+
overflow = await this.growRoot(path, overflow);
|
|
557
580
|
}
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
581
|
+
}
|
|
582
|
+
|
|
583
|
+
/** Put a new root over the old one and the nodes `overflow` left to its right. Written whole when it
|
|
584
|
+
* fits one node, as a root of two children always does. Otherwise — more new nodes than a branch
|
|
585
|
+
* holds, or keys so large that two of them pass the byte target — the root starts as the old root
|
|
586
|
+
* alone and absorbs the rest through {@link branchInsert}, which divides it and may hand back an
|
|
587
|
+
* overflow for the caller to grow another level over. */
|
|
588
|
+
private async growRoot(path: Path<TKey, TEntry>, overflow: Overflow<TKey>): Promise<Overflow<TKey> | undefined> {
|
|
589
|
+
const oldRootId = await this.trunk.getId();
|
|
590
|
+
const keys = overflow.rights.map(right => right.key);
|
|
591
|
+
const ids = overflow.rights.map(right => right.node.header.id);
|
|
592
|
+
const whole = newBranchNode(this.store, keys, [oldRootId, ...ids]);
|
|
593
|
+
if (this.branchRuns(whole, whole.partitions, whole.nodes, overflow.pathRun) === undefined) {
|
|
594
|
+
this.store.insert(whole);
|
|
595
|
+
await this.trunk.set(whole);
|
|
596
|
+
path.branches.unshift(new PathBranch(whole, overflow.pathRun));
|
|
597
|
+
return undefined;
|
|
563
598
|
}
|
|
599
|
+
const root = newBranchNode<TKey>(this.store, [], [oldRootId]);
|
|
600
|
+
this.store.insert(root);
|
|
601
|
+
await this.trunk.set(root);
|
|
602
|
+
path.branches.unshift(new PathBranch(root, 0));
|
|
603
|
+
return await this.branchInsert(path, 0, overflow);
|
|
564
604
|
}
|
|
565
605
|
|
|
566
606
|
/** Starting from the given node, recursively working down to the leaf, build onto the path based on the beginning-most entry. */
|
|
@@ -620,88 +660,139 @@ export class BTree<TKey, TEntry> {
|
|
|
620
660
|
}
|
|
621
661
|
}
|
|
622
662
|
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
663
|
+
/** Apply `edit` to the path's leaf, dividing the leaf when the result would not fit one node (see
|
|
664
|
+
* {@link leafRuns}). The first run of entries stays in the leaf and each further run becomes a new
|
|
665
|
+
* leaf to its right; the edit's entry is placed directly into whichever leaf it falls in rather
|
|
666
|
+
* than logged as an operation on it, so a new leaf is one insert and the old leaf one or two small
|
|
667
|
+
* operations. The path moves to the new leaf when its entry went there.
|
|
668
|
+
* @returns the overflow for the parent to absorb, or `undefined` when the leaf took the edit whole. */
|
|
669
|
+
private leafEdit(path: Path<TKey, TEntry>, edit: LeafEdit<TEntry>): Overflow<TKey> | undefined {
|
|
670
|
+
const { leafNode: leaf } = path;
|
|
671
|
+
const { index, deleteCount, entry } = edit;
|
|
672
|
+
const op: BlockOperation = [entries$, index, deleteCount, [entry]];
|
|
673
|
+
const entries = leaf.entries.slice(); // the leaf as it would stand with the edit applied
|
|
674
|
+
entries.splice(index, deleteCount, entry);
|
|
675
|
+
const runs = this.leafRuns(leaf, entries, index);
|
|
676
|
+
if (runs === undefined) {
|
|
677
|
+
apply(this.store, leaf, op);
|
|
627
678
|
return undefined;
|
|
628
679
|
}
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
//
|
|
635
|
-
if (index
|
|
636
|
-
|
|
680
|
+
const rights = runs.slice(1, -1).map((from, i) => {
|
|
681
|
+
const node = newLeafNode(this.store, entries.slice(from, runs[i + 2]!));
|
|
682
|
+
this.store.insert(node);
|
|
683
|
+
return { key: this.keyFromEntry(entries[from]!), node };
|
|
684
|
+
});
|
|
685
|
+
const end = runs[1]!; // this leaf keeps the entries before it
|
|
686
|
+
if (index < end) { // the edit lands in this leaf: cut the tail off, then apply it
|
|
687
|
+
this.cutTail(leaf, entries$, leaf.entries.length, end - 1 + deleteCount); // what stays, counted in the leaf as it stands
|
|
688
|
+
apply(this.store, leaf, op);
|
|
689
|
+
} else { // the edit landed in a new leaf, placed above
|
|
690
|
+
this.cutTail(leaf, entries$, leaf.entries.length, end);
|
|
637
691
|
}
|
|
638
|
-
const
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
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;
|
|
692
|
+
const pathRun = runOf(runs, index);
|
|
693
|
+
if (pathRun > 0) {
|
|
694
|
+
path.leafNode = rights[pathRun - 1]!.node as LeafNode<TEntry>;
|
|
695
|
+
path.leafIndex = index - runs[pathRun]!;
|
|
649
696
|
}
|
|
697
|
+
return { rights, pathRun };
|
|
698
|
+
}
|
|
650
699
|
|
|
651
|
-
|
|
700
|
+
/** How `entries` — the path's leaf as it would stand after an edit at index `at` — divide into leaves,
|
|
701
|
+
* or `undefined` when they fit one: at most `nodeCapacity` entries and, when the tree has a byte
|
|
702
|
+
* target and the leaf would hold more than one entry, no more than the target's bytes. See
|
|
703
|
+
* {@link divideItems} for the division, a pure function of the leaf's content and the edit, so a
|
|
704
|
+
* replayed or retried action produces the same transforms. */
|
|
705
|
+
private leafRuns(leaf: LeafNode<TEntry>, entries: readonly TEntry[], at: number): number[] | undefined {
|
|
706
|
+
// NOTE: serializes every entry of the leaf once per insert or in-place update, the same order
|
|
707
|
+
// of cost as the commit path's digest of each touched block. If bulk inserts ever show this in
|
|
708
|
+
// a profile, keep a running byte count per leaf instead of re-measuring it.
|
|
709
|
+
const bytes = this.nodeTargetBytes !== undefined && entries.length > 1
|
|
710
|
+
? leafItemBytes(leaf, entries, this.nodeTargetBytes)
|
|
711
|
+
: undefined;
|
|
712
|
+
return divideItems(entries.length, this.nodeCapacity, at, 1, bytes);
|
|
652
713
|
}
|
|
653
714
|
|
|
654
|
-
|
|
715
|
+
/** Absorb a child's overflow into the branch at `branchIndex` of the path: the new children go after
|
|
716
|
+
* the one that split, each under its key. When the branch cannot hold them all ({@link branchRuns})
|
|
717
|
+
* it divides: the first run of children stays with the keys between them, each further run becomes
|
|
718
|
+
* a new branch to the right, and the key before a run's first child is promoted as that branch's
|
|
719
|
+
* key. As in {@link leafEdit}, a new child is placed directly into whichever branch it falls in.
|
|
720
|
+
* @returns the overflow for the next branch up, or `undefined` when this one took the children whole. */
|
|
721
|
+
private async branchInsert(path: Path<TKey, TEntry>, branchIndex: number, overflow: Overflow<TKey>): Promise<Overflow<TKey> | undefined> {
|
|
655
722
|
const pathBranch = path.branches[branchIndex]!;
|
|
656
|
-
const { index:
|
|
657
|
-
pathBranch.index +=
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
723
|
+
const { index: childIndex, node } = pathBranch;
|
|
724
|
+
pathBranch.index += overflow.pathRun;
|
|
725
|
+
const keys = overflow.rights.map(right => right.key);
|
|
726
|
+
const ids = overflow.rights.map(right => right.node.header.id);
|
|
727
|
+
const partitions = node.partitions.slice(); // the branch as it would stand with the children absorbed
|
|
728
|
+
partitions.splice(childIndex, 0, ...keys);
|
|
729
|
+
const nodes = node.nodes.slice();
|
|
730
|
+
nodes.splice(childIndex + 1, 0, ...ids);
|
|
731
|
+
const runs = this.branchRuns(node, partitions, nodes, pathBranch.index);
|
|
732
|
+
if (runs === undefined) {
|
|
733
|
+
this.insertChildren(node, childIndex, keys, ids);
|
|
661
734
|
return undefined;
|
|
662
735
|
}
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
//
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
736
|
+
const rights = runs.slice(1, -1).map((from, i) => {
|
|
737
|
+
const to = runs[i + 2]!;
|
|
738
|
+
const branch = newBranchNode(this.store, partitions.slice(from, to - 1), nodes.slice(from, to));
|
|
739
|
+
this.store.insert(branch);
|
|
740
|
+
return { key: partitions[from - 1]!, node: branch };
|
|
741
|
+
});
|
|
742
|
+
// This branch keeps the children before `end` and the keys between them. Of the new children,
|
|
743
|
+
// those that fall before `end` land here: cut the tail off the branch as it stands, then insert them.
|
|
744
|
+
const end = runs[1]!;
|
|
745
|
+
const landed = Math.min(Math.max(end - (childIndex + 1), 0), ids.length);
|
|
746
|
+
this.cutTail(node, partitions$, node.partitions.length, end - 1 - landed);
|
|
747
|
+
this.cutTail(node, nodes$, node.nodes.length, end - landed);
|
|
748
|
+
if (landed > 0) {
|
|
749
|
+
this.insertChildren(node, childIndex, keys.slice(0, landed), ids.slice(0, landed));
|
|
675
750
|
}
|
|
676
|
-
const
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
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]]);
|
|
751
|
+
const pathRun = runOf(runs, pathBranch.index);
|
|
752
|
+
if (pathRun > 0) {
|
|
753
|
+
pathBranch.node = rights[pathRun - 1]!.node as BranchNode<TKey>;
|
|
754
|
+
pathBranch.index -= runs[pathRun]!;
|
|
687
755
|
}
|
|
756
|
+
return { rights, pathRun };
|
|
757
|
+
}
|
|
688
758
|
|
|
689
|
-
|
|
759
|
+
/** How a branch's children — `partitions` and `nodes` as the branch would stand with new children
|
|
760
|
+
* absorbed, the path following child `at` — divide into branches, or `undefined` when they fit one;
|
|
761
|
+
* the counterpart of {@link leafRuns}. A branch's bytes are its keys and child ids, so only large
|
|
762
|
+
* keys ever make bytes the reason, and a branch of two children (one key) always counts as fitting:
|
|
763
|
+
* nothing smaller routes. */
|
|
764
|
+
private branchRuns(branch: BranchNode<TKey>, partitions: readonly TKey[], nodes: readonly BlockId[], at: number): number[] | undefined {
|
|
765
|
+
const bytes = this.nodeTargetBytes !== undefined && nodes.length > 2
|
|
766
|
+
? branchItemBytes(branch, partitions, nodes, this.nodeTargetBytes)
|
|
767
|
+
: undefined;
|
|
768
|
+
return divideItems(nodes.length, this.nodeCapacity, at, 2, bytes);
|
|
690
769
|
}
|
|
691
770
|
|
|
771
|
+
/** After a delete, fill the path's leaf back up when it is under-full ({@link leafUnderfull}):
|
|
772
|
+
* borrow one entry from a sibling with more than half the count, else merge with a sibling. With
|
|
773
|
+
* a byte target a borrow or merge that would take a leaf past it is refused, so a leaf of a few
|
|
774
|
+
* large entries can stay under half the count for good; see "Node size" in `docs/btree.md`.
|
|
775
|
+
*
|
|
776
|
+
* NOTE: a leaf that is under-full by both measures and whose siblings refuse it by bytes reads
|
|
777
|
+
* both siblings on every delete from it and writes nothing — one delete of its last entry ends
|
|
778
|
+
* that, since an empty leaf always merges. If such reads ever show up, remember the refusal on
|
|
779
|
+
* the path for the rest of the action. */
|
|
692
780
|
protected async rebalanceLeaf(path: Path<TKey, TEntry>, depth: number): Promise<ITreeNode | undefined> {
|
|
693
|
-
if (depth === 0
|
|
781
|
+
if (depth === 0) {
|
|
694
782
|
return undefined;
|
|
695
783
|
}
|
|
696
|
-
|
|
697
784
|
const leaf = path.leafNode;
|
|
785
|
+
const fill = this.measure(leaf);
|
|
786
|
+
if (!this.leafUnderfull(leaf, fill)) {
|
|
787
|
+
return undefined;
|
|
788
|
+
}
|
|
698
789
|
const parent = path.branches.at(depth - 1)!;
|
|
699
790
|
const pIndex = parent.index;
|
|
700
791
|
const pNode = parent.node;
|
|
701
792
|
|
|
702
793
|
const rightSibId = pNode.nodes[pIndex + 1];
|
|
703
794
|
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
|
|
795
|
+
if (rightSib && rightSib.entries.length > (this.nodeCapacity >>> 1) && this.leafTakes(leaf, fill, rightSib.entries[0]!)) { // Attempt to borrow from right sibling
|
|
705
796
|
const entry = rightSib.entries[0]!;
|
|
706
797
|
apply(this.store, rightSib, [entries$, 0, 1, []]);
|
|
707
798
|
apply(this.store, leaf, [entries$, leaf.entries.length, 0, [entry]]);
|
|
@@ -711,7 +802,7 @@ export class BTree<TKey, TEntry> {
|
|
|
711
802
|
|
|
712
803
|
const leftSibId = pNode.nodes[pIndex - 1];
|
|
713
804
|
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
|
|
805
|
+
if (leftSib && leftSib.entries.length > (this.nodeCapacity >>> 1) && this.leafTakes(leaf, fill, leftSib.entries[leftSib.entries.length - 1]!)) { // Attempt to borrow from left sibling
|
|
715
806
|
const entry = leftSib.entries[leftSib.entries.length - 1]!;
|
|
716
807
|
apply(this.store, leftSib, [entries$, leftSib.entries.length - 1, 1, []]);
|
|
717
808
|
apply(this.store, leaf, [entries$, 0, 0, [entry]]);
|
|
@@ -720,7 +811,7 @@ export class BTree<TKey, TEntry> {
|
|
|
720
811
|
return undefined;
|
|
721
812
|
}
|
|
722
813
|
|
|
723
|
-
if (rightSib &&
|
|
814
|
+
if (rightSib && this.leavesMerge(leaf, fill, rightSib)) { // Attempt to merge right sibling into leaf (right sib deleted)
|
|
724
815
|
apply(this.store, leaf, [entries$, leaf.entries.length, 0, rightSib.entries]);
|
|
725
816
|
this.deletePartition(pNode, pIndex);
|
|
726
817
|
if (pIndex === 0) { // 0th node of parent, update parent key
|
|
@@ -730,7 +821,7 @@ export class BTree<TKey, TEntry> {
|
|
|
730
821
|
return await this.rebalanceBranch(path, depth - 1);
|
|
731
822
|
}
|
|
732
823
|
|
|
733
|
-
if (leftSib &&
|
|
824
|
+
if (leftSib && this.leavesMerge(leaf, fill, leftSib)) { // Attempt to merge into left sibling (leaf deleted)
|
|
734
825
|
// NOTE: this fixes leafIndex, but the parent-branch index up the path is left pointing at
|
|
735
826
|
// the now-deleted leaf's old slot (same tolerated-staleness class as rebalanceBranch's
|
|
736
827
|
// left-merge, part c). Harmless today because deleteAt version-bumps and abandons the
|
|
@@ -745,6 +836,10 @@ export class BTree<TKey, TEntry> {
|
|
|
745
836
|
}
|
|
746
837
|
}
|
|
747
838
|
|
|
839
|
+
/** The branch counterpart of {@link rebalanceLeaf}, with the same rules: a branch under-full by
|
|
840
|
+
* count and (with a byte target) by bytes borrows a child from a sibling with more than half the
|
|
841
|
+
* count, else merges with a sibling, and neither may take a branch past the byte target. The key
|
|
842
|
+
* that separates the two in the parent comes down with the borrowed child or the merge. */
|
|
748
843
|
protected async rebalanceBranch(path: Path<TKey, TEntry>, depth: number): Promise<ITreeNode | undefined> {
|
|
749
844
|
const pathBranch = path.branches[depth]!;
|
|
750
845
|
const branch = pathBranch.node;
|
|
@@ -752,7 +847,11 @@ export class BTree<TKey, TEntry> {
|
|
|
752
847
|
return path.branches[depth + 1]?.node ?? path.leafNode;
|
|
753
848
|
}
|
|
754
849
|
|
|
755
|
-
if (depth === 0
|
|
850
|
+
if (depth === 0) {
|
|
851
|
+
return undefined;
|
|
852
|
+
}
|
|
853
|
+
const fill = this.measure(branch);
|
|
854
|
+
if (!this.branchUnderfull(branch, fill)) {
|
|
756
855
|
return undefined;
|
|
757
856
|
}
|
|
758
857
|
|
|
@@ -762,7 +861,7 @@ export class BTree<TKey, TEntry> {
|
|
|
762
861
|
|
|
763
862
|
const rightSibId = pNode.nodes[pIndex + 1];
|
|
764
863
|
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
|
|
864
|
+
if (rightSib && rightSib.nodes.length > (this.nodeCapacity >>> 1) && this.branchTakes(fill, pNode.partitions[pIndex]!, rightSib.nodes[0]!)) { // Attempt to borrow from right sibling
|
|
766
865
|
const node = rightSib.nodes[0]!;
|
|
767
866
|
const rightKey = rightSib.partitions[0]!;
|
|
768
867
|
this.insertPartition(branch, branch.partitions.length, pNode.partitions[pIndex]!, node);
|
|
@@ -773,7 +872,7 @@ export class BTree<TKey, TEntry> {
|
|
|
773
872
|
|
|
774
873
|
const leftSibId = pNode.nodes[pIndex - 1];
|
|
775
874
|
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
|
|
875
|
+
if (leftSib && leftSib.nodes.length > (this.nodeCapacity >>> 1) && this.branchTakes(fill, pNode.partitions[pIndex - 1]!, leftSib.nodes[leftSib.nodes.length - 1]!)) { // Attempt to borrow from left sibling
|
|
777
876
|
const node = leftSib.nodes[leftSib.nodes.length - 1]!;
|
|
778
877
|
const pKey = leftSib.partitions[leftSib.partitions.length - 1]!;
|
|
779
878
|
this.insertPartition(branch, 0, pNode.partitions[pIndex - 1]!, node, 0);
|
|
@@ -783,7 +882,7 @@ export class BTree<TKey, TEntry> {
|
|
|
783
882
|
return undefined;
|
|
784
883
|
}
|
|
785
884
|
|
|
786
|
-
if (rightSib &&
|
|
885
|
+
if (rightSib && this.branchesMerge(branch, fill, rightSib, pNode.partitions[pIndex]!)) { // Attempt to merge right sibling into self
|
|
787
886
|
const pKey = pNode.partitions[pIndex]!;
|
|
788
887
|
this.deletePartition(pNode, pIndex);
|
|
789
888
|
apply(this.store, branch, [partitions$, branch.partitions.length, 0, [pKey]]);
|
|
@@ -793,7 +892,7 @@ export class BTree<TKey, TEntry> {
|
|
|
793
892
|
return this.rebalanceBranch(path, depth - 1);
|
|
794
893
|
}
|
|
795
894
|
|
|
796
|
-
if (leftSib &&
|
|
895
|
+
if (leftSib && this.branchesMerge(branch, fill, leftSib, pNode.partitions[pIndex - 1]!)) { // Attempt to merge self into left sibling
|
|
797
896
|
const leftLen = leftSib.nodes.length; // capture BEFORE the appends below shift it (see leaf path at rebalanceLeaf)
|
|
798
897
|
const pKey = pNode.partitions[pIndex - 1]!;
|
|
799
898
|
this.deletePartition(pNode, pIndex - 1);
|
|
@@ -821,6 +920,22 @@ export class BTree<TKey, TEntry> {
|
|
|
821
920
|
apply(this.store, branch, [nodes$, index + nodeOffset, 0, [node]]);
|
|
822
921
|
}
|
|
823
922
|
|
|
923
|
+
/** Insert children after the child at `index`, each under its key: `keys` go in at `index` and
|
|
924
|
+
* `nodes` at `index + 1`, one operation each. */
|
|
925
|
+
private insertChildren(branch: BranchNode<TKey>, index: number, keys: readonly TKey[], nodes: readonly BlockId[]) {
|
|
926
|
+
apply(this.store, branch, [partitions$, index, 0, keys.slice()]);
|
|
927
|
+
apply(this.store, branch, [nodes$, index + 1, 0, nodes.slice()]);
|
|
928
|
+
}
|
|
929
|
+
|
|
930
|
+
/** Drop the items of `node`'s `entity` array (now `length` long) from `keep` on. Nothing is
|
|
931
|
+
* recorded when there is nothing to drop: a zero-length splice would still mark the block updated
|
|
932
|
+
* and have it written again. */
|
|
933
|
+
private cutTail(node: ITreeNode, entity: string, length: number, keep: number) {
|
|
934
|
+
if (length > keep) {
|
|
935
|
+
apply(this.store, node, [entity, keep, length - keep, []]);
|
|
936
|
+
}
|
|
937
|
+
}
|
|
938
|
+
|
|
824
939
|
protected deletePartition(branch: BranchNode<TKey>, index: number, nodeOffset = 1) {
|
|
825
940
|
apply(this.store, branch, [partitions$, index, 1, []]);
|
|
826
941
|
apply(this.store, branch, [nodes$, index + nodeOffset, 1, []]);
|
|
@@ -848,19 +963,81 @@ export class BTree<TKey, TEntry> {
|
|
|
848
963
|
return path.leafNode.entries[path.leafIndex]!;
|
|
849
964
|
}
|
|
850
965
|
|
|
851
|
-
|
|
852
|
-
|
|
966
|
+
/** Replace the entry at the path in place. A larger entry can take the leaf past the byte target
|
|
967
|
+
* with no insert, so this goes through the same split an insert does ({@link leafEdit}); the path
|
|
968
|
+
* follows the entry when it moves to a new leaf. */
|
|
969
|
+
protected async updateEntry(path: Path<TKey, TEntry>, entry: TEntry) {
|
|
970
|
+
await this.applyLeafEdit(path, { index: path.leafIndex, deleteCount: 1, entry });
|
|
853
971
|
}
|
|
854
|
-
}
|
|
855
972
|
|
|
856
|
-
|
|
857
|
-
|
|
858
|
-
|
|
859
|
-
|
|
860
|
-
|
|
861
|
-
|
|
973
|
+
// The fill rules a delete rebalances by. The node being rebalanced is serialized once, into a
|
|
974
|
+
// `NodeFill`, and each sibling it weighs once; none of this runs without a byte target.
|
|
975
|
+
|
|
976
|
+
/** A node's bytes against the byte target, or `undefined` when the tree has none. */
|
|
977
|
+
private measure(node: ITreeNode): NodeFill | undefined {
|
|
978
|
+
return this.nodeTargetBytes === undefined ? undefined : { bytes: jsonEncodedBytes(node), target: this.nodeTargetBytes };
|
|
979
|
+
}
|
|
980
|
+
|
|
981
|
+
/** A leaf below half the count AND, with a byte target, below half the target — one that a borrow
|
|
982
|
+
* or merge could usefully fill. A leaf of a few large entries is under half the count for good but
|
|
983
|
+
* is a healthy block, so it is left alone and a delete from it reads no sibling. */
|
|
984
|
+
private leafUnderfull(leaf: LeafNode<TEntry>, fill: NodeFill | undefined): boolean {
|
|
985
|
+
return leaf.entries.length < (this.nodeCapacity >>> 1) && (fill === undefined || fill.bytes < fill.target / 2);
|
|
986
|
+
}
|
|
987
|
+
|
|
988
|
+
/** Whether `leaf` may take one more `entry` from a sibling without passing the byte target. */
|
|
989
|
+
private leafTakes(leaf: LeafNode<TEntry>, fill: NodeFill | undefined, entry: TEntry): boolean {
|
|
990
|
+
return fill === undefined
|
|
991
|
+
|| fill.bytes + jsonEncodedBytes(entry) + (leaf.entries.length > 0 ? 1 : 0) <= fill.target;
|
|
992
|
+
}
|
|
993
|
+
|
|
994
|
+
/** Whether `leaf` and a sibling may become one: within the count, and within the byte target unless
|
|
995
|
+
* one of them is empty — removing an empty leaf adds nothing to the other, so that is never refused
|
|
996
|
+
* and no empty leaf outlives the delete that emptied it. Whichever of the two survives, the merged
|
|
997
|
+
* leaf is one fixed part plus both sets of entries and the comma that joins them. */
|
|
998
|
+
private leavesMerge(leaf: LeafNode<TEntry>, fill: NodeFill | undefined, sibling: LeafNode<TEntry>): boolean {
|
|
999
|
+
if (leaf.entries.length + sibling.entries.length > this.nodeCapacity) {
|
|
1000
|
+
return false;
|
|
1001
|
+
}
|
|
1002
|
+
if (fill === undefined || leaf.entries.length === 0 || sibling.entries.length === 0) {
|
|
1003
|
+
return true;
|
|
1004
|
+
}
|
|
1005
|
+
return fill.bytes + jsonEncodedBytes(sibling) - emptyLeafBytes(sibling) + 1 <= fill.target;
|
|
1006
|
+
}
|
|
1007
|
+
|
|
1008
|
+
/** {@link leafUnderfull} for a branch, by its children. */
|
|
1009
|
+
private branchUnderfull(branch: BranchNode<TKey>, fill: NodeFill | undefined): boolean {
|
|
1010
|
+
return branch.nodes.length < (this.nodeCapacity >>> 1) && (fill === undefined || fill.bytes < fill.target / 2);
|
|
1011
|
+
}
|
|
1012
|
+
|
|
1013
|
+
/** Whether the measured branch may take one more child, `node`, under `key` — the parent's key
|
|
1014
|
+
* that comes down with it — without passing the byte target: the key and the id, a comma before each. */
|
|
1015
|
+
private branchTakes(fill: NodeFill | undefined, key: TKey, node: BlockId): boolean {
|
|
1016
|
+
return fill === undefined
|
|
1017
|
+
|| fill.bytes + jsonEncodedBytes(key) + jsonEncodedBytes(node) + 2 <= fill.target;
|
|
1018
|
+
}
|
|
1019
|
+
|
|
1020
|
+
/** Whether `branch` and a sibling may become one under `key`, the parent's key between them: within
|
|
1021
|
+
* the count and, with a byte target, within it — the sibling's keys and ids, the key that comes down,
|
|
1022
|
+
* and the three commas that join them (one before the key, one before each of the two lists). A
|
|
1023
|
+
* branch is never empty, so there is no exemption. */
|
|
1024
|
+
private branchesMerge(branch: BranchNode<TKey>, fill: NodeFill | undefined, sibling: BranchNode<TKey>, key: TKey): boolean {
|
|
1025
|
+
if (branch.nodes.length + sibling.nodes.length > this.nodeCapacity) {
|
|
1026
|
+
return false;
|
|
1027
|
+
}
|
|
1028
|
+
return fill === undefined
|
|
1029
|
+
|| fill.bytes + jsonEncodedBytes(sibling) - emptyBranchBytes(sibling) + jsonEncodedBytes(key) + 3 <= fill.target;
|
|
1030
|
+
}
|
|
862
1031
|
}
|
|
863
1032
|
|
|
1033
|
+
/** A node's bytes weighed against the tree's byte target, measured once per rebalance. */
|
|
1034
|
+
type NodeFill = { bytes: number; target: number };
|
|
1035
|
+
|
|
1036
|
+
/** What a node that divided hands its parent: the nodes now to its right, each under the lowest key
|
|
1037
|
+
* beneath it, and which of the resulting nodes the path's entry is in — 0 for the node that divided,
|
|
1038
|
+
* 1 for the first to its right, and so on. */
|
|
1039
|
+
type Overflow<TKey> = { rights: { key: TKey; node: ITreeNode }[]; pathRun: number };
|
|
1040
|
+
|
|
864
1041
|
function newLeafNode<TEntry>(store: BlockStore<ITreeNode>, entries: TEntry[]): LeafNode<TEntry> {
|
|
865
1042
|
const header = store.createBlockHeader(TreeLeafBlockType);
|
|
866
1043
|
return { header, entries };
|
|
@@ -870,3 +1047,4 @@ function newBranchNode<TKey>(store: BlockStore<ITreeNode>, partitions: TKey[], n
|
|
|
870
1047
|
const header = store.createBlockHeader(TreeBranchBlockType);
|
|
871
1048
|
return { header, partitions, nodes };
|
|
872
1049
|
}
|
|
1050
|
+
|