max-priority-queue-typed 2.4.4 → 2.5.0

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

@@ -28,7 +28,7 @@ import { IBinaryTree } from '../../interfaces';
 import { isComparable, makeTrampoline, makeTrampolineThunk } from '../../utils';
 import { Queue } from '../queue';
 import { IterableEntryBase } from '../base';
-import { DFSOperation, Range } from '../../common';
+import { DFSOperation, ERR, Range } from '../../common';
 
 /**
  * @template K - The type of the key.
@@ -205,84 +205,6 @@ export class BinaryTreeNode<K = any, V = any> {
  * 5. Leaf Nodes: Nodes without children are leaves.
  *
  * @example
- * // basic BinaryTree creation and insertion
- *  // Create a BinaryTree with entries
- *     const entries: [number, string][] = [
- *       [6, 'six'],
- *       [1, 'one'],
- *       [2, 'two'],
- *       [7, 'seven'],
- *       [5, 'five'],
- *       [3, 'three'],
- *       [4, 'four'],
- *       [9, 'nine'],
- *       [8, 'eight']
- *     ];
- *
- *     const tree = new BinaryTree(entries);
- *
- *     // Verify size
- *     console.log(tree.size); // 9;
- *
- *     // Add new element
- *     tree.set(10, 'ten');
- *     console.log(tree.size); // 10;
- * @example
- * // BinaryTree get and has operations
- *  const tree = new BinaryTree(
- *       [
- *         [5, 'five'],
- *         [3, 'three'],
- *         [7, 'seven'],
- *         [1, 'one'],
- *         [4, 'four'],
- *         [6, 'six'],
- *         [8, 'eight']
- *       ],
- *       { isMapMode: false }
- *     );
- *
- *     // Check if key exists
- *     console.log(tree.has(5)); // true;
- *     console.log(tree.has(10)); // false;
- *
- *     // Get value by key
- *     console.log(tree.get(3)); // 'three';
- *     console.log(tree.get(7)); // 'seven';
- *     console.log(tree.get(100)); // undefined;
- *
- *     // Get node structure
- *     const node = tree.getNode(5);
- *     console.log(node?.key); // 5;
- *     console.log(node?.value); // 'five';
- * @example
- * // BinaryTree level-order traversal
- *  const tree = new BinaryTree([
- *       [1, 'one'],
- *       [2, 'two'],
- *       [3, 'three'],
- *       [4, 'four'],
- *       [5, 'five'],
- *       [6, 'six'],
- *       [7, 'seven']
- *     ]);
- *
- *     // Binary tree maintains level-order insertion
- *     // Complete binary tree structure
- *     console.log(tree.size); // 7;
- *
- *     // Verify all keys are present
- *     console.log(tree.has(1)); // true;
- *     console.log(tree.has(4)); // true;
- *     console.log(tree.has(7)); // true;
- *
- *     // Iterate through tree
- *     const keys: number[] = [];
- *     for (const [key] of tree) {
- *       keys.push(key);
- *     }
- *     console.log(keys.length); // 7;
- * @example
  * // determine loan approval using a decision tree
  *  // Decision tree structure
  *     const loanDecisionTree = new BinaryTree<string>(
@@ -371,7 +293,7 @@ export class BinaryTree<K = any, V = any, R = any>
       if (isMapMode !== undefined) this._isMapMode = isMapMode;
       if (isDuplicate !== undefined) this._isDuplicate = isDuplicate;
       if (typeof toEntryFn === 'function') this._toEntryFn = toEntryFn;
-      else if (toEntryFn) throw TypeError('toEntryFn must be a function type');
+      else if (toEntryFn) throw new TypeError(ERR.notAFunction('toEntryFn', 'BinaryTree'));
     }
 
     if (keysNodesEntriesOrRaws) this.setMany(keysNodesEntriesOrRaws);
@@ -644,6 +566,20 @@ export class BinaryTree<K = any, V = any, R = any>
    *
    * @param keyNodeOrEntry - The key, node, or entry to add.
    * @returns True if the addition was successful, false otherwise.
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Add a single node
+ *  const tree = new BinaryTree<number>();
+ *     tree.add(1);
+ *     tree.add(2);
+ *     tree.add(3);
+ *     console.log(tree.size); // 3;
+ *     console.log(tree.has(1)); // true;
    */
   add(
     keyNodeOrEntry: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined
@@ -658,6 +594,40 @@ export class BinaryTree<K = any, V = any, R = any>
    * @param keyNodeOrEntry - The key, node, or entry to set or update.
    * @param [value] - The value, if providing just a key.
    * @returns True if the addition was successful, false otherwise.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // basic BinaryTree creation and insertion
+ *  // Create a BinaryTree with entries
+ *     const entries: [number, string][] = [
+ *       [6, 'six'],
+ *       [1, 'one'],
+ *       [2, 'two'],
+ *       [7, 'seven'],
+ *       [5, 'five'],
+ *       [3, 'three'],
+ *       [4, 'four'],
+ *       [9, 'nine'],
+ *       [8, 'eight']
+ *     ];
+ *
+ *     const tree = new BinaryTree(entries);
+ *
+ *     // Verify size
+ *     console.log(tree.size); // 9;
+ *
+ *     // Add new element
+ *     tree.set(10, 'ten');
+ *     console.log(tree.size); // 10;
    */
   set(
     keyNodeOrEntry: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
@@ -670,7 +640,7 @@ export class BinaryTree<K = any, V = any, R = any>
     if (!this._root) {
       this._setRoot(newNode);
       if (this._isMapMode && newNode !== null && newNode !== undefined) this._store.set(newNode.key, newNode);
-      this._size = 1;
+      if (newNode !== null) this._size = 1;
       return true;
     }
 
@@ -708,7 +678,7 @@ export class BinaryTree<K = any, V = any, R = any>
         potentialParent.right = newNode;
       }
       if (this._isMapMode && newNode !== null && newNode !== undefined) this._store.set(newNode.key, newNode);
-      this._size++;
+      if (newNode !== null) this._size++;
       return true;
     }
 
