@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.
Files changed (96) hide show
  1. package/README.md +2 -1
  2. package/dist/src/blocks/helpers.d.ts +7 -0
  3. package/dist/src/blocks/helpers.d.ts.map +1 -1
  4. package/dist/src/blocks/helpers.js +7 -1
  5. package/dist/src/blocks/helpers.js.map +1 -1
  6. package/dist/src/btree/btree.d.ts +100 -4
  7. package/dist/src/btree/btree.d.ts.map +1 -1
  8. package/dist/src/btree/btree.js +252 -90
  9. package/dist/src/btree/btree.js.map +1 -1
  10. package/dist/src/btree/node-division.d.ts +37 -0
  11. package/dist/src/btree/node-division.d.ts.map +1 -0
  12. package/dist/src/btree/node-division.js +133 -0
  13. package/dist/src/btree/node-division.js.map +1 -0
  14. package/dist/src/chain/chain.d.ts +23 -0
  15. package/dist/src/chain/chain.d.ts.map +1 -1
  16. package/dist/src/chain/chain.js +43 -6
  17. package/dist/src/chain/chain.js.map +1 -1
  18. package/dist/src/collection/collection.d.ts +38 -5
  19. package/dist/src/collection/collection.d.ts.map +1 -1
  20. package/dist/src/collection/collection.js +126 -11
  21. package/dist/src/collection/collection.js.map +1 -1
  22. package/dist/src/collection/struct.d.ts +20 -0
  23. package/dist/src/collection/struct.d.ts.map +1 -1
  24. package/dist/src/collection/struct.js.map +1 -1
  25. package/dist/src/collections/tree/tree.d.ts.map +1 -1
  26. package/dist/src/collections/tree/tree.js +5 -3
  27. package/dist/src/collections/tree/tree.js.map +1 -1
  28. package/dist/src/log/log.d.ts +5 -1
  29. package/dist/src/log/log.d.ts.map +1 -1
  30. package/dist/src/log/log.js +7 -1
  31. package/dist/src/log/log.js.map +1 -1
  32. package/dist/src/network/block-size.d.ts +67 -0
  33. package/dist/src/network/block-size.d.ts.map +1 -0
  34. package/dist/src/network/block-size.js +82 -0
  35. package/dist/src/network/block-size.js.map +1 -0
  36. package/dist/src/network/index.d.ts +2 -0
  37. package/dist/src/network/index.d.ts.map +1 -1
  38. package/dist/src/network/index.js +2 -0
  39. package/dist/src/network/index.js.map +1 -1
  40. package/dist/src/network/struct.d.ts +13 -11
  41. package/dist/src/network/struct.d.ts.map +1 -1
  42. package/dist/src/network/struct.js.map +1 -1
  43. package/dist/src/network/transaction-size.d.ts +59 -0
  44. package/dist/src/network/transaction-size.d.ts.map +1 -0
  45. package/dist/src/network/transaction-size.js +74 -0
  46. package/dist/src/network/transaction-size.js.map +1 -0
  47. package/dist/src/reactivity/config.d.ts +8 -4
  48. package/dist/src/reactivity/config.d.ts.map +1 -1
  49. package/dist/src/reactivity/config.js +7 -3
  50. package/dist/src/reactivity/config.js.map +1 -1
  51. package/dist/src/reactivity/rotation.d.ts +9 -3
  52. package/dist/src/reactivity/rotation.d.ts.map +1 -1
  53. package/dist/src/reactivity/rotation.js +8 -2
  54. package/dist/src/reactivity/rotation.js.map +1 -1
  55. package/dist/src/testing/test-transactor.d.ts +2 -0
  56. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  57. package/dist/src/testing/test-transactor.js +10 -0
  58. package/dist/src/testing/test-transactor.js.map +1 -1
  59. package/dist/src/transaction/coordinator.d.ts +72 -3
  60. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  61. package/dist/src/transaction/coordinator.js +320 -146
  62. package/dist/src/transaction/coordinator.js.map +1 -1
  63. package/dist/src/transactor/change-notifier.d.ts +13 -4
  64. package/dist/src/transactor/change-notifier.d.ts.map +1 -1
  65. package/dist/src/transactor/change-notifier.js.map +1 -1
  66. package/dist/src/transactor/network-transactor.d.ts +57 -8
  67. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  68. package/dist/src/transactor/network-transactor.js +185 -24
  69. package/dist/src/transactor/network-transactor.js.map +1 -1
  70. package/dist/src/transactor/transactor.d.ts +14 -0
  71. package/dist/src/transactor/transactor.d.ts.map +1 -1
  72. package/dist/src/transform/digest.d.ts +20 -0
  73. package/dist/src/transform/digest.d.ts.map +1 -1
  74. package/dist/src/transform/digest.js +23 -3
  75. package/dist/src/transform/digest.js.map +1 -1
  76. package/package.json +1 -1
  77. package/src/blocks/helpers.ts +8 -1
  78. package/src/btree/btree.ts +266 -88
  79. package/src/btree/node-division.ts +155 -0
  80. package/src/chain/chain.ts +55 -6
  81. package/src/collection/collection.ts +135 -13
  82. package/src/collection/struct.ts +18 -0
  83. package/src/collections/tree/tree.ts +4 -2
  84. package/src/log/log.ts +7 -1
  85. package/src/network/block-size.ts +81 -0
  86. package/src/network/index.ts +2 -0
  87. package/src/network/struct.ts +15 -13
  88. package/src/network/transaction-size.ts +73 -0
  89. package/src/reactivity/config.ts +8 -4
  90. package/src/reactivity/rotation.ts +9 -3
  91. package/src/testing/test-transactor.ts +12 -0
  92. package/src/transaction/coordinator.ts +383 -154
  93. package/src/transactor/change-notifier.ts +13 -4
  94. package/src/transactor/network-transactor.ts +192 -29
  95. package/src/transactor/transactor.ts +16 -0
  96. package/src/transform/digest.ts +36 -3
