data-structure-typed 2.2.7 → 2.3.0

package/test/unit/data-structures/binary-tree/red-black-tree.hint-mapmode-defined.coverage.test.ts

@@ -0,0 +1,35 @@
+import { RedBlackTree } from '../../../../src';
+
+describe('RedBlackTree setWithHintNode mapMode defined-value branches', () => {
+  it('direct attach left/right with defined values uses store.set branches', () => {
+    const t = new RedBlackTree<number, number>(); // mapMode default
+    t.set(10, 10);
+    const h10 = t.getNode(10)!;
+
+    const n5 = t.setWithHintNode(5, 5, h10);
+    expect(n5?.key).toBe(5);
+    expect((t as any)._store.get(5)).toBe(5);
+
+    const n15 = t.setWithHintNode(15, 15, h10);
+    expect(n15?.key).toBe(15);
+    expect((t as any)._store.get(15)).toBe(15);
+  });
+
+  it('pred.right and succ.left attach with defined values uses store.set branches', () => {
+    const t = new RedBlackTree<number, number>();
+    t.set(10, 10);
+    const h10 = t.getNode(10)!;
+
+    // Ensure left is real so we take pred path.
+    t.setWithHintNode(5, 5, h10);
+    const n7 = t.setWithHintNode(7, 7, h10);
+    expect(n7?.key).toBe(7);
+    expect((t as any)._store.get(7)).toBe(7);
+
+    // Ensure right is real so we take succ path.
+    t.setWithHintNode(15, 15, h10);
+    const n12 = t.setWithHintNode(12, 12, h10);
+    expect(n12?.key).toBe(12);
+    expect((t as any)._store.get(12)).toBe(12);
+  });
+});

package/test/unit/data-structures/binary-tree/red-black-tree.hint-mapmode-undefined.coverage.test.ts

@@ -0,0 +1,43 @@
+import { RedBlackTree } from '../../../../src';
+
+describe('RedBlackTree setWithHintNode mapMode undefined-value branches', () => {
+  it('direct attach left/right with undefined value hits _setValue branches (no store entry)', () => {
+    const t = new RedBlackTree<number, number>(); // mapMode default
+    t.set(10, 10);
+    const h10 = t.getNode(10)!;
+
+    const n5 = t.setWithHintNode(5, undefined as any, h10);
+    expect(n5?.key).toBe(5);
+    expect(t.getNode(5)).toBeTruthy();
+    expect((t as any)._store.has(5)).toBe(false);
+
+    const n15 = t.setWithHintNode(15, undefined as any, h10);
+    expect(n15?.key).toBe(15);
+    expect(t.getNode(15)).toBeTruthy();
+    expect((t as any)._store.has(15)).toBe(false);
+  });
+
+  it('pred.right and succ.left attach with undefined value hit _setValue branches', () => {
+    const t = new RedBlackTree<number, number>();
+    t.set(10, 10);
+    const h10 = t.getNode(10)!;
+
+    // Ensure left is real so we take the pred path.
+    t.setWithHintNode(5, 5, h10);
+
+    // Insert between pred(5) and hint(10): attaches as pred.right.
+    const n7 = t.setWithHintNode(7, undefined as any, h10);
+    expect(n7?.key).toBe(7);
+    expect(t.getNode(7)).toBeTruthy();
+    expect((t as any)._store.has(7)).toBe(false);
+
+    // Ensure right is real so we take the succ path.
+    t.setWithHintNode(15, 15, h10);
+
+    // Insert between hint(10) and succ(15): attaches as succ.left.
+    const n12 = t.setWithHintNode(12, undefined as any, h10);
+    expect(n12?.key).toBe(12);
+    expect(t.getNode(12)).toBeTruthy();
+    expect((t as any)._store.has(12)).toBe(false);
+  });
+});

package/test/unit/data-structures/binary-tree/red-black-tree.hint-more.coverage.test.ts

