directed-graph-typed 1.48.0 → 1.49.0

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

@@ -11,6 +11,7 @@ exports.BinaryTree = exports.BinaryTreeNode = void 0;
 const types_1 = require("../../types");
 const utils_1 = require("../../utils");
 const queue_1 = require("../queue");
+const base_1 = require("../base");
 /**
  * Represents a node in a binary tree.
  * @template V - The type of data stored in the node.
@@ -64,12 +65,8 @@ exports.BinaryTreeNode = BinaryTreeNode;
  * 3. Depth and Height: Depth is the number of edges from the root to a node; height is the maximum depth in the tree.
  * 4. Subtrees: Each child of a node forms the root of a subtree.
  * 5. Leaf Nodes: Nodes without children are leaves.
- * 6. Internal Nodes: Nodes with at least one child are internal.
- * 7. Balanced Trees: The heights of the left and right subtrees of any node differ by no more than one.
- * 8. Full Trees: Every node has either 0 or 2 children.
- * 9. Complete Trees: All levels are fully filled except possibly the last, filled from left to right.
  */
-class BinaryTree {
+class BinaryTree extends base_1.IterableEntryBase {
     /**
      * The constructor function initializes a binary tree object with optional elements and options.
      * @param [elements] - An optional iterable of BTNodeExemplar objects. These objects represent the
@@ -80,18 +77,26 @@ class BinaryTree {
      * required.
      */
     constructor(elements, options) {
+        super();
         this.iterationType = types_1.IterationType.ITERATIVE;
+        this._extractor = (key) => Number(key);
         this._defaultOneParamCallback = (node) => node.key;
         if (options) {
-            const { iterationType } = options;
+            const { iterationType, extractor } = options;
             if (iterationType) {
                 this.iterationType = iterationType;
             }
+            if (extractor) {
+                this._extractor = extractor;
+            }
         }
         this._size = 0;
         if (elements)
             this.addMany(elements);
     }
+    get extractor() {
+        return this._extractor;
+    }
     get root() {
         return this._root;
     }
@@ -100,7 +105,7 @@ class BinaryTree {
     }
     /**
      * Creates a new instance of BinaryTreeNode with the given key and value.
-     * @param {BTNKey} key - The key for the new node.
+     * @param {K} key - The key for the new node.
      * @param {V} value - The value for the new node.
      * @returns {N} - The newly created BinaryTreeNode.
      */
@@ -119,20 +124,21 @@ class BinaryTree {
     }
     /**
      * The function "isNode" checks if an exemplar is an instance of the BinaryTreeNode class.
-     * @param exemplar - The `exemplar` parameter is a variable of type `BTNodeExemplar<V, N>`.
+     * @param exemplar - The `exemplar` parameter is a variable of type `BTNodeExemplar<K, V,N>`.
      * @returns a boolean value indicating whether the exemplar is an instance of the class N.
      */
     isNode(exemplar) {
         return exemplar instanceof BinaryTreeNode;
     }
     /**
-     * The function `exemplarToNode` converts an exemplar of a binary tree node into an actual node
-     * object.
-     * @param exemplar - BTNodeExemplar<V, N> - A generic type representing the exemplar parameter of the
-     * function. It can be any type.
-     * @returns a value of type `N` (which represents a node), or `null`, or `undefined`.
+     * The function `exemplarToNode` converts an exemplar object into a node object.
+     * @param exemplar - The `exemplar` parameter is of type `BTNodeExemplar<K, V, N>`.
+     * @param {V} [value] - The `value` parameter is an optional value that can be passed to the
+     * `exemplarToNode` function. It represents the value associated with the exemplar node. If no value
+     * is provided, it will be `undefined`.
+     * @returns a value of type N (node), or null, or undefined.
      */
-    exemplarToNode(exemplar) {
+    exemplarToNode(exemplar, value) {
         if (exemplar === undefined)
             return;
         let node;
@@ -154,8 +160,8 @@ class BinaryTree {
         else if (this.isNode(exemplar)) {
             node = exemplar;
         }
-        else if (this.isNodeKey(exemplar)) {
-            node = this.createNode(exemplar);
+        else if (this.isNotNodeInstance(exemplar)) {
+            node = this.createNode(exemplar, value);
         }
         else {
             return;
@@ -164,7 +170,7 @@ class BinaryTree {
     }
     /**
      * The function checks if a given value is an entry in a binary tree node.
-     * @param kne - BTNodeExemplar<V, N> - A generic type representing a node in a binary tree. It has
+     * @param kne - BTNodeExemplar<K, V,N> - A generic type representing a node in a binary tree. It has
      * two type parameters V and N, representing the value and node type respectively.
      * @returns a boolean value.
      */
@@ -179,46 +185,57 @@ class BinaryTree {
      * Time Complexity O(log n) - O(n)
      * Space Complexity O(1)
      *
-     * The `add` function adds a new node to a binary tree, either by key or by providing a node object.
-     * @param keyOrNodeOrEntry - The parameter `keyOrNodeOrEntry` can be one of the following:
-     * @returns The function `add` returns the inserted node (`N`), `null`, or `undefined`.
-     */
-    add(keyOrNodeOrEntry) {
-        let inserted;
-        const newNode = this.exemplarToNode(keyOrNodeOrEntry);
+     * The `add` function adds a new node to a binary tree, either by creating a new node or replacing an
+     * existing node with the same key.
+     * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter can be one of the following:
+     * @param {V} [value] - The value to be inserted into the binary tree.
+     * @returns The function `add` returns either a node (`N`), `null`, or `undefined`.
+     */
+    add(keyOrNodeOrEntry, value) {
+        const newNode = this.exemplarToNode(keyOrNodeOrEntry, value);
         if (newNode === undefined)
             return;
-        const _bfs = (root, newNode) => {
-            const queue = new queue_1.Queue([root]);
-            while (queue.size > 0) {
-                const cur = queue.shift();
-                if (newNode && cur.key === newNode.key) {
-                    this._replaceNode(cur, newNode);
-                    return newNode;
-                }
-                const inserted = this._addTo(newNode, cur);
-                if (inserted !== undefined)
-                    return inserted;
-                if (cur.left)
-                    queue.push(cur.left);
-                if (cur.right)
-                    queue.push(cur.right);
+        // If the tree is empty, directly set the new node as the root node
+        if (!this.root) {
+            this._root = newNode;
+            this._size = 1;
+            return newNode;
+        }
+        const queue = new queue_1.Queue([this.root]);
+        let potentialParent; // Record the parent node of the potential insertion location
+        while (queue.size > 0) {
+            const cur = queue.shift();
+            if (!cur)
+                continue;
+            // Check for duplicate keys when newNode is not null
+            if (newNode !== null && cur.key === newNode.key) {
+                this._replaceNode(cur, newNode);
+                return newNode; // If duplicate keys are found, no insertion is performed
+            }
+            // Record the first possible insertion location found
+            if (potentialParent === undefined && (cur.left === undefined || cur.right === undefined)) {
+                potentialParent = cur;
+            }
+            // Continue traversing the left and right subtrees
+            if (cur.left !== null) {
+                cur.left && queue.push(cur.left);
+            }
+            if (cur.right !== null) {
+                cur.right && queue.push(cur.right);
             }
-        };
-        if (this.root) {
-            inserted = _bfs(this.root, newNode);
         }
-        else {
-            this._setRoot(newNode);
-            if (newNode) {
-                this._size = 1;
+        // At the end of the traversal, if the insertion position is found, insert
+        if (potentialParent) {
+            if (potentialParent.left === undefined) {
+                potentialParent.left = newNode;
             }
-            else {
-                this._size = 0;
+            else if (potentialParent.right === undefined) {
+                potentialParent.right = newNode;
             }
-            inserted = this.root;
+            this._size++;
+            return newNode;
         }
-        return inserted;
+        return undefined; // If the insertion position cannot be found, return undefined
     }
     /**
      * Time Complexity: O(k log n) - O(k * n)
@@ -229,18 +246,28 @@ class BinaryTree {
      * Time Complexity: O(k log n) - O(k * n)
      * Space Complexity: O(1)
      *
-     * The function `addMany` takes in an iterable of `BTNodeExemplar` objects, adds each object to the
-     * current instance, and returns an array of the inserted nodes.
-     * @param nodes - The `nodes` parameter is an iterable (such as an array or a set) of
-     * `BTNodeExemplar<V, N>` objects.
-     * @returns The function `addMany` returns an array of values, where each value is either of type
-     * `N`, `null`, or `undefined`.
-     */
-    addMany(nodes) {
+     * The `addMany` function takes in a collection of nodes and an optional collection of values, and
+     * adds each node with its corresponding value to the data structure.
+     * @param nodes - An iterable collection of BTNodeExemplar objects.
+     * @param [values] - An optional iterable of values that will be assigned to each node being added.
+     * @returns The function `addMany` returns an array of `N`, `null`, or `undefined` values.
+     */
+    addMany(nodes, values) {
         // TODO not sure addMany not be run multi times
         const inserted = [];
+        let valuesIterator;
+        if (values) {
+            valuesIterator = values[Symbol.iterator]();
+        }
         for (const kne of nodes) {
-            inserted.push(this.add(kne));
+            let value = undefined;
+            if (valuesIterator) {
+                const valueResult = valuesIterator.next();
+                if (!valueResult.done) {
+                    value = valueResult.value;
+                }
+            }
+            inserted.push(this.add(kne, value));
         }
         return inserted;
     }
@@ -248,17 +275,9 @@ class BinaryTree {
      * Time Complexity: O(k * n)  "n" is the number of nodes in the tree, and "k" is the number of keys to be inserted.
      * Space Complexity: O(1)
      */
-    /**
-     * Time Complexity: O(k * n)  "n" is the number of nodes in the tree, and "k" is the number of keys to be inserted.
-     * Space Complexity: O(1)
-     *
-     * The `refill` function clears the current collection and adds new nodes, keys, or entries to it.
-     * @param nodesOrKeysOrEntries - The parameter `nodesOrKeysOrEntries` is an iterable object that can
-     * contain either `BTNodeExemplar` objects, keys, or entries.
-     */
-    refill(nodesOrKeysOrEntries) {
+    refill(nodesOrKeysOrEntries, values) {
         this.clear();
-        this.addMany(nodesOrKeysOrEntries);
+        this.addMany(nodesOrKeysOrEntries, values);
     }
     /**
      * Time Complexity: O(n)
@@ -332,11 +351,11 @@ class BinaryTree {
      * Space Complexity: O(1)
      *
      * The function calculates the depth of a given node in a binary tree.
-     * @param {BTNKey | N | null | undefined} distNode - The `distNode` parameter represents the node in
-     * the binary tree whose depth we want to find. It can be of type `BTNKey`, `N`, `null`, or
+     * @param {K | N | null | undefined} distNode - The `distNode` parameter represents the node in
+     * the binary tree whose depth we want to find. It can be of type `K`, `N`, `null`, or
      * `undefined`.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting node
-     * from which we want to calculate the depth. It can be either a `BTNKey` (binary tree node key) or
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting node
+     * from which we want to calculate the depth. It can be either a `K` (binary tree node key) or
      * `N` (binary tree node) or `null` or `undefined`. If no value is provided for `beginRoot
      * @returns the depth of the `distNode` relative to the `beginRoot`.
      */
@@ -363,9 +382,9 @@ class BinaryTree {
      *
      * The function `getHeight` calculates the maximum height of a binary tree using either recursive or
      * iterative traversal.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
      * starting node of the binary tree from which we want to calculate the height. It can be of type
-     * `BTNKey`, `N`, `null`, or `undefined`. If not provided, it defaults to `this.root`.
+     * `K`, `N`, `null`, or `undefined`. If not provided, it defaults to `this.root`.
      * @param iterationType - The `iterationType` parameter is used to determine whether to calculate the
      * height of the tree using a recursive approach or an iterative approach. It can have two possible
      * values:
@@ -410,9 +429,9 @@ class BinaryTree {
      *
      * The `getMinHeight` function calculates the minimum height of a binary tree using either a
      * recursive or iterative approach.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
      * starting node of the binary tree from which we want to calculate the minimum height. It can be of
-     * type `BTNKey`, `N`, `null`, or `undefined`. If no value is provided, it defaults to `this.root`.
+     * type `K`, `N`, `null`, or `undefined`. If no value is provided, it defaults to `this.root`.
      * @param iterationType - The `iterationType` parameter is used to determine the method of iteration
      * to calculate the minimum height of a binary tree. It can have two possible values:
      * @returns The function `getMinHeight` returns the minimum height of a binary tree.
@@ -473,8 +492,8 @@ class BinaryTree {
      *
      * The function checks if a binary tree is perfectly balanced by comparing the minimum height and the
      * height of the tree.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
-     * for calculating the height and minimum height of a binary tree. It can be either a `BTNKey` (a key
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
+     * for calculating the height and minimum height of a binary tree. It can be either a `K` (a key
      * value of a binary tree node), `N` (a node of a binary tree), `null`, or `undefined`. If
      * @returns a boolean value.
      */
@@ -499,7 +518,7 @@ class BinaryTree {
      * matches the identifier. If set to true, the function will stop iterating once it finds a matching
      * node and return that node. If set to false (default), the function will continue iterating and
      * return all nodes that match the identifier.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
      * starting node for the traversal. It can be either a key, a node object, or `null`/`undefined`. If
      * it is `null` or `undefined`, an empty array will be returned.
      * @param iterationType - The `iterationType` parameter determines the type of iteration used to
@@ -556,8 +575,8 @@ class BinaryTree {
      * the binary tree. It is used to filter the nodes based on certain conditions. The `callback`
      * function should return a boolean value indicating whether the node should be included in the
      * result or not.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
-     * for the search in the binary tree. It can be specified as a `BTNKey` (a unique identifier for a
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
+     * for the search in the binary tree. It can be specified as a `K` (a unique identifier for a
      * node in the binary tree), a node object (`N`), or `null`/`undefined` to start the search from
      * @param iterationType - The `iterationType` parameter is a variable that determines the type of
      * iteration to be performed on the binary tree. It is used to specify whether the iteration should
@@ -582,7 +601,7 @@ class BinaryTree {
      * @param {C} callback - The `callback` parameter is a function that will be called for each node in
      * the binary tree. It is used to determine if a node matches the given identifier. The `callback`
      * function should take a single parameter of type `N` (the type of the nodes in the binary tree) and
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
      * for searching the binary tree. It can be either a key value, a node object, or `null`/`undefined`.
      * If `null` or `undefined` is passed, the search will start from the root of the binary tree.
      * @param iterationType - The `iterationType` parameter is used to specify the type of iteration to
@@ -606,7 +625,7 @@ class BinaryTree {
      *
      * The function `getNodeByKey` searches for a node in a binary tree by its key, using either
      * recursive or iterative iteration.
-     * @param {BTNKey} key - The `key` parameter is the key value that we are searching for in the tree.
+     * @param {K} key - The `key` parameter is the key value that we are searching for in the tree.
      * It is used to find the node with the matching key value.
      * @param iterationType - The `iterationType` parameter is used to determine whether the search for
      * the node with the given key should be performed iteratively or recursively. It has two possible
@@ -650,7 +669,7 @@ class BinaryTree {
     /**
      * The function `ensureNode` returns the node corresponding to the given key if it is a valid node
      * key, otherwise it returns the key itself.
-     * @param {BTNKey | N | null | undefined} key - The `key` parameter can be of type `BTNKey`, `N`,
+     * @param {K | N | null | undefined} key - The `key` parameter can be of type `K`, `N`,
      * `null`, or `undefined`. It represents a key used to identify a node in a binary tree.
      * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
      * type of iteration to be used when searching for a node by key. It has a default value of
@@ -659,7 +678,7 @@ class BinaryTree {
      * itself if it is not a valid node key.
      */
     ensureNode(key, iterationType = types_1.IterationType.ITERATIVE) {
-        return this.isNodeKey(key) ? this.getNodeByKey(key, iterationType) : key;
+        return this.isNotNodeInstance(key) ? this.getNodeByKey(key, iterationType) : key;
     }
     /**
      * Time Complexity: O(n)
@@ -674,8 +693,8 @@ class BinaryTree {
      * the binary tree. It is used to determine whether a node matches the given identifier. The callback
      * function should return a value that can be compared to the identifier to determine if it is a
      * match.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
-     * for the search in the binary tree. It can be specified as a `BTNKey` (a unique identifier for a
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
+     * for the search in the binary tree. It can be specified as a `K` (a unique identifier for a
      * node), a node object of type `N`, or `null`/`undefined` to start the search from the root of
      * @param iterationType - The `iterationType` parameter is used to specify the type of iteration to
      * be performed when searching for a node in the binary tree. It is an optional parameter with a
@@ -713,8 +732,8 @@ class BinaryTree {
      *
      * The function `getPathToRoot` returns an array of nodes from a given node to the root of a tree
      * structure, with the option to reverse the order of the nodes.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
-     * starting node from which you want to find the path to the root. It can be of type `BTNKey`, `N`,
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
+     * starting node from which you want to find the path to the root. It can be of type `K`, `N`,
      * `null`, or `undefined`.
      * @param [isReverse=true] - The `isReverse` parameter is a boolean flag that determines whether the
      * resulting path should be reversed or not. If `isReverse` is set to `true`, the path will be
@@ -746,8 +765,8 @@ class BinaryTree {
      *
      * The function `getLeftMost` returns the leftmost node in a binary tree, either recursively or
      * iteratively.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
-     * for finding the leftmost node in a binary tree. It can be either a `BTNKey` (a key value), `N` (a
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
+     * for finding the leftmost node in a binary tree. It can be either a `K` (a key value), `N` (a
      * node), `null`, or `undefined`. If not provided, it defaults to `this.root`,
      * @param iterationType - The `iterationType` parameter is used to determine the type of iteration to
      * be performed when finding the leftmost node in a binary tree. It can have two possible values:
@@ -786,8 +805,8 @@ class BinaryTree {
      *
      * The function `getRightMost` returns the rightmost node in a binary tree, either recursively or
      * iteratively.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
-     * starting node from which we want to find the rightmost node. It can be of type `BTNKey`, `N`,
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
+     * starting node from which we want to find the rightmost node. It can be of type `K`, `N`,
      * `null`, or `undefined`. If not provided, it defaults to `this.root`, which is a property of the
      * current object.
      * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
@@ -827,7 +846,7 @@ class BinaryTree {
      * Space Complexity: O(1)
      *
      * The function `isSubtreeBST` checks if a given binary tree is a valid binary search tree.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the root
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter represents the root
      * node of the binary search tree (BST) that you want to check if it is a subtree of another BST.
      * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
      * type of iteration to use when checking if a subtree is a binary search tree (BST). It can have two
@@ -843,9 +862,10 @@ class BinaryTree {
             const dfs = (cur, min, max) => {
                 if (!cur)
                     return true;
-                if (cur.key <= min || cur.key >= max)
+                const numKey = this.extractor(cur.key);
+                if (numKey <= min || numKey >= max)
                     return false;
-                return dfs(cur.left, min, cur.key) && dfs(cur.right, cur.key, max);
+                return dfs(cur.left, min, numKey) && dfs(cur.right, numKey, max);
             };
             return dfs(beginRoot, Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER);
         }
@@ -858,9 +878,10 @@ class BinaryTree {
                     curr = curr.left;
                 }
                 curr = stack.pop();
-                if (!curr || prev >= curr.key)
+                const numKey = this.extractor(curr.key);
+                if (!curr || prev >= numKey)
                     return false;
-                prev = curr.key;
+                prev = numKey;
                 curr = curr.right;
             }
             return true;
@@ -895,8 +916,8 @@ class BinaryTree {
      * @param {C} callback - The `callback` parameter is a function that will be called for each node in
      * the subtree traversal. It takes a single parameter, which is the current node being traversed, and
      * returns a value of any type.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
-     * starting node or key from which the subtree traversal should begin. It can be of type `BTNKey`,
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
+     * starting node or key from which the subtree traversal should begin. It can be of type `K`,
      * `N`, `null`, or `undefined`. If not provided, the `root` property of the current object is used as
      * the default value.
      * @param iterationType - The `iterationType` parameter determines the type of traversal to be
@@ -959,7 +980,7 @@ class BinaryTree {
      * @returns a boolean value.
      */
     isRealNode(node) {
-        return node instanceof BinaryTreeNode && node.key.toString() !== 'NaN';
+        return node instanceof BinaryTreeNode && String(node.key) !== 'NaN';
     }
     /**
      * The function checks if a given node is a BinaryTreeNode instance and has a key value of NaN.
@@ -967,7 +988,7 @@ class BinaryTree {
      * @returns a boolean value.
      */
     isNIL(node) {
-        return node instanceof BinaryTreeNode && node.key.toString() === 'NaN';
+        return node instanceof BinaryTreeNode && String(node.key) === 'NaN';
     }
     /**
      * The function checks if a given node is a real node or null.
@@ -978,13 +999,13 @@ class BinaryTree {
         return this.isRealNode(node) || node === null;
     }
     /**
-     * The function "isNodeKey" checks if a potential key is a number.
+     * The function "isNotNodeInstance" checks if a potential key is a K.
      * @param {any} potentialKey - The potentialKey parameter is of type any, which means it can be any
      * data type.
      * @returns a boolean value indicating whether the potentialKey is of type number or not.
      */
-    isNodeKey(potentialKey) {
-        return typeof potentialKey === 'number';
+    isNotNodeInstance(potentialKey) {
+        return !(potentialKey instanceof BinaryTreeNode);
     }
     /**
      * Time complexity: O(n)
@@ -998,7 +1019,7 @@ class BinaryTree {
      * `null`, or `undefined`, and returns a value of any type. The default value for this parameter is
      * @param {DFSOrderPattern} [pattern=in] - The `pattern` parameter determines the order in which the
      * nodes are traversed during the depth-first search. It can have one of the following values:
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting node
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting node
      * for the depth-first search traversal. It can be specified as a key, a node object, or
      * `null`/`undefined`. If not provided, the `beginRoot` will default to the root node of the tree.
      * @param {IterationType} iterationType - The `iterationType` parameter determines the type of
@@ -1124,7 +1145,7 @@ class BinaryTree {
      * @param {C} callback - The `callback` parameter is a function that will be called for each node in
      * the breadth-first search traversal. It takes a single parameter, which is the current node being
      * visited, and returns a value of any type.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
      * starting node for the breadth-first search traversal. It can be specified as a key, a node object,
      * or `null`/`undefined` to indicate the root of the tree. If not provided, the `root` property of
      * the class is used as
@@ -1198,9 +1219,9 @@ class BinaryTree {
      * @param {C} callback - The `callback` parameter is a function that will be called for each node in
      * the tree. It takes a single parameter, which can be of type `N`, `null`, or `undefined`, and
      * returns a value of any type.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
      * starting node for traversing the tree. It can be either a node object (`N`), a key value
-     * (`BTNKey`), `null`, or `undefined`. If not provided, it defaults to the root node of the tree.
+     * (`K`), `null`, or `undefined`. If not provided, it defaults to the root node of the tree.
      * @param iterationType - The `iterationType` parameter determines the type of iteration to be
      * performed on the tree. It can have two possible values:
      * @param [includeNull=false] - The `includeNull` parameter is a boolean value that determines
@@ -1259,19 +1280,23 @@ class BinaryTree {
         return levelsNodes;
     }
     /**
-     * The function `getPredecessor` returns the predecessor node of a given node in a binary tree.
-     * @param {BTNKey | N | null | undefined} node - The `node` parameter can be of type `BTNKey`, `N`,
-     * `null`, or `undefined`.
-     * @returns The function `getPredecessor` returns a value of type `N | undefined`.
+     * Time Complexity: O(log n)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(log n)
+     * Space Complexity: O(1)
+     *
+     * The function returns the predecessor of a given node in a tree.
+     * @param {N} node - The parameter `node` is of type `RedBlackTreeNode`, which represents a node in a
+     * tree.
+     * @returns the predecessor of the given 'node'.
      */
     getPredecessor(node) {
-        node = this.ensureNode(node);
-        if (!this.isRealNode(node))
-            return undefined;
-        if (node.left) {
+        if (this.isRealNode(node.left)) {
             let predecessor = node.left;
             while (!this.isRealNode(predecessor) || (this.isRealNode(predecessor.right) && predecessor.right !== node)) {
-                if (predecessor) {
+                if (this.isRealNode(predecessor)) {
                     predecessor = predecessor.right;
                 }
             }
@@ -1283,19 +1308,19 @@ class BinaryTree {
     }
     /**
      * The function `getSuccessor` returns the next node in a binary tree given a current node.
-     * @param {BTNKey | N | null} [x] - The parameter `x` can be of type `BTNKey`, `N`, or `null`.
+     * @param {K | N | null} [x] - The parameter `x` can be of type `K`, `N`, or `null`.
      * @returns the successor of the given node or key. The successor is the node that comes immediately
      * after the given node in the inorder traversal of the binary tree.
      */
     getSuccessor(x) {
         x = this.ensureNode(x);
-        if (!x)
+        if (!this.isRealNode(x))
             return undefined;
-        if (x.right) {
+        if (this.isRealNode(x.right)) {
             return this.getLeftMost(x.right);
         }
         let y = x.parent;
-        while (y && y && x === y.right) {
+        while (this.isRealNode(y) && x === y.right) {
             x = y;
             y = y.parent;
         }
@@ -1312,7 +1337,7 @@ class BinaryTree {
      * @param {DFSOrderPattern} [pattern=in] - The `pattern` parameter in the `morris` function
      * determines the order in which the nodes of a binary tree are traversed. It can have one of the
      * following values:
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting node
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting node
      * for the traversal. It can be specified as a key, a node object, or `null`/`undefined` to indicate
      * the root of the tree. If no value is provided, the default value is the root of the tree.
      * @returns The function `morris` returns an array of values that are the result of invoking the
@@ -1406,116 +1431,89 @@ class BinaryTree {
     }
     /**
      * Time complexity: O(n)
-     * Space complexity: O(1)
+     * Space complexity: O(n)
      */
     /**
-     * The `forEach` function iterates over each entry in a tree and calls a callback function with the
-     * entry and the tree as arguments.
-     * @param callback - The callback parameter is a function that will be called for each entry in the
-     * tree. It takes two parameters: entry and tree.
-     */
-    forEach(callback) {
-        for (const entry of this) {
-            callback(entry, this);
-        }
+     * Time complexity: O(n)
+     * Space complexity: O(n)
+     *
+     * The `clone` function creates a new tree object and copies all the nodes from the original tree to
+     * the new tree.
+     * @returns The `clone()` method is returning a cloned instance of the `TREE` object.
+     */
+    clone() {
+        const cloned = this.createTree();
+        this.bfs(node => cloned.add([node.key, node.value]));
+        return cloned;
     }
     /**
-     * The `filter` function creates a new tree by iterating over the entries of the current tree and
-     * adding the entries that satisfy the given predicate.
-     * @param predicate - The `predicate` parameter is a function that takes two arguments: `entry` and
-     * `tree`.
-     * @returns The `filter` method is returning a new tree object that contains only the entries that
-     * satisfy the given predicate function.
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
      */
-    filter(predicate) {
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     *
+     * The `filter` function creates a new tree by iterating over the elements of the current tree and
+     * adding only the elements that satisfy the given predicate function.
+     * @param predicate - The `predicate` parameter is a function that takes three arguments: `value`,
+     * `key`, and `index`. It should return a boolean value indicating whether the pair should be
+     * included in the filtered tree or not.
+     * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+     * to be used as the `this` value when executing the `predicate` function. If `thisArg` is provided,
+     * it will be passed as the first argument to the `predicate` function. If `thisArg` is
+     * @returns The `filter` method is returning a new tree object that contains the key-value pairs that
+     * pass the given predicate function.
+     */
+    filter(predicate, thisArg) {
         const newTree = this.createTree();
+        let index = 0;
         for (const [key, value] of this) {
-            if (predicate([key, value], this)) {
+            if (predicate.call(thisArg, value, key, index++, this)) {
                 newTree.add([key, value]);
             }
         }
         return newTree;
     }
     /**
-     * The `map` function creates a new tree by applying a callback function to each entry in the current
-     * tree.
-     * @param callback - The callback parameter is a function that takes two arguments: entry and tree.
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     *
+     * The `map` function creates a new tree by applying a callback function to each key-value pair in
+     * the original tree.
+     * @param callback - The callback parameter is a function that will be called for each key-value pair
+     * in the tree. It takes four arguments: the value of the current pair, the key of the current pair,
+     * the index of the current pair, and a reference to the tree itself. The callback function should
+     * return a new
+     * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that allows you to
+     * specify the value of `this` within the callback function. If you pass a value for `thisArg`, it
+     * will be used as the `this` value when the callback function is called. If you don't pass a value
      * @returns The `map` method is returning a new tree object.
      */
-    map(callback) {
+    map(callback, thisArg) {
         const newTree = this.createTree();
+        let index = 0;
         for (const [key, value] of this) {
-            newTree.add([key, callback([key, value], this)]);
+            newTree.add([key, callback.call(thisArg, value, key, index++, this)]);
         }
         return newTree;
     }
-    // TODO Type error, need to return a TREE<NV> that is a value type only for callback function.
-    // map<NV>(callback: (entry: [BTNKey, V | undefined], tree: this) => NV) {
-    //   const newTree = this.createTree();
-    //   for (const [key, value] of this) {
-    //     newTree.add(key, callback([key, value], this));
-    //   }
-    //   return newTree;
-    // }
-    /**
-     * The `reduce` function iterates over the entries of a tree and applies a callback function to each
-     * entry, accumulating a single value.
-     * @param callback - The callback parameter is a function that takes three arguments: accumulator,
-     * entry, and tree. It is called for each entry in the tree and is used to accumulate a single value
-     * based on the logic defined in the callback function.
-     * @param {T} initialValue - The initialValue parameter is the initial value of the accumulator. It
-     * is the value that will be passed as the first argument to the callback function when reducing the
-     * elements of the tree.
-     * @returns The `reduce` method is returning the final value of the accumulator after iterating over
-     * all the entries in the tree and applying the callback function to each entry.
-     */
-    reduce(callback, initialValue) {
-        let accumulator = initialValue;
-        for (const [key, value] of this) {
-            accumulator = callback(accumulator, [key, value], this);
-        }
-        return accumulator;
-    }
-    /**
-     * The above function is an iterator for a binary tree that can be used to traverse the tree in
-     * either an iterative or recursive manner.
-     * @param node - The `node` parameter represents the current node in the binary tree from which the
-     * iteration starts. It is an optional parameter with a default value of `this.root`, which means
-     * that if no node is provided, the iteration will start from the root of the binary tree.
-     * @returns The `*[Symbol.iterator]` method returns a generator object that yields the keys of the
-     * binary tree nodes in a specific order.
-     */
-    *[Symbol.iterator](node = this.root) {
-        if (!node)
-            return;
-        if (this.iterationType === types_1.IterationType.ITERATIVE) {
-            const stack = [];
-            let current = node;
-            while (current || stack.length > 0) {
-                while (current && !isNaN(current.key)) {
-                    stack.push(current);
-                    current = current.left;
-                }
-                current = stack.pop();
-                if (current && !isNaN(current.key)) {
-                    yield [current.key, current.value];
-                    current = current.right;
-                }
-            }
-        }
-        else {
-            if (node.left && !isNaN(node.key)) {
-                yield* this[Symbol.iterator](node.left);
-            }
-            yield [node.key, node.value];
-            if (node.right && !isNaN(node.key)) {
-                yield* this[Symbol.iterator](node.right);
-            }
-        }
-    }
+    // // TODO Type error, need to return a TREE<NV> that is a value type only for callback function.
+    // // map<NV>(callback: (entry: [K, V | undefined], tree: this) => NV) {
+    // //   const newTree = this.createTree();
+    // //   for (const [key, value] of this) {
+    // //     newTree.add(key, callback([key, value], this));
+    // //   }
+    // //   return newTree;
+    // // }
+    //
     /**
      * The `print` function is used to display a binary tree structure in a visually appealing way.
-     * @param {BTNKey | N | null | undefined} [beginRoot=this.root] - The `root` parameter is of type `BTNKey | N | null |
+     * @param {K | N | null | undefined} [beginRoot=this.root] - The `root` parameter is of type `K | N | null |
      * undefined`. It represents the root node of a binary tree. The root node can have one of the
      * following types:
      * @param {BinaryTreePrintOptions} [options={ isShowUndefined: false, isShowNull: false, isShowRedBlackNIL: false}] - Options object that controls printing behavior. You can specify whether to display undefined, null, or sentinel nodes.
@@ -1542,6 +1540,34 @@ class BinaryTree {
         };
         display(beginRoot);
     }
+    *_getIterator(node = this.root) {
+        if (!node)
+            return;
+        if (this.iterationType === types_1.IterationType.ITERATIVE) {
+            const stack = [];
+            let current = node;
+            while (current || stack.length > 0) {
+                while (current && !isNaN(this.extractor(current.key))) {
+                    stack.push(current);
+                    current = current.left;
+                }
+                current = stack.pop();
+                if (current && !isNaN(this.extractor(current.key))) {
+                    yield [current.key, current.value];
+                    current = current.right;
+                }
+            }
+        }
+        else {
+            if (node.left && !isNaN(this.extractor(node.key))) {
+                yield* this[Symbol.iterator](node.left);
+            }
+            yield [node.key, node.value];
+            if (node.right && !isNaN(this.extractor(node.key))) {
+                yield* this[Symbol.iterator](node.right);
+            }
+        }
+    }
     _displayAux(node, options) {
         const { isShowNull, isShowUndefined, isShowRedBlackNIL } = options;
         const emptyDisplayLayout = [['─'], 1, 0, 0];
@@ -1552,12 +1578,12 @@ class BinaryTree {
         else if (node === undefined && !isShowUndefined) {
             return emptyDisplayLayout;
         }
-        else if (node !== null && node !== undefined && isNaN(node.key) && !isShowRedBlackNIL) {
+        else if (node !== null && node !== undefined && isNaN(this.extractor(node.key)) && !isShowRedBlackNIL) {
             return emptyDisplayLayout;
         }
         else if (node !== null && node !== undefined) {
             // Display logic of normal nodes
-            const key = node.key, line = isNaN(key) ? 'S' : key.toString(), width = line.length;
+            const key = node.key, line = isNaN(this.extractor(key)) ? 'S' : this.extractor(key).toString(), width = line.length;
             return _buildNodeDisplay(line, width, this._displayAux(node.left, options), this._displayAux(node.right, options));
         }
         else {
@@ -1644,7 +1670,7 @@ class BinaryTree {
      * If the parent node is null, the function also returns undefined.
      */
     _addTo(newNode, parent) {
-        if (this.isNodeKey(parent))
+        if (this.isNotNodeInstance(parent))
             parent = this.getNode(parent);
         if (parent) {
             // When all leaf nodes are null, it will no longer be possible to add new entity nodes to this binary tree.