directed-graph-typed 1.52.4 → 1.52.5

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

@@ -22,8 +22,9 @@ import type {
   NodeDisplayLayout,
   OptBTNOrNull
 } from '../../types';
+import { DFSOperation, DFSStackItem } from '../../types';
 import { IBinaryTree } from '../../interfaces';
-import { trampoline } from '../../utils';
+import { isComparable, trampoline } from '../../utils';
 import { Queue } from '../queue';
 import { IterableEntryBase } from '../base';
 
@@ -55,7 +56,7 @@ export class BinaryTreeNode<
     this.value = value;
   }
 
-  protected _left?: NODE | null;
+  protected _left?: OptBTNOrNull<NODE>;
 
   /**
    * The function returns the value of the `_left` property, which can be of type `NODE`, `null`, or
@@ -79,7 +80,7 @@ export class BinaryTreeNode<
     this._left = v;
   }
 
-  protected _right?: NODE | null;
+  protected _right?: OptBTNOrNull<NODE>;
 
   /**
    * The function returns the right node of a binary tree or null if it doesn't exist.
@@ -248,17 +249,17 @@ export class BinaryTree<
 
     if (this.isNode(keyOrNodeOrEntryOrRawElement)) return keyOrNodeOrEntryOrRawElement;
 
-    if (this.toEntryFn) {
-      const [key, entryValue] = this.toEntryFn(keyOrNodeOrEntryOrRawElement as R);
-      if (key) return this.createNode(key, entryValue ?? value);
-      else return;
-    }
-
     if (this.isEntry(keyOrNodeOrEntryOrRawElement)) {
-      const [key, value] = keyOrNodeOrEntryOrRawElement;
+      const [key, entryValue] = keyOrNodeOrEntryOrRawElement;
       if (key === undefined) return;
       else if (key === null) return null;
-      else return this.createNode(key, value);
+      if (this.isKey(key)) return this.createNode(key, value ?? entryValue);
+    }
+
+    if (this.toEntryFn) {
+      const [key, entryValue] = this.toEntryFn(keyOrNodeOrEntryOrRawElement as R);
+      if (this.isKey(key)) return this.createNode(key, value ?? entryValue);
+      else return;
     }
 
     if (this.isKey(keyOrNodeOrEntryOrRawElement)) return this.createNode(keyOrNodeOrEntryOrRawElement, value);
@@ -266,11 +267,6 @@ export class BinaryTree<
     return;
   }
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(log n)
-   */
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(log n)
@@ -287,7 +283,7 @@ export class BinaryTree<
    */
   ensureNode(
     keyOrNodeOrEntryOrRawElement: R | BTNKeyOrNodeOrEntry<K, V, NODE>,
-    iterationType: IterationType = 'ITERATIVE'
+    iterationType: IterationType = this.iterationType
   ): OptBTNOrNull<NODE> {
     if (keyOrNodeOrEntryOrRawElement === null) return null;
     if (keyOrNodeOrEntryOrRawElement === undefined) return;
@@ -296,7 +292,7 @@ export class BinaryTree<
 
     if (this.toEntryFn) {
       const [key] = this.toEntryFn(keyOrNodeOrEntryOrRawElement as R);
-      if (key) return this.getNodeByKey(key);
+      if (this.isKey(key)) return this.getNodeByKey(key);
     }
 
     if (this.isEntry(keyOrNodeOrEntryOrRawElement)) {
@@ -338,7 +334,7 @@ export class BinaryTree<
    * `BTNKeyOrNodeOrEntry<K, V, NODE>`.
    * @returns a boolean value.
    */
-  isNodeOrNull(node: R | BTNKeyOrNodeOrEntry<K, V, NODE>): node is NODE | null {
+  isRealNodeOrNull(node: R | BTNKeyOrNodeOrEntry<K, V, NODE>): node is NODE | null {
     return this.isRealNode(node) || node === null;
   }
 
@@ -348,10 +344,26 @@ export class BinaryTree<
    * `BTNKeyOrNodeOrEntry<K, V, NODE>`.
    * @returns a boolean value.
    */
-  isNIL(node: R | BTNKeyOrNodeOrEntry<K, V, NODE>) {
+  isNIL(node: R | BTNKeyOrNodeOrEntry<K, V, NODE>): boolean {
     return node === this.NIL;
   }
 
+  /**
+   * The function `isLeaf` determines whether a given node is a leaf node in a binary tree structure.
+   * @param {R | BTNKeyOrNodeOrEntry<K, V, NODE>} node - The `node` parameter in the `isLeaf` function
+   * can be either a regular node (`R`) or a `BTNKeyOrNodeOrEntry<K, V, NODE>`.
+   * @returns The `isLeaf` function is checking if the provided node is a leaf node in a binary tree.
+   * If the node is `undefined`, it returns `false`. If the node is `null`, it returns `true`.
+   * Otherwise, it checks if both the left and right children of the node are not real nodes, and
+   * returns `true` if they are not, indicating that the node is a
+   */
+  isLeaf(node: R | BTNKeyOrNodeOrEntry<K, V, NODE>): boolean {
+    node = this.ensureNode(node);
+    if (node === undefined) return false;
+    if (node === null) return true;
+    return !this.isRealNode(node.left) && !this.isRealNode(node.right);
+  }
+
   /**
    * The function checks if the input is an array with two elements, indicating it is a binary tree
    * node entry.
@@ -366,38 +378,21 @@ export class BinaryTree<
   }
 
   /**
-   * The function checks if a given value is a valid key by evaluating its type and value.
-   * @param {any} key - The `key` parameter can be of any type. It is the value that we want to check
-   * if it is a valid key.
-   * @param [isCheckValueOf=true] - The `isCheckValueOf` parameter is a boolean flag that determines
-   * whether the function should check the valueOf() method of an object when the key is of type
-   * 'object'. If `isCheckValueOf` is true, the function will recursively call itself with the value
-   * returned by key.valueOf().
-   * @returns a boolean value.
-   */
-  isKey(key: any, isCheckValueOf = true): key is K {
+   * Time Complexity O(1)
+   * Space Complexity O(1)
+   *
+   * The function `isKey` checks if a given key is comparable.
+   * @param {any} key - The `key` parameter is of type `any`, which means it can be any data type in
+   * TypeScript.
+   * @returns The function `isKey` is checking if the `key` parameter is `null` or if it is comparable.
+   * If the `key` is `null`, the function returns `true`. Otherwise, it returns the result of the
+   * `isComparable` function, which is not provided in the code snippet.
+   */
+  isKey(key: any): key is K {
     if (key === null) return true;
-    const keyType = typeof key;
-    if (keyType === 'string' || keyType === 'bigint' || keyType === 'boolean') return true;
-    if (keyType === 'number') return !isNaN(key);
-    if (keyType === 'symbol' || keyType === 'undefined') return false;
-    if (keyType === 'function') return this.isKey(key());
-    if (keyType === 'object') {
-      if (typeof key.toString === 'function') return true;
-      if (isCheckValueOf && typeof key.valueOf === 'function') {
-        this.isKey(key.valueOf(), false);
-      }
-      return false;
-    }
-
-    return false;
+    return isComparable(key);
   }
 
-  /**
-   * Time Complexity O(n)
-   * Space Complexity O(1)
-   */
-
   /**
    * Time Complexity O(n)
    * Space Complexity O(1)
@@ -467,12 +462,6 @@ export class BinaryTree<
     return false; // If the insertion position cannot be found, return undefined
   }
 
-  /**
-   * Time Complexity: O(k * n)
-   * Space Complexity: O(1)
-   * Comments: The time complexity for adding a node depends on the depth of the tree. In the best case (when the tree is empty), it's O(1). In the worst case (when the tree is a degenerate tree), it's O(n). The space complexity is constant.
-   */
-
   /**
    * Time Complexity: O(k * n)
    * Space Complexity: O(1)
@@ -515,12 +504,6 @@ export class BinaryTree<
     return inserted;
   }
 
-  /**
-   * Time Complexity: O(k * n)
-   * Space Complexity: O(1)
-   * "n" is the number of nodes in the tree, and "k" is the number of keys to be inserted.
-   */
-
   /**
    * Time Complexity: O(k * n)
    * Space Complexity: O(1)
@@ -549,11 +532,6 @@ export class BinaryTree<
 
   delete<C extends BTNCallback<NODE>>(identifier: ReturnType<C>, callback: C): BinaryTreeDeleteResult<NODE>[];
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(1)
-   */
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(1)
@@ -587,7 +565,7 @@ export class BinaryTree<
     if (!curr.left && !curr.right && !parent) {
       this._setRoot(undefined);
     } else if (curr.left) {
-      const leftSubTreeRightMost = this.getRightMost(curr.left);
+      const leftSubTreeRightMost = this.getRightMost(node => node, curr.left);
       if (leftSubTreeRightMost) {
         const parentOfLeftSubTreeMax = leftSubTreeRightMost.parent;
         orgCurrent = this._swapProperties(curr, leftSubTreeRightMost);
@@ -641,11 +619,6 @@ export class BinaryTree<
     iterationType?: IterationType
   ): NODE[];
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(k + log n)
-   */
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(k + log n)
@@ -677,6 +650,8 @@ export class BinaryTree<
     beginRoot: R | BTNKeyOrNodeOrEntry<K, V, NODE> = this.root,
     iterationType: IterationType = this.iterationType
   ): NODE[] {
+    if (identifier === undefined) return [];
+    if (identifier === null) return [];
     beginRoot = this.ensureNode(beginRoot);
     if (!beginRoot) return [];
     callback = this._ensureCallback(identifier, callback);
@@ -734,11 +709,6 @@ export class BinaryTree<
     iterationType?: IterationType
   ): OptBTNOrNull<NODE>;
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(log n).
-   */
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(log n).
@@ -766,11 +736,6 @@ export class BinaryTree<
     return this.getNodes(identifier, callback, true, beginRoot, iterationType)[0] ?? null;
   }
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(log n)
-   */
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(log n)
@@ -783,7 +748,7 @@ export class BinaryTree<
    * It has a default value of `'ITERATIVE'`.
    * @returns a value of type NODE, null, or undefined.
    */
-  getNodeByKey(key: K, iterationType: IterationType = 'ITERATIVE'): OptBTNOrNull<NODE> {
+  getNodeByKey(key: K, iterationType: IterationType = this.iterationType): OptBTNOrNull<NODE> {
     return this.getNode(key, this._DEFAULT_CALLBACK, this.root, iterationType);
   }
 
@@ -808,11 +773,6 @@ export class BinaryTree<
     iterationType?: IterationType
   ): V | undefined;
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(log n)
-   */
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(log n)
@@ -864,11 +824,6 @@ export class BinaryTree<
     iterationType?: IterationType
   ): boolean;
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(log n)
-   */
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(log n)
@@ -900,11 +855,6 @@ export class BinaryTree<
     return this.getNodes(identifier, callback, true, beginRoot, iterationType).length > 0;
   }
 
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   */
-
   /**
    * Time Complexity: O(1)
    * Space Complexity: O(1)
@@ -916,11 +866,6 @@ export class BinaryTree<
     this._size = 0;
   }
 
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   */
-
   /**
    * Time Complexity: O(1)
    * Space Complexity: O(1)
@@ -932,11 +877,6 @@ export class BinaryTree<
     return this.size === 0;
   }
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(log n)
-   */
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(log n)
@@ -953,11 +893,6 @@ export class BinaryTree<
     return this.getMinHeight(beginRoot) + 1 >= this.getHeight(beginRoot);
   }
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(1)
-   */
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(1)
@@ -1016,11 +951,6 @@ export class BinaryTree<
     }
   }
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(1)
-   */
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(1)
@@ -1052,11 +982,6 @@ export class BinaryTree<
     return depth;
   }
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(1)
-   */
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(1)
@@ -1103,11 +1028,6 @@ export class BinaryTree<
     }
   }
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(log n)
-   */
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(log n)
@@ -1170,11 +1090,6 @@ export class BinaryTree<
     }
   }
 
