data-structure-typed 1.52.3 → 1.52.5

package/dist/mjs/data-structures/binary-tree/binary-tree.js

@@ -5,7 +5,8 @@
  * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import { trampoline } from '../../utils';
+import { DFSOperation } from '../../types';
+import { isComparable, trampoline } from '../../utils';
 import { Queue } from '../queue';
 import { IterableEntryBase } from '../base';
 /**
@@ -189,30 +190,26 @@ export class BinaryTree extends IterableEntryBase {
             return null;
         if (this.isNode(keyOrNodeOrEntryOrRawElement))
             return keyOrNodeOrEntryOrRawElement;
-        if (this.toEntryFn) {
-            const [key, entryValue] = this.toEntryFn(keyOrNodeOrEntryOrRawElement);
-            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;
+            if (this.isKey(key))
+                return this.createNode(key, value ?? entryValue);
+        }
+        if (this.toEntryFn) {
+            const [key, entryValue] = this.toEntryFn(keyOrNodeOrEntryOrRawElement);
+            if (this.isKey(key))
+                return this.createNode(key, value ?? entryValue);
             else
-                return this.createNode(key, value);
+                return;
         }
         if (this.isKey(keyOrNodeOrEntryOrRawElement))
             return this.createNode(keyOrNodeOrEntryOrRawElement, value);
         return;
     }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(log n)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(log n)
@@ -227,7 +224,7 @@ export class BinaryTree extends IterableEntryBase {
      * default value of `'ITERATIVE'`.
      * @returns The function `ensureNode` returns either a `NODE` object, `null`, or `undefined`.
      */
