red-black-tree-typed 1.53.7 → 1.54.2

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

@@ -6,8 +6,6 @@
  * @license MIT License
  */
 import type {
-  BSTNested,
-  BSTNodeNested,
   BSTNOptKeyOrNode,
   BSTOptions,
   BTNRep,
@@ -15,10 +13,12 @@ import type {
   Comparator,
   CP,
   DFSOrderPattern,
+  EntryCallback,
   IterationType,
   NodeCallback,
   NodePredicate,
-  OptNode
+  OptNode,
+  OptNodeOrNull
 } from '../../types';
 import { BinaryTree, BinaryTreeNode } from './binary-tree';
 import { IBinaryTree } from '../../interfaces';
@@ -26,61 +26,44 @@ import { Queue } from '../queue';
 import { isComparable } from '../../utils';
 import { Range } from '../../common';
 
-export class BSTNode<K = any, V = any, NODE extends BSTNode<K, V, NODE> = BSTNodeNested<K, V>> extends BinaryTreeNode<
-  K,
-  V,
-  NODE
-> {
-  override parent?: NODE;
-
+export class BSTNode<K = any, V = any> extends BinaryTreeNode<K, V> {
+  /**
+   * This TypeScript constructor function initializes an instance with a key and an optional value.
+   * @param {K} key - The `key` parameter is typically used to uniquely identify an object or element
+   * within a data structure. It serves as a reference or identifier for accessing or manipulating the
+   * associated value.
+   * @param {V} [value] - The `value` parameter in the constructor is optional, meaning it does not
+   * have to be provided when creating an instance of the class. If a value is not provided, it will
+   * default to `undefined`.
+   */
   constructor(key: K, value?: V) {
     super(key, value);
-    this.parent = undefined;
-    this._left = undefined;
-    this._right = undefined;
   }
 
-  protected override _left?: NODE;
+  override parent?: BSTNode<K, V> = undefined;
 
-  /**
-   * The function returns the value of the `_left` property.
-   * @returns The `_left` property of the current object is being returned.
-   */
-  override get left(): OptNode<NODE> {
+  override _left?: OptNodeOrNull<BSTNode<K, V>> = undefined;
+
+  override get left(): OptNodeOrNull<BSTNode<K, V>> {
     return this._left;
   }
 
-  /**
-   * The function sets the left child of a node and updates the parent reference of the child.
-   * @param {OptNode<NODE>} v - The parameter `v` is of type `OptNode<NODE>`. It can either be an
-   * instance of the `NODE` class or `undefined`.
-   */
-  override set left(v: OptNode<NODE>) {
+  override set left(v: OptNodeOrNull<BSTNode<K, V>>) {
     if (v) {
-      v.parent = this as unknown as NODE;
+      v.parent = this;
     }
     this._left = v;
   }
 
-  protected override _right?: NODE;
+  override _right?: OptNodeOrNull<BSTNode<K, V>> = undefined;
 
-  /**
-   * The function returns the right node of a binary tree or undefined if there is no right node.
-   * @returns The method is returning the value of the `_right` property, which is of type `NODE` or
-   * `undefined`.
-   */
-  override get right(): OptNode<NODE> {
+  override get right(): OptNodeOrNull<BSTNode<K, V>> {
     return this._right;
   }
 
-  /**
-   * The function sets the right child of a node and updates the parent reference of the child.
-   * @param {OptNode<NODE>} v - The parameter `v` is of type `OptNode<NODE>`. It can either be a
-   * `NODE` object or `undefined`.
-   */
-  override set right(v: OptNode<NODE>) {
+  override set right(v: OptNodeOrNull<BSTNode<K, V>>) {
     if (v) {
-      v.parent = this as unknown as NODE;
+      v.parent = this;
     }
     this._right = v;
   }
@@ -95,32 +78,48 @@ export class BSTNode<K = any, V = any, NODE extends BSTNode<K, V, NODE> = BSTNod
  * 6. Balance Variability: Can become unbalanced; special types maintain balance.
  * 7. No Auto-Balancing: Standard BSTs don't automatically balance themselves.
  * @example
- * // Find kth smallest element
- *     // Create a BST with some elements
- *     const bst = new BST<number>([5, 3, 7, 1, 4, 6, 8]);
- *     const sortedKeys = bst.dfs(node => node.key, 'IN');
+ * // Merge 3 sorted datasets
+ *     const dataset1 = new BST<number, string>([
+ *       [1, 'A'],
+ *       [7, 'G']
+ *     ]);
+ *     const dataset2 = [
+ *       [2, 'B'],
+ *       [6, 'F']
+ *     ];
+ *     const dataset3 = new BST<number, string>([
+ *       [3, 'C'],
+ *       [5, 'E'],
+ *       [4, 'D']
+ *     ]);
  *
- *     // Helper function to find kth smallest
- *     const findKthSmallest = (k: number): number | undefined => {
- *       return sortedKeys[k - 1];
- *     };
+ *     // Merge datasets into a single BinarySearchTree
+ *     const merged = new BST<number, string>(dataset1);
+ *     merged.addMany(dataset2);
+ *     merged.merge(dataset3);
  *
- *     // Assertions
- *     console.log(findKthSmallest(1)); // 1
- *     console.log(findKthSmallest(3)); // 4
- *     console.log(findKthSmallest(7)); // 8
+ *     // Verify merged dataset is in sorted order
+ *     console.log([...merged.values()]); // ['A', 'B', 'C', 'D', 'E', 'F', 'G']
  * @example
  * // Find elements in a range
  *     const bst = new BST<number>([10, 5, 15, 3, 7, 12, 18]);
  *     console.log(bst.search(new Range(5, 10))); // [10, 5, 7]
- *     console.log(bst.search(new Range(4, 12))); // [10, 12, 5, 7]
+ *     console.log(bst.rangeSearch([4, 12], node => node.key.toString())); // ['10', '12', '5', '7']
  *     console.log(bst.search(new Range(4, 12, true, false))); // [10, 5, 7]
- *     console.log(bst.search(new Range(15, 20))); // [15, 18]
+ *     console.log(bst.rangeSearch([15, 20])); // [15, 18]
  *     console.log(bst.search(new Range(15, 20, false))); // [18]
  * @example
  * // Find lowest common ancestor
  *     const bst = new BST<number>([20, 10, 30, 5, 15, 25, 35, 3, 7, 12, 18]);
  *
+ *     // LCA helper function
+ *     const findLCA = (num1: number, num2: number): number | undefined => {
+ *       const path1 = bst.getPathToRoot(num1);
+ *       const path2 = bst.getPathToRoot(num2);
+ *       // Find the first common ancestor
+ *       return findFirstCommon(path1, path2);
+ *     };
+ *
  *     function findFirstCommon(arr1: number[], arr2: number[]): number | undefined {
  *       for (const num of arr1) {
  *         if (arr2.indexOf(num) !== -1) {
@@ -130,116 +129,112 @@ export class BSTNode<K = any, V = any, NODE extends BSTNode<K, V, NODE> = BSTNod
  *       return undefined;
  *     }
  *
- *     // LCA helper function
- *     const findLCA = (num1: number, num2: number): number | undefined => {
- *       const path1 = bst.getPathToRoot(num1);
- *       const path2 = bst.getPathToRoot(num2);
- *       // Find the first common ancestor
- *       return findFirstCommon(path1, path2);
- *     };
- *
  *     // Assertions
  *     console.log(findLCA(3, 10)); // 7
  *     console.log(findLCA(5, 35)); // 15
  *     console.log(findLCA(20, 30)); // 25
  */
-export class BST<
-    K = any,
-    V = any,
-    R = object,
-    NODE extends BSTNode<K, V, NODE> = BSTNode<K, V, BSTNodeNested<K, V>>,
-    TREE extends BST<K, V, R, NODE, TREE> = BST<K, V, R, NODE, BSTNested<K, V, R, NODE>>
-  >
-  extends BinaryTree<K, V, R, NODE, TREE>
-  implements IBinaryTree<K, V, R, NODE, TREE>
+export class BST<K = any, V = any, R = object, MK = any, MV = any, MR = object>
+  extends BinaryTree<K, V, R, MK, MV, MR>
+  implements IBinaryTree<K, V, R, MK, MV, MR>
 {
   /**
-   * This is the constructor function for a Binary Search Tree class in TypeScript.
-   * @param keysNodesEntriesOrRaws - The `keysNodesEntriesOrRaws` parameter is an
-   * iterable that can contain either keys, nodes, entries, or raw elements. These elements will be
-   * added to the binary search tree during the construction of the object.
-   * @param [options] - An optional object that contains additional options for the Binary Search Tree.
-   * It can include a comparator function that defines the order of the elements in the tree.
+   * This TypeScript constructor initializes a binary search tree with optional options and adds
+   * elements if provided.
+   * @param keysNodesEntriesOrRaws - The `keysNodesEntriesOrRaws` parameter in the constructor is an
+   * iterable that can contain elements of type `BTNRep<K, V, BSTNode<K, V>>` or `R`. It is used to
+   * initialize the binary search tree with keys, nodes, entries, or raw data.
+   * @param [options] - The `options` parameter is an optional object that can contain the following
+   * properties:
    */
-  constructor(keysNodesEntriesOrRaws: Iterable<R | BTNRep<K, V, NODE>> = [], options?: BSTOptions<K, V, R>) {
+  constructor(keysNodesEntriesOrRaws: Iterable<BTNRep<K, V, BSTNode<K, V>> | R> = [], options?: BSTOptions<K, V, R>) {
     super([], options);
 
     if (options) {
-      const { extractComparable, isReverse } = options;
-      if (typeof extractComparable === 'function') this._extractComparable = extractComparable;
+      const { specifyComparable, isReverse } = options;
+      if (typeof specifyComparable === 'function') this._specifyComparable = specifyComparable;
       if (isReverse !== undefined) this._isReverse = isReverse;
     }
 
     if (keysNodesEntriesOrRaws) this.addMany(keysNodesEntriesOrRaws);
   }
 
-  protected override _root?: NODE = undefined;
+  protected override _root?: BSTNode<K, V> = undefined;
 
-  /**
-   * The function returns the root node of a tree structure.
-   * @returns The `_root` property of the object, which is of type `NODE` or `undefined`.
-   */
-  override get root(): OptNode<NODE> {
+  override get root(): OptNode<BSTNode<K, V>> {
     return this._root;
   }
 
   protected _isReverse: boolean = false;
 
-  /**
-   * The above function is a getter method in TypeScript that returns the value of the private property
-   * `_isReverse`.
-   * @returns The `isReverse` property of the object, which is a boolean value.
-   */
   get isReverse(): boolean {
     return this._isReverse;
   }
 
+  protected _comparator: Comparator<K> = (a: K, b: K): number => {
+    if (isComparable(a) && isComparable(b)) {
+      if (a > b) return 1;
+      if (a < b) return -1;
+      return 0;
+    }
+    if (this._specifyComparable) {
+      if (this._specifyComparable(a) > this._specifyComparable(b)) return 1;
+      if (this._specifyComparable(a) < this._specifyComparable(b)) return -1;
+      return 0;
+    }
+    if (typeof a === 'object' || typeof b === 'object') {
+      throw TypeError(
+        `When comparing object types, a custom specifyComparable must be defined in the constructor's options parameter.`
+      );
+    }
+
+    return 0;
+  };
+
+  get comparator() {
+    return this._comparator;
+  }
+
+  protected _specifyComparable?: (key: K) => Comparable;
+
+  get specifyComparable() {
+    return this._specifyComparable;
+  }
+
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The function creates a new BSTNode with the given key and value and returns it.
    * @param {K} key - The key parameter is of type K, which represents the type of the key for the node
    * being created.
    * @param {V} [value] - The "value" parameter is an optional parameter of type V. It represents the
    * value associated with the key in the node being created.
-   * @returns The method is returning a new instance of the BSTNode class, casted as the NODE type.
+   * @returns The method is returning a new instance of the BSTNode class, casted as the BSTNode<K, V> type.
    */
-  override createNode(key: K, value?: V): NODE {
-    return new BSTNode<K, V, NODE>(key, this._isMapMode ? undefined : value) as NODE;
+  override createNode(key: K, value?: V): BSTNode<K, V> {
+    return new BSTNode<K, V>(key, this._isMapMode ? undefined : value);
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The function creates a new binary search tree with the specified options.
    * @param [options] - The `options` parameter is an optional object that allows you to customize the
    * behavior of the `createTree` method. It accepts a partial `BSTOptions` object, which has the
    * following properties:
    * @returns a new instance of the BST class with the provided options.
    */
-  override createTree(options?: BSTOptions<K, V, R>): TREE {
-    return new BST<K, V, R, NODE, TREE>([], {
+  override createTree(options?: BSTOptions<K, V, R>) {
+    return new BST<K, V, R, MK, MV, MR>([], {
       iterationType: this.iterationType,
       isMapMode: this._isMapMode,
-      extractComparable: this._extractComparable,
+      specifyComparable: this._specifyComparable,
       toEntryFn: this._toEntryFn,
       isReverse: this._isReverse,
       ...options
-    }) as TREE;
-  }
-
-  /**
-   * The function overrides a method and converts a key, value pair or entry or raw element to a node.
-   * @param {BTNRep<K, V, NODE> | R} keyNodeEntryOrRaw - A variable that can be of
-   * type R or BTNRep<K, V, NODE>. It represents either a key, a node, an entry, or a raw
-   * element.
-   * @param {V} [value] - The `value` parameter is an optional value of type `V`. It represents the
-   * value associated with a key in a key-value pair.
-   * @returns either a NODE object or undefined.
-   */
-  override keyValueNodeEntryRawToNodeAndValue(
-    keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R,
-    value?: V
-  ): [OptNode<NODE>, V | undefined] {
-    const [node, entryValue] = super.keyValueNodeEntryRawToNodeAndValue(keyNodeEntryOrRaw, value);
-    if (node === null) return [undefined, undefined];
-    return [node, value ?? entryValue];
+    });
   }
 
   /**
@@ -248,8 +243,8 @@ export class BST<
    *
    * The function ensures the existence of a node in a data structure and returns it, or undefined if
    * it doesn't exist.
-   * @param {BTNRep<K, V, NODE> | R} keyNodeEntryOrRaw - The parameter
-   * `keyNodeEntryOrRaw` can accept a value of type `R`, which represents the key, node,
+   * @param {BTNRep<K, V, BSTNode<K, V>>} keyNodeOrEntry - The parameter
+   * `keyNodeOrEntry` can accept a value of type `R`, which represents the key, node,
    * entry, or raw element that needs to be ensured in the tree.
    * @param {IterationType} [iterationType=ITERATIVE] - The `iterationType` parameter is an optional
    * parameter that specifies the type of iteration to be used when ensuring a node. It has a default
@@ -258,48 +253,54 @@ export class BST<
    * not be ensured.
    */
   override ensureNode(
-    keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R,
+    keyNodeOrEntry: BTNRep<K, V, BSTNode<K, V>>,
     iterationType: IterationType = this.iterationType
-  ): OptNode<NODE> {
-    return super.ensureNode(keyNodeEntryOrRaw, iterationType) ?? undefined;
+  ): OptNode<BSTNode<K, V>> {
+    return super.ensureNode(keyNodeOrEntry, iterationType) ?? undefined;
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The function checks if the input is an instance of the BSTNode class.
-   * @param {BTNRep<K, V, NODE> | R} keyNodeEntryOrRaw - The parameter
-   * `keyNodeEntryOrRaw` can be of type `R` or `BTNRep<K, V, NODE>`.
-   * @returns a boolean value indicating whether the input parameter `keyNodeEntryOrRaw` is
+   * @param {BTNRep<K, V, BSTNode<K, V>>} keyNodeOrEntry - The parameter
+   * `keyNodeOrEntry` can be of type `R` or `BTNRep<K, V, BSTNode<K, V>>`.
+   * @returns a boolean value indicating whether the input parameter `keyNodeOrEntry` is
    * an instance of the `BSTNode` class.
    */
-  override isNode(keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R): keyNodeEntryOrRaw is NODE {
-    return keyNodeEntryOrRaw instanceof BSTNode;
+  override isNode(keyNodeOrEntry: BTNRep<K, V, BSTNode<K, V>>): keyNodeOrEntry is BSTNode<K, V> {
+    return keyNodeOrEntry instanceof BSTNode;
   }
 
   /**
-   * The function "override isKey" checks if a key is comparable based on a given comparator.
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The function "override isValidKey" checks if a key is comparable based on a given comparator.
    * @param {any} key - The `key` parameter is a value that will be checked to determine if it is of
    * type `K`.
-   * @returns The `override isKey(key: any): key is K` function is returning a boolean value based on
+   * @returns The `override isValidKey(key: any): key is K` function is returning a boolean value based on
    * the result of the `isComparable` function with the condition `this._compare !==
    * this._DEFAULT_COMPARATOR`.
    */
-  override isKey(key: any): key is K {
-    return isComparable(key, this._extractComparable !== undefined);
+  override isValidKey(key: any): key is K {
+    return isComparable(key, this._specifyComparable !== undefined);
   }
 
   /**
    * Time Complexity: O(log n)
-   * Space Complexity: O(1)
+   * Space Complexity: O(log n)
    *
    * The `add` function in TypeScript adds a new node to a binary search tree based on the key value.
-   * @param {BTNRep<K, V, NODE> | R} keyNodeEntryOrRaw - The parameter
-   * `keyNodeEntryOrRaw` can accept a value of type `R` or `BTNRep<K, V, NODE>`.
+   * @param {BTNRep<K, V, BSTNode<K, V>>} keyNodeOrEntry - The parameter
+   * `keyNodeOrEntry` can accept a value of type `R` or `BTNRep<K, V, BSTNode<K, V>>`.
    * @param {V} [value] - The `value` parameter is an optional value that can be associated with the
    * key in the binary search tree. If provided, it will be stored in the node along with the key.
    * @returns a boolean value.
    */
-  override add(keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R, value?: V): boolean {
-    const [newNode, newValue] = this.keyValueNodeEntryRawToNodeAndValue(keyNodeEntryOrRaw, value);
+  override add(keyNodeOrEntry: BTNRep<K, V, BSTNode<K, V>>, value?: V): boolean {
+    const [newNode, newValue] = this._keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry, value);
     if (newNode === undefined) return false;
 
     if (this._root === undefined) {
@@ -322,7 +323,7 @@ export class BST<
           this._size++;
           return true;
         }
-        current = current.left;
+        if (current.left !== null) current = current.left;
       } else {
         if (current.right === undefined) {
           current.right = newNode;
@@ -330,7 +331,7 @@ export class BST<
           this._size++;
           return true;
         }
-        current = current.right;
+        if (current.right !== null) current = current.right;
       }
     }
 
@@ -359,7 +360,7 @@ export class BST<
    * successfully inserted into the data structure.
    */
   override addMany(
-    keysNodesEntriesOrRaws: Iterable<R | BTNRep<K, V, NODE>>,
+    keysNodesEntriesOrRaws: Iterable<R | BTNRep<K, V, BSTNode<K, V>>>,
     values?: Iterable<V | undefined>,
     isBalanceAdd = true,
     iterationType: IterationType = this.iterationType
@@ -373,15 +374,16 @@ export class BST<
     }
 
     if (!isBalanceAdd) {
-      for (const kve of keysNodesEntriesOrRaws) {
+      for (let kve of keysNodesEntriesOrRaws) {
         const value = valuesIterator?.next().value;
+        if (this.isRaw(kve)) kve = this._toEntryFn!(kve);
         inserted.push(this.add(kve, value));
       }
       return inserted;
     }
 
     const realBTNExemplars: {
-      key: R | BTNRep<K, V, NODE>;
+      key: R | BTNRep<K, V, BSTNode<K, V>>;
       value: V | undefined;
       orgIndex: number;
     }[] = [];
@@ -392,23 +394,21 @@ export class BST<
       i++;
     }
 
-    let sorted: { key: R | BTNRep<K, V, NODE>; value: V | undefined; orgIndex: number }[] = [];
+    let sorted: { key: R | BTNRep<K, V, BSTNode<K, V>>; value: V | undefined; orgIndex: number }[] = [];
 
     sorted = realBTNExemplars.sort(({ key: a }, { key: b }) => {
       let keyA: K | undefined | null, keyB: K | undefined | null;
-      if (this.isEntry(a)) keyA = a[0];
+      if (this.isRaw(a)) keyA = this._toEntryFn!(a)[0];
+      else if (this.isEntry(a)) keyA = a[0];
       else if (this.isRealNode(a)) keyA = a.key;
-      else if (this._toEntryFn) {
-        keyA = this._toEntryFn(a as R)[0];
-      } else {
+      else {
         keyA = a as K;
       }
 
-      if (this.isEntry(b)) keyB = b[0];
+      if (this.isRaw(b)) keyB = this._toEntryFn!(b)[0];
+      else if (this.isEntry(b)) keyB = b[0];
       else if (this.isRealNode(b)) keyB = b.key;
-      else if (this._toEntryFn) {
-        keyB = this._toEntryFn(b as R)[0];
-      } else {
+      else {
         keyB = b as K;
       }
 
@@ -418,11 +418,17 @@ export class BST<
       return 0;
     });
 
-    const _dfs = (arr: { key: R | BTNRep<K, V, NODE>; value: V | undefined; orgIndex: number }[]) => {
+    const _dfs = (arr: { key: R | BTNRep<K, V, BSTNode<K, V>>; value: V | undefined; orgIndex: number }[]) => {
       if (arr.length === 0) return;
 
       const mid = Math.floor((arr.length - 1) / 2);
-      const { key, value, orgIndex } = arr[mid];
+      let { key, value } = arr[mid];
+      const { orgIndex } = arr[mid];
+      if (this.isRaw(key)) {
+        const entry = this._toEntryFn!(key);
+        key = entry[0];
+        value = entry[1] ?? value;
+      }
       inserted[orgIndex] = this.add(key, value);
       _dfs(arr.slice(0, mid));
       _dfs(arr.slice(mid + 1));
@@ -437,7 +443,13 @@ export class BST<
           const [l, r] = popped;
           if (l <= r) {
             const m = l + Math.floor((r - l) / 2);
-            const { key, value, orgIndex } = sorted[m];
+            let { key, value } = sorted[m];
+            const { orgIndex } = sorted[m];
+            if (this.isRaw(key)) {
+              const entry = this._toEntryFn!(key);
+              key = entry[0];
+              value = entry[1] ?? value;
+            }
             inserted[orgIndex] = this.add(key, value);
             stack.push([m + 1, r]);
             stack.push([l, m - 1]);
@@ -455,36 +467,23 @@ export class BST<
     return inserted;
   }
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(1)
-   *
-   * The `merge` function overrides the base class method by adding elements from another
-   * binary search tree.
-   * @param anotherTree - `anotherTree` is an instance of a Binary Search Tree (BST) with key type `K`,
-   * value type `V`, return type `R`, node type `NODE`, and tree type `TREE`.
-   */
-  override merge(anotherTree: BST<K, V, R, NODE, TREE>) {
-    this.addMany(anotherTree, [], false);
-  }
-
   /**
    * Time Complexity: O(log n)
    * Space Complexity: O(k + log n)
    *
    * The function `search` in TypeScript overrides the search behavior in a binary tree structure based
    * on specified criteria.
-   * @param {BTNRep<K, V, NODE> | R | NodePredicate<NODE>} keyNodeEntryRawOrPredicate - The
-   * `keyNodeEntryRawOrPredicate` parameter in the `override search` method can accept one of the
+   * @param {BTNRep<K, V, BSTNode<K, V>> | NodePredicate<BSTNode<K, V>>} keyNodeEntryOrPredicate - The
+   * `keyNodeEntryOrPredicate` parameter in the `override search` method can accept one of the
    * following types:
    * @param [onlyOne=false] - The `onlyOne` parameter is a boolean flag that determines whether the
    * search should stop after finding the first matching node. If `onlyOne` is set to `true`, the
    * search will return as soon as a matching node is found. If `onlyOne` is set to `false`, the
    * @param {C} callback - The `callback` parameter in the `override search` function is a function
    * that will be called on each node that matches the search criteria. It is of type `C`, which
-   * extends `NodeCallback<NODE>`. The callback function should accept a node of type `NODE` as its
+   * extends `NodeCallback<BSTNode<K, V>>`. The callback function should accept a node of type `BSTNode<K, V>` as its
    * argument and
-   * @param {BTNRep<K, V, NODE> | R} startNode - The `startNode` parameter in the `override search`
+   * @param {BTNRep<K, V, BSTNode<K, V>>} startNode - The `startNode` parameter in the `override search`
    * method represents the node from which the search operation will begin. It is the starting point
    * for searching within the tree data structure. The method ensures that the `startNode` is a valid
    * node before proceeding with the search operation. If the `
@@ -496,29 +495,29 @@ export class BST<
    * structure based on the provided key, predicate, and other options. The search results are
    * collected in an array and returned as the output of the method.
    */
-  override search<C extends NodeCallback<NODE>>(
-    keyNodeEntryRawOrPredicate: BTNRep<K, V, NODE> | R | NodePredicate<NODE> | Range<K>,
+  override search<C extends NodeCallback<BSTNode<K, V>>>(
+    keyNodeEntryOrPredicate: BTNRep<K, V, BSTNode<K, V>> | NodePredicate<BSTNode<K, V>> | Range<K>,
     onlyOne = false,
     callback: C = this._DEFAULT_NODE_CALLBACK as C,
-    startNode: BTNRep<K, V, NODE> | R = this._root,
+    startNode: BTNRep<K, V, BSTNode<K, V>> = this._root,
     iterationType: IterationType = this.iterationType
   ): ReturnType<C>[] {
-    if (keyNodeEntryRawOrPredicate === undefined) return [];
-    if (keyNodeEntryRawOrPredicate === null) return [];
+    if (keyNodeEntryOrPredicate === undefined) return [];
+    if (keyNodeEntryOrPredicate === null) return [];
     startNode = this.ensureNode(startNode);
     if (!startNode) return [];
-    let predicate: NodePredicate<NODE>;
+    let predicate: NodePredicate<BSTNode<K, V>>;
 
-    const isRange = this.isRange(keyNodeEntryRawOrPredicate);
+    const isRange = this.isRange(keyNodeEntryOrPredicate);
     // Set predicate based on parameter type
     if (isRange) {
-      predicate = node => keyNodeEntryRawOrPredicate.isInRange(node.key, this._comparator);
+      predicate = node => keyNodeEntryOrPredicate.isInRange(node.key, this._comparator);
     } else {
-      predicate = this._ensurePredicate(keyNodeEntryRawOrPredicate);
+      predicate = this._ensurePredicate(keyNodeEntryOrPredicate);
     }
-    const isToLeftByRange = (cur: NODE) => {
+    const isToLeftByRange = (cur: BSTNode<K, V>) => {
       if (isRange) {
-        const range = keyNodeEntryRawOrPredicate;
+        const range = keyNodeEntryOrPredicate;
         const leftS = this.isReverse ? range.high : range.low;
         const leftI = this.isReverse ? range.includeHigh : range.includeLow;
         return (leftI && this._compare(cur.key, leftS) >= 0) || (!leftI && this._compare(cur.key, leftS) > 0);
@@ -526,9 +525,9 @@ export class BST<
       return false;
     };
 
-    const isToRightByRange = (cur: NODE) => {
+    const isToRightByRange = (cur: BSTNode<K, V>) => {
       if (isRange) {
-        const range = keyNodeEntryRawOrPredicate;
+        const range = keyNodeEntryOrPredicate;
         const rightS = this.isReverse ? range.low : range.high;
         const rightI = this.isReverse ? range.includeLow : range.includeLow;
 
@@ -538,7 +537,7 @@ export class BST<
     };
     const ans: ReturnType<C>[] = [];
     if (iterationType === 'RECURSIVE') {
-      const dfs = (cur: NODE) => {
+      const dfs = (cur: BSTNode<K, V>) => {
         if (predicate(cur)) {
           ans.push(callback(cur));
           if (onlyOne) return;
@@ -549,8 +548,8 @@ export class BST<
         if (isRange) {
           if (this.isRealNode(cur.left) && isToLeftByRange(cur)) dfs(cur.left);
           if (this.isRealNode(cur.right) && isToRightByRange(cur)) dfs(cur.right);
-        } else if (!this._isPredicate(keyNodeEntryRawOrPredicate)) {
-          const benchmarkKey = this._extractKey(keyNodeEntryRawOrPredicate);
+        } else if (!this._isPredicate(keyNodeEntryOrPredicate)) {
+          const benchmarkKey = this._extractKey(keyNodeEntryOrPredicate);
           if (
             this.isRealNode(cur.left) &&
             benchmarkKey !== null &&
@@ -583,8 +582,8 @@ export class BST<
         if (isRange) {
           if (this.isRealNode(cur.left) && isToLeftByRange(cur)) stack.push(cur.left);
           if (this.isRealNode(cur.right) && isToRightByRange(cur)) stack.push(cur.right);
-        } else if (!this._isPredicate(keyNodeEntryRawOrPredicate)) {
-          const benchmarkKey = this._extractKey(keyNodeEntryRawOrPredicate);
+        } else if (!this._isPredicate(keyNodeEntryOrPredicate)) {
+          const benchmarkKey = this._extractKey(keyNodeEntryOrPredicate);
           if (
             this.isRealNode(cur.right) &&
             benchmarkKey !== null &&
@@ -611,12 +610,43 @@ export class BST<
 
   /**
    * Time Complexity: O(log n)
-   * Space Complexity: O(1)
+   * Space Complexity: O(k + log n)
+   *
+   * The `rangeSearch` function searches for nodes within a specified range in a binary search tree.
+   * @param {Range<K> | [K, K]} range - The `range` parameter in the `rangeSearch` function can be
+   * either a `Range` object or an array of two elements representing the range boundaries.
+   * @param {C} callback - The `callback` parameter in the `rangeSearch` function is a callback
+   * function that is used to process each node that is found within the specified range during the
+   * search operation. It is of type `NodeCallback<BSTNode<K, V>>`, where `BSTNode<K, V>` is the type of nodes in the
+   * data structure.
+   * @param {BTNRep<K, V, BSTNode<K, V>>} startNode - The `startNode` parameter in the `rangeSearch`
+   * function represents the node from which the search for nodes within the specified range will
+   * begin. It is the starting point for the range search operation.
+   * @param {IterationType} iterationType - The `iterationType` parameter in the `rangeSearch` function
+   * is used to specify the type of iteration to be performed during the search operation. It has a
+   * default value of `this.iterationType`, which suggests that it is likely a property of the class or
+   * object that the `rangeSearch`
+   * @returns The `rangeSearch` function is returning the result of calling the `search` method with
+   * the specified parameters.
+   */
+  rangeSearch<C extends NodeCallback<BSTNode<K, V>>>(
+    range: Range<K> | [K, K],
+    callback: C = this._DEFAULT_NODE_CALLBACK as C,
+    startNode: BTNRep<K, V, BSTNode<K, V>> = this._root,
+    iterationType: IterationType = this.iterationType
+  ) {
+    const searchRange: Range<K> = range instanceof Range ? range : new Range(range[0], range[1]);
+    return this.search(searchRange, false, callback, startNode, iterationType);
+  }
+
+  /**
+   * Time Complexity: O(log n)
+   * Space Complexity: O(log n)
    *
-   * This function retrieves a node based on a given keyNodeEntryRawOrPredicate within a binary search tree structure.
-   * @param {BTNRep<K, V, NODE> | R | NodePredicate<NODE>} keyNodeEntryRawOrPredicate - The `keyNodeEntryRawOrPredicate`
-   * parameter can be of type `BTNRep<K, V, NODE>`, `R`, or `NodePredicate<NODE>`.
-   * @param {R | BSTNOptKeyOrNode<K, NODE>} startNode - The `startNode` parameter in the `getNode` method
+   * This function retrieves a node based on a given keyNodeEntryOrPredicate within a binary search tree structure.
+   * @param {BTNRep<K, V, BSTNode<K, V>> | NodePredicate<BSTNode<K, V>>} keyNodeEntryOrPredicate - The `keyNodeEntryOrPredicate`
+   * parameter can be of type `BTNRep<K, V, BSTNode<K, V>>`, `R`, or `NodePredicate<BSTNode<K, V>>`.
+   * @param {BSTNOptKeyOrNode<K, BSTNode<K, V>>} startNode - The `startNode` parameter in the `getNode` method
    * is used to specify the starting point for searching nodes in the binary search tree. If no
    * specific starting point is provided, the default value is set to `this._root`, which is the root
    * node of the binary search tree.
@@ -624,17 +654,17 @@ export class BST<
    * parameter that specifies the type of iteration to be used. It has a default value of
    * `this.iterationType`, which means it will use the iteration type defined in the class instance if
    * no value is provided when calling the method.
-   * @returns The `getNode` method is returning an optional binary search tree node (`OptNode<NODE>`).
-   * It is using the `getNodes` method to find the node based on the provided keyNodeEntryRawOrPredicate, beginning at
+   * @returns The `getNode` method is returning an optional binary search tree node (`OptNode<BSTNode<K, V>>`).
+   * It is using the `getNodes` method to find the node based on the provided keyNodeEntryOrPredicate, beginning at
    * the specified root node (`startNode`) and using the specified iteration type. The method then
    * returns the first node found or `undefined` if no node is found.
    */
   override getNode(
-    keyNodeEntryRawOrPredicate: BTNRep<K, V, NODE> | R | NodePredicate<NODE>,
-    startNode: R | BSTNOptKeyOrNode<K, NODE> = this._root,
+    keyNodeEntryOrPredicate: BTNRep<K, V, BSTNode<K, V>> | NodePredicate<BSTNode<K, V>>,
+    startNode: BSTNOptKeyOrNode<K, BSTNode<K, V>> = this._root,
     iterationType: IterationType = this.iterationType
-  ): OptNode<NODE> {
-    return this.getNodes(keyNodeEntryRawOrPredicate, true, startNode, iterationType)[0] ?? undefined;
+  ): OptNode<BSTNode<K, V>> {
+    return this.getNodes(keyNodeEntryOrPredicate, true, startNode, iterationType)[0] ?? undefined;
   }
 
   /**
@@ -649,7 +679,7 @@ export class BST<
    * @param {DFSOrderPattern} [pattern=IN] - The "pattern" parameter in the code snippet refers to the
    * order in which the Depth-First Search (DFS) algorithm visits the nodes in a tree or graph. It can
    * take one of the following values:
-   * @param {BTNRep<K, V, NODE> | R} startNode - The `startNode` parameter is the starting
+   * @param {BTNRep<K, V, BSTNode<K, V>>} startNode - The `startNode` parameter is the starting
    * point for the depth-first search traversal. It can be either a root node, a key-value pair, or a
    * node entry. If not specified, the default value is the root of the tree.
    * @param {IterationType} [iterationType=ITERATIVE] - The `iterationType` parameter specifies the
@@ -657,10 +687,10 @@ export class BST<
    * following values:
    * @returns The method is returning an array of the return type of the callback function.
    */
-  override dfs<C extends NodeCallback<NODE>>(
+  override dfs<C extends NodeCallback<BSTNode<K, V>>>(
     callback: C = this._DEFAULT_NODE_CALLBACK as C,
     pattern: DFSOrderPattern = 'IN',
-    startNode: BTNRep<K, V, NODE> | R = this._root,
+    startNode: BTNRep<K, V, BSTNode<K, V>> = this._root,
     iterationType: IterationType = this.iterationType
   ): ReturnType<C>[] {
     return super.dfs(callback, pattern, startNode, iterationType);
@@ -675,7 +705,7 @@ export class BST<
    * @param {C} callback - The `callback` parameter is a function that will be called for each node
    * visited during the breadth-first search. It should take a single argument, which is the current
    * node being visited, and it can return a value of any type.
-   * @param {BTNRep<K, V, NODE> | R} startNode - The `startNode` parameter is the starting
+   * @param {BTNRep<K, V, BSTNode<K, V>>} startNode - The `startNode` parameter is the starting
    * point for the breadth-first search. It can be either a root node, a key-value pair, or an entry
    * object. If no value is provided, the default value is the root of the tree.
    * @param {IterationType} iterationType - The `iterationType` parameter is used to specify the type
@@ -683,9 +713,9 @@ export class BST<
    * the following values:
    * @returns an array of the return type of the callback function.
    */
-  override bfs<C extends NodeCallback<NODE>>(
+  override bfs<C extends NodeCallback<BSTNode<K, V>>>(
     callback: C = this._DEFAULT_NODE_CALLBACK as C,
-    startNode: BTNRep<K, V, NODE> | R = this._root,
+    startNode: BTNRep<K, V, BSTNode<K, V>> = this._root,
     iterationType: IterationType = this.iterationType
   ): ReturnType<C>[] {
     return super.bfs(callback, startNode, iterationType, false);
@@ -698,9 +728,9 @@ export class BST<
    * The function overrides the listLevels method from the superclass and returns an array of arrays
    * containing the results of the callback function applied to each level of the tree.
    * @param {C} callback - The `callback` parameter is a generic type `C` that extends
-   * `NodeCallback<NODE>`. It represents a callback function that will be called for each node in the
+   * `NodeCallback<BSTNode<K, V>>`. It represents a callback function that will be called for each node in the
    * tree during the iteration process.
-   * @param {BTNRep<K, V, NODE> | R} startNode - The `startNode` parameter is the starting
+   * @param {BTNRep<K, V, BSTNode<K, V>>} startNode - The `startNode` parameter is the starting
    * point for listing the levels of the binary tree. It can be either a root node of the tree, a
    * key-value pair representing a node in the tree, or a key representing a node in the tree. If no
    * value is provided, the root of
@@ -709,9 +739,9 @@ export class BST<
    * @returns The method is returning a two-dimensional array of the return type of the callback
    * function.
    */
-  override listLevels<C extends NodeCallback<NODE>>(
+  override listLevels<C extends NodeCallback<BSTNode<K, V>>>(
     callback: C = this._DEFAULT_NODE_CALLBACK as C,
-    startNode: BTNRep<K, V, NODE> | R = this._root,
+    startNode: BTNRep<K, V, BSTNode<K, V>> = this._root,
     iterationType: IterationType = this.iterationType
   ): ReturnType<C>[][] {
     return super.listLevels(callback, startNode, iterationType, false);
@@ -729,7 +759,7 @@ export class BST<
    * @param {CP} lesserOrGreater - The `lesserOrGreater` parameter is used to determine whether to
    * traverse nodes that are lesser, greater, or both than the `targetNode`. It accepts the values -1,
    * 0, or 1, where:
-   * @param {BTNRep<K, V, NODE> | R} targetNode - The `targetNode` parameter is the node in
+   * @param {BTNRep<K, V, BSTNode<K, V>>} targetNode - The `targetNode` parameter is the node in
    * the binary tree that you want to start traversing from. It can be specified either by providing
    * the key of the node, the node itself, or an entry containing the key and value of the node. If no
    * `targetNode` is provided,
@@ -738,21 +768,21 @@ export class BST<
    * @returns The function `lesserOrGreaterTraverse` returns an array of values of type
    * `ReturnType<C>`, which is the return type of the callback function passed as an argument.
    */
-  lesserOrGreaterTraverse<C extends NodeCallback<NODE>>(
+  lesserOrGreaterTraverse<C extends NodeCallback<BSTNode<K, V>>>(
     callback: C = this._DEFAULT_NODE_CALLBACK as C,
     lesserOrGreater: CP = -1,
-    targetNode: BTNRep<K, V, NODE> | R = this._root,
+    targetNode: BTNRep<K, V, BSTNode<K, V>> = this._root,
     iterationType: IterationType = this.iterationType
   ): ReturnType<C>[] {
     const targetNodeEnsured = this.ensureNode(targetNode);
-    const ans: ReturnType<NodeCallback<NODE>>[] = [];
+    const ans: ReturnType<NodeCallback<BSTNode<K, V>>>[] = [];
     if (!this._root) return ans;
     if (!targetNodeEnsured) return ans;
 
     const targetKey = targetNodeEnsured.key;
 
     if (iterationType === 'RECURSIVE') {
-      const dfs = (cur: NODE) => {
+      const dfs = (cur: BSTNode<K, V>) => {
         const compared = this._compare(cur.key, targetKey);
         if (Math.sign(compared) === lesserOrGreater) ans.push(callback(cur));
         // TODO here can be optimized to O(log n)
@@ -763,7 +793,7 @@ export class BST<
       dfs(this._root);
       return ans;
     } else {
-      const queue = new Queue<NODE>([this._root]);
+      const queue = new Queue<BSTNode<K, V>>([this._root]);
       while (queue.size > 0) {
         const cur = queue.shift();
         if (this.isRealNode(cur)) {
@@ -847,7 +877,7 @@ export class BST<
     let balanced = true;
 
     if (iterationType === 'RECURSIVE') {
-      const _height = (cur: OptNode<NODE>): number => {
+      const _height = (cur: OptNodeOrNull<BSTNode<K, V>>): number => {
         if (!cur) return 0;
         const leftHeight = _height(cur.left),
           rightHeight = _height(cur.right);
@@ -856,15 +886,15 @@ export class BST<
       };
       _height(this._root);
     } else {
-      const stack: NODE[] = [];
-      let node: OptNode<NODE> = this._root,
-        last: OptNode<NODE> = undefined;
-      const depths: Map<NODE, number> = new Map();
+      const stack: BSTNode<K, V>[] = [];
+      let node: OptNode<BSTNode<K, V>> = this._root,
+        last: OptNode<BSTNode<K, V>> = undefined;
+      const depths: Map<BSTNode<K, V>, number> = new Map();
 
       while (stack.length > 0 || node) {
         if (node) {
           stack.push(node);
-          node = node.left;
+          if (node.left !== null) node = node.left;
         } else {
           node = stack[stack.length - 1];
           if (!node.right || last === node.right) {
@@ -885,57 +915,102 @@ export class BST<
     return balanced;
   }
 
-  protected _comparator: Comparator<K> = (a: K, b: K): number => {
-    if (isComparable(a) && isComparable(b)) {
-      if (a > b) return 1;
-      if (a < b) return -1;
-      return 0;
-    }
-    if (this._extractComparable) {
-      if (this._extractComparable(a) > this._extractComparable(b)) return 1;
-      if (this._extractComparable(a) < this._extractComparable(b)) return -1;
-      return 0;
-    }
-    if (typeof a === 'object' || typeof b === 'object') {
-      throw TypeError(
-        `When comparing object types, a custom extractComparable must be defined in the constructor's options parameter.`
-      );
+  /**
+   * Time complexity: O(n)
+   * Space complexity: O(n)
+   *
+   * The `map` function in TypeScript overrides the default map behavior for a binary search tree by
+   * applying a callback function to each entry and creating a new tree with the results.
+   * @param callback - A function that will be called for each entry in the BST. It takes four
+   * arguments: the key, the value (which can be undefined), the index of the entry, and a reference to
+   * the BST itself.
+   * @param [options] - The `options` parameter in the `override map` method is of type `BSTOptions<MK,
+   * MV, MR>`. It is an optional parameter that allows you to specify additional options for the Binary
+   * Search Tree (BST) being created in the `map` method. These options could include configuration
+   * @param {any} [thisArg] - The `thisArg` parameter in the `override map` method is used to specify
+   * the value of `this` that should be used when executing the `callback` function. It allows you to
+   * set the context or scope in which the callback function will be called. This can be useful when
+   * you want
+   * @returns The `map` method is returning a new Binary Search Tree (`BST`) instance with the entries
+   * transformed by the provided callback function.
+   */
+  override map(
+    callback: EntryCallback<K, V | undefined, [MK, MV]>,
+    options?: BSTOptions<MK, MV, MR>,
+    thisArg?: any
+  ): BST<MK, MV, MR> {
+    const newTree = new BST<MK, MV, MR>([], options);
+    let index = 0;
+    for (const [key, value] of this) {
+      newTree.add(callback.call(thisArg, key, value, index++, this));
     }
-
-    return 0;
-  };
+    return newTree;
+  }
 
   /**
-   * The function returns the value of the _comparator property.
-   * @returns The `_comparator` property is being returned.
+   * Time complexity: O(n)
+   * Space complexity: O(n)
+   *
+   * The function `clone` overrides the default cloning behavior to create a deep copy of a tree
+   * structure.
+   * @returns The `cloned` object is being returned.
    */
-  get comparator() {
-    return this._comparator;
+  override clone() {
+    const cloned = this.createTree();
+    this._clone(cloned);
+    return cloned;
   }
 
-  protected _extractComparable?: (key: K) => Comparable;
-
   /**
-   * This function returns the value of the `_extractComparable` property.
-   * @returns The method `extractComparable()` is being returned, which is a getter method for the
-   * `_extractComparable` property.
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The function overrides a method and converts a key, value pair or entry or raw element to a node.
+   * @param {BTNRep<K, V, BSTNode<K, V>>} keyNodeOrEntry - A variable that can be of
+   * type R or BTNRep<K, V, BSTNode<K, V>>. It represents either a key, a node, an entry, or a raw
+   * element.
+   * @param {V} [value] - The `value` parameter is an optional value of type `V`. It represents the
+   * value associated with a key in a key-value pair.
+   * @returns either a BSTNode<K, V> object or undefined.
    */
-  get extractComparable() {
-    return this._extractComparable;
+  protected override _keyValueNodeOrEntryToNodeAndValue(
+    keyNodeOrEntry: BTNRep<K, V, BSTNode<K, V>>,
+    value?: V
+  ): [OptNode<BSTNode<K, V>>, V | undefined] {
+    const [node, entryValue] = super._keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry, value);
+    if (node === null) return [undefined, undefined];
+    return [node, value ?? entryValue];
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The function sets the root of a tree-like structure and updates the parent property of the new
    * root.
-   * @param {OptNode<NODE>} v - v is a parameter of type NODE or undefined.
+   * @param {OptNode<BSTNode<K, V>>} v - v is a parameter of type BSTNode<K, V> or undefined.
    */
-  protected override _setRoot(v: OptNode<NODE>) {
+  protected override _setRoot(v: OptNode<BSTNode<K, V>>) {
     if (v) {
       v.parent = undefined;
     }
     this._root = v;
   }
 
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The _compare function compares two values using a specified comparator function and optionally
+   * reverses the result.
+   * @param {K} a - The parameter `a` is of type `K`, which is used as an input for comparison in the
+   * `_compare` method.
+   * @param {K} b - The parameter `b` in the `_compare` function is of type `K`.
+   * @returns The `_compare` method is returning the result of the ternary expression. If `_isReverse`
+   * is true, it returns the negation of the result of calling the `_comparator` function with
+   * arguments `a` and `b`. If `_isReverse` is false, it returns the result of calling the
+   * `_comparator` function with arguments `a` and `b`.
+   */
   protected _compare(a: K, b: K) {
     return this._isReverse ? -this._comparator(a, b) : this._comparator(a, b);
   }