-  /**
-   * Time Complexity: O(log n)
-   * Space Complexity: O(log n)
-   */
-
   /**
    * Time Complexity: O(log n)
    * Space Complexity: O(log n)
@@ -1203,32 +1118,36 @@ export class BinaryTree<
     return isReverse ? result.reverse() : result;
   }
 
-  /**
-   * Time Complexity: O(log n)
-   * Space Complexity: O(1)
-   */
-
   /**
    * Time Complexity: O(log n)
    * Space Complexity: O(1)
    *
-   * The `getLeftMost` function returns the leftmost node in a binary tree, either using recursive or
-   * iterative traversal.
-   * @param {R | BTNKeyOrNodeOrEntry<K, V, NODE>} beginRoot - The `beginRoot` parameter represents the
-   * starting point for finding the leftmost node in a binary tree. It can be either a root node (`R`),
-   * a key or node or entry (`BTNKeyOrNodeOrEntry<K, V, NODE>`), or `null` or `undefined`.
-   * @param {IterationType} iterationType - The `iterationType` parameter is used to specify the type
-   * of iteration to be performed. It can have two possible values:
-   * @returns The function `getLeftMost` returns the leftmost node in a binary tree.
+   * The function `getLeftMost` retrieves the leftmost node in a binary tree using either recursive or
+   * tail-recursive iteration.
+   * @param {C} callback - The `callback` parameter is a function that will be called with the leftmost
+   * node of a binary tree or null if the tree is empty. It has a default value of `_DEFAULT_CALLBACK`
+   * if not provided explicitly.
+   * @param {R | BTNKeyOrNodeOrEntry<K, V, NODE>} beginRoot - The `beginRoot` parameter in the
+   * `getLeftMost` function represents the starting point for finding the leftmost node in a binary
+   * tree. It can be either a reference to the root node of the tree (`R`), or a key, node, or entry in
+   * the binary tree structure (`
+   * @param {IterationType} iterationType - The `iterationType` parameter in the `getLeftMost` function
+   * specifies the type of iteration to be used when traversing the binary tree nodes. It can have two
+   * possible values:
+   * @returns The `getLeftMost` function returns the result of the callback function `C` applied to the
+   * leftmost node in the binary tree starting from the `beginRoot` node. If the `beginRoot` is `NIL`,
+   * it returns the result of the callback function applied to `undefined`. If the `beginRoot` is not a
+   * real node, it returns the result of the callback function applied
    */