@@ -0,0 +1,99 @@
+import { RedBlackTree, RedBlackTreeNode } from '../../../../src';
+
+class RBTWithBadCreate extends RedBlackTree<number, number> {
+  override createNode(key: number, value?: number): any {
+    // Simulate unexpected internal failure so setWithHintNode guard branches are covered.
+    // Keys chosen to avoid falling back to _setKVNode boundary attach (which assumes createNode always succeeds).
+    if (key === 7 || key === 6 || key === 17 || key === 14) return undefined;
+    return super.createNode(key, value);
+  }
+}
+
+describe('RedBlackTree setWithHintNode more branch coverage', () => {
+  it('covers c0===0 update (set mode + mapMode undefined/value)', () => {
+    // set mode
+    const s = new RedBlackTree<number, number>([], { isMapMode: false });
+    s.set(10, 1);
+    const h10 = s.getNode(10)!;
+    s.setWithHintNode(10, 2, h10);
+    expect(s.getNode(10)?.value).toBe(2);
+
+    // mapMode: value !== undefined uses store.set; value === undefined uses _setValue path.
+    const m = new RedBlackTree<number, number>();
+    m.set(10, 1);
+    const mh10 = m.getNode(10)!;
+    m.setWithHintNode(10, 3, mh10);
+    expect(m.get(10)).toBe(3);
+
+    // undefined update should preserve existing value (existing semantics).
+    m.setWithHintNode(10, undefined as any, mh10);
+    expect(m.get(10)).toBe(3);
+  });
+
+  it('covers c0<0: direct attach to hint.left, pred fallback, and pred.right attach', () => {
+    const t = new RedBlackTree<number, number>([], { isMapMode: false });
+
+    // direct attach: hint.left is empty
+    t.set(10, 10);
+    const h10 = t.getNode(10)!;
+    const n5 = t.setWithHintNode(5, 5, h10)!;
+    expect(n5.key).toBe(5);
+
+    // pred fallback: key equals predecessor (cmp(pred.key,key) >= 0)
+    t.setWithHintNode(5, 55, h10);
+    expect(t.getNode(5)?.value).toBe(55);
+
+    // pred.right attach: insert between pred(5) and hint(10)
+    const n7 = t.setWithHintNode(7, 7, h10)!;
+    expect(n7.key).toBe(7);
+    expect(t.getNode(7)?.value).toBe(7);
+  });
+
+  it('covers c0>0: direct attach to hint.right, succ fallback, and succ.left attach', () => {
+    const t = new RedBlackTree<number, number>([], { isMapMode: false });
+
+    // direct attach: hint.right is empty
+    t.set(10, 10);
+    const h10 = t.getNode(10)!;
+    const n15 = t.setWithHintNode(15, 15, h10)!;
+    expect(n15.key).toBe(15);
+
+    // succ fallback: key equals successor (cmp(succ.key,key) <= 0)
+    t.setWithHintNode(15, 155, h10);
+    expect(t.getNode(15)?.value).toBe(155);
+
+    // succ.left attach: insert between hint(10) and succ(15)
+    const n12 = t.setWithHintNode(12, 12, h10)!;
+    expect(n12.key).toBe(12);
+    expect(t.getNode(12)?.value).toBe(12);
+  });
+
+  it('covers guard branches where createNode unexpectedly fails (returns undefined)', () => {
+    const t = new RBTWithBadCreate([], { isMapMode: false });
+    t.set(10, 10);
+    const h10 = t.getNode(10)!;
+
+    // c0<0 direct attach guard (newNode not real)
+    expect(t.setWithHintNode(7, 7, h10)).toBeUndefined();
+
+    // ensure left is real so we go pred-right attach guard
+    t.setWithHintNode(5, 5, h10);
+    expect(t.setWithHintNode(6, 6, h10)).toBeUndefined();
+
+    // c0>0 direct attach guard (hint.right is empty)
+    expect(t.setWithHintNode(17, 17, h10)).toBeUndefined();
+
+    // ensure right is real so we go succ-left attach guard (key between hint and succ)
+    t.setWithHintNode(15, 15, h10);
+    expect(t.setWithHintNode(14, 14, h10)).toBeUndefined();
+  });
+
+  it('covers setWithHintNode fallback when hint is not real', () => {
+    const t = new RedBlackTree<number, number>([], { isMapMode: false });
+    t.set(1, 1);
+
+    // Passing NIL should be treated as not-real and fallback to normal set.
+    const out = t.setWithHintNode(2, 2, t.NIL as any);
+    expect(out?.key).toBe(2);
+  });
+});

