data-structure-typed 2.5.3 → 2.6.1

package/src/data-structures/binary-tree/red-black-tree.ts

@@ -5,15 +5,15 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-
 import type {
   BTNRep,
   CRUD,
   EntryCallback,
-  FamilyPosition, NodePredicate,
+  FamilyPosition,
+  IterationType,
+  NodePredicate,
   OptNode,
   RBTNColor,
-  IterationType,
   RedBlackTreeOptions
 } from '../../types';
 import { BST } from './bst';
@@ -31,7 +31,6 @@ export class RedBlackTreeNode<K = any, V = any> {
    * @param [value] - Node value (unused in map mode trees).
    * @param color - Node color.
    */
-
   constructor(key: K, value?: V, color: RBTNColor = 'BLACK') {
     this.key = key;
     this.value = value;
@@ -45,7 +44,6 @@ export class RedBlackTreeNode<K = any, V = any> {
    * @remarks Time O(1), Space O(1)
    * @returns Left child node, or null/undefined.
    */
-
   get left(): RedBlackTreeNode<K, V> | null | undefined {
     return this._left;
   }
@@ -56,7 +54,6 @@ export class RedBlackTreeNode<K = any, V = any> {
    * @param v - New left node, or null/undefined.
    * @returns void
    */
-
   set left(v: RedBlackTreeNode<K, V> | null | undefined) {
     if (v) {
       v.parent = this;
@@ -71,7 +68,6 @@ export class RedBlackTreeNode<K = any, V = any> {
    * @remarks Time O(1), Space O(1)
    * @returns Right child node, or null/undefined.
    */
-
   get right(): RedBlackTreeNode<K, V> | null | undefined {
     return this._right;
   }
@@ -82,7 +78,6 @@ export class RedBlackTreeNode<K = any, V = any> {
    * @param v - New right node, or null/undefined.
    * @returns void
    */
-
   set right(v: RedBlackTreeNode<K, V> | null | undefined) {
     if (v) {
       v.parent = this;
@@ -98,6 +93,7 @@ export class RedBlackTreeNode<K = any, V = any> {
    *
    * @returns The height.
    */
+
   /* istanbul ignore next -- covered by AVLTree tests (subclass uses height) */
   get height(): number {
     return this._height;
@@ -138,6 +134,7 @@ export class RedBlackTreeNode<K = any, V = any> {
    *
    * @returns The subtree node count.
    */
+
   /* istanbul ignore next -- internal field, exercised indirectly via tree operations */
   get count(): number {
     return this._count;
@@ -153,13 +150,11 @@ export class RedBlackTreeNode<K = any, V = any> {
     if (!this.parent) {
       return this.left || this.right ? 'ROOT' : 'ISOLATED';
     }
-
     if (this.parent.left === this) {
       return this.left || this.right ? 'ROOT_LEFT' : 'LEFT';
     } else if (this.parent.right === this) {
       return this.left || this.right ? 'ROOT_RIGHT' : 'RIGHT';
     }
-
     /* istanbul ignore next -- defensive: unreachable if tree structure is correct */
     return 'MAL_NODE';
   }
@@ -250,26 +245,41 @@ export class RedBlackTreeNode<K = any, V = any> {
  *     console.log(stocksInRange.some((s: any) => s.symbol === 'META')); // true;
  *     console.log(stocksInRange.some((s: any) => s.symbol === 'MSFT')); // true;
  */
-
 export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implements IBinaryTree<K, V, R> {
+  /**
+   * (Internal) Header sentinel:
+   * - header.parent -> root
+   * - header._left  -> min (or NIL)
+   * - header._right -> max (or NIL)
+   *
+   * IMPORTANT:
+   * - This header is NOT part of the actual tree.
+   * - Do NOT use `header.left` / `header.right` accessors for wiring: those setters update `NIL.parent`
+   *   and can corrupt sentinel invariants / cause hangs. Only touch `header._left/_right`.
+   */
+  protected _header: RedBlackTreeNode<K, V>;
+
+  /**
+   * (Internal) Cache of the current minimum and maximum nodes.
+   * Used for fast-path insert/update when keys are monotonic or near-boundary.
+   */
+  protected _minNode: RedBlackTreeNode<K, V> | undefined;
+  protected _maxNode: RedBlackTreeNode<K, V> | undefined;
+
   constructor(
     keysNodesEntriesOrRaws: Iterable<
       K | RedBlackTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R
     > = [],
     options?: RedBlackTreeOptions<K, V, R>
   ) {
-
     super([], options);
-
     this._root = this.NIL;
-
     // Not part of the actual tree; used only as an internal cache hub.
     this._header = new RedBlackTreeNode<K, V>(undefined as K, undefined, 'BLACK');
     this._header.parent = this.NIL;
     // Avoid using accessors here: they would set NIL.parent and can corrupt sentinel invariants.
     this._header._left = this.NIL;
     this._header._right = this.NIL;
-
     if (keysNodesEntriesOrRaws) {
       this.setMany(keysNodesEntriesOrRaws);
     }
@@ -277,26 +287,6 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
 
   protected override _root: RedBlackTreeNode<K, V> | undefined;
 
-  /**
-   * (Internal) Header sentinel:
-   * - header.parent -> root
-   * - header._left  -> min (or NIL)
-   * - header._right -> max (or NIL)
-   *
-   * IMPORTANT:
-   * - This header is NOT part of the actual tree.
-   * - Do NOT use `header.left` / `header.right` accessors for wiring: those setters update `NIL.parent`
-   *   and can corrupt sentinel invariants / cause hangs. Only touch `header._left/_right`.
-   */
-  protected _header: RedBlackTreeNode<K, V>;
-
-  /**
-   * (Internal) Cache of the current minimum and maximum nodes.
-   * Used for fast-path insert/update when keys are monotonic or near-boundary.
-   */
-  protected _minNode: RedBlackTreeNode<K, V> | undefined;
-  protected _maxNode: RedBlackTreeNode<K, V> | undefined;
-
   /**
    * Get the current root node.
    * @remarks Time O(1), Space O(1)
@@ -324,7 +314,6 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
    * @param keyNodeOrEntry - See parameter type for details.
    * @returns True if the value is a RedBlackTreeNode.
    */
-
   override isNode(
     keyNodeOrEntry: K | RedBlackTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined
   ): keyNodeOrEntry is RedBlackTreeNode<K, V> {
@@ -334,158 +323,11 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
   /**
    * Remove all nodes, clear the key→value store (if in map mode) and internal caches.
    * @remarks Time O(n), Space O(1)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Remove all entries
- *  const rbt = new RedBlackTree<number>([1, 2, 3]);
- *     rbt.clear();
- *     console.log(rbt.isEmpty()); // true;
+   * @example
+   * // Remove all entries
+   *  const rbt = new RedBlackTree<number>([1, 2, 3]);
+   *     rbt.clear();
+   *     console.log(rbt.isEmpty()); // true;
    */
   override clear() {
     super.clear();
@@ -495,557 +337,137 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
     this._setMaxCache(undefined);
   }
 
-
   /**
-   * (Internal) Find a node by key using a tight BST walk (no allocations).
+   * Insert/update using a hint node to speed up nearby insertions.
    *
-   * NOTE: This uses `header.parent` as the canonical root pointer.
+   * close to the expected insertion position (often the previously returned node in a loop).
+   *
+   * When the hint is a good fit (sorted / nearly-sorted insertion), this can avoid most of the
+   * normal root-to-leaf search and reduce constant factors.
+   *
+   * When the hint does not match (random workloads), this will fall back to the normal set path.
    * @remarks Time O(log n) average, Space O(1)
    */
-  protected _findNodeByKey(key: K): RedBlackTreeNode<K, V> | undefined {
-    const NIL = this.NIL;
+  setWithHintNode(key: K, value: V, hint?: RedBlackTreeNode<K, V>): RedBlackTreeNode<K, V> | undefined {
+    if (!hint || !this.isRealNode(hint)) {
+      return this._setKVNode(key, value)?.node;
+    }
     const cmp = this._compare.bind(this);
-
-    let cur = (this._header.parent) ?? NIL;
-    while (cur !== NIL) {
-      const c = cmp(key, cur.key);
-      if (c < 0) cur = cur.left ?? NIL;
-      else if (c > 0) cur = cur.right ?? NIL;
-      else return cur;
+    const c0 = cmp(key, hint.key);
+    if (c0 === 0) {
+      hint.value = value;
+      if (this._isMapMode) this._store.set(key, hint);
+      return hint;
     }
-    return undefined;
-  }
-
-  /**
-   * (Internal) In-order predecessor of a node in a BST.
-   * @remarks Time O(log n) average, Space O(1)
-   */
-  protected _predecessorOf(node: RedBlackTreeNode<K, V>): RedBlackTreeNode<K, V> | undefined {
-    const NIL = this.NIL;
-    if (node.left && node.left !== NIL) {
-      let cur = node.left;
-      while (cur.right && cur.right !== NIL) cur = cur.right;
-      return cur;
+    if (c0 < 0) {
+      // Ultra-fast path: direct attach if the target slot is empty.
+      if (!this.isRealNode(hint.left)) {
+        const newNode = this.createNode(key, value);
+        if (!this.isRealNode(newNode)) return undefined;
+        this._attachNewNode(hint, 'left', newNode);
+        if (this._isMapMode) this._store.set(key, newNode);
+        this._size++;
+        // Maintain header/min/max caches.
+        const NIL = this.NIL;
+        const hMin = this._header._left ?? NIL;
+        if (hMin === NIL || this._compare(newNode.key, hMin.key) < 0) this._setMinCache(newNode);
+        const hMax = this._header._right ?? NIL;
+        if (hMax === NIL || this._compare(newNode.key, hMax.key) > 0) this._setMaxCache(newNode);
+        return newNode;
+      }
+      const pred = this._predecessorOf(hint);
+      if (pred && cmp(pred.key, key) >= 0) {
+        return this._setKVNode(key, value)?.node;
+      }
+      // Try attach as right of pred.
+      if (pred && !this.isRealNode(pred.right)) {
+        const newNode = this.createNode(key, value);
+        if (!this.isRealNode(newNode)) return undefined;
+        this._attachNewNode(pred, 'right', newNode);
+        if (this._isMapMode) this._store.set(key, newNode);
+        this._size++;
+        // Maintain header/min/max caches.
+        const NIL = this.NIL;
+        const hMin = this._header._left ?? NIL;
+        if (hMin === NIL || this._compare(newNode.key, hMin.key) < 0) this._setMinCache(newNode);
+        const hMax = this._header._right ?? NIL;
+        if (hMax === NIL || this._compare(newNode.key, hMax.key) > 0) this._setMaxCache(newNode);
+        return newNode;
+      }
+      /* istanbul ignore next -- structurally unreachable: predecessor never has a right child (it's the max of left subtree) */
+      return this._setKVNode(key, value)?.node;
     }
-    let cur: RedBlackTreeNode<K, V> | undefined = node;
-    let p = node.parent;
-    while (p && cur === p.left) {
-      cur = p;
-      p = p.parent;
+    // c0 > 0
+    // Ultra-fast path: direct attach if the target slot is empty.
+    if (!this.isRealNode(hint.right)) {
+      const newNode = this.createNode(key, value);
+      if (!this.isRealNode(newNode)) return undefined;
+      this._attachNewNode(hint, 'right', newNode);
+      if (this._isMapMode) this._store.set(key, newNode);
+      this._size++;
+      // Maintain header/min/max caches.
+      const NIL = this.NIL;
+      const hMin = this._header._left ?? NIL;
+      if (hMin === NIL || this._compare(newNode.key, hMin.key) < 0) this._setMinCache(newNode);
+      const hMax = this._header._right ?? NIL;
+      if (hMax === NIL || this._compare(newNode.key, hMax.key) > 0) this._setMaxCache(newNode);
+      return newNode;
     }
-    return p;
-  }
-
-  /**
-   * (Internal) In-order successor of a node in a BST.
-   * @remarks Time O(log n) average, Space O(1)
-   */
-  protected _successorOf(node: RedBlackTreeNode<K, V>): RedBlackTreeNode<K, V> | undefined {
-    const NIL = this.NIL;
-    if (node.right && node.right !== NIL) {
-      let cur = node.right;
-      while (cur.left && cur.left !== NIL) cur = cur.left;
-      return cur;
+    const succ = this._successorOf(hint);
+    if (succ && cmp(succ.key, key) <= 0) {
+      return this._setKVNode(key, value)?.node;
     }
-    let cur: RedBlackTreeNode<K, V> | undefined = node;
-    let p = node.parent;
-    while (p && cur === p.right) {
-      cur = p;
-      p = p.parent;
+    if (succ && !this.isRealNode(succ.left)) {
+      const newNode = this.createNode(key, value);
+      if (!this.isRealNode(newNode)) return undefined;
+      this._attachNewNode(succ, 'left', newNode);
+      if (this._isMapMode) this._store.set(key, newNode);
+      this._size++;
+      // Maintain header/min/max caches.
+      const NIL = this.NIL;
+      const hMin = this._header._left ?? NIL;
+      if (hMin === NIL || this._compare(newNode.key, hMin.key) < 0) this._setMinCache(newNode);
+      const hMax = this._header._right ?? NIL;
+      if (hMax === NIL || this._compare(newNode.key, hMax.key) > 0) this._setMaxCache(newNode);
+      return newNode;
     }
-    return p;
+    /* istanbul ignore next -- structurally unreachable: successor never has a left child (it's the min of right subtree) */
+    return this._setKVNode(key, value)?.node;
   }
 
   /**
-   * (Internal) Attach a new node directly under a known parent/side (no search).
-   *
-   * This is a performance-oriented helper used by boundary fast paths and hinted insertion.
-   * It will:
-   * - wire parent/child pointers (using accessors, so parent pointers are updated)
-   * - initialize children to NIL
-   * - mark the new node RED, then run insert fix-up
-   *
-   * Precondition: the chosen slot (parent.left/parent.right) is empty (NIL/null/undefined).
+   * Boolean wrapper for setWithHintNode.
    * @remarks Time O(log n) average, Space O(1)
    */
-  protected _attachNewNode(parent: RedBlackTreeNode<K, V>, side: 'left' | 'right', node: RedBlackTreeNode<K, V>): void {
-    const NIL = this.NIL;
-    node.parent = parent;
-    if (side === 'left') parent.left = node;
-    else parent.right = node;
-    node.left = NIL;
-    node.right = NIL;
-    node.color = 'RED';
-    this._updateCountAlongPath(node);
-    this._insertFixup(node);
-    if (this.isRealNode(this._root)) this._root.color = 'BLACK';
-  }
-
-  /**
-   * (Internal) a single source of truth for min/max is header._left/_right.
-   * Keep legacy _minNode/_maxNode mirrored for compatibility.
-   * @remarks Time O(1), Space O(1)
-   */
-  /**
-   * (Internal) Update min cache pointers (header._left is the canonical min pointer).
-   * @remarks Time O(1), Space O(1)
-   */
-  protected _setMinCache(node: RedBlackTreeNode<K, V> | undefined): void {
-    this._minNode = node;
-    this._header._left = node ?? this.NIL;
-  }
-
-  /**
-   * (Internal) Update max cache pointers (header._right is the canonical max pointer).
-   * @remarks Time O(1), Space O(1)
-   */
-  protected _setMaxCache(node: RedBlackTreeNode<K, V> | undefined): void {
-    this._maxNode = node;
-    this._header._right = node ?? this.NIL;
+  setWithHint(key: K, value: V, hint?: RedBlackTreeNode<K, V>): boolean {
+    return this.setWithHintNode(key, value, hint) !== undefined;
   }
 
   /**
-   * (Internal) Core set implementation returning the affected node.
+   * Insert or update a key/value (map mode) or key-only (set mode).
    *
-   * Hot path goals:
-   * - Avoid double walks (search+insert): do a single traversal that either updates or inserts.
-   * - Use header min/max caches to fast-path boundary inserts.
-   * - Keep header._left/_right as canonical min/max pointers.
+   * This method is optimized for:
+   * - monotonic inserts via min/max boundary fast paths
+   * - updates via a single-pass search (no double walk)
    *
-   * Return value:
-   * - `{ node, created:false }` when an existing key is updated
-   * - `{ node, created:true }` when a new node is inserted
-   * - `undefined` only on unexpected internal failure.
    * @remarks Time O(log n) average, Space O(1)
-   */
-  protected _setKVNode(key: K, nextValue?: V): { node: RedBlackTreeNode<K, V>; created: boolean } | undefined {
-    const NIL = this.NIL;
-    const comparator = this._comparator;
-
-    // Read via header to avoid undefined checks (header uses NIL when empty).
-    const header = this._header;
-    const minN = header._left ?? NIL;
-    if (minN !== NIL) {
-      const cMin = comparator(key, minN.key);
-      if (cMin === 0) {
-        minN.value = nextValue as V;
-        if (this._isMapMode) this._store.set(key, minN);
-        return { node: minN, created: false };
-      }
-      // Boundary attach: if key is smaller than current min and min has no left child.
-      // Inline NIL/null/undefined check to avoid isRealNode overhead on hot path.
-      const minL = minN.left;
-      if (cMin < 0 && (minL === NIL || minL === null || minL === undefined)) {
-        const newNode = this.createNode(key, nextValue);
-        this._attachNewNode(minN, 'left', newNode);
-        if (this._isMapMode) this._store.set(newNode.key, newNode);
-        this._size++;
-        this._setMinCache(newNode);
-        // If max is not initialized yet (tree had 0/1 nodes), mirror max too.
-        if (header._right  === NIL) this._setMaxCache(newNode);
-        return { node: newNode, created: true };
-      }
-
-      // Only touch max when key is not less than min.
-      if (cMin > 0) {
-        const maxN = header._right ?? NIL;
-        // Boundary attach: if key is greater than current max and max has no right child.
-        const cMax = comparator(key, maxN.key);
-        if (cMax === 0) {
-          maxN.value = nextValue as V;
-          if (this._isMapMode) this._store.set(key, maxN);
-          return { node: maxN, created: false };
-        }
-        const maxR = maxN.right;
-        if (cMax > 0 && (maxR === NIL || maxR === null || maxR === undefined)) {
-          const newNode = this.createNode(key, nextValue);
-          this._attachNewNode(maxN, 'right', newNode);
-          if (this._isMapMode) this._store.set(newNode.key, newNode);
-          this._size++;
-          this._setMaxCache(newNode);
-          if (header._left === NIL) this._setMinCache(newNode);
-          return { node: newNode, created: true };
-        }
-      }
-    }
-
-    // Normal path: single-pass search + insert/update (avoid double-walking the tree).
-    const cmp = comparator;
-    const isMapMode = this._isMapMode;
-    const store = this._store;
-    let current = this._header.parent ?? NIL;
-    let parent: RedBlackTreeNode<K, V> | undefined;
-    let lastCompared = 0;
-
-    while (current !== NIL) {
-      parent = current;
-      lastCompared = cmp(key, current.key);
-      if (lastCompared < 0) current = current.left ?? NIL;
-      else if (lastCompared > 0) current = current.right ?? NIL;
-      else {
-        // Update existing.
-        current.value = nextValue as V;
-        if (isMapMode) store.set(key, current);
-        return { node: current, created: false };
-      }
-    }
-
-    // Insert new.
-    const newNode = this.createNode(key, nextValue);
-    // createNode always returns a real node in RedBlackTree.
-    newNode.parent = parent;
-
-    if (!parent) {
-      this._setRoot(newNode);
-    } else if (lastCompared < 0) {
-      parent.left = newNode;
-    } else {
-      parent.right = newNode;
-    }
-
-    newNode.left = NIL;
-    newNode.right = NIL;
-    newNode.color = 'RED';
-
-    this._updateCountAlongPath(newNode);
-    this._insertFixup(newNode);
-    if (this.isRealNode(this._root)) this._root.color = 'BLACK';
-    else return undefined;
-
-    if (isMapMode) store.set(newNode.key, newNode);
-    this._size++;
-
-    // Maintain min/max caches on insertion (header.left/right are canonical).
-    const hMin = this._header._left ?? NIL;
-    const hMax = this._header._right ?? NIL;
-
-    // Fast-path: empty tree or attaching directly to an extreme.
-    if (hMin === NIL || hMax === NIL) {
-      this._setMinCache(newNode);
-      this._setMaxCache(newNode);
-    } else /* istanbul ignore next -- boundary fast-paths at top of _setKVNode intercept boundary inserts before normal path */ if (parent === hMax && lastCompared > 0) {
-      /* istanbul ignore next */ this._setMaxCache(newNode);
-    } else /* istanbul ignore next */ if (parent === hMin && lastCompared < 0) {
-      /* istanbul ignore next */ this._setMinCache(newNode);
-    } else {
-      if (cmp(newNode.key, hMin.key) < 0) this._setMinCache(newNode);
-      if (cmp(newNode.key, hMax.key) > 0) this._setMaxCache(newNode);
-    }
-
-    return { node: newNode, created: true };
-  }
-
-  /**
-   * (Internal) Boolean wrapper around `_setKVNode`.
-   *
-   * Includes a map-mode update fast-path:
-   * - If `isMapMode=true` and the key already exists in `_store`, then updating the value does not
-   *   require any tree search/rotation (tree shape depends only on key).
-   * - This path is intentionally limited to `nextValue !== undefined` to preserve existing
-   *   semantics for `undefined` values.
-   * @remarks Time O(log n) average, Space O(1)
-   */
-  protected _setKV(key: K, nextValue?: V): boolean {
-    if (this._isMapMode) {
-      const store = this._store;
-      const node = store.get(key);
-      if (node) {
-        node.value = nextValue as V;
-        return true;
-      }
-    }
-
-    return this._setKVNode(key, nextValue) !== undefined;
-  }
-
-  /**
-   * Insert/update using a hint node to speed up nearby insertions.
-   *
-   * close to the expected insertion position (often the previously returned node in a loop).
-   *
-   * When the hint is a good fit (sorted / nearly-sorted insertion), this can avoid most of the
-   * normal root-to-leaf search and reduce constant factors.
-   *
-   * When the hint does not match (random workloads), this will fall back to the normal set path.
-   * @remarks Time O(log n) average, Space O(1)
-   */
-  setWithHintNode(key: K, value: V, hint?: RedBlackTreeNode<K, V>): RedBlackTreeNode<K, V> | undefined {
-    if (!hint || !this.isRealNode(hint)) {
-      return this._setKVNode(key, value)?.node;
-    }
-
-    const cmp = this._compare.bind(this);
-    const c0 = cmp(key, hint.key);
-    if (c0 === 0) {
-      hint.value = value;
-      if (this._isMapMode) this._store.set(key, hint);
-      return hint;
-    }
-
-    if (c0 < 0) {
-      // Ultra-fast path: direct attach if the target slot is empty.
-      if (!this.isRealNode(hint.left)) {
-        const newNode = this.createNode(key, value);
-        if (!this.isRealNode(newNode)) return undefined;
-        this._attachNewNode(hint, 'left', newNode);
-        if (this._isMapMode) this._store.set(key, newNode);
-        this._size++;
-        // Maintain header/min/max caches.
-        const NIL = this.NIL;
-        const hMin = this._header._left ?? NIL;
-        if (hMin === NIL || this._compare(newNode.key, hMin.key) < 0) this._setMinCache(newNode);
-        const hMax = this._header._right ?? NIL;
-        if (hMax === NIL || this._compare(newNode.key, hMax.key) > 0) this._setMaxCache(newNode);
-        return newNode;
-      }
-
-      const pred = this._predecessorOf(hint);
-      if (pred && cmp(pred.key, key) >= 0) {
-        return this._setKVNode(key, value)?.node;
-      }
-
-      // Try attach as right of pred.
-      if (pred && !this.isRealNode(pred.right)) {
-        const newNode = this.createNode(key, value);
-        if (!this.isRealNode(newNode)) return undefined;
-        this._attachNewNode(pred, 'right', newNode);
-        if (this._isMapMode) this._store.set(key, newNode);
-        this._size++;
-        // Maintain header/min/max caches.
-        const NIL = this.NIL;
-        const hMin = this._header._left ?? NIL;
-        if (hMin === NIL || this._compare(newNode.key, hMin.key) < 0) this._setMinCache(newNode);
-        const hMax = this._header._right ?? NIL;
-        if (hMax === NIL || this._compare(newNode.key, hMax.key) > 0) this._setMaxCache(newNode);
-        return newNode;
-      }
-
-      /* istanbul ignore next -- structurally unreachable: predecessor never has a right child (it's the max of left subtree) */
-      return this._setKVNode(key, value)?.node;
-    }
-
-    // c0 > 0
-    // Ultra-fast path: direct attach if the target slot is empty.
-    if (!this.isRealNode(hint.right)) {
-      const newNode = this.createNode(key, value);
-      if (!this.isRealNode(newNode)) return undefined;
-      this._attachNewNode(hint, 'right', newNode);
-      if (this._isMapMode) this._store.set(key, newNode);
-      this._size++;
-      // Maintain header/min/max caches.
-      const NIL = this.NIL;
-      const hMin = this._header._left ?? NIL;
-      if (hMin === NIL || this._compare(newNode.key, hMin.key) < 0) this._setMinCache(newNode);
-      const hMax = this._header._right ?? NIL;
-      if (hMax === NIL || this._compare(newNode.key, hMax.key) > 0) this._setMaxCache(newNode);
-      return newNode;
-    }
-
-    const succ = this._successorOf(hint);
-    if (succ && cmp(succ.key, key) <= 0) {
-      return this._setKVNode(key, value)?.node;
-    }
-
-    if (succ && !this.isRealNode(succ.left)) {
-      const newNode = this.createNode(key, value);
-      if (!this.isRealNode(newNode)) return undefined;
-      this._attachNewNode(succ, 'left', newNode);
-      if (this._isMapMode) this._store.set(key, newNode);
-      this._size++;
-      // Maintain header/min/max caches.
-      const NIL = this.NIL;
-      const hMin = this._header._left ?? NIL;
-      if (hMin === NIL || this._compare(newNode.key, hMin.key) < 0) this._setMinCache(newNode);
-      const hMax = this._header._right ?? NIL;
-      if (hMax === NIL || this._compare(newNode.key, hMax.key) > 0) this._setMaxCache(newNode);
-      return newNode;
-    }
-
-    /* istanbul ignore next -- structurally unreachable: successor never has a left child (it's the min of right subtree) */
-    return this._setKVNode(key, value)?.node;
-  }
-
-  /**
-   * Boolean wrapper for setWithHintNode.
-   * @remarks Time O(log n) average, Space O(1)
-   */
-  setWithHint(key: K, value: V, hint?: RedBlackTreeNode<K, V>): boolean {
-    return this.setWithHintNode(key, value, hint) !== undefined;
-  }
-
-  /**
-   * Insert or update a key/value (map mode) or key-only (set mode).
-   *
-   * This method is optimized for:
-   * - monotonic inserts via min/max boundary fast paths
-   * - updates via a single-pass search (no double walk)
-   *
-   * @remarks Time O(log n) average, Space O(1)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // basic Red-Black Tree with simple number keys
- *  // Create a simple Red-Black Tree with numeric keys
- *     const tree = new RedBlackTree([5, 2, 8, 1, 9]);
- *
- *     tree.print();
- *     //   _2___
- *     //  /     \
- *     //  1    _8_
- *     //      /   \
- *     //      5   9
- *
- *     // Verify the tree maintains sorted order
- *     console.log([...tree.keys()]); // [1, 2, 5, 8, 9];
- *
- *     // Check size
- *     console.log(tree.size); // 5;
+   * @example
+   * // basic Red-Black Tree with simple number keys
+   *  // Create a simple Red-Black Tree with numeric keys
+   *     const tree = new RedBlackTree([5, 2, 8, 1, 9]);
+   *
+   *     tree.print();
+   *     //   _2___
+   *     //  /     \
+   *     //  1    _8_
+   *     //      /   \
+   *     //      5   9
+   *
+   *     // Verify the tree maintains sorted order
+   *     console.log([...tree.keys()]); // [1, 2, 5, 8, 9];
+   *
+   *     // Check size
+   *     console.log(tree.size); // 5;
    */
   override set(
     keyNodeOrEntry: K | RedBlackTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
@@ -1054,24 +476,19 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
     // Common path: tree.set(key, value) or tree.set([key, value]).
     if (!this.isNode(keyNodeOrEntry)) {
       if (keyNodeOrEntry === null || keyNodeOrEntry === undefined) return false;
-
       if (this.isEntry(keyNodeOrEntry)) {
         const key = keyNodeOrEntry[0];
         if (key === null || key === undefined) return false;
         const nextValue = value ?? keyNodeOrEntry[1];
         return this._setKV(key, nextValue);
       }
-
       // key-only
       return this._setKV(keyNodeOrEntry, value);
     }
-
     // Node insertion path (advanced usage)
     const [newNode, newValue] = this._keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry, value);
     if (!this.isRealNode(newNode)) return false;
-
     const insertStatus = this._insert(newNode);
-
     if (insertStatus === 'CREATED') {
       if (this.isRealNode(this._root)) {
         this._root.color = 'BLACK';
@@ -1107,186 +524,34 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
    * @remarks Time O(log n) average, Space O(1)
    * @param keyNodeEntryRawOrPredicate - Key, node, or [key, value] entry identifying the node to delete.
    * @returns Array with deletion metadata (removed node, rebalancing hint if any).
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Remove and rebalance
- *  const rbt = new RedBlackTree<number>([10, 5, 15, 3, 7]);
- *     rbt.delete(5);
- *     console.log(rbt.has(5)); // false;
- *     console.log(rbt.size); // 4;
+   * @example
+   * // Remove and rebalance
+   *  const rbt = new RedBlackTree<number>([10, 5, 15, 3, 7]);
+   *     rbt.delete(5);
+   *     console.log(rbt.has(5)); // false;
+   *     console.log(rbt.size); // 4;
    */
   override delete(
     keyNodeEntryRawOrPredicate: BTNRep<K, V, RedBlackTreeNode<K, V>> | NodePredicate<RedBlackTreeNode<K, V> | null>
   ): boolean {
     if (keyNodeEntryRawOrPredicate === null) return false;
-
     let nodeToDelete: OptNode<RedBlackTreeNode<K, V>>;
     if (this._isPredicate(keyNodeEntryRawOrPredicate)) nodeToDelete = this.getNode(keyNodeEntryRawOrPredicate);
-    else nodeToDelete = this.isRealNode(keyNodeEntryRawOrPredicate) ? keyNodeEntryRawOrPredicate : this.getNode(keyNodeEntryRawOrPredicate);
-
+    else
+      nodeToDelete = this.isRealNode(keyNodeEntryRawOrPredicate)
+        ? keyNodeEntryRawOrPredicate
+        : this.getNode(keyNodeEntryRawOrPredicate);
     if (!nodeToDelete) {
       return false;
     }
-
     // Track min/max cache updates before structural modifications.
     const willDeleteMin = nodeToDelete === this._minNode;
     const willDeleteMax = nodeToDelete === this._maxNode;
     const nextMin = willDeleteMin ? this._successorOf(nodeToDelete) : undefined;
     const nextMax = willDeleteMax ? this._predecessorOf(nodeToDelete) : undefined;
-
     let originalColor = nodeToDelete.color;
     const NIL = this.NIL;
     let replacementNode: RedBlackTreeNode<K, V> = NIL;
-
     if (!this.isRealNode(nodeToDelete.left)) {
       // No real left child → replace with right (may be NIL)
       replacementNode = nodeToDelete.right ?? NIL;
@@ -1301,7 +566,6 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
       if (successor) {
         originalColor = successor.color;
         replacementNode = successor.right ?? NIL;
-
         if (successor.parent === nodeToDelete) {
           // Even if replacementNode is NIL, set its parent for fixup
           replacementNode.parent = successor;
@@ -1312,7 +576,6 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
             successor.right.parent = successor;
           }
         }
-
         this._transplant(nodeToDelete, successor);
         successor.left = nodeToDelete.left;
         if (successor.left) {
@@ -1323,10 +586,8 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
     }
     if (this._isMapMode) this._store.delete(nodeToDelete.key);
     this._size--;
-
     // Update order-statistic counts from replacement up to root
-    this._updateCountAlongPath(replacementNode?.parent as RedBlackTreeNode<K, V> | undefined ?? replacementNode);
-
+    this._updateCountAlongPath((replacementNode?.parent as RedBlackTreeNode<K, V> | undefined) ?? replacementNode);
     // Update min/max caches.
     if (this._size <= 0) {
       this._setMinCache(undefined);
@@ -1342,325 +603,319 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
         this._setMaxCache(this.isRealNode(this._root) ? this.getRightMost(n => n, this._root) : undefined);
       }
     }
-
-    if (originalColor === 'BLACK') {
-      this._deleteFixup(replacementNode);
+    if (originalColor === 'BLACK') {
+      this._deleteFixup(replacementNode);
+    }
+    return true;
+  }
+
+  /**
+   * Transform entries into a like-kind red-black tree with possibly different key/value types.
+   * @remarks Time O(n) average, Space O(n)
+   * @template MK
+   * @template MV
+   * @template MR
+   * @param callback - Mapping function from (key, value, index, tree) to a new [key, value].
+   * @param [options] - See parameter type for details.
+   * @param [thisArg] - See parameter type for details.
+   * @returns A new RedBlackTree with mapped entries.
+   */
+  /**
+   * Red-Black trees are self-balancing — `perfectlyBalance` rebuilds via
+   * sorted bulk insert, which naturally produces a balanced RBT.
+   * @remarks Time O(N), Space O(N)
+   * @example
+   * // Rebalance tree
+   *  const rbt = new RedBlackTree<number>([1, 2, 3, 4, 5]);
+   *     rbt.perfectlyBalance();
+   *     console.log(rbt.isAVLBalanced()); // true;
+   */
+  override perfectlyBalance(_iterationType?: IterationType): boolean {
+    // Extract sorted entries, clear, re-insert — RBT self-balances on insert
+    const entries: [K, V | undefined][] = [];
+    for (const [key, value] of this) entries.push([key, value]);
+    if (entries.length <= 1) return true;
+    this.clear();
+    this.setMany(
+      entries.map(([k]) => k),
+      entries.map(([, v]) => v),
+      true // isBalanceAdd
+    );
+    return true;
+  }
+
+  /**
+   * Transform to new tree
+   * @example
+   * // Transform to new tree
+   *  const rbt = new RedBlackTree<number, number>([
+   *       [1, 10],
+   *       [2, 20]
+   *     ]);
+   *     const doubled = rbt.map((v, k) => [k, (v ?? 0) * 2] as [number, number]);
+   *     console.log([...doubled.values()]); // [20, 40];
+   */
+  override map<MK = K, MV = V, MR = any>(
+    callback: EntryCallback<K, V | undefined, [MK, MV]>,
+    options?: Partial<RedBlackTreeOptions<MK, MV, MR>>,
+    thisArg?: unknown
+  ): RedBlackTree<MK, MV, MR> {
+    const out = this._createLike<MK, MV, MR>([], options);
+    let index = 0;
+    for (const [key, value] of this) {
+      out.set(callback.call(thisArg, value, key, index++, this));
+    }
+    return out;
+  }
+
+  /**
+   * (Internal) Find a node by key using a tight BST walk (no allocations).
+   *
+   * NOTE: This uses `header.parent` as the canonical root pointer.
+   * @remarks Time O(log n) average, Space O(1)
+   */
+  protected _findNodeByKey(key: K): RedBlackTreeNode<K, V> | undefined {
+    const NIL = this.NIL;
+    const cmp = this._compare.bind(this);
+    let cur = this._header.parent ?? NIL;
+    while (cur !== NIL) {
+      const c = cmp(key, cur.key);
+      if (c < 0) cur = cur.left ?? NIL;
+      else if (c > 0) cur = cur.right ?? NIL;
+      else return cur;
+    }
+    return undefined;
+  }
+
+  /**
+   * (Internal) In-order predecessor of a node in a BST.
+   * @remarks Time O(log n) average, Space O(1)
+   */
+  protected _predecessorOf(node: RedBlackTreeNode<K, V>): RedBlackTreeNode<K, V> | undefined {
+    const NIL = this.NIL;
+    if (node.left && node.left !== NIL) {
+      let cur = node.left;
+      while (cur.right && cur.right !== NIL) cur = cur.right;
+      return cur;
+    }
+    let cur: RedBlackTreeNode<K, V> | undefined = node;
+    let p = node.parent;
+    while (p && cur === p.left) {
+      cur = p;
+      p = p.parent;
+    }
+    return p;
+  }
+
+  /**
+   * (Internal) In-order successor of a node in a BST.
+   * @remarks Time O(log n) average, Space O(1)
+   */
+  protected _successorOf(node: RedBlackTreeNode<K, V>): RedBlackTreeNode<K, V> | undefined {
+    const NIL = this.NIL;
+    if (node.right && node.right !== NIL) {
+      let cur = node.right;
+      while (cur.left && cur.left !== NIL) cur = cur.left;
+      return cur;
+    }
+    let cur: RedBlackTreeNode<K, V> | undefined = node;
+    let p = node.parent;
+    while (p && cur === p.right) {
+      cur = p;
+      p = p.parent;
     }
+    return p;
+  }
 
-    return true;
+  /**
+   * (Internal) Attach a new node directly under a known parent/side (no search).
+   *
+   * This is a performance-oriented helper used by boundary fast paths and hinted insertion.
+   * It will:
+   * - wire parent/child pointers (using accessors, so parent pointers are updated)
+   * - initialize children to NIL
+   * - mark the new node RED, then run insert fix-up
+   *
+   * Precondition: the chosen slot (parent.left/parent.right) is empty (NIL/null/undefined).
+   * @remarks Time O(log n) average, Space O(1)
+   */
+  protected _attachNewNode(parent: RedBlackTreeNode<K, V>, side: 'left' | 'right', node: RedBlackTreeNode<K, V>): void {
+    const NIL = this.NIL;
+    node.parent = parent;
+    if (side === 'left') parent.left = node;
+    else parent.right = node;
+    node.left = NIL;
+    node.right = NIL;
+    node.color = 'RED';
+    this._updateCountAlongPath(node);
+    this._insertFixup(node);
+    if (this.isRealNode(this._root)) this._root.color = 'BLACK';
   }
 
   /**
-   * Transform entries into a like-kind red-black tree with possibly different key/value types.
-   * @remarks Time O(n) average, Space O(n)
-   * @template MK
-   * @template MV
-   * @template MR
-   * @param callback - Mapping function from (key, value, index, tree) to a new [key, value].
-   * @param [options] - See parameter type for details.
-   * @param [thisArg] - See parameter type for details.
-   * @returns A new RedBlackTree with mapped entries.
+   * (Internal) a single source of truth for min/max is header._left/_right.
+   * Keep legacy _minNode/_maxNode mirrored for compatibility.
+   * @remarks Time O(1), Space O(1)
    */
   /**
-   * Red-Black trees are self-balancing — `perfectlyBalance` rebuilds via
-   * sorted bulk insert, which naturally produces a balanced RBT.
-   * @remarks Time O(N), Space O(N)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Rebalance tree
- *  const rbt = new RedBlackTree<number>([1, 2, 3, 4, 5]);
- *     rbt.perfectlyBalance();
- *     console.log(rbt.isAVLBalanced()); // true;
+   * (Internal) Update min cache pointers (header._left is the canonical min pointer).
+   * @remarks Time O(1), Space O(1)
    */
-  override perfectlyBalance(_iterationType?: IterationType): boolean {
-    // Extract sorted entries, clear, re-insert — RBT self-balances on insert
-    const entries: [K, V | undefined][] = [];
-    for (const [key, value] of this) entries.push([key, value]);
-    if (entries.length <= 1) return true;
-    this.clear();
-    this.setMany(
-      entries.map(([k]) => k),
-      entries.map(([, v]) => v),
-      true // isBalanceAdd
-    );
-    return true;
+  protected _setMinCache(node: RedBlackTreeNode<K, V> | undefined): void {
+    this._minNode = node;
+    this._header._left = node ?? this.NIL;
   }
 
-    /**
-   * Transform to new tree
-  
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Transform to new tree
- *  const rbt = new RedBlackTree<number, number>([[1, 10], [2, 20]]);
- *     const doubled = rbt.map((v, k) => [k, (v ?? 0) * 2] as [number, number]);
- *     console.log([...doubled.values()]); // [20, 40];
+  /**
+   * (Internal) Update max cache pointers (header._right is the canonical max pointer).
+   * @remarks Time O(1), Space O(1)
    */
-  override map<MK = K, MV = V, MR = any>(
-    callback: EntryCallback<K, V | undefined, [MK, MV]>,
-    options?: Partial<RedBlackTreeOptions<MK, MV, MR>>,
-    thisArg?: unknown
-  ): RedBlackTree<MK, MV, MR> {
-    const out = this._createLike<MK, MV, MR>([], options);
+  protected _setMaxCache(node: RedBlackTreeNode<K, V> | undefined): void {
+    this._maxNode = node;
+    this._header._right = node ?? this.NIL;
+  }
 
-    let index = 0;
-    for (const [key, value] of this) {
-      out.set(callback.call(thisArg, value, key, index++, this));
+  /**
+   * (Internal) Core set implementation returning the affected node.
+   *
+   * Hot path goals:
+   * - Avoid double walks (search+insert): do a single traversal that either updates or inserts.
+   * - Use header min/max caches to fast-path boundary inserts.
+   * - Keep header._left/_right as canonical min/max pointers.
+   *
+   * Return value:
+   * - `{ node, created:false }` when an existing key is updated
+   * - `{ node, created:true }` when a new node is inserted
+   * - `undefined` only on unexpected internal failure.
+   * @remarks Time O(log n) average, Space O(1)
+   */
+  protected _setKVNode(key: K, nextValue?: V): { node: RedBlackTreeNode<K, V>; created: boolean } | undefined {
+    const NIL = this.NIL;
+    const comparator = this._comparator;
+    // Read via header to avoid undefined checks (header uses NIL when empty).
+    const header = this._header;
+    const minN = header._left ?? NIL;
+    if (minN !== NIL) {
+      const cMin = comparator(key, minN.key);
+      if (cMin === 0) {
+        minN.value = nextValue as V;
+        if (this._isMapMode) this._store.set(key, minN);
+        return { node: minN, created: false };
+      }
+      // Boundary attach: if key is smaller than current min and min has no left child.
+      // Inline NIL/null/undefined check to avoid isRealNode overhead on hot path.
+      const minL = minN.left;
+      if (cMin < 0 && (minL === NIL || minL === null || minL === undefined)) {
+        const newNode = this.createNode(key, nextValue);
+        this._attachNewNode(minN, 'left', newNode);
+        if (this._isMapMode) this._store.set(newNode.key, newNode);
+        this._size++;
+        this._setMinCache(newNode);
+        // If max is not initialized yet (tree had 0/1 nodes), mirror max too.
+        if (header._right === NIL) this._setMaxCache(newNode);
+        return { node: newNode, created: true };
+      }
+      // Only touch max when key is not less than min.
+      if (cMin > 0) {
+        const maxN = header._right ?? NIL;
+        // Boundary attach: if key is greater than current max and max has no right child.
+        const cMax = comparator(key, maxN.key);
+        if (cMax === 0) {
+          maxN.value = nextValue as V;
+          if (this._isMapMode) this._store.set(key, maxN);
+          return { node: maxN, created: false };
+        }
+        const maxR = maxN.right;
+        if (cMax > 0 && (maxR === NIL || maxR === null || maxR === undefined)) {
+          const newNode = this.createNode(key, nextValue);
+          this._attachNewNode(maxN, 'right', newNode);
+          if (this._isMapMode) this._store.set(newNode.key, newNode);
+          this._size++;
+          this._setMaxCache(newNode);
+          if (header._left === NIL) this._setMinCache(newNode);
+          return { node: newNode, created: true };
+        }
+      }
     }
-    return out;
+    // Normal path: single-pass search + insert/update (avoid double-walking the tree).
+    const cmp = comparator;
+    const isMapMode = this._isMapMode;
+    const store = this._store;
+    let current = this._header.parent ?? NIL;
+    let parent: RedBlackTreeNode<K, V> | undefined;
+    let lastCompared = 0;
+    while (current !== NIL) {
+      parent = current;
+      lastCompared = cmp(key, current.key);
+      if (lastCompared < 0) current = current.left ?? NIL;
+      else if (lastCompared > 0) current = current.right ?? NIL;
+      else {
+        // Update existing.
+        current.value = nextValue as V;
+        if (isMapMode) store.set(key, current);
+        return { node: current, created: false };
+      }
+    }
+    // Insert new.
+    const newNode = this.createNode(key, nextValue);
+    // createNode always returns a real node in RedBlackTree.
+    newNode.parent = parent;
+    if (!parent) {
+      this._setRoot(newNode);
+    } else if (lastCompared < 0) {
+      parent.left = newNode;
+    } else {
+      parent.right = newNode;
+    }
+    newNode.left = NIL;
+    newNode.right = NIL;
+    newNode.color = 'RED';
+    this._updateCountAlongPath(newNode);
+    this._insertFixup(newNode);
+    if (this.isRealNode(this._root)) this._root.color = 'BLACK';
+    else return undefined;
+    if (isMapMode) store.set(newNode.key, newNode);
+    this._size++;
+    // Maintain min/max caches on insertion (header.left/right are canonical).
+    const hMin = this._header._left ?? NIL;
+    const hMax = this._header._right ?? NIL;
+    // Fast-path: empty tree or attaching directly to an extreme.
+    if (hMin === NIL || hMax === NIL) {
+      this._setMinCache(newNode);
+      this._setMaxCache(newNode);
+    } else if (parent === hMax && lastCompared > 0) {
+      /* istanbul ignore next -- boundary fast-paths at top of _setKVNode intercept boundary inserts before normal path */ /* istanbul ignore next */
+      this._setMaxCache(newNode);
+    } else if (parent === hMin && lastCompared < 0) {
+      /* istanbul ignore next */ /* istanbul ignore next */
+      this._setMinCache(newNode);
+    } else {
+      if (cmp(newNode.key, hMin.key) < 0) this._setMinCache(newNode);
+      if (cmp(newNode.key, hMax.key) > 0) this._setMaxCache(newNode);
+    }
+    return { node: newNode, created: true };
+  }
+
+  /**
+   * (Internal) Boolean wrapper around `_setKVNode`.
+   *
+   * Includes a map-mode update fast-path:
+   * - If `isMapMode=true` and the key already exists in `_store`, then updating the value does not
+   *   require any tree search/rotation (tree shape depends only on key).
+   * - This path is intentionally limited to `nextValue !== undefined` to preserve existing
+   *   semantics for `undefined` values.
+   * @remarks Time O(log n) average, Space O(1)
+   */
+  protected _setKV(key: K, nextValue?: V): boolean {
+    if (this._isMapMode) {
+      const store = this._store;
+      const node = store.get(key);
+      if (node) {
+        node.value = nextValue as V;
+        return true;
+      }
+    }
+    return this._setKVNode(key, nextValue) !== undefined;
   }
 
   /**
@@ -1716,7 +971,6 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
     newNode: RedBlackTreeNode<K, V>
   ): RedBlackTreeNode<K, V> {
     newNode.color = oldNode.color;
-
     return super._replaceNode(oldNode, newNode);
   }
 
@@ -1729,11 +983,9 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
   protected _insert(node: RedBlackTreeNode<K, V>): CRUD {
     const NIL = this.NIL;
     const cmp = this._compare.bind(this);
-
     let current = this._header.parent ?? NIL;
     let parent: RedBlackTreeNode<K, V> | undefined;
     let lastCompared = 0;
-
     while (current !== NIL) {
       parent = current;
       lastCompared = cmp(node.key, current.key);
@@ -1746,9 +998,7 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
         return 'UPDATED';
       }
     }
-
     node.parent = parent;
-
     if (!parent) {
       this._setRoot(node);
     } else if (lastCompared < 0) {
@@ -1756,14 +1006,11 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
     } else {
       parent.right = node;
     }
-
     node.left = NIL;
     node.right = NIL;
     node.color = 'RED';
-
     // Update counts along insertion path before fixup
     this._updateCountAlongPath(node);
-
     this._insertFixup(node);
     return 'CREATED';
   }
@@ -1783,7 +1030,6 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
     } else {
       u.parent.right = v;
     }
-
     if (v) {
       v.parent = u.parent;
     }
@@ -1798,14 +1044,11 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
   protected _insertFixup(z: RedBlackTreeNode<K, V> | undefined): void {
     const leftRotate = this._leftRotate.bind(this);
     const rightRotate = this._rightRotate.bind(this);
-
     while (z) {
       const p = z.parent;
       if (!p || p.color !== 'RED') break;
-
       const gp = p.parent;
       if (!gp) break;
-
       if (p === gp.left) {
         const y = gp.right;
         if (y?.color === 'RED') {
@@ -1815,12 +1058,10 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
           z = gp;
           continue;
         }
-
         if (z === p.right) {
           z = p;
           leftRotate(z);
         }
-
         const p2 = z?.parent;
         const gp2 = p2?.parent;
         if (p2 && gp2) {
@@ -1837,12 +1078,10 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
           z = gp;
           continue;
         }
-
         if (z === p.left) {
           z = p;
           rightRotate(z);
         }
-
         const p2 = z?.parent;
         const gp2 = p2?.parent;
         if (p2 && gp2) {
@@ -1851,10 +1090,8 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
           leftRotate(gp2);
         }
       }
-
       break;
     }
-
     if (this.isRealNode(this._root)) this._root.color = 'BLACK';
   }
 
@@ -1869,17 +1106,13 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
     // `node` is the child that replaced the deleted node (may be NIL sentinel).
     // If RED → just recolor BLACK (trivial fix). If BLACK → double-black repair.
     if (!node) return;
-
     const NIL = this.NIL;
     let current: RedBlackTreeNode<K, V> = node;
-
     while (current !== this.root && current.color === 'BLACK') {
       const parent: RedBlackTreeNode<K, V> | undefined = current.parent;
       if (!parent) break;
-
       const nodeIsLeft = current === parent.left;
       let sibling = nodeIsLeft ? parent.right : parent.left;
-
       // Case 1: sibling is RED → rotate to get a BLACK sibling
       if (sibling && sibling.color === 'RED') {
         sibling.color = 'BLACK';
@@ -1892,12 +1125,10 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
           sibling = parent.left;
         }
       }
-
       const sibLeft = sibling?.left;
       const sibRight = sibling?.right;
       const sibLeftBlack = !sibLeft || sibLeft === NIL || sibLeft.color === 'BLACK';
       const sibRightBlack = !sibRight || sibRight === NIL || sibRight.color === 'BLACK';
-
       if (sibLeftBlack && sibRightBlack) {
         // Case 2: sibling's children are both BLACK → recolor sibling RED, move up
         if (sibling) sibling.color = 'RED';
@@ -1933,7 +1164,6 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
         current = this.root!;
       }
     }
-
     current.color = 'BLACK';
   }
 
@@ -1947,16 +1177,12 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
     if (!x || !x.right) {
       return;
     }
-
     const y = x.right;
     x.right = y.left;
-
     if (y.left && y.left !== this.NIL) {
       y.left.parent = x;
     }
-
     y.parent = x.parent;
-
     if (!x.parent) {
       this._setRoot(y);
     } else if (x === x.parent.left) {
@@ -1964,10 +1190,8 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
     } else {
       x.parent.right = y;
     }
-
     y.left = x;
     x.parent = y;
-
     // Update counts: x first (now child), then y (now parent)
     this._updateCount(x);
     this._updateCount(y);
@@ -1983,16 +1207,12 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
     if (!y || !y.left) {
       return;
     }
-
     const x = y.left;
     y.left = x.right;
-
     if (x.right && x.right !== this.NIL) {
       x.right.parent = y;
     }
-
     x.parent = y.parent;
-
     if (!y.parent) {
       this._setRoot(x);
     } else if (y === y.parent.left) {
@@ -2000,10 +1220,8 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
     } else {
       y.parent.right = x;
     }
-
     x.right = y;
     y.parent = x;
-
     // Update counts: y first (now child), then x (now parent)
     this._updateCount(y);
     this._updateCount(x);