-  getLeftMost(
+  getLeftMost<C extends BTNCallback<OptBTNOrNull<NODE>>>(
+    callback: C = this._DEFAULT_CALLBACK as C,
     beginRoot: R | BTNKeyOrNodeOrEntry<K, V, NODE> = this.root,
     iterationType: IterationType = this.iterationType
-  ): OptBTNOrNull<NODE> {
-    if (this.isNIL(beginRoot)) return beginRoot as NODE;
+  ): ReturnType<C> {
+    if (this.isNIL(beginRoot)) return callback(undefined);
     beginRoot = this.ensureNode(beginRoot);
 
-    if (!this.isRealNode(beginRoot)) return beginRoot;
+    if (!this.isRealNode(beginRoot)) return callback(beginRoot);
 
     if (iterationType === 'RECURSIVE') {
       const dfs = (cur: NODE): NODE => {
@@ -1236,45 +1155,49 @@ export class BinaryTree<
         return dfs(cur.left);
       };
 
-      return dfs(beginRoot);
+      return callback(dfs(beginRoot));
     } else {
       // Indirect implementation of iteration using tail recursion optimization
-      const dfs = trampoline((cur: NODE) => {
+      const dfs = trampoline((cur: NODE): NODE => {
         if (!this.isRealNode(cur.left)) return cur;
         return dfs.cont(cur.left);
       });
 
-      return dfs(beginRoot);
+      return callback(dfs(beginRoot));
     }
   }
 
-  /**
-   * Time Complexity: O(log n)
-   * Space Complexity: O(1)
-   */
-
   /**
    * Time Complexity: O(log n)
    * Space Complexity: O(1)
    *
-   * The `getRightMost` function returns the rightmost node in a binary tree, either recursively or
-   * iteratively.
-   * @param {R | BTNKeyOrNodeOrEntry<K, V, NODE>} beginRoot - The `beginRoot` parameter represents the
-   * starting point for finding the rightmost node in a binary tree. It can be either a root node
-   * (`R`), a key or node or entry (`BTNKeyOrNodeOrEntry<K, V, NODE>`), or `null` or `undefined`.
-   * @param {IterationType} iterationType - The `iterationType` parameter is used to specify the type
-   * of iteration to be performed when finding the rightmost node in a binary tree. It can have two
-   * possible values:
-   * @returns The function `getRightMost` returns a NODE object, `null`, or `undefined`.
-   */
-  getRightMost(
+   * The function `getRightMost` retrieves the rightmost node in a binary tree using either recursive
+   * or iterative traversal methods.
+   * @param {C} callback - The `callback` parameter is a function that will be called with the result
+   * of the operation. It has a generic type `C` which extends `BTNCallback<OptBTNOrNull<NODE>>`. The
+   * default value for `callback` is `this._DEFAULT_CALLBACK` if it is not provided.
+   * @param {R | BTNKeyOrNodeOrEntry<K, V, NODE>} beginRoot - The `beginRoot` parameter in the
+   * `getRightMost` function represents the starting point for finding the rightmost node in a binary
+   * tree. It can be either a reference to the root node of the tree (`this.root`) or a specific key,
+   * node, or entry in the tree. If
+   * @param {IterationType} iterationType - The `iterationType` parameter in the `getRightMost`
+   * function specifies the type of iteration to be used when finding the rightmost node in a binary
+   * tree. It can have two possible values:
+   * @returns The `getRightMost` function returns the result of the callback function `C` applied to
+   * the rightmost node in the binary tree. The rightmost node is found either through a recursive
+   * depth-first search (if `iterationType` is 'RECURSIVE') or through an indirect implementation of
+   * iteration using tail recursion optimization. The result of the callback function applied to the
+   * rightmost node is returned
+   */
+  getRightMost<C extends BTNCallback<OptBTNOrNull<NODE>>>(
+    callback: C = this._DEFAULT_CALLBACK as C,
     beginRoot: R | BTNKeyOrNodeOrEntry<K, V, NODE> = this.root,
     iterationType: IterationType = this.iterationType
-  ): OptBTNOrNull<NODE> {
-    if (this.isNIL(beginRoot)) return beginRoot as NODE;
+  ): ReturnType<C> {
+    if (this.isNIL(beginRoot)) return callback(undefined);
     // TODO support get right most by passing key in
     beginRoot = this.ensureNode(beginRoot);
-    if (!beginRoot) return beginRoot;
+    if (!beginRoot) return callback(beginRoot);
 
     if (iterationType === 'RECURSIVE') {
       const dfs = (cur: NODE): NODE => {
@@ -1282,7 +1205,7 @@ export class BinaryTree<
         return dfs(cur.right);
       };
 
-      return dfs(beginRoot);
+      return callback(dfs(beginRoot));
     } else {
       // Indirect implementation of iteration using tail recursion optimization
       const dfs = trampoline((cur: NODE) => {
@@ -1290,15 +1213,10 @@ export class BinaryTree<
         return dfs.cont(cur.right);
       });
 
-      return dfs(beginRoot);
+      return callback(dfs(beginRoot));
     }
   }
 
-  /**
-   * Time Complexity: O(log n)
-   * Space Complexity: O(1)
-   */
-
   /**
    * Time Complexity: O(log n)
    * Space Complexity: O(1)
@@ -1322,11 +1240,6 @@ export class BinaryTree<
     }
   }
 
-  /**
-   * Time Complexity: O(log n)
-   * Space Complexity: O(1)
-   */
-
   /**
    * Time Complexity: O(log n)
    * Space Complexity: O(1)
@@ -1341,7 +1254,7 @@ export class BinaryTree<
     if (!this.isRealNode(x)) return undefined;
 
     if (this.isRealNode(x.right)) {
-      return this.getLeftMost(x.right);
+      return this.getLeftMost(node => node, x.right);
     }
 
     let y: OptBTNOrNull<NODE> = x.parent;
@@ -1356,8 +1269,7 @@ export class BinaryTree<
     callback?: C,
     pattern?: DFSOrderPattern,
     beginRoot?: R | BTNKeyOrNodeOrEntry<K, V, NODE>,
-    iterationType?: IterationType,
-    includeNull?: false
+    iterationType?: IterationType
   ): ReturnType<C>[];
 
   dfs<C extends BTNCallback<NODE | null>>(
@@ -1365,14 +1277,9 @@ export class BinaryTree<
     pattern?: DFSOrderPattern,
     beginRoot?: R | BTNKeyOrNodeOrEntry<K, V, NODE>,
     iterationType?: IterationType,
-    includeNull?: true
+    includeNull?: boolean
   ): ReturnType<C>[];
 
-  /**
-   * Time complexity: O(n)
-   * Space complexity: O(n)
-   */
-
   /**
    * Time complexity: O(n)
    * Space complexity: O(n)
@@ -1400,95 +1307,12 @@ export class BinaryTree<
     callback: C = this._DEFAULT_CALLBACK as C,
     pattern: DFSOrderPattern = 'IN',
     beginRoot: R | BTNKeyOrNodeOrEntry<K, V, NODE> = this.root,
-    iterationType: IterationType = 'ITERATIVE',
+    iterationType: IterationType = this.iterationType,
     includeNull = false
   ): ReturnType<C>[] {
     beginRoot = this.ensureNode(beginRoot);
     if (!beginRoot) return [];
-    const ans: ReturnType<C>[] = [];
-    if (iterationType === 'RECURSIVE') {
-      const dfs = (node: OptBTNOrNull<NODE>) => {
-        switch (pattern) {
-          case 'IN':
-            if (includeNull) {
-              if (this.isRealNode(node) && this.isNodeOrNull(node.left)) dfs(node.left);
-              this.isNodeOrNull(node) && ans.push(callback(node));
-              if (this.isRealNode(node) && this.isNodeOrNull(node.right)) dfs(node.right);
-            } else {
-              if (this.isRealNode(node) && this.isRealNode(node.left)) dfs(node.left);
-              this.isRealNode(node) && ans.push(callback(node));
-              if (this.isRealNode(node) && this.isRealNode(node.right)) dfs(node.right);
-            }
-            break;
-          case 'PRE':
-            if (includeNull) {
-              this.isNodeOrNull(node) && ans.push(callback(node));
-              if (this.isRealNode(node) && this.isNodeOrNull(node.left)) dfs(node.left);
-              if (this.isRealNode(node) && this.isNodeOrNull(node.right)) dfs(node.right);
-            } else {
-              this.isRealNode(node) && ans.push(callback(node));
-              if (this.isRealNode(node) && this.isRealNode(node.left)) dfs(node.left);
-              if (this.isRealNode(node) && this.isRealNode(node.right)) dfs(node.right);
-            }
-            break;
-          case 'POST':
-            if (includeNull) {
-              if (this.isRealNode(node) && this.isNodeOrNull(node.left)) dfs(node.left);
-              if (this.isRealNode(node) && this.isNodeOrNull(node.right)) dfs(node.right);
-              this.isNodeOrNull(node) && ans.push(callback(node));
-            } else {
-              if (this.isRealNode(node) && this.isRealNode(node.left)) dfs(node.left);
-              if (this.isRealNode(node) && this.isRealNode(node.right)) dfs(node.right);
-              this.isRealNode(node) && ans.push(callback(node));
-            }
-
-            break;
-        }
-      };
-
-      dfs(beginRoot);
-    } else {
-      // 0: visit, 1: print
-      const stack: { opt: 0 | 1; node: OptBTNOrNull<NODE> }[] = [{ opt: 0, node: beginRoot }];
-
-      while (stack.length > 0) {
-        const cur = stack.pop();
-        if (cur === undefined || this.isNIL(cur.node)) continue;
-        if (includeNull) {
-          if (cur.node === undefined) continue;
-        } else {
-          if (cur.node === null || cur.node === undefined) continue;
-        }
-        if (cur.opt === 1) {
-          ans.push(callback(cur.node));
-        } else {
-          switch (pattern) {
-            case 'IN':
-              cur.node && stack.push({ opt: 0, node: cur.node.right });
-              stack.push({ opt: 1, node: cur.node });
-              cur.node && stack.push({ opt: 0, node: cur.node.left });
-              break;
-            case 'PRE':
-              cur.node && stack.push({ opt: 0, node: cur.node.right });
-              cur.node && stack.push({ opt: 0, node: cur.node.left });
-              stack.push({ opt: 1, node: cur.node });
-              break;
-            case 'POST':
-              stack.push({ opt: 1, node: cur.node });
-              cur.node && stack.push({ opt: 0, node: cur.node.right });
-              cur.node && stack.push({ opt: 0, node: cur.node.left });
-              break;
-            default:
-              cur.node && stack.push({ opt: 0, node: cur.node.right });
-              stack.push({ opt: 1, node: cur.node });
-              cur.node && stack.push({ opt: 0, node: cur.node.left });
-              break;
-          }
-        }
-      }
-    }
-
-    return ans;
+    return this._dfs(callback, pattern, beginRoot, iterationType, includeNull);
   }
 
   bfs<C extends BTNCallback<NODE>>(
@@ -1505,11 +1329,6 @@ export class BinaryTree<
     includeNull?: true
   ): ReturnType<C>[];
 
-  /**
-   * Time complexity: O(n)
-   * Space complexity: O(n)
-   */
-
   /**
    * Time complexity: O(n)
    * Space complexity: O(n)
@@ -1553,8 +1372,8 @@ export class BinaryTree<
         ans.push(callback(current));
 
         if (includeNull) {
-          if (current && this.isNodeOrNull(current.left)) queue.push(current.left);
-          if (current && this.isNodeOrNull(current.right)) queue.push(current.right);
+          if (current && this.isRealNodeOrNull(current.left)) queue.push(current.left);
+          if (current && this.isRealNodeOrNull(current.right)) queue.push(current.right);
         } else {
           if (this.isRealNode(current.left)) queue.push(current.left);
           if (this.isRealNode(current.right)) queue.push(current.right);
@@ -1574,8 +1393,8 @@ export class BinaryTree<
           ans.push(callback(current));
 
           if (includeNull) {
-            if (current && this.isNodeOrNull(current.left)) queue.push(current.left);
-            if (current && this.isNodeOrNull(current.right)) queue.push(current.right);
+            if (current && this.isRealNodeOrNull(current.left)) queue.push(current.left);
+            if (current && this.isRealNodeOrNull(current.right)) queue.push(current.right);
           } else {
             if (this.isRealNode(current.left)) queue.push(current.left);
             if (this.isRealNode(current.right)) queue.push(current.right);
@@ -1586,6 +1405,63 @@ export class BinaryTree<
     return ans;
   }
 
+  /**
+   * Time complexity: O(n)
+   * Space complexity: O(n)
+   *
+   * The `leaves` function in TypeScript iterates through a binary tree to find and return the leaf
+   * nodes based on a specified callback and iteration type.
+   * @param {C} callback - The `callback` parameter is a function that will be called on each leaf node
+   * in the binary tree. It is a generic type `C` that extends `BTNCallback<NODE | null>`, where `NODE`
+   * represents a node in the binary tree. The default value for `callback` is
+   * @param {R | BTNKeyOrNodeOrEntry<K, V, NODE>} beginRoot - The `beginRoot` parameter in the `leaves`
+   * method is used to specify the starting point for finding and processing the leaves of a binary
+   * tree. It represents the root node of the binary tree or a specific key, node, or entry within the
+   * tree from which the search for leaves should begin
+   * @param {IterationType} iterationType - The `iterationType` parameter in the `leaves` method
+   * specifies the type of iteration to be performed when collecting the leaves of a binary tree. It
+   * can have two possible values:
+   * @returns The `leaves` method returns an array of values that are the result of applying the
+   * provided callback function to the leaf nodes in the binary tree structure.
+   */
+  leaves<C extends BTNCallback<NODE | null>>(
+    callback: C = this._DEFAULT_CALLBACK as C,
+    beginRoot: R | BTNKeyOrNodeOrEntry<K, V, NODE> = this.root,
+    iterationType: IterationType = this.iterationType
+  ): ReturnType<C>[] {
+    beginRoot = this.ensureNode(beginRoot);
+    const leaves: ReturnType<BTNCallback<NODE>>[] = [];
+    if (!this.isRealNode(beginRoot)) {
+      return [];
+    }
+    if (iterationType === 'RECURSIVE') {
+      const dfs = (cur: NODE) => {
+        if (this.isLeaf(cur)) {
+          leaves.push(callback(cur));
+        }
+        if (!this.isRealNode(cur.left) && !this.isRealNode(cur.right)) return;
+        this.isRealNode(cur.left) && dfs(cur.left);
+        this.isRealNode(cur.right) && dfs(cur.right);
+      };
+
+      dfs(beginRoot);
+    } else {
+      const queue = new Queue([beginRoot]);
+      while (queue.size > 0) {
+        const cur = queue.shift();
+        if (this.isRealNode(cur)) {
+          if (this.isLeaf(cur)) {
+            leaves.push(callback(cur));
+          }
+          this.isRealNode(cur.left) && queue.push(cur.left);
+          this.isRealNode(cur.right) && queue.push(cur.right);
+        }
+      }
+    }
+
+    return leaves;
+  }
+
   listLevels<C extends BTNCallback<NODE>>(
     callback?: C,
     beginRoot?: R | BTNKeyOrNodeOrEntry<K, V, NODE>,
@@ -1600,11 +1476,6 @@ export class BinaryTree<
     includeNull?: true
   ): ReturnType<C>[][];
 
-  /**
-   * Time complexity: O(n)
-   * Space complexity: O(n)
-   */
-
   /**
    * Time complexity: O(n)
    * Space complexity: O(n)
@@ -1641,8 +1512,8 @@ export class BinaryTree<
         if (!levelsNodes[level]) levelsNodes[level] = [];
         levelsNodes[level].push(callback(node));
         if (includeNull) {
-          if (node && this.isNodeOrNull(node.left)) _recursive(node.left, level + 1);
-          if (node && this.isNodeOrNull(node.right)) _recursive(node.right, level + 1);
+          if (node && this.isRealNodeOrNull(node.left)) _recursive(node.left, level + 1);
+          if (node && this.isRealNodeOrNull(node.right)) _recursive(node.right, level + 1);
         } else {
           if (node && node.left) _recursive(node.left, level + 1);
           if (node && node.right) _recursive(node.right, level + 1);
@@ -1661,8 +1532,8 @@ export class BinaryTree<
         levelsNodes[level].push(callback(node));
 
         if (includeNull) {
-          if (node && this.isNodeOrNull(node.right)) stack.push([node.right, level + 1]);
-          if (node && this.isNodeOrNull(node.left)) stack.push([node.left, level + 1]);
+          if (node && this.isRealNodeOrNull(node.right)) stack.push([node.right, level + 1]);
+          if (node && this.isRealNodeOrNull(node.left)) stack.push([node.left, level + 1]);
         } else {
           if (node && node.right) stack.push([node.right, level + 1]);
           if (node && node.left) stack.push([node.left, level + 1]);
@@ -1673,11 +1544,6 @@ export class BinaryTree<
     return levelsNodes;
   }
 
-  /**
-   * Time complexity: O(n)
-   * Space complexity: O(n)
-   */
-
   /**
    * Time complexity: O(n)
    * Space complexity: O(n)
@@ -1783,11 +1649,6 @@ export class BinaryTree<
     return ans;
   }
 
-  /**
-   * Time complexity: O(n)
-   * Space complexity: O(n)
-   */
-
   /**
    * Time complexity: O(n)
    * Space complexity: O(n)
@@ -1809,11 +1670,6 @@ export class BinaryTree<
     return cloned;
   }
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(n)
-   */
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(n)
@@ -1840,11 +1696,6 @@ export class BinaryTree<
     return newTree;
   }
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(n)
-   */
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(n)
@@ -1879,11 +1730,6 @@ export class BinaryTree<
   // // }
   //
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(n)
-   */
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(n)
@@ -1898,35 +1744,185 @@ export class BinaryTree<
    * @returns Nothing is being returned. The function has a return type of `void`, which means it does
    * not return any value.
    */
-  override print(beginRoot: R | BTNKeyOrNodeOrEntry<K, V, NODE> = this.root, options?: BinaryTreePrintOptions): void {
+  override print(beginRoot: R | BTNKeyOrNodeOrEntry<K, V, NODE> = this.root, options?: BinaryTreePrintOptions): string {
     const opts = { isShowUndefined: false, isShowNull: false, isShowRedBlackNIL: false, ...options };
     beginRoot = this.ensureNode(beginRoot);
-    if (!beginRoot) return;
+    let output = '';
+    if (!beginRoot) return output;
 
     if (opts.isShowUndefined)
-      console.log(`U for undefined
-      `);
+      output += `U for undefined
+      `;
     if (opts.isShowNull)
-      console.log(`N for null
-      `);
+      output += `N for null
+      `;
     if (opts.isShowRedBlackNIL)
-      console.log(`S for Sentinel Node(NIL)
-      `);
+      output += `S for Sentinel Node(NIL)
+      `;
 
     const display = (root: OptBTNOrNull<NODE>): void => {
       const [lines, , ,] = this._displayAux(root, opts);
+      let paragraph = '';
       for (const line of lines) {
-        console.log(line);
+        paragraph += line + '\n';
       }
+      output += paragraph;
     };
 
     display(beginRoot);
+    return output;
   }
 
+  protected _dfs<C extends BTNCallback<NODE>>(
+    callback?: C,
+    pattern?: DFSOrderPattern,
+    beginRoot?: R | BTNKeyOrNodeOrEntry<K, V, NODE>,
+    iterationType?: IterationType
+  ): ReturnType<C>[];
+
+  protected _dfs<C extends BTNCallback<NODE | null>>(
+    callback?: C,
+    pattern?: DFSOrderPattern,
+    beginRoot?: R | BTNKeyOrNodeOrEntry<K, V, NODE>,
+    iterationType?: IterationType,
+    includeNull?: boolean
+  ): ReturnType<C>[];
+
   /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   */
+   * Time complexity: O(n)
+   * Space complexity: O(n)
+   *
+   * The function `_dfs` performs a depth-first search traversal on a binary tree structure based on
+   * the specified order pattern and callback function.
+   * @param {C} callback - The `callback` parameter is a function that will be called on each node
+   * visited during the depth-first search. It is of type `C`, which extends
+   * `BTNCallback<OptBTNOrNull<NODE>>`. The default value is set to `this._DEFAULT_CALLBACK` if not
+   * provided.
+   * @param {DFSOrderPattern} [pattern=IN] - The `pattern` parameter in the `_dfs` method specifies the
+   * order in which the Depth-First Search (DFS) algorithm should traverse the nodes in a binary tree.
+   * It can have one of the following values:
+   * @param {R | BTNKeyOrNodeOrEntry<K, V, NODE>} beginRoot - The `beginRoot` parameter in the `_dfs`
+   * method is used to specify the starting point for the depth-first search traversal in a binary
+   * tree. It can be provided as either the root node of the tree or a key, node, or entry that exists
+   * in the tree. If no specific `
+   * @param {IterationType} iterationType - The `iterationType` parameter in the `_dfs` method
+   * specifies the type of iteration to be performed during the Depth-First Search (DFS) traversal. It
+   * can have two possible values:
+   * @param [includeNull=false] - The `includeNull` parameter in the `_dfs` method is a boolean flag
+   * that determines whether null nodes should be included in the depth-first search traversal. If
+   * `includeNull` is set to `true`, the traversal will consider null nodes as valid nodes to visit and
+   * process. If set to `
+   * @param shouldVisitLeft - The `shouldVisitLeft` parameter is a function that takes a node as input
+   * and returns a boolean value. It is used to determine whether the left child of a node should be
+   * visited during the depth-first search traversal. By default, it checks if the node is truthy (not
+   * null or undefined
+   * @param shouldVisitRight - The `shouldVisitRight` parameter is a function that takes a node as
+   * input and returns a boolean value. It is used to determine whether the right child of a node
+   * should be visited during the depth-first search traversal. The default implementation checks if
+   * the node is truthy before visiting the right child.
+   * @param shouldVisitRoot - The `shouldVisitRoot` parameter is a function that takes a node as an
+   * argument and returns a boolean value. It is used to determine whether a given node should be
+   * visited during the depth-first search traversal based on certain conditions. The default
+   * implementation checks if the node is a real node or null based
+   * @param shouldProcessRoot - The `shouldProcessRoot` parameter is a function that takes a node as
+   * input and returns a boolean value indicating whether the node should be processed during the
+   * depth-first search traversal. The default implementation of this function simply returns `true`,
+   * meaning that by default all nodes will be processed. However, you can
+   * @returns The `_dfs` method returns an array of the return type of the callback function provided
+   * as input.
+   */
+  protected _dfs<C extends BTNCallback<OptBTNOrNull<NODE>>>(
+    callback: C = this._DEFAULT_CALLBACK as C,
+    pattern: DFSOrderPattern = 'IN',
+    beginRoot: R | BTNKeyOrNodeOrEntry<K, V, NODE> = this.root,
+    iterationType: IterationType = this.iterationType,
+    includeNull = false,
+    shouldVisitLeft: (node: OptBTNOrNull<NODE>) => boolean = node => !!node,
+    shouldVisitRight: (node: OptBTNOrNull<NODE>) => boolean = node => !!node,
+    shouldVisitRoot: (node: OptBTNOrNull<NODE>) => boolean = node => {
+      if (includeNull) return this.isRealNodeOrNull(node);
+      return this.isRealNode(node);
+    },
+    shouldProcessRoot: (node: OptBTNOrNull<NODE>) => boolean = node => true
+  ): ReturnType<C>[] {
+    beginRoot = this.ensureNode(beginRoot);
+    if (!beginRoot) return [];
+    const ans: ReturnType<C>[] = [];
+
+    if (iterationType === 'RECURSIVE') {
+      const dfs = (node: OptBTNOrNull<NODE>) => {
+        if (!shouldVisitRoot(node)) return;
+
+        const visitLeft = () => {
+          if (shouldVisitLeft(node)) dfs(node?.left);
+        };
+        const visitRight = () => {
+          if (shouldVisitRight(node)) dfs(node?.right);
+        };
+
+        switch (pattern) {
+          case 'IN':
+            visitLeft();
+            if (shouldProcessRoot(node)) ans.push(callback(node));
+            visitRight();
+            break;
+          case 'PRE':
+            if (shouldProcessRoot(node)) ans.push(callback(node));
+            visitLeft();
+            visitRight();
+            break;
+          case 'POST':
+            visitLeft();
+            visitRight();
+            if (shouldProcessRoot(node)) ans.push(callback(node));
+            break;
+        }
+      };
+
+      dfs(beginRoot);
+    } else {
+      const stack: DFSStackItem<NODE>[] = [{ opt: DFSOperation.VISIT, node: beginRoot }];
+
+      const pushLeft = (cur: DFSStackItem<NODE>) => {
+        if (shouldVisitLeft(cur.node)) stack.push({ opt: DFSOperation.VISIT, node: cur.node?.left });
+      };
+      const pushRight = (cur: DFSStackItem<NODE>) => {
+        if (shouldVisitRight(cur.node)) stack.push({ opt: DFSOperation.VISIT, node: cur.node?.right });
+      };
+      const pushRoot = (cur: DFSStackItem<NODE>) => {
+        if (shouldVisitRoot(cur.node)) stack.push({ opt: DFSOperation.PROCESS, node: cur.node });
+      };
+
+      while (stack.length > 0) {
+        const cur = stack.pop();
+        if (cur === undefined) continue;
+        if (!shouldVisitRoot(cur.node)) continue;
+        if (cur.opt === DFSOperation.PROCESS) {
+          if (shouldProcessRoot(cur.node)) ans.push(callback(cur.node));
+        } else {
+          switch (pattern) {
+            case 'IN':
+              pushRight(cur);
+              pushRoot(cur);
+              pushLeft(cur);
+              break;
+            case 'PRE':
+              pushRight(cur);
+              pushLeft(cur);
+              pushRoot(cur);
+              break;
+            case 'POST':
+              pushRoot(cur);
+              pushRight(cur);
+              pushLeft(cur);
+              break;
+          }
+        }
+      }
+    }
+
+    return ans;
+  }
 
   /**
    * Time Complexity: O(1)
@@ -1969,11 +1965,6 @@ export class BinaryTree<
     }
   }
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(n)
-   */
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(n)
@@ -2061,11 +2052,6 @@ export class BinaryTree<
 
   protected _DEFAULT_CALLBACK = (node: OptBTNOrNull<NODE>) => (node ? node.key : undefined);
 
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   */
-
   /**
    * Time Complexity: O(1)
    * Space Complexity: O(1)
@@ -2103,11 +2089,6 @@ export class BinaryTree<
     return undefined;
   }
 
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   */
-
   /**
    * Time Complexity: O(1)
    * Space Complexity: O(1)
@@ -2138,11 +2119,6 @@ export class BinaryTree<
     return newNode;
   }
 
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   */
-
   /**
    * Time Complexity: O(1)
    * Space Complexity: O(1)
@@ -2159,11 +2135,6 @@ export class BinaryTree<
     this._root = v;
   }
 
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   */
-
   /**
    * Time Complexity: O(1)
    * Space Complexity: O(1)