package/test/unit/data-structures/binary-tree/red-black-tree.hint.coverage.test.ts

@@ -0,0 +1,60 @@
+import { RedBlackTree } from '../../../../src';
+
+describe('RedBlackTree hint/update coverage', () => {
+  it('mapMode update fast-path keeps size and node reference stable', () => {
+    const t = new RedBlackTree<number, string>([], { isMapMode: true });
+    t.set(1, 'a');
+    const n1 = t.getNode(1);
+    expect(n1).toBeTruthy();
+
+    t.set(1, 'b');
+    const n2 = t.getNode(1);
+
+    expect(t.size).toBe(1);
+    expect(t.get(1)).toBe('b');
+    expect(n2).toBe(n1);
+  });
+
+  it('setWithHintNode covers: no hint -> fallback, c0==0 update, and left/right attach branches', () => {
+    const t = new RedBlackTree<number, number>([], { isMapMode: false });
+    for (const k of [10, 5, 15]) t.set(k, k);
+
+    // no hint -> fallback
+    const n20 = t.setWithHintNode(20, 20, undefined);
+    expect(n20?.key).toBe(20);
+
+    // c0 == 0 update
+    const hint10 = t.getNode(10)!;
+    const updated10 = t.setWithHintNode(10, 999, hint10);
+    expect(updated10).toBe(hint10);
+    expect(t.get(10)).toBe(999);
+
+    // left attach (hint.left is empty)
+    const hint5 = t.getNode(5)!;
+    const n2 = t.setWithHintNode(2, 2, hint5);
+    expect(n2?.parent?.key).toBe(5);
+    expect(n2?.key).toBe(2);
+
+    // predecessor-right attach (hint.left exists)
+    // key=7 is <10, pred(10)=5 and pred.right is empty -> attach there.
+    const n7 = t.setWithHintNode(7, 7, hint10);
+    expect(n7?.key).toBe(7);
+    expect(n7?.parent?.key).toBe(5);
+
+    // successor-left attach (hint.right exists)
+    // key=13 is >10, succ(10)=15 and succ.left is empty -> attach there.
+    const n13 = t.setWithHintNode(13, 13, hint10);
+    expect(n13?.key).toBe(13);
+    expect(n13?.parent?.key).toBe(15);
+
+    // succ.key <= key fallback branch
+    const n30 = t.setWithHintNode(30, 30, hint10);
+    expect(n30?.key).toBe(30);
+    expect(t.getNode(30)).toBeTruthy();
+
+    // pred.key >= key fallback branch
+    const n4 = t.setWithHintNode(4, 4, hint10);
+    expect(n4?.key).toBe(4);
+    expect(t.getNode(4)).toBeTruthy();
+  });
+});

package/test/unit/data-structures/binary-tree/red-black-tree.insert-cache-nullish.coverage.test.ts

@@ -0,0 +1,29 @@
+import { RedBlackTree } from '../../../../src';
+
+describe('RedBlackTree insert cache nullish coverage', () => {
+  it('normal insert repairs nullish header._left/_right via (hMin===NIL || hMax===NIL) fast-path', () => {
+    const t = new RedBlackTree<number, number>([], { isMapMode: false });
+
+    // Build a non-empty tree so header.parent/root is real.
+    for (const k of [10, 20, 30]) t.set(k, k);
+
+    // Corrupt caches so boundary fast-path is skipped (minN becomes NIL via ??) and
+    // post-insert cache maintenance sees hMin/hMax as NIL.
+    (t as any)._header._left = undefined;
+    (t as any)._header._right = undefined;
+
+    t.set(25, 25);
+
+    // After insertion, cache maintenance should have initialized both caches.
+    expect((t as any)._header._left.key).toBe(25);
+    expect((t as any)._header._right.key).toBe(25);
+
+    // Repair caches to avoid polluting subsequent tests/users.
+    const root = (t as any)._root;
+    (t as any)._setMinCache(t.isRealNode(root) ? t.getLeftMost((n: any) => n, root) : undefined);
+    (t as any)._setMaxCache(t.isRealNode(root) ? t.getRightMost((n: any) => n, root) : undefined);
+
+    expect((t as any)._header._left.key).toBe(10);
+    expect((t as any)._header._right.key).toBe(30);
+  });
+});

