doubly-linked-list-typed 1.53.9 → 1.54.1

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

@@ -5,8 +5,7 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import {
-  BSTNodeNested,
+import type {
   BSTNOptKeyOrNode,
   BSTOptions,
   BTNRep,
@@ -18,7 +17,8 @@ import {
   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;
   }
@@ -151,19 +134,20 @@ export class BSTNode<K = any, V = any, NODE extends BSTNode<K, V, NODE> = BSTNod
  *     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>>>
-  extends BinaryTree<K, V, R, NODE>
-  implements IBinaryTree<K, V, R, NODE>
+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) {
@@ -175,23 +159,14 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
     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;
   }
@@ -216,51 +191,43 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
     return 0;
   };
 
-  /**
-   * The function returns the value of the _comparator property.
-   * @returns The `_comparator` property is being returned.
-   */
   get comparator() {
     return this._comparator;
   }
 
   protected _specifyComparable?: (key: K) => Comparable;
 
-  /**
-   * This function returns the value of the `_specifyComparable` property.
-   * @returns The method `specifyComparable()` is being returned, which is a getter method for the
-   * `_specifyComparable` property.
-   */
   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 `createTree` function in TypeScript overrides the default options with the provided options to
-   * create a new Binary Search Tree.
-   * @param [options] - The `options` parameter in the `createTree` method is an optional object that
-   * can contain the following properties:
-   * @returns A new instance of a Binary Search Tree (BST) is being returned with the specified options
-   * and properties inherited from the current instance.
+   * 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.
    */
-  // @ts-ignore
   override createTree(options?: BSTOptions<K, V, R>) {
-    return new BST<K, V, R>([], {
+    return new BST<K, V, R, MK, MV, MR>([], {
       iterationType: this.iterationType,
       isMapMode: this._isMapMode,
       specifyComparable: this._specifyComparable,
@@ -276,8 +243,8 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
    *
    * 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
@@ -286,48 +253,54 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
    * 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 {
+  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) {
@@ -350,7 +323,7 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
           this._size++;
           return true;
         }
-        current = current.left;
+        if (current.left !== null) current = current.left;
       } else {
         if (current.right === undefined) {
           current.right = newNode;
@@ -358,7 +331,7 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
           this._size++;
           return true;
         }
-        current = current.right;
+        if (current.right !== null) current = current.right;
       }
     }
 
@@ -387,7 +360,7 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
    * 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
@@ -401,15 +374,16 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
     }
 
     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;
     }[] = [];
@@ -420,23 +394,21 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
       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;
       }
 
@@ -446,11 +418,17 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
       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));
@@ -465,7 +443,13 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
           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]);
@@ -483,36 +467,23 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
     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: this) {
-    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 `
@@ -524,29 +495,29 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
    * 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);
@@ -554,9 +525,9 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
       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;
 
@@ -566,7 +537,7 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
     };
     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;
@@ -577,8 +548,8 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
         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 &&
@@ -611,8 +582,8 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
         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 &&
@@ -639,16 +610,16 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
 
   /**
    * Time Complexity: O(log n)
-   * Space Complexity: O(n)
+   * 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<NODE>`, where `NODE` is the type of nodes in 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, NODE> | R} startNode - The `startNode` parameter in the `rangeSearch`
+   * @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
@@ -658,10 +629,10 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
    * @returns The `rangeSearch` function is returning the result of calling the `search` method with
    * the specified parameters.
    */
-  rangeSearch<C extends NodeCallback<NODE>>(
+  rangeSearch<C extends NodeCallback<BSTNode<K, V>>>(
     range: Range<K> | [K, K],
     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
   ) {
     const searchRange: Range<K> = range instanceof Range ? range : new Range(range[0], range[1]);
@@ -670,12 +641,12 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
 
   /**
    * Time Complexity: O(log n)
-   * Space Complexity: O(1)
+   * 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.
@@ -683,17 +654,17 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
    * 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;
   }
 
   /**
@@ -708,7 +679,7 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
    * @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
@@ -716,10 +687,10 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
    * 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);
@@ -734,7 +705,7 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
    * @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
@@ -742,9 +713,9 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
    * 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);
@@ -757,9 +728,9 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
    * 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
@@ -768,9 +739,9 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
    * @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);
@@ -788,7 +759,7 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
    * @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,
@@ -797,21 +768,21 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
    * @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)
@@ -822,7 +793,7 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
       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)) {
@@ -906,7 +877,7 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
     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);
@@ -915,15 +886,15 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
       };
       _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) {
@@ -944,12 +915,30 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
     return balanced;
   }
 
-  // @ts-ignore
-  override map<MK, MV, MR>(
+  /**
+   * 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) {
@@ -959,35 +948,69 @@ export class BST<K = any, V = any, R = object, NODE extends BSTNode<K, V, NODE>
   }
 
   /**
+   * 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.
+   */
+  override clone() {
+    const cloned = this.createTree();
+    this._clone(cloned);
+    return cloned;
+  }
+
+  /**
+   * 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, 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
+   * @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 NODE object or undefined.
+   * @returns either a BSTNode<K, V> object or undefined.
    */
-  protected override _keyValueNodeEntryRawToNodeAndValue(
-    keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R,
+  protected override _keyValueNodeOrEntryToNodeAndValue(
+    keyNodeOrEntry: BTNRep<K, V, BSTNode<K, V>>,
     value?: V
-  ): [OptNode<NODE>, V | undefined] {
-    const [node, entryValue] = super._keyValueNodeEntryRawToNodeAndValue(keyNodeEntryOrRaw, value);
+  ): [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);
   }