@@ -2,6 +2,8 @@ import { Path, PathBranch } from "./path.js";
2
2
  import { apply, get } from "../blocks/index.js";
3
3
  import { TreeLeafBlockType, TreeBranchBlockType, entries$, nodes$, partitions$ } from "./nodes.js";
4
4
  import { AtomicProxy } from "../transform/atomic-proxy.js";
5
+ import { jsonEncodedBytes } from "../network/transaction-size.js";
6
+ import { branchItemBytes, divideItems, emptyBranchBytes, emptyLeafBytes, leafItemBytes, runOf } from "./node-division.js";
5
7
  export const NodeCapacity = 64;
6
8
  /**
7
9
  * Represents a lightweight B+(ish)Tree (data at leaves, but no linked list of leaves).
@@ -15,18 +17,27 @@ export class BTree {
15
17
  keyFromEntry;
16
18
  compare;
17
19
  nodeCapacity;
20
+ nodeTargetBytes;
18
21
  _version = 0; // only for path invalidation
19
22
  _proxy;
20
23
  /**
21
24
  * @param [compare=(a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0] a comparison function for keys. The default uses < and > operators.
22
25
  * @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.
23
26
  */
24
- constructor(store, trunk, keyFromEntry = (entry) => entry, compare = (a, b) => a < b ? -1 : a > b ? 1 : 0, nodeCapacity = NodeCapacity) {
27
+ constructor(store, trunk, keyFromEntry = (entry) => entry, compare = (a, b) => a < b ? -1 : a > b ? 1 : 0, nodeCapacity = NodeCapacity,
28
+ /** When set, a node also splits once its JSON (`jsonEncodedBytes`) would pass this many bytes, and
29
+ * a borrow or merge that would take a node past it is refused. A node may exceed it only while
30
+ * holding the least a node holds — one entry for a leaf, two children for a branch — so a leaf is
31
+ * never larger than the entry that was written into it. Absent, nodes split by count alone and
32
+ * are never serialized to be measured. The tree collection sets it to `BLOCK_TARGET_BYTES`; see
33
+ * "Node size" in `docs/btree.md`. */
34
+ nodeTargetBytes) {
25
35
  this.store = store;
26
36
  this.trunk = trunk;
27
37
  this.keyFromEntry = keyFromEntry;
28
38
  this.compare = compare;
29
39
  this.nodeCapacity = nodeCapacity;
40
+ this.nodeTargetBytes = nodeTargetBytes;
30
41
  }
31
42
  atomic(fn, parent) {
32
43
  return this._proxy ? this._proxy.atomic(fn, parent) : fn(parent);
@@ -38,12 +49,14 @@ export class BTree {
38
49
  // `as number` so the inferred param type is a comparator returning any number, matching the
39
50
  // constructor above — without it the default narrows to `-1 | 0 | 1` and a perfectly valid
40
51
  // `(a, b) => a - b` comparator is rejected here but accepted there.
41
- compare = (a, b) => a < b ? -1 : a > b ? 1 : 0, nodeCapacity = NodeCapacity, newId) {
52
+ compare = (a, b) => a < b ? -1 : a > b ? 1 : 0, nodeCapacity = NodeCapacity, newId,
53
+ /** See the constructor's `nodeTargetBytes`. */
54
+ nodeTargetBytes) {
42
55
  const proxy = new AtomicProxy(store);
43
56
  const root = BTree.createRoot(proxy);
44
57
  proxy.insert(root);
45
58
  const trunk = createTrunk(proxy, root.header.id, newId);
46
- const tree = new BTree(proxy, trunk, keyFromEntry, compare, nodeCapacity);
59
+ const tree = new BTree(proxy, trunk, keyFromEntry, compare, nodeCapacity, nodeTargetBytes);
47
60
  tree._proxy = proxy;
48
61
  return tree;
49
62
  }
@@ -161,7 +174,7 @@ export class BTree {
161
174
  const path = await this.find(this.keyFromEntry(entry));
162
175
  Object.freeze(entry);
163
176
  if (path.on) {
164
- this.updateEntry(path, entry);
177
+ await this.updateEntry(path, entry);
165
178
  }
166
179
  else {
167
180
  await this.internalInsertAt(path, entry);
@@ -462,7 +475,7 @@ export class BTree {
462
475
  return [newPath, false];
463
476
  }
464
477
  else {
465
- this.updateEntry(path, newEntry);
478
+ await this.updateEntry(path, newEntry);
466
479
  }
467
480
  }
468
481
  return [path, true];
@@ -498,18 +511,41 @@ export class BTree {
498
511
  return path;
499
512
  }
500
513
  async internalInsertAt(path, entry) {
501
- let split = this.leafInsert(path, entry);
502
- let branchIndex = path.branches.length - 1;
503
- while (split && branchIndex >= 0) {
504
- split = await this.branchInsert(path, branchIndex, split);
505
- --branchIndex;
506
- }
507
- if (split) {
508
- const newBranch = newBranchNode(this.store, [split.key], [await this.trunk.getId(), split.right.header.id]);
509
- this.store.insert(newBranch);
510
- await this.trunk.set(newBranch);
511
- path.branches.unshift(new PathBranch(newBranch, split.indexDelta));
514
+ await this.applyLeafEdit(path, { index: path.leafIndex, deleteCount: 0, entry });
515
+ }
516
+ /** Apply `edit` to the path's leaf and absorb whatever splits it causes up the path: each parent
517
+ * that cannot take the new children splits in turn, and a split that reaches the root grows the
518
+ * tree by a level. The path follows the edited entry throughout. */
519
+ async applyLeafEdit(path, edit) {
520
+ let overflow = this.leafEdit(path, edit);
521
+ for (let branchIndex = path.branches.length - 1; overflow && branchIndex >= 0; --branchIndex) {
522
+ overflow = await this.branchInsert(path, branchIndex, overflow);
523
+ }
524
+ while (overflow) {
525
+ overflow = await this.growRoot(path, overflow);
526
+ }
527
+ }
528
+ /** Put a new root over the old one and the nodes `overflow` left to its right. Written whole when it
529
+ * fits one node, as a root of two children always does. Otherwise — more new nodes than a branch
530
+ * holds, or keys so large that two of them pass the byte target — the root starts as the old root
531
+ * alone and absorbs the rest through {@link branchInsert}, which divides it and may hand back an
532
+ * overflow for the caller to grow another level over. */
533
+ async growRoot(path, overflow) {
534
+ const oldRootId = await this.trunk.getId();
535
+ const keys = overflow.rights.map(right => right.key);
536
+ const ids = overflow.rights.map(right => right.node.header.id);
537
+ const whole = newBranchNode(this.store, keys, [oldRootId, ...ids]);
538
+ if (this.branchRuns(whole, whole.partitions, whole.nodes, overflow.pathRun) === undefined) {
539
+ this.store.insert(whole);
540
+ await this.trunk.set(whole);
541
+ path.branches.unshift(new PathBranch(whole, overflow.pathRun));
542
+ return undefined;
512
543
  }
544
+ const root = newBranchNode(this.store, [], [oldRootId]);
545
+ this.store.insert(root);
546
+ await this.trunk.set(root);
547
+ path.branches.unshift(new PathBranch(root, 0));
548
+ return await this.branchInsert(path, 0, overflow);
513
549
  }
514
550
  /** Starting from the given node, recursively working down to the leaf, build onto the path based on the beginning-most entry. */
515
551
  async moveToFirst(node, path) {
@@ -568,75 +604,135 @@ export class BTree {
568
604
  return path;
569
605
  }
570
606
  }
571
- leafInsert(path, entry) {
572
- const { leafNode: leaf, leafIndex: index } = path;
573
- if (leaf.entries.length < this.nodeCapacity) { // No split needed
574
- apply(this.store, leaf, [entries$, index, 0, [entry]]);
607
+ /** Apply `edit` to the path's leaf, dividing the leaf when the result would not fit one node (see
608
+ * {@link leafRuns}). The first run of entries stays in the leaf and each further run becomes a new
609
+ * leaf to its right; the edit's entry is placed directly into whichever leaf it falls in rather
610
+ * than logged as an operation on it, so a new leaf is one insert and the old leaf one or two small
611
+ * operations. The path moves to the new leaf when its entry went there.
612
+ * @returns the overflow for the parent to absorb, or `undefined` when the leaf took the edit whole. */
613
+ leafEdit(path, edit) {
614
+ const { leafNode: leaf } = path;
615
+ const { index, deleteCount, entry } = edit;
616
+ const op = [entries$, index, deleteCount, [entry]];
617
+ const entries = leaf.entries.slice(); // the leaf as it would stand with the edit applied
618
+ entries.splice(index, deleteCount, entry);
619
+ const runs = this.leafRuns(leaf, entries, index);
620
+ if (runs === undefined) {
621
+ apply(this.store, leaf, op);
575
622
  return undefined;
576
623
  }
577
- // Full. Split needed
578
- const midIndex = (leaf.entries.length + 1) >>> 1;
579
- const newEntries = leaf.entries.slice(midIndex);
580
- // New node
581
- if (index >= midIndex) { // Put the new entry directly rather than log an insert
582
- newEntries.splice(index - midIndex, 0, entry);
583
- }
584
- const newLeaf = newLeafNode(this.store, newEntries);
585
- this.store.insert(newLeaf);
586
- // Delete entries from old node
587
- apply(this.store, leaf, [entries$, midIndex, leaf.entries.length - midIndex, []]);
588
- if (index < midIndex) { // Insert new entry into old node
589
- apply(this.store, leaf, [entries$, index, 0, [entry]]);
590
- }
591
- else {
592
- path.leafNode = newLeaf;
593
- path.leafIndex -= midIndex;
594
- }
595
- return new Split(this.keyFromEntry(newEntries[0]), newLeaf, index < midIndex ? 0 : 1);
596
- }
597
- async branchInsert(path, branchIndex, split) {
624
+ const rights = runs.slice(1, -1).map((from, i) => {
625
+ const node = newLeafNode(this.store, entries.slice(from, runs[i + 2]));
626
+ this.store.insert(node);
627
+ return { key: this.keyFromEntry(entries[from]), node };
628
+ });
629
+ const end = runs[1]; // this leaf keeps the entries before it
630
+ if (index < end) { // the edit lands in this leaf: cut the tail off, then apply it
631
+ this.cutTail(leaf, entries$, leaf.entries.length, end - 1 + deleteCount); // what stays, counted in the leaf as it stands
632
+ apply(this.store, leaf, op);
633
+ }
634
+ else { // the edit landed in a new leaf, placed above
635
+ this.cutTail(leaf, entries$, leaf.entries.length, end);
636
+ }
637
+ const pathRun = runOf(runs, index);
638
+ if (pathRun > 0) {
639
+ path.leafNode = rights[pathRun - 1].node;
640
+ path.leafIndex = index - runs[pathRun];
641
+ }
642
+ return { rights, pathRun };
643
+ }
644
+ /** How `entries` — the path's leaf as it would stand after an edit at index `at` — divide into leaves,
645
+ * or `undefined` when they fit one: at most `nodeCapacity` entries and, when the tree has a byte
646
+ * target and the leaf would hold more than one entry, no more than the target's bytes. See
647
+ * {@link divideItems} for the division, a pure function of the leaf's content and the edit, so a
648
+ * replayed or retried action produces the same transforms. */
649
+ leafRuns(leaf, entries, at) {
650
+ // NOTE: serializes every entry of the leaf once per insert or in-place update, the same order
651
+ // of cost as the commit path's digest of each touched block. If bulk inserts ever show this in
652
+ // a profile, keep a running byte count per leaf instead of re-measuring it.
653
+ const bytes = this.nodeTargetBytes !== undefined && entries.length > 1
654
+ ? leafItemBytes(leaf, entries, this.nodeTargetBytes)
655
+ : undefined;
656
+ return divideItems(entries.length, this.nodeCapacity, at, 1, bytes);
657
+ }
658
+ /** Absorb a child's overflow into the branch at `branchIndex` of the path: the new children go after
659
+ * the one that split, each under its key. When the branch cannot hold them all ({@link branchRuns})
660
+ * it divides: the first run of children stays with the keys between them, each further run becomes
661
+ * a new branch to the right, and the key before a run's first child is promoted as that branch's
662
+ * key. As in {@link leafEdit}, a new child is placed directly into whichever branch it falls in.
663
+ * @returns the overflow for the next branch up, or `undefined` when this one took the children whole. */
664
+ async branchInsert(path, branchIndex, overflow) {
598
665
  const pathBranch = path.branches[branchIndex];
599
- const { index: splitIndex, node } = pathBranch;
600
- pathBranch.index += split.indexDelta;
601
- if (node.nodes.length < this.nodeCapacity) { // no split needed
602
- apply(this.store, node, [partitions$, splitIndex, 0, [split.key]]);
603
- apply(this.store, node, [nodes$, splitIndex + 1, 0, [split.right.header.id]]);
666
+ const { index: childIndex, node } = pathBranch;
667
+ pathBranch.index += overflow.pathRun;
668
+ const keys = overflow.rights.map(right => right.key);
669
+ const ids = overflow.rights.map(right => right.node.header.id);
670
+ const partitions = node.partitions.slice(); // the branch as it would stand with the children absorbed
671
+ partitions.splice(childIndex, 0, ...keys);
672
+ const nodes = node.nodes.slice();
673
+ nodes.splice(childIndex + 1, 0, ...ids);
674
+ const runs = this.branchRuns(node, partitions, nodes, pathBranch.index);
675
+ if (runs === undefined) {
676
+ this.insertChildren(node, childIndex, keys, ids);
604
677
  return undefined;
605
678
  }
606
- // Full. Split needed
607
- const midIndex = (node.nodes.length + 1) >>> 1;
608
- const newPartitions = node.partitions.slice(midIndex);
609
- const newNodes = node.nodes.slice(midIndex);
610
- const delta = pathBranch.index < midIndex ? 0 : 1;
611
- // New node
612
- if (delta) { // If split is on new, add it before the split to avoid logging an insert
613
- pathBranch.index -= midIndex;
614
- newPartitions.splice(pathBranch.index, 0, split.key);
615
- newNodes.splice(pathBranch.index + 1, 0, split.right.header.id);
616
- }
617
- const newBranch = newBranchNode(this.store, newPartitions, newNodes);
618
- this.store.insert(newBranch);
619
- // Delete partitions and nodes
620
- const newPartition = node.partitions[midIndex - 1];
621
- apply(this.store, node, [partitions$, midIndex - 1, newPartitions.length + 1, []]);
622
- apply(this.store, node, [nodes$, midIndex, newNodes.length, []]);
623
- if (pathBranch.index < midIndex) { // Insert into old node
624
- apply(this.store, node, [partitions$, splitIndex, 0, [split.key]]);
625
- apply(this.store, node, [nodes$, splitIndex + 1, 0, [split.right.header.id]]);
626
- }
627
- return new Split(newPartition, newBranch, delta);
628
- }
679
+ const rights = runs.slice(1, -1).map((from, i) => {
680
+ const to = runs[i + 2];
681
+ const branch = newBranchNode(this.store, partitions.slice(from, to - 1), nodes.slice(from, to));
682
+ this.store.insert(branch);
683
+ return { key: partitions[from - 1], node: branch };
684
+ });
685
+ // This branch keeps the children before `end` and the keys between them. Of the new children,
686
+ // those that fall before `end` land here: cut the tail off the branch as it stands, then insert them.
687
+ const end = runs[1];
688
+ const landed = Math.min(Math.max(end - (childIndex + 1), 0), ids.length);
689
+ this.cutTail(node, partitions$, node.partitions.length, end - 1 - landed);
690
+ this.cutTail(node, nodes$, node.nodes.length, end - landed);
691
+ if (landed > 0) {
692
+ this.insertChildren(node, childIndex, keys.slice(0, landed), ids.slice(0, landed));
693
+ }
694
+ const pathRun = runOf(runs, pathBranch.index);
695
+ if (pathRun > 0) {
696
+ pathBranch.node = rights[pathRun - 1].node;
697
+ pathBranch.index -= runs[pathRun];
698
+ }
699
+ return { rights, pathRun };
700
+ }
701
+ /** How a branch's children — `partitions` and `nodes` as the branch would stand with new children
702
+ * absorbed, the path following child `at` — divide into branches, or `undefined` when they fit one;
703
+ * the counterpart of {@link leafRuns}. A branch's bytes are its keys and child ids, so only large
704
+ * keys ever make bytes the reason, and a branch of two children (one key) always counts as fitting:
705
+ * nothing smaller routes. */
706
+ branchRuns(branch, partitions, nodes, at) {
707
+ const bytes = this.nodeTargetBytes !== undefined && nodes.length > 2
708
+ ? branchItemBytes(branch, partitions, nodes, this.nodeTargetBytes)
709
+ : undefined;
710
+ return divideItems(nodes.length, this.nodeCapacity, at, 2, bytes);
711
+ }
712
+ /** After a delete, fill the path's leaf back up when it is under-full ({@link leafUnderfull}):
713
+ * borrow one entry from a sibling with more than half the count, else merge with a sibling. With
714
+ * a byte target a borrow or merge that would take a leaf past it is refused, so a leaf of a few
715
+ * large entries can stay under half the count for good; see "Node size" in `docs/btree.md`.
716
+ *
717
+ * NOTE: a leaf that is under-full by both measures and whose siblings refuse it by bytes reads
718
+ * both siblings on every delete from it and writes nothing — one delete of its last entry ends
719
+ * that, since an empty leaf always merges. If such reads ever show up, remember the refusal on
720
+ * the path for the rest of the action. */
629
721
  async rebalanceLeaf(path, depth) {
630
- if (depth === 0 || path.leafNode.entries.length >= (this.nodeCapacity >>> 1)) {
722
+ if (depth === 0) {
631
723
  return undefined;
632
724
  }
633
725
  const leaf = path.leafNode;
726
+ const fill = this.measure(leaf);
727
+ if (!this.leafUnderfull(leaf, fill)) {
728
+ return undefined;
729
+ }
634
730
  const parent = path.branches.at(depth - 1);
635
731
  const pIndex = parent.index;
636
732
  const pNode = parent.node;
637
733
  const rightSibId = pNode.nodes[pIndex + 1];
638
734
  const rightSib = rightSibId ? (await get(this.store, rightSibId)) : undefined;
639
- if (rightSib && rightSib.entries.length > (this.nodeCapacity >>> 1)) { // Attempt to borrow from right sibling
735
+ if (rightSib && rightSib.entries.length > (this.nodeCapacity >>> 1) && this.leafTakes(leaf, fill, rightSib.entries[0])) { // Attempt to borrow from right sibling
640
736
  const entry = rightSib.entries[0];
641
737
  apply(this.store, rightSib, [entries$, 0, 1, []]);
642
738
  apply(this.store, leaf, [entries$, leaf.entries.length, 0, [entry]]);
@@ -645,7 +741,7 @@ export class BTree {
645
741
  }
646
742
  const leftSibId = pNode.nodes[pIndex - 1];
647
743
  const leftSib = leftSibId ? (await get(this.store, leftSibId)) : undefined;
648
- if (leftSib && leftSib.entries.length > (this.nodeCapacity >>> 1)) { // Attempt to borrow from left sibling
744
+ if (leftSib && leftSib.entries.length > (this.nodeCapacity >>> 1) && this.leafTakes(leaf, fill, leftSib.entries[leftSib.entries.length - 1])) { // Attempt to borrow from left sibling
649
745
  const entry = leftSib.entries[leftSib.entries.length - 1];
650
746
  apply(this.store, leftSib, [entries$, leftSib.entries.length - 1, 1, []]);
651
747
  apply(this.store, leaf, [entries$, 0, 0, [entry]]);
@@ -653,7 +749,7 @@ export class BTree {
653
749
  path.leafIndex += 1;
654
750
  return undefined;
655
751
  }
656
- if (rightSib && rightSib.entries.length + leaf.entries.length <= this.nodeCapacity) { // Attempt to merge right sibling into leaf (right sib deleted)
752
+ if (rightSib && this.leavesMerge(leaf, fill, rightSib)) { // Attempt to merge right sibling into leaf (right sib deleted)
657
753
  apply(this.store, leaf, [entries$, leaf.entries.length, 0, rightSib.entries]);
658
754
  this.deletePartition(pNode, pIndex);
659
755
  if (pIndex === 0) { // 0th node of parent, update parent key
@@ -662,7 +758,7 @@ export class BTree {
662
758
  this.store.delete(rightSib.header.id);
663
759
  return await this.rebalanceBranch(path, depth - 1);
664
760
  }
665
- if (leftSib && leftSib.entries.length + leaf.entries.length <= this.nodeCapacity) { // Attempt to merge into left sibling (leaf deleted)
761
+ if (leftSib && this.leavesMerge(leaf, fill, leftSib)) { // Attempt to merge into left sibling (leaf deleted)
666
762
  // NOTE: this fixes leafIndex, but the parent-branch index up the path is left pointing at
667
763
  // the now-deleted leaf's old slot (same tolerated-staleness class as rebalanceBranch's
668
764
  // left-merge, part c). Harmless today because deleteAt version-bumps and abandons the
@@ -676,13 +772,21 @@ export class BTree {
676
772
  return await this.rebalanceBranch(path, depth - 1);
677
773
  }
678
774
  }
775
+ /** The branch counterpart of {@link rebalanceLeaf}, with the same rules: a branch under-full by
776
+ * count and (with a byte target) by bytes borrows a child from a sibling with more than half the
777
+ * count, else merges with a sibling, and neither may take a branch past the byte target. The key
778
+ * that separates the two in the parent comes down with the borrowed child or the merge. */
679
779
  async rebalanceBranch(path, depth) {
680
780
  const pathBranch = path.branches[depth];
681
781
  const branch = pathBranch.node;
682
782
  if (depth === 0 && branch.partitions.length === 0) { // last node... collapse child into root
683
783
  return path.branches[depth + 1]?.node ?? path.leafNode;
684
784
  }
685
- if (depth === 0 || (branch.nodes.length >= this.nodeCapacity >>> 1)) {
785
+ if (depth === 0) {
786
+ return undefined;
787
+ }
788
+ const fill = this.measure(branch);
789
+ if (!this.branchUnderfull(branch, fill)) {
686
790
  return undefined;
687
791
  }
688
792
  const parent = path.branches.at(depth - 1);
@@ -690,7 +794,7 @@ export class BTree {
690
794
  const pNode = parent.node;
691
795
  const rightSibId = pNode.nodes[pIndex + 1];
692
796
  const rightSib = rightSibId ? (await get(this.store, rightSibId)) : undefined;
693
- if (rightSib && rightSib.nodes.length > (this.nodeCapacity >>> 1)) { // Attempt to borrow from right sibling
797
+ if (rightSib && rightSib.nodes.length > (this.nodeCapacity >>> 1) && this.branchTakes(fill, pNode.partitions[pIndex], rightSib.nodes[0])) { // Attempt to borrow from right sibling
694
798
  const node = rightSib.nodes[0];
695
799
  const rightKey = rightSib.partitions[0];
696
800
  this.insertPartition(branch, branch.partitions.length, pNode.partitions[pIndex], node);
@@ -700,7 +804,7 @@ export class BTree {
700
804
  }
701
805
  const leftSibId = pNode.nodes[pIndex - 1];
702
806
  const leftSib = leftSibId ? (await get(this.store, leftSibId)) : undefined;
703
- if (leftSib && leftSib.nodes.length > (this.nodeCapacity >>> 1)) { // Attempt to borrow from left sibling
807
+ 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
704
808
  const node = leftSib.nodes[leftSib.nodes.length - 1];
705
809
  const pKey = leftSib.partitions[leftSib.partitions.length - 1];
706
810
  this.insertPartition(branch, 0, pNode.partitions[pIndex - 1], node, 0);
@@ -709,7 +813,7 @@ export class BTree {
709
813
  this.updatePartition(pIndex, path, depth - 1, pKey);
710
814
  return undefined;
711
815
  }
712
- if (rightSib && rightSib.nodes.length + branch.nodes.length <= this.nodeCapacity) { // Attempt to merge right sibling into self
816
+ if (rightSib && this.branchesMerge(branch, fill, rightSib, pNode.partitions[pIndex])) { // Attempt to merge right sibling into self
713
817
  const pKey = pNode.partitions[pIndex];
714
818
  this.deletePartition(pNode, pIndex);
715
819
  apply(this.store, branch, [partitions$, branch.partitions.length, 0, [pKey]]);
@@ -718,7 +822,7 @@ export class BTree {
718
822
  this.store.delete(rightSib.header.id);
719
823
  return this.rebalanceBranch(path, depth - 1);
720
824
  }
721
- if (leftSib && leftSib.nodes.length + branch.nodes.length <= this.nodeCapacity) { // Attempt to merge self into left sibling
825
+ if (leftSib && this.branchesMerge(branch, fill, leftSib, pNode.partitions[pIndex - 1])) { // Attempt to merge self into left sibling
722
826
  const leftLen = leftSib.nodes.length; // capture BEFORE the appends below shift it (see leaf path at rebalanceLeaf)
723
827
  const pKey = pNode.partitions[pIndex - 1];
724
828
  this.deletePartition(pNode, pIndex - 1);
@@ -744,6 +848,20 @@ export class BTree {
744
848
  apply(this.store, branch, [partitions$, index, 0, [key]]);
745
849
  apply(this.store, branch, [nodes$, index + nodeOffset, 0, [node]]);
746
850
  }
851
+ /** Insert children after the child at `index`, each under its key: `keys` go in at `index` and
852
+ * `nodes` at `index + 1`, one operation each. */
853
+ insertChildren(branch, index, keys, nodes) {
854
+ apply(this.store, branch, [partitions$, index, 0, keys.slice()]);
855
+ apply(this.store, branch, [nodes$, index + 1, 0, nodes.slice()]);
856
+ }
857
+ /** Drop the items of `node`'s `entity` array (now `length` long) from `keep` on. Nothing is
858
+ * recorded when there is nothing to drop: a zero-length splice would still mark the block updated
859
+ * and have it written again. */
860
+ cutTail(node, entity, length, keep) {
861
+ if (length > keep) {
862
+ apply(this.store, node, [entity, keep, length - keep, []]);
863
+ }
864
+ }
747
865
  deletePartition(branch, index, nodeOffset = 1) {
748
866
  apply(this.store, branch, [partitions$, index, 1, []]);
749
867
  apply(this.store, branch, [nodes$, index + nodeOffset, 1, []]);
@@ -767,18 +885,62 @@ export class BTree {
767
885
  getEntry(path) {
768
886
  return path.leafNode.entries[path.leafIndex];
769
887
  }
770
- updateEntry(path, entry) {
771
- apply(this.store, path.leafNode, [entries$, path.leafIndex, 1, [entry]]);
888
+ /** Replace the entry at the path in place. A larger entry can take the leaf past the byte target
889
+ * with no insert, so this goes through the same split an insert does ({@link leafEdit}); the path
890
+ * follows the entry when it moves to a new leaf. */
891
+ async updateEntry(path, entry) {
892
+ await this.applyLeafEdit(path, { index: path.leafIndex, deleteCount: 1, entry });
893
+ }
894
+ // The fill rules a delete rebalances by. The node being rebalanced is serialized once, into a
895
+ // `NodeFill`, and each sibling it weighs once; none of this runs without a byte target.
896
+ /** A node's bytes against the byte target, or `undefined` when the tree has none. */
897
+ measure(node) {
898
+ return this.nodeTargetBytes === undefined ? undefined : { bytes: jsonEncodedBytes(node), target: this.nodeTargetBytes };
899
+ }
900
+ /** A leaf below half the count AND, with a byte target, below half the target — one that a borrow
901
+ * or merge could usefully fill. A leaf of a few large entries is under half the count for good but
902
+ * is a healthy block, so it is left alone and a delete from it reads no sibling. */
903
+ leafUnderfull(leaf, fill) {
904
+ return leaf.entries.length < (this.nodeCapacity >>> 1) && (fill === undefined || fill.bytes < fill.target / 2);
905
+ }
906
+ /** Whether `leaf` may take one more `entry` from a sibling without passing the byte target. */
907
+ leafTakes(leaf, fill, entry) {
908
+ return fill === undefined
909
+ || fill.bytes + jsonEncodedBytes(entry) + (leaf.entries.length > 0 ? 1 : 0) <= fill.target;
910
+ }
911
+ /** Whether `leaf` and a sibling may become one: within the count, and within the byte target unless
912
+ * one of them is empty — removing an empty leaf adds nothing to the other, so that is never refused
913
+ * and no empty leaf outlives the delete that emptied it. Whichever of the two survives, the merged
914
+ * leaf is one fixed part plus both sets of entries and the comma that joins them. */
915
+ leavesMerge(leaf, fill, sibling) {
916
+ if (leaf.entries.length + sibling.entries.length > this.nodeCapacity) {
917
+ return false;
918
+ }
919
+ if (fill === undefined || leaf.entries.length === 0 || sibling.entries.length === 0) {
920
+ return true;
921
+ }
922
+ return fill.bytes + jsonEncodedBytes(sibling) - emptyLeafBytes(sibling) + 1 <= fill.target;
772
923
  }
773
- }
774
- class Split {
775
- key;
776
- right;
777
- indexDelta;
778
- constructor(key, right, indexDelta) {
779
- this.key = key;
780
- this.right = right;
781
- this.indexDelta = indexDelta;
924
+ /** {@link leafUnderfull} for a branch, by its children. */
925
+ branchUnderfull(branch, fill) {
926
+ return branch.nodes.length < (this.nodeCapacity >>> 1) && (fill === undefined || fill.bytes < fill.target / 2);
927
+ }
928
+ /** Whether the measured branch may take one more child, `node`, under `key` — the parent's key
929
+ * that comes down with it — without passing the byte target: the key and the id, a comma before each. */
930
+ branchTakes(fill, key, node) {
931
+ return fill === undefined
932
+ || fill.bytes + jsonEncodedBytes(key) + jsonEncodedBytes(node) + 2 <= fill.target;
933
+ }
934
+ /** Whether `branch` and a sibling may become one under `key`, the parent's key between them: within
935
+ * the count and, with a byte target, within it — the sibling's keys and ids, the key that comes down,
936
+ * and the three commas that join them (one before the key, one before each of the two lists). A
937
+ * branch is never empty, so there is no exemption. */
938
+ branchesMerge(branch, fill, sibling, key) {
939
+ if (branch.nodes.length + sibling.nodes.length > this.nodeCapacity) {
940
+ return false;
941
+ }
942
+ return fill === undefined
943
+ || fill.bytes + jsonEncodedBytes(sibling) - emptyBranchBytes(sibling) + jsonEncodedBytes(key) + 3 <= fill.target;
782
944
  }
783
945
  }
784
946
  function newLeafNode(store, entries) {