package/test/unit/data-structures/binary-tree/red-black-tree.insert-header-parent-nullish.coverage.test.ts

@@ -0,0 +1,17 @@
+import { RedBlackTree, RedBlackTreeNode } from '../../../../src';
+
+describe('RedBlackTree _insert header.parent ?? NIL coverage', () => {
+  it('covers _insert with header.parent undefined (current starts at NIL)', () => {
+    const t = new RedBlackTree<number, number>([], { isMapMode: false });
+
+    // Force the _insert walk to start from NIL.
+    (t as any)._header.parent = undefined;
+    (t as any)._root = t.NIL;
+
+    const n = new RedBlackTreeNode<number, number>(10, 10, 'BLACK');
+    expect(t.set(n, 10)).toBe(true);
+
+    // Should have established a real root via _setRoot.
+    expect(t.getNode(10)?.key).toBe(10);
+  });
+});

package/test/unit/data-structures/binary-tree/red-black-tree.internal-walk.coverage.test.ts

@@ -0,0 +1,57 @@
+import { RedBlackTree, RedBlackTreeNode } from '../../../../src';
+
+describe('RedBlackTree internal walk coverage', () => {
+  it('_findNodeByKey covers header.parent ?? NIL and child ?? NIL branches', () => {
+    const t = new RedBlackTree<number, number>([], { isMapMode: false });
+    t.set(10, 10);
+
+    // header.parent ?? NIL (set to undefined)
+    (t as any)._header.parent = undefined;
+    expect((t as any)._findNodeByKey(10)).toBeUndefined();
+
+    // Restore canonical root pointer.
+    (t as any)._header.parent = (t as any)._root;
+
+    // Force missing children to exercise `cur.left ?? NIL` and `cur.right ?? NIL`.
+    const root = (t as any)._header.parent;
+    root._left = undefined;
+    root._right = undefined;
+
+    expect((t as any)._findNodeByKey(5)).toBeUndefined();
+    expect((t as any)._findNodeByKey(15)).toBeUndefined();
+  });
+
+  it('_insert covers current.left/right ?? NIL branches when root child pointers are undefined', () => {
+    const t = new RedBlackTree<number, number>([], { isMapMode: false });
+    t.set(10, 10);
+
+    const root = (t as any)._header.parent;
+
+    // Insert left with root._left undefined
+    root._left = undefined;
+    const n5 = new RedBlackTreeNode<number, number>(5, 5, 'BLACK');
+    expect(t.set(n5)).toBe(true);
+
+    // Reset to single root
+    t.clear();
+    t.set(10, 10);
+
+    const root2 = (t as any)._header.parent;
+    // Insert right with root._right undefined
+    root2._right = undefined;
+    const n15 = new RedBlackTreeNode<number, number>(15, 15, 'BLACK');
+    expect(t.set(n15)).toBe(true);
+  });
+
+  it('_setKVNode covers header._left ?? NIL when header._left is undefined (no boundary fast path)', () => {
+    const t = new RedBlackTree<number, number>([], { isMapMode: false });
+    t.set(10, 10);
+
+    // Corrupt cache pointer so `header._left ?? NIL` uses NIL.
+    (t as any)._header._left = undefined;
+
+    // Should still insert normally.
+    expect(t.set(5, 5)).toBe(true);
+    expect(t.getNode(5)).toBeTruthy();
+  });
+});

package/test/unit/data-structures/binary-tree/red-black-tree.minmax-cache.test.ts

