red-black-tree-typed 1.53.6 → 1.54.1

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

@@ -6,79 +6,64 @@
  * @license MIT License
  */
 import type {
-  BSTNested,
-  BSTNodeNested,
   BSTNOptKeyOrNode,
   BSTOptions,
   BTNRep,
+  Comparable,
   Comparator,
   CP,
   DFSOrderPattern,
+  EntryCallback,
   IterationType,
   NodeCallback,
   NodePredicate,
-  OptNode
+  OptNode,
+  OptNodeOrNull
 } from '../../types';
 import { BinaryTree, BinaryTreeNode } from './binary-tree';
 import { IBinaryTree } from '../../interfaces';
 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;
   }
@@ -92,91 +77,164 @@ export class BSTNode<K = any, V = any, NODE extends BSTNode<K, V, NODE> = BSTNod
  * 5. Logarithmic Operations: Ideal operations like insertion, deletion, and searching are O(log n) time-efficient.
  * 6. Balance Variability: Can become unbalanced; special types maintain balance.
  * 7. No Auto-Balancing: Standard BSTs don't automatically balance themselves.
+ * @example
+ * // 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']
+ *     ]);
+ *
+ *     // Merge datasets into a single BinarySearchTree
+ *     const merged = new BST<number, string>(dataset1);
+ *     merged.addMany(dataset2);
+ *     merged.merge(dataset3);
+ *
+ *     // 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.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.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) {
+ *           return num;
+ *         }
+ *       }
+ *       return undefined;
+ *     }
+ *
+ *     // 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 { comparator } = options;
-      if (comparator) this._comparator = comparator;
+      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;
+
+  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,
-      comparator: this._comparator,
+      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];
+    });
   }
 
   /**
@@ -185,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
@@ -195,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
-   * the result of the `isComparable` function with the condition `this.comparator !==
+   * @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.comparator !== this._DEFAULT_COMPARATOR);
+  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) {
@@ -248,18 +312,18 @@ export class BST<
 
     let current = this._root;
     while (current !== undefined) {
-      if (this.comparator(current.key, newNode.key) === 0) {
+      if (this._compare(current.key, newNode.key) === 0) {
         this._replaceNode(current, newNode);
         if (this._isMapMode) this._setValue(current.key, newValue);
         return true;
-      } else if (this.comparator(current.key, newNode.key) > 0) {
+      } else if (this._compare(current.key, newNode.key) > 0) {
         if (current.left === undefined) {
           current.left = newNode;
           if (this._isMapMode) this._setValue(newNode?.key, newValue);
           this._size++;
           return true;
         }
-        current = current.left;
+        if (current.left !== null) current = current.left;
       } else {
         if (current.right === undefined) {
           current.right = newNode;
@@ -267,7 +331,7 @@ export class BST<
           this._size++;
           return true;
         }
-        current = current.right;
+        if (current.right !== null) current = current.right;
       }
     }
 
@@ -296,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
@@ -310,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;
     }[] = [];
@@ -329,37 +394,41 @@ 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;
       }
 
       if (keyA !== undefined && keyA !== null && keyB !== undefined && keyB !== null) {
-        return this.comparator(keyA, keyB);
+        return this._compare(keyA, keyB);
       }
       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));
@@ -374,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]);
@@ -396,60 +471,97 @@ export class BST<
    * Time Complexity: O(log n)
    * Space Complexity: O(k + log n)
    *
-   * The function `getNodes` in TypeScript overrides the base class method to retrieve nodes based on a
-   * given keyNodeEntryRawOrPredicate and iteration type.
-   * @param {BTNRep<K, V, NODE> | R | NodePredicate<NODE>} keyNodeEntryRawOrPredicate - The `keyNodeEntryRawOrPredicate`
-   * parameter in the `getNodes` method is used to filter the nodes that will be returned. It can be a
-   * key, a node, an entry, or a custom keyNodeEntryRawOrPredicate function that determines whether a node should be
-   * included in the result.
-   * @param [onlyOne=false] - The `onlyOne` parameter in the `getNodes` method is a boolean flag that
-   * determines whether to return only the first node that matches the keyNodeEntryRawOrPredicate (`true`) or all nodes
-   * that match the keyNodeEntryRawOrPredicate (`false`). If `onlyOne` is set to `true`, the method will stop iterating
-   * and
-   * @param {BTNRep<K, V, NODE> | R} startNode - The `startNode` parameter in the
-   * `getNodes` method is used to specify the starting point for traversing the tree when searching for
-   * nodes that match a given keyNodeEntryRawOrPredicate. It represents the root node of the subtree where the search
-   * should begin. If not explicitly provided, the default value for `begin
-   * @param {IterationType} iterationType - The `iterationType` parameter in the `getNodes` method
-   * specifies the type of iteration to be performed when traversing the nodes of a binary tree. It can
-   * have two possible values:
-   * @returns The `getNodes` method returns an array of nodes that satisfy the given keyNodeEntryRawOrPredicate.
+   * The function `search` in TypeScript overrides the search behavior in a binary tree structure based
+   * on specified criteria.
+   * @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<BSTNode<K, V>>`. The callback function should accept a node of type `BSTNode<K, V>` as its
+   * argument and
+   * @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 `
+   * @param {IterationType} iterationType - The `iterationType` parameter in the `override search`
+   * function determines the type of iteration to be used during the search operation. It can have two
+   * possible values:
+   * @returns The `override search` method returns an array of values that match the search criteria
+   * specified by the input parameters. The method performs a search operation on a binary tree
+   * 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 getNodes(
-    keyNodeEntryRawOrPredicate: BTNRep<K, V, NODE> | R | NodePredicate<NODE>,
+  override search<C extends NodeCallback<BSTNode<K, V>>>(
+    keyNodeEntryOrPredicate: BTNRep<K, V, BSTNode<K, V>> | NodePredicate<BSTNode<K, V>> | Range<K>,
     onlyOne = false,
-    startNode: BTNRep<K, V, NODE> | R = this._root,
+    callback: C = this._DEFAULT_NODE_CALLBACK as C,
+    startNode: BTNRep<K, V, BSTNode<K, V>> = this._root,
     iterationType: IterationType = this.iterationType
-  ): NODE[] {
-    if (keyNodeEntryRawOrPredicate === undefined) return [];
-    if (keyNodeEntryRawOrPredicate === null) return [];
+  ): ReturnType<C>[] {
+    if (keyNodeEntryOrPredicate === undefined) return [];
+    if (keyNodeEntryOrPredicate === null) return [];
     startNode = this.ensureNode(startNode);
     if (!startNode) return [];
-    const callback = this._ensurePredicate(keyNodeEntryRawOrPredicate);
-    const ans: NODE[] = [];
+    let predicate: NodePredicate<BSTNode<K, V>>;
 
+    const isRange = this.isRange(keyNodeEntryOrPredicate);
+    // Set predicate based on parameter type
+    if (isRange) {
+      predicate = node => keyNodeEntryOrPredicate.isInRange(node.key, this._comparator);
+    } else {
+      predicate = this._ensurePredicate(keyNodeEntryOrPredicate);
+    }
+    const isToLeftByRange = (cur: BSTNode<K, V>) => {
+      if (isRange) {
+        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);
+      }
+      return false;
+    };
+
+    const isToRightByRange = (cur: BSTNode<K, V>) => {
+      if (isRange) {
+        const range = keyNodeEntryOrPredicate;
+        const rightS = this.isReverse ? range.low : range.high;
+        const rightI = this.isReverse ? range.includeLow : range.includeLow;
+
+        return (rightI && this._compare(cur.key, rightS) <= 0) || (!rightI && this._compare(cur.key, rightS) < 0);
+      }
+      return false;
+    };
+    const ans: ReturnType<C>[] = [];
     if (iterationType === 'RECURSIVE') {
-      const dfs = (cur: NODE) => {
-        if (callback(cur)) {
-          ans.push(cur);
+      const dfs = (cur: BSTNode<K, V>) => {
+        if (predicate(cur)) {
+          ans.push(callback(cur));
           if (onlyOne) return;
         }
 
         if (!this.isRealNode(cur.left) && !this.isRealNode(cur.right)) return;
-        if (!this._isPredicate(keyNodeEntryRawOrPredicate)) {
-          const benchmarkKey = this._getKey(keyNodeEntryRawOrPredicate);
+
+        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(keyNodeEntryOrPredicate)) {
+          const benchmarkKey = this._extractKey(keyNodeEntryOrPredicate);
           if (
             this.isRealNode(cur.left) &&
             benchmarkKey !== null &&
             benchmarkKey !== undefined &&
-            this.comparator(cur.key, benchmarkKey) > 0
+            this._compare(cur.key, benchmarkKey) > 0
           )
             dfs(cur.left);
           if (
             this.isRealNode(cur.right) &&
             benchmarkKey !== null &&
             benchmarkKey !== undefined &&
-            this.comparator(cur.key, benchmarkKey) < 0
+            this._compare(cur.key, benchmarkKey) < 0
           )
             dfs(cur.right);
         } else {
@@ -463,24 +575,27 @@ export class BST<
       const stack = [startNode];
       while (stack.length > 0) {
         const cur = stack.pop()!;
-        if (callback(cur)) {
-          ans.push(cur);
+        if (predicate(cur)) {
+          ans.push(callback(cur));
           if (onlyOne) return ans;
         }
-        if (!this._isPredicate(keyNodeEntryRawOrPredicate)) {
-          const benchmarkKey = this._getKey(keyNodeEntryRawOrPredicate);
+        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(keyNodeEntryOrPredicate)) {
+          const benchmarkKey = this._extractKey(keyNodeEntryOrPredicate);
           if (
             this.isRealNode(cur.right) &&
             benchmarkKey !== null &&
             benchmarkKey !== undefined &&
-            this.comparator(cur.key, benchmarkKey) < 0
+            this._compare(cur.key, benchmarkKey) < 0
           )
             stack.push(cur.right);
           if (
             this.isRealNode(cur.left) &&
             benchmarkKey !== null &&
             benchmarkKey !== undefined &&
-            this.comparator(cur.key, benchmarkKey) > 0
+            this._compare(cur.key, benchmarkKey) > 0
           )
             stack.push(cur.left);
         } else {
@@ -495,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.
@@ -508,34 +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;
-  }
-
-  /**
-   * Time Complexity: O(log n)
-   * Space Complexity: O(1)
-   *
-   * The function `getNodeByKey` returns a node with a specific key from a tree data structure.
-   * @param {K} key - The key parameter is the value used to search for a specific node in the tree. It
-   * is typically a unique identifier or a value that can be used to determine the position of the node
-   * in the tree structure.
-   * @param {IterationType} [iterationType=ITERATIVE] - The `iterationType` parameter is an optional
-   * parameter that specifies the type of iteration to be used when searching for a node in the tree.
-   * It has a default value of `'ITERATIVE'`.
-   * @returns The method is returning a NODE object or undefined.
-   */
-  override getNodeByKey(key: K, iterationType: IterationType = this.iterationType): OptNode<NODE> {
-    return this.getNode(key, this._root, iterationType);
+  ): OptNode<BSTNode<K, V>> {
+    return this.getNodes(keyNodeEntryOrPredicate, true, startNode, iterationType)[0] ?? undefined;
   }
 
   /**
@@ -550,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
@@ -558,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);
@@ -576,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
@@ -584,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);
@@ -599,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
@@ -610,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);
@@ -630,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,
@@ -639,24 +768,24 @@ 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 compared = this.comparator(cur.key, targetKey);
+      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)
         if (this.isRealNode(cur.left)) dfs(cur.left);
         if (this.isRealNode(cur.right)) dfs(cur.right);
       };
@@ -664,11 +793,11 @@ 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)) {
-          const compared = this.comparator(cur.key, targetKey);
+          const compared = this._compare(cur.key, targetKey);
           if (Math.sign(compared) === lesserOrGreater) ans.push(callback(cur));
 
           if (this.isRealNode(cur.left)) queue.push(cur.left);
@@ -748,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);
@@ -757,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) {
@@ -786,36 +915,103 @@ export class BST<
     return balanced;
   }
 
-  protected _DEFAULT_COMPARATOR = (a: K, b: K): number => {
-    if (typeof a === 'object' || typeof b === 'object') {
-      throw TypeError(
-        `When comparing object types, a custom comparator 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));
     }
-    if (a > b) return 1;
-    if (a < b) return -1;
-    return 0;
-  };
+    return newTree;
+  }
 
-  protected _comparator: Comparator<K> = this._DEFAULT_COMPARATOR;
+  /**
+   * 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;
+  }
 
   /**
-   * The function returns the value of the _comparator property.
-   * @returns The `_comparator` property is being returned.
+   * 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 comparator() {
-    return this._comparator;
+  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);
+  }
 }