@@ -721,6 +691,20 @@ export class BinaryTree<K = any, V = any, R = any>
    *
    * @param keysNodesEntriesOrRaws - An iterable of items to set.
    * @returns An array of booleans indicating the success of each individual `set` operation.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Bulk add
+ *  const tree = new BinaryTree<number>();
+ *     tree.addMany([1, 2, 3, 4, 5]);
+ *     console.log(tree.size); // 5;
    */
   addMany(
     keysNodesEntriesOrRaws: Iterable<
@@ -737,6 +721,13 @@ export class BinaryTree<K = any, V = any, R = any>
    * @param keysNodesEntriesOrRaws - An iterable of items to set or update.
    * @param [values] - An optional parallel iterable of values.
    * @returns An array of booleans indicating the success of each individual `set` operation.
+   
+   
+    * @example
+ * // Set multiple entries
+ *  const tree = new BinaryTree<number, string>();
+ *     tree.setMany([[1, 'a'], [2, 'b'], [3, 'c']]);
+ *     console.log(tree.size); // 3;
    */
   setMany(
     keysNodesEntriesOrRaws: Iterable<
@@ -772,6 +763,21 @@ export class BinaryTree<K = any, V = any, R = any>
    * @remarks Time O(N * M), same as `setMany`, where N is the size of `anotherTree` and M is the size of this tree. Space O(M) (from `set`).
    *
    * @param anotherTree - The tree to merge.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Combine trees
+ *  const t1 = new BinaryTree<number>([1, 2]);
+ *     const t2 = new BinaryTree<number>([3, 4]);
+ *     t1.merge(t2);
+ *     console.log(t1.size); // 4;
    */
   merge(anotherTree: BinaryTree<K, V, R>) {
     this.setMany(anotherTree, []);
@@ -800,6 +806,23 @@ export class BinaryTree<K = any, V = any, R = any>
    *
    * @param keyNodeEntryRawOrPredicate - The node to delete.
    * @returns An array containing deletion results (for compatibility with self-balancing trees).
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove a node
+ *  const tree = new BinaryTree<number>([1, 2, 3, 4, 5]);
+ *     tree.delete(3);
+ *     console.log(tree.has(3)); // false;
+ *     console.log(tree.size); // 4;
    */
   delete(
     keyNodeEntryRawOrPredicate: BTNRep<K, V, BinaryTreeNode<K, V>> | NodePredicate<BinaryTreeNode<K, V> | null>
@@ -865,6 +888,16 @@ export class BinaryTree<K = any, V = any, R = any>
     return deletedResult;
   }
 
+    /**
+   * Search by predicate
+  
+   
+    * @example
+ * // Search by predicate
+ *  const tree = new BinaryTree<number>([5, 3, 7, 1, 9]);
+ *     const found = tree.search(n => n!.key > 5, true);
+ *     console.log(found.length); // >= 1;
+   */
   search(
     keyNodeEntryOrPredicate:
       | K
@@ -963,6 +996,19 @@ export class BinaryTree<K = any, V = any, R = any>
    * @param [startNode=this._root] - The node to start the search from.
    * @param [iterationType=this.iterationType] - The traversal method.
    * @returns An array of matching nodes.
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Get nodes by condition
+ *  const tree = new BinaryTree<number>([1, 2, 3, 4, 5]);
+ *     const nodes = tree.getNodes(node => node.key > 3);
+ *     console.log(nodes.length); // 2;
    */
   getNodes(
     keyNodeEntryOrPredicate:
@@ -1000,6 +1046,19 @@ export class BinaryTree<K = any, V = any, R = any>
    * @param [startNode=this._root] - The node to start the search from.
    * @param [iterationType=this.iterationType] - The traversal method.
    * @returns The first matching node, or undefined if not found.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Get node by key
+ *  const tree = new BinaryTree<number, string>([[1, 'root'], [2, 'child']]);
+ *     console.log(tree.getNode(2)?.value); // 'child';
    */
   getNode(
     keyNodeEntryOrPredicate:
@@ -1030,6 +1089,22 @@ export class BinaryTree<K = any, V = any, R = any>
    * @param [startNode=this._root] - The node to start searching from (if not in Map mode).
    * @param [iterationType=this.iterationType] - The traversal method (if not in Map mode).
    * @returns The associated value, or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Retrieve value by key
+ *  const tree = new BinaryTree<number, string>([[1, 'root'], [2, 'left'], [3, 'right']]);
+ *     console.log(tree.get(2)); // 'left';
+ *     console.log(tree.get(99)); // undefined;
    */
   override get(
     keyNodeEntryOrPredicate: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
@@ -1052,6 +1127,45 @@ export class BinaryTree<K = any, V = any, R = any>
    * @param [startNode] - The node to start the search from.
    * @param [iterationType] - The traversal method.
    * @returns True if a matching node exists, false otherwise.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // BinaryTree get and has operations
+ *  const tree = new BinaryTree(
+ *       [
+ *         [5, 'five'],
+ *         [3, 'three'],
+ *         [7, 'seven'],
+ *         [1, 'one'],
+ *         [4, 'four'],
+ *         [6, 'six'],
+ *         [8, 'eight']
+ *       ],
+ *       { isMapMode: false }
+ *     );
+ *
+ *     // Check if key exists
+ *     console.log(tree.has(5)); // true;
+ *     console.log(tree.has(10)); // false;
+ *
+ *     // Get value by key
+ *     console.log(tree.get(3)); // 'three';
+ *     console.log(tree.get(7)); // 'seven';
+ *     console.log(tree.get(100)); // undefined;
+ *
+ *     // Get node structure
+ *     const node = tree.getNode(5);
+ *     console.log(node?.key); // 5;
+ *     console.log(node?.value); // 'five';
    */
   override has(
     keyNodeEntryOrPredicate?:
@@ -1089,6 +1203,20 @@ export class BinaryTree<K = any, V = any, R = any>
   /**
    * Clears the tree of all nodes and values.
    * @remarks Time O(N) if in Map mode (due to `_store.clear()`), O(1) otherwise. Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove all nodes
+ *  const tree = new BinaryTree<number>([1, 2, 3]);
+ *     tree.clear();
+ *     console.log(tree.isEmpty()); // true;
    */
   clear() {
     this._clearNodes();
@@ -1100,6 +1228,18 @@ export class BinaryTree<K = any, V = any, R = any>
    * @remarks Time O(1), Space O(1)
    *
    * @returns True if the tree has no nodes, false otherwise.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Check empty
+ *  console.log(new BinaryTree().isEmpty()); // true;
    */
   isEmpty(): boolean {
     return this._size === 0;
@@ -1125,6 +1265,20 @@ export class BinaryTree<K = any, V = any, R = any>
    * @param [startNode=this._root] - The node to start checking from.
    * @param [iterationType=this.iterationType] - The traversal method.
    * @returns True if it's a valid BST, false otherwise.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Check BST property
+ *  const tree = new BinaryTree<number>([1, 2, 3]);
+ *     // BinaryTree doesn't guarantee BST order
+ *     console.log(typeof tree.isBST()); // 'boolean';
    */
   isBST(
     startNode: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined = this._root,
@@ -1176,6 +1330,22 @@ export class BinaryTree<K = any, V = any, R = any>
    * @param dist - The node to find the depth of.
    * @param [startNode=this._root] - The node to measure depth from (defaults to root).
    * @returns The depth (0 if `dist` is `startNode`).
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Get depth of a node
+ *  const tree = new BinaryTree<number>([1, 2, 3, 4, 5]);
+ *     const node = tree.getNode(4);
+ *     console.log(tree.getDepth(node!)); // 2;
    */
   getDepth(
     dist: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
@@ -1201,6 +1371,21 @@ export class BinaryTree<K = any, V = any, R = any>
    * @param [startNode=this._root] - The node to start measuring from.
    * @param [iterationType=this.iterationType] - The traversal method.
    * @returns The height ( -1 for an empty tree, 0 for a single-node tree).
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Get tree height
+ *  const tree = new BinaryTree<number>([1, 2, 3, 4, 5]);
+ *     console.log(tree.getHeight()); // 2;
    */
   getHeight(
     startNode: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined = this._root,
@@ -1466,6 +1651,25 @@ export class BinaryTree<K = any, V = any, R = any>
     return y;
   }
 
+    /**
+   * Depth-first search traversal
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Depth-first search traversal
+ *  const tree = new BinaryTree<number>([1, 2, 3, 4, 5]);
+ *     const inOrder = tree.dfs(node => node.key, 'IN');
+ *     console.log(inOrder); // [4, 2, 5, 1, 3];
+   */
   dfs(): (K | undefined)[];
 
   dfs<C extends NodeCallback<BinaryTreeNode<K, V>>>(
@@ -1511,6 +1715,47 @@ export class BinaryTree<K = any, V = any, R = any>
     return this._dfs(callback, pattern, onlyOne, startNode, iterationType, includeNull);
   }
 
+    /**
+   * BinaryTree level-order traversal
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // BinaryTree level-order traversal
+ *  const tree = new BinaryTree([
+ *       [1, 'one'],
+ *       [2, 'two'],
+ *       [3, 'three'],
+ *       [4, 'four'],
+ *       [5, 'five'],
+ *       [6, 'six'],
+ *       [7, 'seven']
+ *     ]);
+ *
+ *     // Binary tree maintains level-order insertion
+ *     // Complete binary tree structure
+ *     console.log(tree.size); // 7;
+ *
+ *     // Verify all keys are present
+ *     console.log(tree.has(1)); // true;
+ *     console.log(tree.has(4)); // true;
+ *     console.log(tree.has(7)); // true;
+ *
+ *     // Iterate through tree
+ *     const keys: number[] = [];
+ *     for (const [key] of tree) {
+ *       keys.push(key);
+ *     }
+ *     console.log(keys.length); // 7;
+   */
   bfs(): (K | undefined)[];
 
   bfs<C extends NodeCallback<BinaryTreeNode<K, V>>>(
@@ -1595,6 +1840,23 @@ export class BinaryTree<K = any, V = any, R = any>
     return ans;
   }
 
+    /**
+   * Get leaf nodes
+  
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Get leaf nodes
+ *  const tree = new BinaryTree<number>([1, 2, 3, 4, 5]);
+ *     const leafKeys = tree.leaves(node => node.key);
+ *     console.log(leafKeys.length); // > 0;
+   */
   leaves(): (K | undefined)[];
 
   leaves<C extends NodeCallback<BinaryTreeNode<K, V>>>(
@@ -1605,7 +1867,7 @@ export class BinaryTree<K = any, V = any, R = any>
 
   /**
    * Finds all leaf nodes in the tree.
-   * @remarks Time O(N), visits every node. Space O(H) for recursive stack or O(N) for iterative queue.
+   * @remarks Time O(N), visits every node. Space O(H) for recursive or iterative stack.
    *
    * @template C - The type of the callback function.
    * @param [callback=this._DEFAULT_NODE_CALLBACK] - Function to call on each leaf node.
@@ -1636,17 +1898,18 @@ export class BinaryTree<K = any, V = any, R = any>
 
       dfs(startNode);
     } else {
-      // BFS-based
-      const queue = new Queue([startNode]);
+      // DFS-based (stack) to match recursive order
+      const stack = [startNode];
 
-      while (queue.length > 0) {
-        const cur = queue.shift();
+      while (stack.length > 0) {
+        const cur = stack.pop()!;
         if (this.isRealNode(cur)) {
           if (this.isLeaf(cur)) {
             leaves.push(callback(cur));
           }
-          if (this.isRealNode(cur.left)) queue.push(cur.left);
-          if (this.isRealNode(cur.right)) queue.push(cur.right);
+          // Push right first so left is processed first (LIFO)
+          if (this.isRealNode(cur.right)) stack.push(cur.right);
+          if (this.isRealNode(cur.left)) stack.push(cur.left);
         }
       }
     }
@@ -1654,6 +1917,23 @@ export class BinaryTree<K = any, V = any, R = any>
     return leaves;
   }
 
+    /**
+   * Level-order grouping
+  
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Level-order grouping
+ *  const tree = new BinaryTree<number>([1, 2, 3, 4, 5]);
+ *     const levels = tree.listLevels(node => node.key);
+ *     console.log(levels[0]); // [1];
+ *     console.log(levels[1].sort()); // [2, 3];
+   */
   listLevels(): (K | undefined)[][];
 
   listLevels<C extends NodeCallback<BinaryTreeNode<K, V>>>(
@@ -1731,6 +2011,22 @@ export class BinaryTree<K = any, V = any, R = any>
     return levelsNodes;
   }
 
+    /**
+   * Morris traversal (O(1) space)
+  
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Morris traversal (O(1) space)
+ *  const tree = new BinaryTree<number>([1, 2, 3]);
+ *     const result = tree.morris(node => node.key, 'IN');
+ *     console.log(result.length); // 3;
+   */
   morris(): (K | undefined)[];
 
   morris<C extends NodeCallback<BinaryTreeNode<K, V>>>(
@@ -1854,6 +2150,21 @@ export class BinaryTree<K = any, V = any, R = any>
    * @remarks Time O(N * M), where N is the number of nodes and M is the tree size during insertion (due to `bfs` + `set`, and `set` is O(M)). Space O(N) for the new tree and the BFS queue.
    *
    * @returns A new, cloned instance of the tree.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Deep copy
+ *  const tree = new BinaryTree<number>([1, 2, 3]);
+ *     const copy = tree.clone();
+ *     copy.delete(1);
+ *     console.log(tree.has(1)); // true;
    */
   clone(): this {
     const out = this._createInstance<K, V, R>();
@@ -1868,6 +2179,20 @@ export class BinaryTree<K = any, V = any, R = any>
    * @param predicate - A function to test each [key, value] pair.
    * @param [thisArg] - `this` context for the predicate.
    * @returns A new, filtered tree.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Filter nodes by condition
+ *  const tree = new BinaryTree<number>([1, 2, 3, 4]);
+ *     const result = tree.filter((_, key) => key > 2);
+ *     console.log(result.size); // 2;
    */
   filter(predicate: EntryCallback<K, V | undefined, boolean>, thisArg?: unknown): this {
     const out = this._createInstance<K, V, R>();
@@ -1887,6 +2212,20 @@ export class BinaryTree<K = any, V = any, R = any>
    * @param [options] - Options for the new tree.
    * @param [thisArg] - `this` context for the callback.
    * @returns A new, mapped tree.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Transform to new tree
+ *  const tree = new BinaryTree<number, number>([[1, 10], [2, 20]]);
+ *     const mapped = tree.map((v, key) => [key, (v ?? 0) + 1] as [number, number]);
+ *     console.log([...mapped.values()]); // contains 11;
    */
   map<MK = K, MV = V, MR = any>(
     cb: EntryCallback<K, V | undefined, [MK, MV]>,
@@ -1939,6 +2278,19 @@ export class BinaryTree<K = any, V = any, R = any>
    *
    * @param [options] - Options to control the output.
    * @param [startNode=this._root] - The node to start printing from.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Display tree
+ *  const tree = new BinaryTree<number>([1, 2, 3]);
+ *     expect(() => tree.print()).not.toThrow();
    */
   override print(
     options?: BinaryTreePrintOptions,
@@ -2257,41 +2609,60 @@ export class BinaryTree<K = any, V = any, R = any>
     node: BinaryTreeNode<K, V> | null | undefined,
     options: BinaryTreePrintOptions
   ): NodeDisplayLayout {
-    const { isShowNull, isShowUndefined, isShowRedBlackNIL } = options;
-    const emptyDisplayLayout = <NodeDisplayLayout>[['─'], 1, 0, 0]; // Represents an empty spot
-
-    if (node === null && !isShowNull) {
-      return emptyDisplayLayout;
-    } else if (node === undefined && !isShowUndefined) {
-      return emptyDisplayLayout;
-    } else if (this.isNIL(node) && !isShowRedBlackNIL) {
-      return emptyDisplayLayout;
-    } else if (node !== null && node !== undefined) {
-      // Real node
-      const key = node.key,
-        line = this.isNIL(node) ? 'S' : String(key),
-        width = line.length;
-
-      return _buildNodeDisplay(
-        line,
-        width,
-        this._displayAux(node.left, options),
-        this._displayAux(node.right, options)
-      );
-    } else {
-      // Null or Undefined
-      const line = node === undefined ? 'U' : 'N',
-        width = line.length;
+    const emptyDisplayLayout = <NodeDisplayLayout>[['─'], 1, 0, 0];
+
+    // Iterative post-order: compute display layout bottom-up using an explicit stack.
+    // Stages: 0=process left, 1=process right, 2=merge
+    type Frame = {
+      node: BinaryTreeNode<K, V> | null | undefined;
+      stage: 0 | 1 | 2;
+      leftLayout: NodeDisplayLayout;
+      rightLayout: NodeDisplayLayout;
+    };
+
+    const newFrame = (n: BinaryTreeNode<K, V> | null | undefined): Frame => ({
+      node: n, stage: 0, leftLayout: emptyDisplayLayout, rightLayout: emptyDisplayLayout
+    });
 
-      // Treat as a leaf
-      return _buildNodeDisplay(line, width, [[''], 1, 0, 0], [[''], 1, 0, 0]);
+    const stack: Frame[] = [newFrame(node)];
+    let result: NodeDisplayLayout = emptyDisplayLayout;
+
+    const setChildResult = (layout: NodeDisplayLayout) => {
+      if (stack.length === 0) { result = layout; return; }
+      const parent = stack[stack.length - 1];
+      if (parent.stage === 1) parent.leftLayout = layout;
+      else parent.rightLayout = layout;
+    };
+
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      const cur = frame.node;
+
+      if (frame.stage === 0) {
+        // Leaf / empty node — resolve immediately
+        if (this._isDisplayLeaf(cur, options)) {
+          stack.pop();
+          const layout = this._resolveDisplayLeaf(cur, options, emptyDisplayLayout);
+          setChildResult(layout);
+          continue;
+        }
+        frame.stage = 1;
+        stack.push(newFrame(cur!.left));
+      } else if (frame.stage === 1) {
+        frame.stage = 2;
+        stack.push(newFrame(cur!.right));
+      } else {
+        stack.pop();
+        const line = this.isNIL(cur) ? 'S' : String(cur!.key);
+        const layout = BinaryTree._buildNodeDisplay(line, line.length, frame.leftLayout, frame.rightLayout);
+        setChildResult(layout);
+      }
     }
 
-    /**
-     * (Inner) Builds the display lines for a node.
-     * @remarks Time/Space: Proportional to the width and height of the subtrees.
-     */
-    function _buildNodeDisplay(line: string, width: number, left: NodeDisplayLayout, right: NodeDisplayLayout) {
+    return result;
+  }
+
+  protected static _buildNodeDisplay(line: string, width: number, left: NodeDisplayLayout, right: NodeDisplayLayout) {
       const [leftLines, leftWidth, leftHeight, leftMiddle] = left;
       const [rightLines, rightWidth, rightHeight, rightMiddle] = right;
       const firstLine =
@@ -2324,7 +2695,57 @@ export class BinaryTree<K = any, V = any, R = any>
         Math.max(leftHeight, rightHeight) + 2,
         leftWidth + Math.floor(width / 2)
       ];
+  }
+
+  /**
+   * Check if a node is a display leaf (empty, null, undefined, NIL, or real leaf).
+   */
+  protected _isDisplayLeaf(
+    node: BinaryTreeNode<K, V> | null | undefined,
+    options: BinaryTreePrintOptions
+  ): boolean {
+    const { isShowNull, isShowUndefined, isShowRedBlackNIL } = options;
+    // Empty/hidden nodes are always leaves
+    if (node === null && !isShowNull) return true;
+    if (node === undefined && !isShowUndefined) return true;
+    if (this.isNIL(node) && !isShowRedBlackNIL) return true;
+    // Shown null/undefined are leaves (no children to recurse into)
+    if (node === null || node === undefined) return true;
+    // Real node: check if it has any children that would be displayed
+    const hasDisplayableLeft = this._hasDisplayableChild(node.left, options);
+    const hasDisplayableRight = this._hasDisplayableChild(node.right, options);
+    return !hasDisplayableLeft && !hasDisplayableRight;
+  }
+
+  protected _hasDisplayableChild(
+    child: BinaryTreeNode<K, V> | null | undefined,
+    options: BinaryTreePrintOptions
+  ): boolean {
+    if (child === null) return !!options.isShowNull;
+    if (child === undefined) return !!options.isShowUndefined;
+    if (this.isNIL(child)) return !!options.isShowRedBlackNIL;
+    return true; // real node is always displayable
+  }
+
+  /**
+   * Resolve a display leaf node to its layout.
+   */
+  protected _resolveDisplayLeaf(
+    node: BinaryTreeNode<K, V> | null | undefined,
+    options: BinaryTreePrintOptions,
+    emptyDisplayLayout: NodeDisplayLayout
+  ): NodeDisplayLayout {
+    const { isShowNull, isShowUndefined, isShowRedBlackNIL } = options;
+    if (node === null && !isShowNull) return emptyDisplayLayout;
+    if (node === undefined && !isShowUndefined) return emptyDisplayLayout;
+    if (this.isNIL(node) && !isShowRedBlackNIL) return emptyDisplayLayout;
+    if (node !== null && node !== undefined) {
+      const line = this.isNIL(node) ? 'S' : String(node.key);
+      return BinaryTree._buildNodeDisplay(line, line.length, emptyDisplayLayout, emptyDisplayLayout);
     }
+    // Shown null / undefined
+    const line = node === undefined ? 'U' : 'N';
+    return BinaryTree._buildNodeDisplay(line, line.length, [[''], 1, 0, 0], [[''], 1, 0, 0]);
   }
 
   /**