@@ -0,0 +1,65 @@
+import { RedBlackTree } from '../../../../src';
+
+/**
+ * Regression tests for RedBlackTree min/max cache + boundary fast paths.
+ * Focus: correctness when inserting monotonic keys and deleting boundary nodes.
+ */
+
+describe('RedBlackTree min/max cache regression', () => {
+  it('should keep min/max correct across increasing inserts and boundary deletes', () => {
+    const rb = new RedBlackTree<number, number>();
+
+    for (let i = 0; i < 1000; i++) rb.set(i, i);
+
+    // delete min repeatedly
+    for (let i = 0; i < 250; i++) {
+      rb.delete(i);
+      const min = rb.getLeftMost(n => n, rb.root);
+      expect(min?.key).toBe(i + 1);
+    }
+
+    // delete max repeatedly
+    for (let i = 999; i >= 750; i--) {
+      rb.delete(i);
+      const max = rb.getRightMost(n => n, rb.root);
+      expect(max?.key).toBe(i - 1);
+    }
+  });
+
+  it('should reset min/max on clear and after deleting to empty', () => {
+    const rb = new RedBlackTree<number, number>();
+    rb.set(1, 1);
+    rb.set(2, 2);
+
+    rb.clear();
+    expect(rb.size).toBe(0);
+    expect(rb.getLeftMost(n => n, rb.root)).toBe(undefined);
+    expect(rb.getRightMost(n => n, rb.root)).toBe(undefined);
+
+    rb.set(10, 10);
+    rb.delete(10);
+    expect(rb.size).toBe(0);
+    expect(rb.getLeftMost(n => n, rb.root)).toBe(undefined);
+    expect(rb.getRightMost(n => n, rb.root)).toBe(undefined);
+  });
+
+  it('should keep min/max correct across decreasing inserts and boundary deletes', () => {
+    const rb = new RedBlackTree<number, number>();
+
+    for (let i = 1000; i >= 1; i--) rb.set(i, i);
+
+    // delete min repeatedly
+    for (let k = 1; k <= 250; k++) {
+      rb.delete(k);
+      const min = rb.getLeftMost(n => n, rb.root);
+      expect(min?.key).toBe(k + 1);
+    }
+
+    // delete max repeatedly
+    for (let k = 1000; k >= 751; k--) {
+      rb.delete(k);
+      const max = rb.getRightMost(n => n, rb.root);
+      expect(max?.key).toBe(k - 1);
+    }
+  });
+});

package/test/unit/data-structures/binary-tree/red-black-tree.misc-inputs.coverage.test.ts

@@ -0,0 +1,17 @@
+import { RedBlackTree } from '../../../../src';
+
+describe('RedBlackTree misc input coverage', () => {
+  it('delete(null) returns [] and does not throw', () => {
+    const t = new RedBlackTree<number, number>([], { isMapMode: false });
+    t.set(1, 1);
+    expect(t.delete(null as any)).toEqual([]);
+    expect(t.size).toBe(1);
+  });
+
+  it('delete(undefined) returns [] and does not throw', () => {
+    const t = new RedBlackTree<number, number>([], { isMapMode: false });
+    t.set(1, 1);
+    expect(t.delete(undefined as any)).toEqual([]);
+    expect(t.size).toBe(1);
+  });
+});

package/test/unit/data-structures/binary-tree/red-black-tree.more-branches-2.coverage.test.ts