-    ensureNode(keyOrNodeOrEntryOrRawElement, iterationType = 'ITERATIVE') {
+    ensureNode(keyOrNodeOrEntryOrRawElement, iterationType = this.iterationType) {
         if (keyOrNodeOrEntryOrRawElement === null)
             return null;
         if (keyOrNodeOrEntryOrRawElement === undefined)
@@ -238,7 +235,7 @@ export class BinaryTree extends IterableEntryBase {
             return keyOrNodeOrEntryOrRawElement;
         if (this.toEntryFn) {
             const [key] = this.toEntryFn(keyOrNodeOrEntryOrRawElement);
-            if (key)
+            if (this.isKey(key))
                 return this.getNodeByKey(key);
         }
         if (this.isEntry(keyOrNodeOrEntryOrRawElement)) {
@@ -280,7 +277,7 @@ export class BinaryTree extends IterableEntryBase {
      * `BTNKeyOrNodeOrEntry<K, V, NODE>`.
      * @returns a boolean value.
      */
-    isNodeOrNull(node) {
+    isRealNodeOrNull(node) {
         return this.isRealNode(node) || node === null;
     }
     /**
@@ -292,6 +289,23 @@ export class BinaryTree extends IterableEntryBase {
     isNIL(node) {
         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) {
+        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.
@@ -303,41 +317,21 @@ export class BinaryTree extends IterableEntryBase {
         return Array.isArray(keyOrNodeOrEntryOrRawElement) && keyOrNodeOrEntryOrRawElement.length === 2;
     }
     /**
-     * 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, isCheckValueOf = true) {
+     * 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) {
         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)
@@ -400,11 +394,6 @@ export class BinaryTree extends IterableEntryBase {
         }
         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)
@@ -438,11 +427,6 @@ export class BinaryTree extends IterableEntryBase {
         }
         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)
@@ -458,10 +442,6 @@ export class BinaryTree extends IterableEntryBase {
         this.clear();
         this.addMany(keysOrNodesOrEntriesOrRawElements, values);
     }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(1)
@@ -492,7 +472,7 @@ export class BinaryTree extends IterableEntryBase {
             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);
@@ -523,10 +503,6 @@ export class BinaryTree extends IterableEntryBase {
         deletedResult.push({ deleted: orgCurrent, needBalanced });
         return deletedResult;
     }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(k + log n)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(k + log n)
@@ -552,6 +528,10 @@ export class BinaryTree extends IterableEntryBase {
      * @returns an array of NODE objects.
      */
     getNodes(identifier, callback = this._DEFAULT_CALLBACK, onlyOne = false, beginRoot = this.root, iterationType = this.iterationType) {
+        if (identifier === undefined)
+            return [];
+        if (identifier === null)
+            return [];
         beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return [];
@@ -588,10 +568,6 @@ export class BinaryTree extends IterableEntryBase {
         }
         return ans;
     }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(log n).
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(log n).
@@ -613,10 +589,6 @@ export class BinaryTree extends IterableEntryBase {
     getNode(identifier, callback = this._DEFAULT_CALLBACK, beginRoot = this.root, iterationType = this.iterationType) {
         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)
@@ -629,13 +601,9 @@ export class BinaryTree extends IterableEntryBase {
      * It has a default value of `'ITERATIVE'`.
      * @returns a value of type NODE, null, or undefined.
      */
-    getNodeByKey(key, iterationType = 'ITERATIVE') {
+    getNodeByKey(key, iterationType = this.iterationType) {
         return this.getNode(key, this._DEFAULT_CALLBACK, this.root, iterationType);
     }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(log n)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(log n)
@@ -660,10 +628,6 @@ export class BinaryTree extends IterableEntryBase {
     get(identifier, callback = this._DEFAULT_CALLBACK, beginRoot = this.root, iterationType = this.iterationType) {
         return this.getNode(identifier, callback, beginRoot, iterationType)?.value;
     }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(log n)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(log n)
@@ -688,10 +652,6 @@ export class BinaryTree extends IterableEntryBase {
         callback = this._ensureCallback(identifier, callback);
         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)
@@ -702,10 +662,6 @@ export class BinaryTree extends IterableEntryBase {
         this._setRoot(undefined);
         this._size = 0;
     }
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     */
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -716,10 +672,6 @@ export class BinaryTree extends IterableEntryBase {
     isEmpty() {
         return this.size === 0;
     }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(log n)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(log n)
@@ -735,10 +687,6 @@ export class BinaryTree extends IterableEntryBase {
     isPerfectlyBalanced(beginRoot = this.root) {
         return this.getMinHeight(beginRoot) + 1 >= this.getHeight(beginRoot);
     }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(1)
@@ -795,10 +743,6 @@ export class BinaryTree extends IterableEntryBase {
             return isStandardBST || isInverseBST;
         }
     }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(1)
@@ -826,10 +770,6 @@ export class BinaryTree extends IterableEntryBase {
         }
         return depth;
     }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(1)
@@ -871,10 +811,6 @@ export class BinaryTree extends IterableEntryBase {
             return maxHeight;
         }
     }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(log n)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(log n)
@@ -935,10 +871,6 @@ export class BinaryTree extends IterableEntryBase {
             return depths.get(beginRoot) ?? -1;
         }
     }
-    /**
-     * Time Complexity: O(log n)
-     * Space Complexity: O(log n)
-     */
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(log n)
@@ -965,36 +897,40 @@ export class BinaryTree extends IterableEntryBase {
         result.push(beginNodeEnsured);
         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(beginRoot = this.root, iterationType = this.iterationType) {
+    getLeftMost(callback = this._DEFAULT_CALLBACK, beginRoot = this.root, iterationType = this.iterationType) {
         if (this.isNIL(beginRoot))
-            return beginRoot;
+            return callback(undefined);
         beginRoot = this.ensureNode(beginRoot);
         if (!this.isRealNode(beginRoot))
-            return beginRoot;
+            return callback(beginRoot);
         if (iterationType === 'RECURSIVE') {
             const dfs = (cur) => {
                 if (!this.isRealNode(cur.left))
                     return cur;
                 return dfs(cur.left);
             };
-            return dfs(beginRoot);
+            return callback(dfs(beginRoot));
         }
         else {
             // Indirect implementation of iteration using tail recursion optimization
@@ -1003,41 +939,45 @@ export class BinaryTree extends IterableEntryBase {
                     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(beginRoot = this.root, iterationType = this.iterationType) {
+     * 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(callback = this._DEFAULT_CALLBACK, beginRoot = this.root, iterationType = this.iterationType) {
         if (this.isNIL(beginRoot))
-            return beginRoot;
+            return callback(undefined);
         // TODO support get right most by passing key in
         beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
-            return beginRoot;
+            return callback(beginRoot);
         if (iterationType === 'RECURSIVE') {
             const dfs = (cur) => {
                 if (!this.isRealNode(cur.right))
                     return cur;
                 return dfs(cur.right);
             };
-            return dfs(beginRoot);
+            return callback(dfs(beginRoot));
         }
         else {
             // Indirect implementation of iteration using tail recursion optimization
@@ -1046,13 +986,9 @@ export class BinaryTree extends IterableEntryBase {
                     return cur;
                 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)
@@ -1076,10 +1012,6 @@ export class BinaryTree extends IterableEntryBase {
             return node;
         }
     }
-    /**
-     * Time Complexity: O(log n)
-     * Space Complexity: O(1)
-     */
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
@@ -1094,7 +1026,7 @@ export class BinaryTree extends IterableEntryBase {
         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 = x.parent;
         while (this.isRealNode(y) && x === y.right) {
@@ -1103,10 +1035,6 @@ export class BinaryTree extends IterableEntryBase {
         }
         return y;
     }
-    /**
-     * Time complexity: O(n)
-     * Space complexity: O(n)
-     */
     /**
      * Time complexity: O(n)
      * Space complexity: O(n)
@@ -1130,116 +1058,12 @@ export class BinaryTree extends IterableEntryBase {
      * values will
      * @returns an array of the return types of the callback function.
      */
-    dfs(callback = this._DEFAULT_CALLBACK, pattern = 'IN', beginRoot = this.root, iterationType = 'ITERATIVE', includeNull = false) {
+    dfs(callback = this._DEFAULT_CALLBACK, pattern = 'IN', beginRoot = this.root, iterationType = this.iterationType, includeNull = false) {
         beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return [];
-        const ans = [];
-        if (iterationType === 'RECURSIVE') {
-            const dfs = (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, 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);
     }
-    /**
-     * Time complexity: O(n)
-     * Space complexity: O(n)
-     */
     /**
      * Time complexity: O(n)
      * Space complexity: O(n)
@@ -1275,9 +1099,9 @@ export class BinaryTree extends IterableEntryBase {
                 const current = queue.shift();
                 ans.push(callback(current));
                 if (includeNull) {
-                    if (current && this.isNodeOrNull(current.left))
+                    if (current && this.isRealNodeOrNull(current.left))
                         queue.push(current.left);
-                    if (current && this.isNodeOrNull(current.right))
+                    if (current && this.isRealNodeOrNull(current.right))
                         queue.push(current.right);
                 }
                 else {
@@ -1298,9 +1122,9 @@ export class BinaryTree extends IterableEntryBase {
                     const current = queue.shift();
                     ans.push(callback(current));
                     if (includeNull) {
-                        if (current && this.isNodeOrNull(current.left))
+                        if (current && this.isRealNodeOrNull(current.left))
                             queue.push(current.left);
-                        if (current && this.isNodeOrNull(current.right))
+                        if (current && this.isRealNodeOrNull(current.right))
                             queue.push(current.right);
                     }
                     else {
@@ -1317,7 +1141,55 @@ export class BinaryTree extends IterableEntryBase {
     /**
      * 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(callback = this._DEFAULT_CALLBACK, beginRoot = this.root, iterationType = this.iterationType) {
+        beginRoot = this.ensureNode(beginRoot);
+        const leaves = [];
+        if (!this.isRealNode(beginRoot)) {
+            return [];
+        }
+        if (iterationType === 'RECURSIVE') {
+            const dfs = (cur) => {
+                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;
+    }
     /**
      * Time complexity: O(n)
      * Space complexity: O(n)
@@ -1350,9 +1222,9 @@ export class BinaryTree extends IterableEntryBase {
                     levelsNodes[level] = [];
                 levelsNodes[level].push(callback(node));
                 if (includeNull) {
-                    if (node && this.isNodeOrNull(node.left))
+                    if (node && this.isRealNodeOrNull(node.left))
                         _recursive(node.left, level + 1);
-                    if (node && this.isNodeOrNull(node.right))
+                    if (node && this.isRealNodeOrNull(node.right))
                         _recursive(node.right, level + 1);
                 }
                 else {
@@ -1373,9 +1245,9 @@ export class BinaryTree extends IterableEntryBase {
                     levelsNodes[level] = [];
                 levelsNodes[level].push(callback(node));
                 if (includeNull) {
-                    if (node && this.isNodeOrNull(node.right))
+                    if (node && this.isRealNodeOrNull(node.right))
                         stack.push([node.right, level + 1]);
-                    if (node && this.isNodeOrNull(node.left))
+                    if (node && this.isRealNodeOrNull(node.left))
                         stack.push([node.left, level + 1]);
                 }
                 else {
@@ -1388,10 +1260,6 @@ export class BinaryTree extends IterableEntryBase {
         }
         return levelsNodes;
     }
-    /**
-     * Time complexity: O(n)
-     * Space complexity: O(n)
-     */
     /**
      * Time complexity: O(n)
      * Space complexity: O(n)
@@ -1496,10 +1364,6 @@ export class BinaryTree extends IterableEntryBase {
         }
         return ans;
     }
-    /**
-     * Time complexity: O(n)
-     * Space complexity: O(n)
-     */
     /**
      * Time complexity: O(n)
      * Space complexity: O(n)
@@ -1517,10 +1381,6 @@ export class BinaryTree extends IterableEntryBase {
         }, this.root, this.iterationType, true);
         return cloned;
     }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)
@@ -1546,10 +1406,6 @@ export class BinaryTree extends IterableEntryBase {
         }
         return newTree;
     }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)
@@ -1582,10 +1438,6 @@ export class BinaryTree extends IterableEntryBase {
     // //   return newTree;
     // // }
     //
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)
@@ -1603,29 +1455,163 @@ export class BinaryTree extends IterableEntryBase {
     print(beginRoot = this.root, options) {
         const opts = { isShowUndefined: false, isShowNull: false, isShowRedBlackNIL: false, ...options };
         beginRoot = this.ensureNode(beginRoot);
+        let output = '';
         if (!beginRoot)
-            return;
+            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) => {
             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;
     }
     /**
-     * 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.
+     */
+    _dfs(callback = this._DEFAULT_CALLBACK, pattern = 'IN', beginRoot = this.root, iterationType = this.iterationType, includeNull = false, shouldVisitLeft = node => !!node, shouldVisitRight = node => !!node, shouldVisitRoot = node => {
+        if (includeNull)
+            return this.isRealNodeOrNull(node);
+        return this.isRealNode(node);
+    }, shouldProcessRoot = node => true) {
+        beginRoot = this.ensureNode(beginRoot);
+        if (!beginRoot)
+            return [];
+        const ans = [];
+        if (iterationType === 'RECURSIVE') {
+            const dfs = (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 = [{ opt: DFSOperation.VISIT, node: beginRoot }];
+            const pushLeft = (cur) => {
+                if (shouldVisitLeft(cur.node))
+                    stack.push({ opt: DFSOperation.VISIT, node: cur.node?.left });
+            };
+            const pushRight = (cur) => {
+                if (shouldVisitRight(cur.node))
+                    stack.push({ opt: DFSOperation.VISIT, node: cur.node?.right });
+            };
+            const pushRoot = (cur) => {
+                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)
      * Space Complexity: O(1)
@@ -1664,10 +1650,6 @@ export class BinaryTree extends IterableEntryBase {
             }
         }
     }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)
@@ -1738,10 +1720,6 @@ export class BinaryTree extends IterableEntryBase {
         }
     }
     _DEFAULT_CALLBACK = (node) => (node ? node.key : undefined);
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     */
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -1771,10 +1749,6 @@ export class BinaryTree extends IterableEntryBase {
         }
         return undefined;
     }
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     */
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -1804,10 +1778,6 @@ export class BinaryTree extends IterableEntryBase {
         }
         return newNode;
     }
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     */
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -1823,10 +1793,6 @@ export class BinaryTree extends IterableEntryBase {
         }
         this._root = v;
     }
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     */
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)