priority-queue-typed 1.47.6 → 1.47.7

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

@@ -5,8 +5,18 @@
  * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { BSTNested, BSTNodeNested, BSTOptions, BTNCallback, BTNKey, Comparator } from '../../types';
-import { CP, IterableEntriesOrKeys, IterationType } from '../../types';
+import type {
+  BSTNested,
+  BSTNodeKeyOrNode,
+  BSTNodeNested,
+  BSTOptions,
+  BTNCallback,
+  BTNKey,
+  BTNodeExemplar,
+  BTNodePureExemplar,
+  Comparator
+} from '../../types';
+import { CP, IterationType } from '../../types';
 import { BinaryTree, BinaryTreeNode } from './binary-tree';
 import { IBinaryTree } from '../../interfaces';
 import { Queue } from '../queue';
@@ -62,16 +72,29 @@ export class BSTNode<V = any, N extends BSTNode<V, N> = BSTNodeNested<V>> extend
   }
 }
 
+/**
+ * 1. Node Order: Each node's left child has a lesser value, and the right child has a greater value.
+ * 2. Unique Keys: No duplicate keys in a standard BST.
+ * 3. Efficient Search: Enables quick search, minimum, and maximum operations.
+ * 4. Inorder Traversal: Yields nodes in ascending order.
+ * 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.
+ */
 export class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNested<V>>, TREE extends BST<V, N, TREE> = BST<V, N, BSTNested<V, N>>>
   extends BinaryTree<V, N, TREE>
   implements IBinaryTree<V, N, TREE> {
 
+
   /**
-   * The constructor function initializes a binary search tree with an optional comparator function.
-   * @param {BSTOptions} [options] - An optional object that contains additional configuration options
-   * for the binary search tree.
+   * This is the constructor function for a binary search tree class in TypeScript, which initializes
+   * the tree with optional elements and options.
+   * @param [elements] - An optional iterable of BTNodeExemplar objects that will be added to the
+   * binary search tree.
+   * @param [options] - The `options` parameter is an optional object that can contain additional
+   * configuration options for the binary search tree. It can have the following properties:
    */
-  constructor(elements?: IterableEntriesOrKeys<V>, options?: Partial<BSTOptions>) {
+  constructor(elements?: Iterable<BTNodeExemplar<V, N>>, options?: Partial<BSTOptions>) {
     super([], options);
 
     if (options) {
@@ -82,14 +105,12 @@ export class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNested<V>>
     }
 
     this._root = undefined;
-    if (elements) this.init(elements);
+
+    if (elements) this.addMany(elements);
   }
 
   protected override _root?: N;
 
-  /**
-   * Get the root node of the binary tree.
-   */
   override get root(): N | undefined {
     return this._root;
   }
@@ -108,6 +129,13 @@ export class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNested<V>>
     return new BSTNode<V, N>(key, value) as N;
   }
 
+  /**
+   * 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 is a type
+   * that defines various options for creating a binary search tree.
+   * @returns a new instance of the BST class with the specified options.
+   */
   override createTree(options?: Partial<BSTOptions>): TREE {
     return new BST<V, N, TREE>([], {
       iterationType: this.iterationType,
@@ -115,162 +143,154 @@ export class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNested<V>>
     }) as TREE;
   }
 
+  /**
+   * Time Complexity: O(log n) - Average case for a balanced tree. In the worst case (unbalanced tree), it can be O(n).
+   * Space Complexity: O(1) - Constant space is used.
+   */
+
   /**
    * Time Complexity: O(log n) - Average case for a balanced tree. In the worst case (unbalanced tree), it can be O(n).
    * Space Complexity: O(1) - Constant space is used.
    *
-   * The `add` function adds a new node to a binary search tree based on the provided key and value.
-   * @param {BTNKey | N | null | undefined} keyOrNode - The `keyOrNode` parameter can be one of the
-   * following types:
-   * @param {V} [value] - The `value` parameter is an optional value that can be associated with the
-   * key or node being added to the binary search tree.
-   * @returns The method `add` returns a node (`N`) that was inserted into the binary search tree. If
-   * no node was inserted, it returns `undefined`.
+   * The `add` function adds a new node to a binary search tree, either by key or by providing a node
+   * object.
+   * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter can be one of the following:
+   * @returns The method returns either the newly added node (`newNode`) or `undefined` if the input
+   * (`keyOrNodeOrEntry`) is null, undefined, or does not match any of the expected types.
    */
-  override add(keyOrNode: BTNKey | N | null | undefined, value?: V): N | undefined {
-    if (keyOrNode === null) return undefined;
-    // TODO support node as a parameter
-    let inserted: N | undefined;
+  override add(keyOrNodeOrEntry: BTNodeExemplar<V, N>): N | undefined {
+    if (keyOrNodeOrEntry === null || keyOrNodeOrEntry === undefined) {
+      return undefined;
+    }
+
     let newNode: N | undefined;
-    if (keyOrNode instanceof BSTNode) {
-      newNode = keyOrNode;
-    } else if (this.isNodeKey(keyOrNode)) {
-      newNode = this.createNode(keyOrNode, value);
+    if (keyOrNodeOrEntry instanceof BSTNode) {
+      newNode = keyOrNodeOrEntry;
+    } else if (this.isNodeKey(keyOrNodeOrEntry)) {
+      newNode = this.createNode(keyOrNodeOrEntry);
+    } else if (this.isEntry(keyOrNodeOrEntry)) {
+      const [key, value] = keyOrNodeOrEntry;
+      if (key === undefined || key === null) {
+        return;
+      } else {
+        newNode = this.createNode(key, value);
+      }
     } else {
-      newNode = undefined;
+      return;
     }
+
     if (this.root === undefined) {
       this._setRoot(newNode);
-      this._size = this.size + 1;
-      inserted = this.root;
-    } else {
-      let cur = this.root;
-      let traversing = true;
-      while (traversing) {
-        if (cur !== undefined && newNode !== undefined) {
-          if (this._compare(cur.key, newNode.key) === CP.eq) {
-            if (newNode) {
-              cur.value = newNode.value;
-            }
-            //Duplicates are not accepted.
-            traversing = false;
-            inserted = cur;
-          } else if (this._compare(cur.key, newNode.key) === CP.gt) {
-            // Traverse left of the node
-            if (cur.left === undefined) {
-              if (newNode) {
-                newNode.parent = cur;
-              }
-              //Add to the left of the current node
-              cur.left = newNode;
-              this._size = this.size + 1;
-              traversing = false;
-              inserted = cur.left;
-            } else {
-              //Traverse the left of the current node
-              if (cur.left) cur = cur.left;
-            }
-          } else if (this._compare(cur.key, newNode.key) === CP.lt) {
-            // Traverse right of the node
-            if (cur.right === undefined) {
-              if (newNode) {
-                newNode.parent = cur;
-              }
-              //Add to the right of the current node
-              cur.right = newNode;
-              this._size = this.size + 1;
-              traversing = false;
-              inserted = cur.right;
-            } else {
-              //Traverse the left of the current node
-              if (cur.right) cur = cur.right;
-            }
-          }
-        } else {
-          traversing = false;
+      this._size++;
+      return this.root;
+    }
+
+    let current = this.root;
+    while (current !== undefined) {
+      if (this._compare(current.key, newNode.key) === CP.eq) {
+        // if (current !== newNode) {
+        // The key value is the same but the reference is different, update the value of the existing node
+        this._replaceNode(current, newNode);
+        return newNode;
+
+        // } else {
+        // The key value is the same and the reference is the same, replace the entire node
+        // this._replaceNode(current, newNode);
+
+        //   return;
+        // }
+      } else if (this._compare(current.key, newNode.key) === CP.gt) {
+        if (current.left === undefined) {
+          current.left = newNode;
+          newNode.parent = current;
+          this._size++;
+          return newNode;
+        }
+        current = current.left;
+      } else {
+        if (current.right === undefined) {
+          current.right = newNode;
+          newNode.parent = current;
+          this._size++;
+          return newNode;
         }
+        current = current.right;
       }
     }
-    return inserted;
+
+    return undefined;
   }
 
   /**
-   * Time Complexity: O(log n) - Average case for a balanced tree. In the worst case (unbalanced tree), it can be O(n).
-   * Space Complexity: O(1) - Constant space is used.
+   * Time Complexity: O(k log n) - Adding each element individually in a balanced tree.
+   * Space Complexity: O(k) - Additional space is required for the sorted array.
    */
 
   /**
-   * Time Complexity: O(n log n) - Adding each element individually in a balanced tree.
-   * Space Complexity: O(n) - Additional space is required for the sorted array.
+   * Time Complexity: O(k log n) - Adding each element individually in a balanced tree.
+   * Space Complexity: O(k) - Additional space is required for the sorted array.
    *
-   * The `addMany` function is used to efficiently add multiple keys or nodes with corresponding data
-   * to a binary search tree.
-   * @param {(BTNKey | N | undefined)[]} keysOrNodes - An array of keys or nodes to be added to the
-   * binary search tree. Each element can be of type `BTNKey` (binary tree node key), `N` (binary tree
-   * node), or `undefined`.
-   * @param {(V | undefined)[]} [data] - An optional array of values to associate with the keys or
-   * nodes being added. If provided, the length of the `data` array must be the same as the length of
-   * the `keysOrNodes` array.
+   * The `addMany` function in TypeScript adds multiple nodes to a binary tree, either in a balanced or
+   * unbalanced manner, and returns an array of the inserted nodes.
+   * @param keysOrNodesOrEntries - An iterable containing keys, nodes, or entries to be added to the
+   * binary tree.
    * @param [isBalanceAdd=true] - A boolean flag indicating whether the tree should be balanced after
-   * adding the nodes. The default value is `true`.
+   * adding the nodes. The default value is true.
    * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
-   * type of iteration to use when adding multiple keys or nodes to the binary search tree. It has a
-   * default value of `this.iterationType`, which means it will use the iteration type specified in the
-   * current instance of the binary search tree
-   * @returns The function `addMany` returns an array of nodes (`N`) or `undefined` values.
+   * type of iteration to use when adding multiple keys or nodes to the binary tree. It has a default
+   * value of `this.iterationType`, which means it will use the iteration type specified by the binary
+   * tree instance.
+   * @returns The `addMany` function returns an array of `N` or `undefined` values.
    */
   override addMany(
-    keysOrNodes: (BTNKey | N | undefined)[],
-    data?: (V | undefined)[],
+    keysOrNodesOrEntries: Iterable<BTNodeExemplar<V, N>>,
     isBalanceAdd = true,
     iterationType = this.iterationType
   ): (N | undefined)[] {
-    // TODO this addMany function is inefficient, it should be optimized
-    function hasNoUndefined(arr: (BTNKey | N | undefined)[]): arr is (BTNKey | N)[] {
-      return arr.indexOf(undefined) === -1;
+    const inserted: (N | undefined)[] = []
+    if (!isBalanceAdd) {
+      for (const kve of keysOrNodesOrEntries) {
+        const nn = this.add(kve)
+        inserted.push(nn);
+      }
+      return inserted;
     }
+    const realBTNExemplars: BTNodePureExemplar<V, N>[] = [];
 
-    if (!isBalanceAdd || !hasNoUndefined(keysOrNodes)) {
-      return super.addMany(keysOrNodes, data).map(n => n ?? undefined);
+    const isRealBTNExemplar = (kve: BTNodeExemplar<V, N>): kve is BTNodePureExemplar<V, N> => {
+      if (kve === undefined || kve === null) return false;
+      return !(this.isEntry(kve) && (kve[0] === undefined || kve[0] === null));
     }
 
-    const inserted: (N | undefined)[] = [];
-    const combinedArr: [BTNKey | N, V][] = keysOrNodes.map(
-      (value: BTNKey | N, index) => [value, data?.[index]] as [BTNKey | N, V]
-    );
+    for (const kve of keysOrNodesOrEntries) {
+      isRealBTNExemplar(kve) && realBTNExemplars.push(kve);
+    }
 
-    let sorted = [];
+    // TODO this addMany function is inefficient, it should be optimized
+    let sorted: BTNodePureExemplar<V, N>[] = [];
 
-    function _isNodeOrUndefinedTuple(arr: [BTNKey | N, V][]): arr is [N, V][] {
-      for (const [keyOrNode] of arr) if (keyOrNode instanceof BSTNode) return true;
-      return false;
-    }
+    sorted = realBTNExemplars.sort((a, b) => {
+      let aR: number, bR: number;
+      if (this.isEntry(a)) aR = a[0]
+      else if (this.isRealNode(a)) aR = a.key
+      else aR = a;
 
-    const _isBinaryTreeKeyOrNullTuple = (arr: [BTNKey | N, V][]): arr is [BTNKey, V][] => {
-      for (const [keyOrNode] of arr) if (this.isNodeKey(keyOrNode)) return true;
-      return false;
-    };
+      if (this.isEntry(b)) bR = b[0]
+      else if (this.isRealNode(b)) bR = b.key
+      else bR = b;
 
-    let sortedKeysOrNodes: (number | N | undefined)[] = [],
-      sortedData: (V | undefined)[] | undefined = [];
+      return aR - bR;
+    })
 
-    if (_isNodeOrUndefinedTuple(combinedArr)) {
-      sorted = combinedArr.sort((a, b) => a[0].key - b[0].key);
-    } else if (_isBinaryTreeKeyOrNullTuple(combinedArr)) {
-      sorted = combinedArr.sort((a, b) => a[0] - b[0]);
-    } else {
-      throw new Error('Invalid input keysOrNodes');
-    }
-    sortedKeysOrNodes = sorted.map(([keyOrNode]) => keyOrNode);
-    sortedData = sorted.map(([, value]) => value);
-    const _dfs = (arr: (BTNKey | undefined | N)[], data?: (V | undefined)[]) => {
+
+    const _dfs = (arr: BTNodePureExemplar<V, N>[]) => {
       if (arr.length === 0) return;
 
       const mid = Math.floor((arr.length - 1) / 2);
-      const newNode = this.add(arr[mid], data?.[mid]);
+      const newNode = this.add(arr[mid]);
       inserted.push(newNode);
-      _dfs(arr.slice(0, mid), data?.slice(0, mid));
-      _dfs(arr.slice(mid + 1), data?.slice(mid + 1));
+      _dfs(arr.slice(0, mid));
+      _dfs(arr.slice(mid + 1));
     };
     const _iterate = () => {
       const n = sorted.length;
@@ -281,7 +301,7 @@ export class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNested<V>>
           const [l, r] = popped;
           if (l <= r) {
             const m = l + Math.floor((r - l) / 2);
-            const newNode = this.add(sortedKeysOrNodes[m], sortedData?.[m]);
+            const newNode = this.add(sorted[m]);
             inserted.push(newNode);
             stack.push([m + 1, r]);
             stack.push([l, m - 1]);
@@ -290,7 +310,7 @@ export class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNested<V>>
       }
     };
     if (iterationType === IterationType.RECURSIVE) {
-      _dfs(sortedKeysOrNodes, sortedData);
+      _dfs(sorted);
     } else {
       _iterate();
     }
@@ -318,7 +338,7 @@ export class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNested<V>>
    * the key of the leftmost node if the comparison result is greater than, and the key of the
    * rightmost node otherwise. If no node is found, it returns 0.
    */
-  lastKey(beginRoot: BTNKey | N | undefined = this.root, iterationType = this.iterationType): BTNKey {
+  lastKey(beginRoot: BSTNodeKeyOrNode<N> = this.root, iterationType = this.iterationType): BTNKey {
     if (this._compare(0, 1) === CP.lt) return this.getRightMost(beginRoot, iterationType)?.key ?? 0;
     else if (this._compare(0, 1) === CP.gt) return this.getLeftMost(beginRoot, iterationType)?.key ?? 0;
     else return this.getRightMost(beginRoot, iterationType)?.key ?? 0;
@@ -374,7 +394,7 @@ export class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNested<V>>
    */
 
   /**
-   * The function `ensureNotKey` returns the node corresponding to the given key if it is a node key,
+   * The function `ensureNode` returns the node corresponding to the given key if it is a node key,
    * otherwise it returns the key itself.
    * @param {BTNKey | N | undefined} key - The `key` parameter can be of type `BTNKey`, `N`, or
    * `undefined`.
@@ -382,7 +402,7 @@ export class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNested<V>>
    * type of iteration to be performed. It has a default value of `IterationType.ITERATIVE`.
    * @returns either a node object (N) or undefined.
    */
-  override ensureNotKey(key: BTNKey | N | undefined, iterationType = IterationType.ITERATIVE): N | undefined {
+  override ensureNode(key: BSTNodeKeyOrNode<N>, iterationType = IterationType.ITERATIVE): N | undefined {
     return this.isNodeKey(key) ? this.getNodeByKey(key, iterationType) : key;
   }
 
@@ -413,10 +433,10 @@ export class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNested<V>>
     identifier: ReturnType<C> | undefined,
     callback: C = this._defaultOneParamCallback as C,
     onlyOne = false,
-    beginRoot: BTNKey | N | undefined = this.root,
+    beginRoot: BSTNodeKeyOrNode<N> = this.root,
     iterationType = this.iterationType
   ): N[] {
-    beginRoot = this.ensureNotKey(beginRoot);
+    beginRoot = this.ensureNode(beginRoot);
     if (!beginRoot) return [];
     const ans: N[] = [];
 
@@ -494,10 +514,10 @@ export class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNested<V>>
   lesserOrGreaterTraverse<C extends BTNCallback<N>>(
     callback: C = this._defaultOneParamCallback as C,
     lesserOrGreater: CP = CP.lt,
-    targetNode: BTNKey | N | undefined = this.root,
+    targetNode: BSTNodeKeyOrNode<N> = this.root,
     iterationType = this.iterationType
   ): ReturnType<C>[] {
-    targetNode = this.ensureNotKey(targetNode);
+    targetNode = this.ensureNode(targetNode);
     const ans: ReturnType<BTNCallback<N>>[] = [];
     if (!targetNode) return ans;
     if (!this.root) return ans;
@@ -559,7 +579,7 @@ export class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNested<V>>
         if (l > r) return;
         const m = l + Math.floor((r - l) / 2);
         const midNode = sorted[m];
-        this.add(midNode.key, midNode.value);
+        this.add([midNode.key, midNode.value]);
         buildBalanceBST(l, m - 1);
         buildBalanceBST(m + 1, r);
       };
@@ -576,7 +596,7 @@ export class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNested<V>>
             const m = l + Math.floor((r - l) / 2);
             const midNode = sorted[m];
             debugger;
-            this.add(midNode.key, midNode.value);
+            this.add([midNode.key, midNode.value]);
             stack.push([m + 1, r]);
             stack.push([l, m - 1]);
           }
@@ -654,23 +674,6 @@ export class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNested<V>>
     return balanced;
   }
 
-  /**
-   * Time Complexity: O(n) - Visiting each node once.
-   * Space Complexity: O(log n) - Space for the recursive call stack in the worst case.
-   */
-
-  init(elements: IterableEntriesOrKeys<V>): void {
-    if (elements) {
-      for (const entryOrKey of elements) {
-        if (Array.isArray(entryOrKey)) {
-          const [key, value] = entryOrKey;
-          this.add(key, value);
-        } else {
-          this.add(entryOrKey);
-        }
-      }
-    }
-  }
 
   protected _setRoot(v: N | undefined) {
     if (v) {

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

@@ -8,9 +8,10 @@
 
 import {
   BiTreeDeleteResult,
+  BSTNodeKeyOrNode,
   BTNCallback,
   BTNKey,
-  IterableEntriesOrKeys,
+  BTNodeExemplar,
   IterationType,
   RBTNColor,
   RBTreeOptions,
@@ -45,17 +46,22 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
   implements IBinaryTree<V, N, TREE> {
   Sentinel: N = new RedBlackTreeNode<V>(NaN) as unknown as N;
 
-
   /**
-   * The constructor function initializes a Red-Black Tree with an optional set of options.
-   * @param {RBTreeOptions} [options] - The `options` parameter is an optional object that can be
-   * passed to the constructor. It is used to configure the RBTree object with specific options.
+   * This is the constructor function for a Red-Black Tree data structure in TypeScript, which
+   * initializes the tree with optional elements and options.
+   * @param [elements] - The `elements` parameter is an optional iterable of `BTNodeExemplar<V, N>`
+   * objects. It represents the initial elements that will be added to the RBTree during its
+   * construction. If this parameter is provided, the `addMany` method is called to add all the
+   * elements to the
+   * @param [options] - The `options` parameter is an optional object that allows you to customize the
+   * behavior of the RBTree. It is of type `Partial<RBTreeOptions>`, which means that you can provide
+   * only a subset of the properties defined in the `RBTreeOptions` interface.
    */
-  constructor(elements?: IterableEntriesOrKeys<V>, options?: Partial<RBTreeOptions>) {
+  constructor(elements?: Iterable<BTNodeExemplar<V, N>>, options?: Partial<RBTreeOptions>) {
     super([], options);
 
     this._root = this.Sentinel;
-    if (elements) this.init(elements);
+    if (elements) super.addMany(elements);
   }
 
   protected _root: N;
@@ -70,10 +76,29 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
     return this._size;
   }
 
+  /**
+   * The function creates a new Red-Black Tree node with the specified key, value, and color.
+   * @param {BTNKey} key - The key parameter is the key value associated with the node. It is used to
+   * identify and compare nodes in the Red-Black Tree.
+   * @param {V} [value] - The `value` parameter is an optional parameter that represents the value
+   * associated with the node. It is of type `V`, which is a generic type that can be replaced with any
+   * specific type when using the `createNode` method.
+   * @param {RBTNColor} color - The "color" parameter is used to specify the color of the node in a
+   * Red-Black Tree. It can be either "RED" or "BLACK". By default, the color is set to "BLACK".
+   * @returns The method is returning a new instance of a RedBlackTreeNode with the specified key,
+   * value, and color.
+   */
   override createNode(key: BTNKey, value?: V, color: RBTNColor = RBTNColor.BLACK): N {
     return new RedBlackTreeNode<V, N>(key, value, color) as N;
   }
 
+  /**
+   * The function creates a Red-Black Tree with the specified options and returns it.
+   * @param {RBTreeOptions} [options] - The `options` parameter is an optional object that can be
+   * passed to the `createTree` function. It is used to customize the behavior of the `RedBlackTree`
+   * class.
+   * @returns a new instance of a RedBlackTree object.
+   */
   override createTree(options?: RBTreeOptions): TREE {
     return new RedBlackTree<V, N, TREE>([], {
       iterationType: this.iterationType,
@@ -84,24 +109,30 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
   /**
    * Time Complexity: O(log n) on average (where n is the number of nodes in the tree)
    * Space Complexity: O(1)
-   *
-   * The `add` function adds a new node to a Red-Black Tree data structure.
-   * @param {BTNKey | N | null | undefined} keyOrNode - The `keyOrNode` parameter can be one of the
-   * following types:
-   * @param {V} [value] - The `value` parameter is an optional value that can be associated with the
-   * key in the node being added to the Red-Black Tree.
-   * @returns The method returns either a node (`N`) or `undefined`.
    */
-  override add(keyOrNode: BTNKey | N | null | undefined, value?: V): N | undefined {
+
+
+  /**
+   * The function adds a node to a Red-Black Tree data structure.
+   * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter can be one of the following:
+   * @returns The method `add` returns either an instance of `N` (the node that was added) or
+   * `undefined`.
+   */
+  override add(keyOrNodeOrEntry: BTNodeExemplar<V, N>): N | undefined {
     let node: N;
-    if (this.isNodeKey(keyOrNode)) {
-      node = this.createNode(keyOrNode, value, RBTNColor.RED);
-    } else if (keyOrNode instanceof RedBlackTreeNode) {
-      node = keyOrNode;
-    } else if (keyOrNode === null) {
-      return;
-    } else if (keyOrNode === undefined) {
+    if (this.isNodeKey(keyOrNodeOrEntry)) {
+      node = this.createNode(keyOrNodeOrEntry, undefined, RBTNColor.RED);
+    } else if (keyOrNodeOrEntry instanceof RedBlackTreeNode) {
+      node = keyOrNodeOrEntry;
+    } else if (keyOrNodeOrEntry === null || keyOrNodeOrEntry === undefined) {
       return;
+    } else if (this.isEntry(keyOrNodeOrEntry)) {
+      const [key, value] = keyOrNodeOrEntry;
+      if (key === undefined || key === null) {
+        return;
+      } else {
+        node = this.createNode(key, value, RBTNColor.RED);
+      }
     } else {
       return;
     }
@@ -120,6 +151,9 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
         } else if (node.key > x.key) {
           x = x?.right;
         } else {
+          if (node !== x) {
+            this._replaceNode(x, node)
+          }
           return;
         }
       }
@@ -261,6 +295,11 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
     iterationType?: IterationType
   ): N | undefined;
 
+  /**
+   * Time Complexity: O(log n) on average (where n is the number of nodes in the tree)
+   * Space Complexity: O(1)
+   */
+
   /**
    * Time Complexity: O(log n) on average (where n is the number of nodes in the tree)
    * Space Complexity: O(1)
@@ -285,11 +324,11 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
   getNode<C extends BTNCallback<N>>(
     identifier: ReturnType<C> | undefined,
     callback: C = this._defaultOneParamCallback as C,
-    beginRoot: BTNKey | N | undefined = this.root,
+    beginRoot: BSTNodeKeyOrNode<N> = this.root,
     iterationType = this.iterationType
   ): N | null | undefined {
     if ((identifier as any) instanceof BinaryTreeNode) callback = (node => node) as C;
-    beginRoot = this.ensureNotKey(beginRoot);
+    beginRoot = this.ensureNode(beginRoot);
     return this.getNodes(identifier, callback, true, beginRoot, iterationType)[0] ?? undefined;
   }
 
@@ -357,19 +396,6 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
     this._size = 0;
   }
 
-  init(elements: IterableEntriesOrKeys<V>): void {
-    if (elements) {
-      for (const entryOrKey of elements) {
-        if (Array.isArray(entryOrKey)) {
-          const [key, value] = entryOrKey;
-          this.add(key, value);
-        } else {
-          this.add(entryOrKey);
-        }
-      }
-    }
-  }
-
   protected override _setRoot(v: N) {
     if (v) {
       v.parent = undefined;
@@ -596,4 +622,19 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
     }
     this.root.color = RBTNColor.BLACK;
   }
+
+  /**
+   * The function replaces an old node with a new node while preserving the color of the old node.
+   * @param {N} oldNode - The `oldNode` parameter represents the node that needs to be replaced in a
+   * data structure. It is of type `N`, which is the type of the nodes in the data structure.
+   * @param {N} newNode - The `newNode` parameter is the node that will replace the `oldNode` in the
+   * data structure.
+   * @returns The method is returning the result of calling the `_replaceNode` method from the
+   * superclass, passing in the `oldNode` and `newNode` as arguments.
+   */
+  protected _replaceNode(oldNode: N, newNode: N): N {
+    newNode.color = oldNode.color;
+
+    return super._replaceNode(oldNode, newNode)
+  }
 }