@@ -0,0 +1,121 @@
+import { RedBlackTree, RedBlackTreeNode } from '../../../../src';
+
+describe('RedBlackTree remaining reachable branches (coverage)', () => {
+  it('mapMode updates existing MAX key with defined value via boundary cMax===0 path inside _setKVNode (covers store.set branch)', () => {
+    const t = new RedBlackTree<number, string>([], { isMapMode: true });
+    t.set(1, 'a');
+    t.set(2, 'b');
+
+    // Bypass _setKV store.has fast-path by corrupting the store (node exists but store.has(key) is false).
+    (t as any)._store.delete(2);
+
+    // key==max => boundary cMax===0 update in _setKVNode
+    t.set(2, 'bb');
+    expect(t.get(2)).toBe('bb');
+  });
+
+  it('mapMode updates existing interior key with defined value via normal search update branch inside _setKVNode', () => {
+    const t = new RedBlackTree<number, string>([], { isMapMode: true });
+    t.set(10, 'x');
+    t.set(5, 'a');
+    t.set(15, 'z');
+
+    // Bypass _setKV store.has fast-path for this key.
+    (t as any)._store.delete(10);
+
+    // Update a non-min/non-max key to avoid boundary min/max equality early returns.
+    t.set(10, 'xx');
+    expect(t.get(10)).toBe('xx');
+  });
+
+  it('normal-path search uses right ?? NIL fallback when a node child pointer is undefined', () => {
+    const t = new RedBlackTree<number, number>([], { isMapMode: false });
+    t.set(10, 10);
+    t.set(5, 5);
+
+    const n5 = t.getNode(5)!;
+
+    // Corrupt: right pointer becomes undefined (instead of NIL).
+    // This should exercise `current = current.right ?? NIL` fallback.
+    (n5 as any).right = undefined;
+
+    t.set(7, 7);
+    expect(t.get(7)).toBe(7);
+  });
+
+  it('setWithHintNode cache maintenance evaluates compare operands in all 4 fast-attach variants', () => {
+    // (1) c0 < 0, direct attach to hint.left
+    {
+      const t = new RedBlackTree<number, number>();
+      t.set(10, 10);
+      t.set(20, 20);
+      // Ensure caches are real nodes (not NIL)
+      (t as any)._header._left = t.getNode(10);
+      (t as any)._header._right = t.getNode(20);
+
+      const hint = t.getNode(20)!;
+      const n = t.setWithHintNode(15, 15, hint)!;
+      expect(n.key).toBe(15);
+    }
+
+    // (2) c0 < 0, attach as right child of predecessor
+    {
+      const t = new RedBlackTree<number, number>();
+      t.set(10, 10);
+      t.set(20, 20);
+      // Make hint.left real so direct attach is skipped
+      t.set(5, 5);
+      (t as any)._header._left = t.getNode(5);
+      (t as any)._header._right = t.getNode(20);
+
+      const hint = t.getNode(20)!;
+      const n = t.setWithHintNode(15, 15, hint)!;
+      expect(n.key).toBe(15);
+    }
+
+    // (3) c0 > 0, direct attach to hint.right
+    {
+      const t = new RedBlackTree<number, number>();
+      t.set(10, 10);
+      t.set(20, 20);
+      (t as any)._header._left = t.getNode(10);
+      (t as any)._header._right = t.getNode(20);
+
+      const hint = t.getNode(20)!;
+      const n = t.setWithHintNode(30, 30, hint)!;
+      expect(n.key).toBe(30);
+    }
+
+    // (4) c0 > 0, attach as left child of successor
+    {
+      const t = new RedBlackTree<number, number>();
+      t.set(10, 10);
+      t.set(30, 30);
+      t.set(20, 20);
+      // ensure hint.right is real (30) so direct attach is skipped
+      (t as any)._header._left = t.getNode(10);
+      (t as any)._header._right = t.getNode(30);
+
+      const hint = t.getNode(20)!;
+      const n = t.setWithHintNode(25, 25, hint)!;
+      expect(n.key).toBe(25);
+    }
+  });
+
+  it('_leftRotate and _rightRotate early-return when pivot or required child is missing', () => {
+    const t = new RedBlackTree<number, number>([], { isMapMode: false });
+
+    // undefined pivot
+    (t as any)._leftRotate(undefined);
+    (t as any)._rightRotate(undefined);
+
+    // pivot exists but missing required child
+    const x = new RedBlackTreeNode<number, number>(1);
+    (x as any).right = undefined;
+    const y = new RedBlackTreeNode<number, number>(2);
+    (y as any).left = undefined;
+
+    (t as any)._leftRotate(x);
+    (t as any)._rightRotate(y);
+  });
+});

package/test/unit/data-structures/binary-tree/red-black-tree.more-branches-3.coverage.test.ts

@@ -0,0 +1,55 @@
+import { RedBlackTree } from '../../../../src';
+
+describe('RedBlackTree additional reachable branch coverage (batch 3)', () => {
+  it('insertion cache: hits parent===hMax and parent===hMin else-if branches', () => {
+    const t = new RedBlackTree<number, number>();
+
+    t.set(2, 2);
+    // new max: parent should be current max
+    t.set(3, 3);
+
+    t.clear();
+
+    t.set(2, 2);
+    // new min: parent should be current min
+    t.set(1, 1);
+
+    // Sanity: min/max nodes exist and are ordered.
+    expect(t.getLeftMost((n: any) => n)?.key).toBe(1);
+    expect(t.getRightMost((n: any) => n)?.key).toBe(2);
+  });
+
+  it('setWithHintNode: executes min/max cache logical-expr second operands across all 4 ultra-fast attach variants', () => {
+    const t = new RedBlackTree<number, number>();
+
+    // Seed non-empty tree so hMin/hMax are real and `hMin===NIL || compare(...)` evaluates RHS.
+    t.setMany([
+      [10, 10],
+      [20, 20],
+      [30, 30]
+    ]);
+
+    const n10 = t.getNode(10)!;
+    const n20 = t.getNode(20)!;
+    const n30 = t.getNode(30)!;
+
+    // 1) direct attach as left of hint (new global min)
+    const n5 = t.setWithHintNode(5, 5, n10);
+    expect(n5?.key).toBe(5);
+
+    // 2) attach as right of predecessor
+    const n15 = t.setWithHintNode(15, 15, n20);
+    expect(n15?.key).toBe(15);
+
+    // 3) direct attach as right of hint (new global max)
+    const n40 = t.setWithHintNode(40, 40, n30);
+    expect(n40?.key).toBe(40);
+
+    // 4) attach as left of successor
+    const n25 = t.setWithHintNode(25, 25, n20);
+    expect(n25?.key).toBe(25);
+
+    expect(t.getLeftMost((n: any) => n)?.key).toBe(5);
+    expect(t.getRightMost((n: any) => n)?.key).toBe(40);
+  });
+});

package/test/unit/data-structures/binary-tree/red-black-tree.more-branches-4.coverage.test.ts

@@ -0,0 +1,44 @@
+import { RedBlackTree } from '../../../../src';
+
+describe('RedBlackTree additional reachable branch coverage (batch 4)', () => {
+  it('setWithHintNode: covers header._left/_right nullish-coalescing RHS (?? NIL) in all 4 ultra-fast attach variants', () => {
+    const t = new RedBlackTree<number, number>();
+
+    t.setMany([
+      [10, 10],
+      [20, 20],
+      [30, 30]
+    ]);
+
+    const n10 = t.getNode(10)!;
+    const n20 = t.getNode(20)!;
+    const n30 = t.getNode(30)!;
+
+    const clearHeaderMinMaxToUndefined = () => {
+      // Simulate a stale/partial cache state. This is a realistic “repair” scenario:
+      // the code uses `?? NIL` to tolerate undefined here.
+      (t as any)._header._left = undefined;
+      (t as any)._header._right = undefined;
+    };
+
+    // 1) direct attach as left of hint
+    clearHeaderMinMaxToUndefined();
+    expect(t.setWithHintNode(5, 5, n10)?.key).toBe(5);
+
+    // 2) attach as right of predecessor
+    clearHeaderMinMaxToUndefined();
+    expect(t.setWithHintNode(15, 15, n20)?.key).toBe(15);
+
+    // 3) direct attach as right of hint
+    clearHeaderMinMaxToUndefined();
+    expect(t.setWithHintNode(40, 40, n30)?.key).toBe(40);
+
+    // 4) attach as left of successor
+    clearHeaderMinMaxToUndefined();
+    expect(t.setWithHintNode(25, 25, n20)?.key).toBe(25);
+
+    // Sanity: tree still orders correctly.
+    expect(t.getLeftMost(n => n)?.key).toBe(5);
+    expect(t.getRightMost(n => n)?.key).toBe(40);
+  });
+});