min-heap-typed 1.47.6 → 1.47.7

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

@@ -6,14 +6,21 @@
  * @license MIT License
  */
 
-import type { BinaryTreeNodeNested, BinaryTreeOptions, BTNCallback, BTNKey } from '../../types';
+import type {
+  BinaryTreeNodeNested,
+  BinaryTreeOptions,
+  BTNCallback,
+  BTNKey,
+  BTNodeEntry,
+  BTNodeExemplar,
+  BTNodeKeyOrNode
+} from '../../types';
 import {
   BinaryTreeNested,
   BinaryTreePrintOptions,
   BiTreeDeleteResult,
   DFSOrderPattern,
   FamilyPosition,
-  IterableEntriesOrKeys,
   IterationType,
   NodeDisplayLayout
 } from '../../types';
@@ -27,26 +34,12 @@ import { Queue } from '../queue';
  * @template N - The type of the family relationship in the binary tree.
  */
 export class BinaryTreeNode<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode<V, BinaryTreeNodeNested<V>>> {
-  /**
-   * The key associated with the node.
-   */
   key: BTNKey;
 
-  /**
-   * The value stored in the node.
-   */
   value?: V;
 
-  /**
-   * The parent node of the current node.
-   */
-  parent?: N | null;
+  parent?: N;
 
-  /**
-   * Creates a new instance of BinaryTreeNode.
-   * @param {BTNKey} key - The key associated with the node.
-   * @param {V} value - The value stored in the node.
-   */
   constructor(key: BTNKey, value?: V) {
     this.key = key;
     this.value = value;
@@ -54,17 +47,10 @@ export class BinaryTreeNode<V = any, N extends BinaryTreeNode<V, N> = BinaryTree
 
   protected _left?: N | null;
 
-  /**
-   * Get the left child node.
-   */
   get left(): N | null | undefined {
     return this._left;
   }
 
-  /**
-   * Set the left child node.
-   * @param {N | null | undefined} v - The left child node.
-   */
   set left(v: N | null | undefined) {
     if (v) {
       v.parent = this as unknown as N;
@@ -74,17 +60,10 @@ export class BinaryTreeNode<V = any, N extends BinaryTreeNode<V, N> = BinaryTree
 
   protected _right?: N | null;
 
-  /**
-   * Get the right child node.
-   */
   get right(): N | null | undefined {
     return this._right;
   }
 
-  /**
-   * Set the right child node.
-   * @param {N | null | undefined} v - The right child node.
-   */
   set right(v: N | null | undefined) {
     if (v) {
       v.parent = this as unknown as N;
@@ -113,8 +92,15 @@ export class BinaryTreeNode<V = any, N extends BinaryTreeNode<V, N> = BinaryTree
 }
 
 /**
- * Represents a binary tree data structure.
- * @template N - The type of the binary tree's nodes.
+ * 1. Two Children Maximum: Each node has at most two children.
+ * 2. Left and Right Children: Nodes have distinct left and right children.
+ * 3. Depth and Height: Depth is the number of edges from the root to a node; height is the maximum depth in the tree.
+ * 4. Subtrees: Each child of a node forms the root of a subtree.
+ * 5. Leaf Nodes: Nodes without children are leaves.
+ * 6. Internal Nodes: Nodes with at least one child are internal.
+ * 7. Balanced Trees: The heights of the left and right subtrees of any node differ by no more than one.
+ * 8. Full Trees: Every node has either 0 or 2 children.
+ * 9. Complete Trees: All levels are fully filled except possibly the last, filled from left to right.
  */
 export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode<V, BinaryTreeNodeNested<V>>, TREE extends BinaryTree<V, N, TREE> = BinaryTree<V, N, BinaryTreeNested<V, N>>>
   implements IBinaryTree<V, N, TREE> {
@@ -122,10 +108,15 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
   iterationType = IterationType.ITERATIVE
 
   /**
-   * Creates a new instance of BinaryTree.
-   * @param {BinaryTreeOptions} [options] - The options for the binary tree.
+   * The constructor function initializes a binary tree object with optional elements and options.
+   * @param [elements] - An optional iterable of BTNodeExemplar objects. These objects represent the
+   * elements to be added to the binary tree.
+   * @param [options] - The `options` parameter is an optional object that can contain additional
+   * configuration options for the binary tree. In this case, it is of type
+   * `Partial<BinaryTreeOptions>`, which means that not all properties of `BinaryTreeOptions` are
+   * required.
    */
-  constructor(elements?: IterableEntriesOrKeys<V>, options?: Partial<BinaryTreeOptions>) {
+  constructor(elements?: Iterable<BTNodeExemplar<V, N>>, options?: Partial<BinaryTreeOptions>) {
 
     if (options) {
       const { iterationType } = options;
@@ -136,23 +127,17 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
 
     this._size = 0;
 
-    if (elements) this.init(elements);
+    if (elements) this.addMany(elements);
   }
 
   protected _root?: N | null;
 
-  /**
-   * Get the root node of the binary tree.
-   */
   get root(): N | null | undefined {
     return this._root;
   }
 
   protected _size: number;
 
-  /**
-   * Get the number of nodes in the binary tree.
-   */
   get size(): number {
     return this._size;
   }
@@ -167,31 +152,51 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     return new BinaryTreeNode<V, N>(key, value) as N;
   }
 
+  /**
+   * The function creates a binary tree with the given options.
+   * @param [options] - The `options` parameter is an optional object that allows you to customize the
+   * behavior of the `BinaryTree` class. It is of type `Partial<BinaryTreeOptions>`, which means that
+   * you can provide only a subset of the properties defined in the `BinaryTreeOptions` interface.
+   * @returns a new instance of a binary tree.
+   */
   createTree(options?: Partial<BinaryTreeOptions>): TREE {
     return new BinaryTree<V, N, TREE>([], { iterationType: this.iterationType, ...options }) as TREE;
   }
 
   /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(1)
+   * The function checks if a given value is an entry in a binary tree node.
+   * @param kne - BTNodeExemplar<V, N> - A generic type representing a node in a binary tree. It has
+   * two type parameters V and N, representing the value and node type respectively.
+   * @returns a boolean value.
+   */
+  isEntry(kne: BTNodeExemplar<V, N>): kne is BTNodeEntry<V> {
+    return Array.isArray(kne) && kne.length === 2;
+  }
+
+  /**
+   * Time Complexity O(log n) - O(n)
+   * Space Complexity O(1)
+   */
+
+  /**
+   * Time Complexity O(log n) - O(n)
+   * Space Complexity O(1)
    *
-   * The `add` function adds a new node with a key and value to a binary tree, or updates the value of
-   * an existing node with the same key.
-   * @param {BTNKey | N | null | undefined} keyOrNode - The `keyOrNode` parameter can be one of the
-   * following types:
-   * @param {V} [value] - The value to be associated with the key or node being added to the binary
-   * tree.
-   * @returns The function `add` returns a node (`N`) if it was successfully inserted into the binary
-   * tree, or `null` or `undefined` if the insertion was not successful.
+   * The `add` function adds a new node to a binary tree, either by key or by providing a node object.
+   * @param keyOrNodeOrEntry - The parameter `keyOrNodeOrEntry` can be one of the following:
+   * @returns The function `add` returns the inserted node (`N`), `null`, or `undefined`.
    */
-  add(keyOrNode: BTNKey | N | null | undefined, value?: V): N | null | undefined {
+  add(keyOrNodeOrEntry: BTNodeExemplar<V, N>): N | null | undefined {
+
+    let inserted: N | null | undefined, needInsert: N | null | undefined;
+
     const _bfs = (root: N, newNode: N | null): N | undefined | null => {
       const queue = new Queue<N>([root]);
       while (queue.size > 0) {
         const cur = queue.shift()!;
         if (newNode && cur.key === newNode.key) {
-          cur.value = newNode.value;
-          return;
+          this._replaceNode(cur, newNode);
+          return newNode;
         }
         const inserted = this._addTo(newNode, cur);
         if (inserted !== undefined) return inserted;
@@ -200,14 +205,21 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
       }
     };
 
-    let inserted: N | null | undefined, needInsert: N | null | undefined;
-
-    if (keyOrNode === null) {
+    if (keyOrNodeOrEntry === null) {
       needInsert = null;
-    } else if (this.isNodeKey(keyOrNode)) {
-      needInsert = this.createNode(keyOrNode, value);
-    } else if (keyOrNode instanceof BinaryTreeNode) {
-      needInsert = keyOrNode;
+    } else if (this.isNodeKey(keyOrNodeOrEntry)) {
+      needInsert = this.createNode(keyOrNodeOrEntry);
+    } else if (keyOrNodeOrEntry instanceof BinaryTreeNode) {
+      needInsert = keyOrNodeOrEntry;
+    } else if (this.isEntry(keyOrNodeOrEntry)) {
+      const [key, value] = keyOrNodeOrEntry;
+      if (key === undefined) {
+        return;
+      } else if (key === null) {
+        needInsert = null;
+      } else {
+        needInsert = this.createNode(key, value);
+      }
     } else {
       return;
     }
@@ -227,39 +239,30 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
   }
 
   /**
-   * Time Complexity: O(n)
+   * Time Complexity: O(k log n) - O(k * n)
    * Space Complexity: O(1)
    * Comments: The time complexity for adding a node depends on the depth of the tree. In the best case (when the tree is empty), it's O(1). In the worst case (when the tree is a degenerate tree), it's O(n). The space complexity is constant.
    */
 
+
   /**
-   * Time Complexity: O(k * n)  "n" is the number of nodes in the tree, and "k" is the number of keys to be inserted.
+   * Time Complexity: O(k log n) - O(k * n)
    * Space Complexity: O(1)
    *
-   * The `addMany` function takes an array of keys or nodes and an optional array of values, and adds
-   * each key-value pair to a data structure.
-   * @param {(BTNKey | N |null | undefined)[]} keysOrNodes - An array of keys or nodes to be added to
-   * the binary search tree. Each element can be of type `BTNKey` (a key value), `N` (a node), `null`,
-   * or `undefined`.
-   * @param {(V | undefined)[]} [values] - The `values` parameter is an optional array of values that
-   * correspond to the keys or nodes being added. If provided, the values will be associated with the
-   * keys or nodes during the add operation.
-   * @returns The function `addMany` returns an array of `N`, `null`, or `undefined` values.
-   */
-  addMany(keysOrNodes: (BTNKey | N | null | undefined)[], values?: (V | undefined)[]): (N | null | undefined)[] {
+   * The function `addMany` takes in an iterable of `BTNodeExemplar` objects, adds each object to the
+   * current instance, and returns an array of the inserted nodes.
+   * @param nodes - The `nodes` parameter is an iterable (such as an array or a set) of
+   * `BTNodeExemplar<V, N>` objects.
+   * @returns The function `addMany` returns an array of values, where each value is either of type
+   * `N`, `null`, or `undefined`.
+   */
+  addMany(nodes: Iterable<BTNodeExemplar<V, N>>): (N | null | undefined)[] {
     // TODO not sure addMany not be run multi times
-    return keysOrNodes.map((keyOrNode, i) => {
-      if (keyOrNode instanceof BinaryTreeNode) {
-        return this.add(keyOrNode.key, keyOrNode.value);
-      }
-
-      if (keyOrNode === null) {
-        return this.add(null);
-      }
-
-      const value = values?.[i];
-      return this.add(keyOrNode, value);
-    });
+    const inserted: (N | null | undefined)[] = [];
+    for (const kne of nodes) {
+      inserted.push(this.add(kne));
+    }
+    return inserted;
   }
 
   /**
@@ -271,17 +274,13 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * Time Complexity: O(k * n)  "n" is the number of nodes in the tree, and "k" is the number of keys to be inserted.
    * Space Complexity: O(1)
    *
-   * The `refill` function clears the binary tree and adds multiple nodes with the given IDs or nodes and optional data.
-   * @param {(BTNKey | N)[]} keysOrNodes - The `keysOrNodes` parameter is an array that can contain either
-   * `BTNKey` or `N` values.
-   * @param {N[] | Array<V>} [values] - The `data` parameter is an optional array of values that will be assigned to
-   * the nodes being added. If provided, the length of the `data` array should be equal to the length of the `keysOrNodes`
-   * array. Each value in the `data` array will be assigned to the
-   * @returns The method is returning a boolean value.
-   */
-  refill(keysOrNodes: (BTNKey | N | null | undefined)[], values?: (V | undefined)[]): boolean {
+   * The `refill` function clears the current collection and adds new nodes, keys, or entries to it.
+   * @param nodesOrKeysOrEntries - The parameter `nodesOrKeysOrEntries` is an iterable object that can
+   * contain either `BTNodeExemplar` objects, keys, or entries.
+   */
+  refill(nodesOrKeysOrEntries: Iterable<BTNodeExemplar<V, N>>): void {
     this.clear();
-    return keysOrNodes.length === this.addMany(keysOrNodes, values).length;
+    this.addMany(nodesOrKeysOrEntries);
   }
 
   /**
@@ -344,7 +343,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
         const leftSubTreeRightMost = this.getRightMost(curr.left);
         if (leftSubTreeRightMost) {
           const parentOfLeftSubTreeMax = leftSubTreeRightMost.parent;
-          orgCurrent = this._swap(curr, leftSubTreeRightMost);
+          orgCurrent = this._swapProperties(curr, leftSubTreeRightMost);
           if (parentOfLeftSubTreeMax) {
             if (parentOfLeftSubTreeMax.right === leftSubTreeRightMost)
               parentOfLeftSubTreeMax.right = leftSubTreeRightMost.left;
@@ -378,9 +377,9 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * `N` (binary tree node) or `null` or `undefined`. If no value is provided for `beginRoot
    * @returns the depth of the `distNode` relative to the `beginRoot`.
    */
-  getDepth(distNode: BTNKey | N | null | undefined, beginRoot: BTNKey | N | null | undefined = this.root): number {
-    distNode = this.ensureNotKey(distNode);
-    beginRoot = this.ensureNotKey(beginRoot);
+  getDepth(distNode: BTNodeKeyOrNode<N>, beginRoot: BTNodeKeyOrNode<N> = this.root): number {
+    distNode = this.ensureNode(distNode);
+    beginRoot = this.ensureNode(beginRoot);
     let depth = 0;
     while (distNode?.parent) {
       if (distNode === beginRoot) {
@@ -411,8 +410,8 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * values:
    * @returns the height of the binary tree.
    */
-  getHeight(beginRoot: BTNKey | N | null | undefined = this.root, iterationType = this.iterationType): number {
-    beginRoot = this.ensureNotKey(beginRoot);
+  getHeight(beginRoot: BTNodeKeyOrNode<N> = this.root, iterationType = this.iterationType): number {
+    beginRoot = this.ensureNode(beginRoot);
     if (!beginRoot) return -1;
 
     if (iterationType === IterationType.RECURSIVE) {
@@ -460,8 +459,8 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * to calculate the minimum height of a binary tree. It can have two possible values:
    * @returns The function `getMinHeight` returns the minimum height of a binary tree.
    */
-  getMinHeight(beginRoot: BTNKey | N | null | undefined = this.root, iterationType = this.iterationType): number {
-    beginRoot = this.ensureNotKey(beginRoot);
+  getMinHeight(beginRoot: BTNodeKeyOrNode<N> = this.root, iterationType = this.iterationType): number {
+    beginRoot = this.ensureNode(beginRoot);
     if (!beginRoot) return -1;
 
     if (iterationType === IterationType.RECURSIVE) {
@@ -520,7 +519,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * value of a binary tree node), `N` (a node of a binary tree), `null`, or `undefined`. If
    * @returns a boolean value.
    */
-  isPerfectlyBalanced(beginRoot: BTNKey | N | null | undefined = this.root): boolean {
+  isPerfectlyBalanced(beginRoot: BTNodeKeyOrNode<N> = this.root): boolean {
     return this.getMinHeight(beginRoot) + 1 >= this.getHeight(beginRoot);
   }
 
@@ -533,7 +532,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     identifier: BTNKey,
     callback?: C,
     onlyOne?: boolean,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType
   ): N[];
 
@@ -541,7 +540,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     identifier: N | null | undefined,
     callback?: C,
     onlyOne?: boolean,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType
   ): N[];
 
@@ -549,7 +548,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     identifier: ReturnType<C>,
     callback: C,
     onlyOne?: boolean,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType
   ): N[];
 
@@ -582,12 +581,12 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     identifier: ReturnType<C> | null | undefined,
     callback: C = this._defaultOneParamCallback as C,
     onlyOne = false,
-    beginRoot: BTNKey | N | null | undefined = this.root,
+    beginRoot: BTNodeKeyOrNode<N> = this.root,
     iterationType = this.iterationType
   ): N[] {
     if ((!callback || callback === this._defaultOneParamCallback) && (identifier as any) instanceof BinaryTreeNode)
       callback = (node => node) as C;
-    beginRoot = this.ensureNotKey(beginRoot);
+    beginRoot = this.ensureNode(beginRoot);
     if (!beginRoot) return [];
 
     const ans: N[] = [];
@@ -630,21 +629,21 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
   has<C extends BTNCallback<N, BTNKey>>(
     identifier: BTNKey,
     callback?: C,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType
   ): boolean;
 
   has<C extends BTNCallback<N, N>>(
     identifier: N | null | undefined,
     callback?: C,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType
   ): boolean;
 
   has<C extends BTNCallback<N>>(
     identifier: ReturnType<C> | null | undefined,
     callback: C,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType
   ): boolean;
 
@@ -671,7 +670,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
   has<C extends BTNCallback<N>>(
     identifier: ReturnType<C> | null | undefined,
     callback: C = this._defaultOneParamCallback as C,
-    beginRoot: BTNKey | N | null | undefined = this.root,
+    beginRoot: BTNodeKeyOrNode<N> = this.root,
     iterationType = this.iterationType
   ): boolean {
     if ((!callback || callback === this._defaultOneParamCallback) && (identifier as any) instanceof BinaryTreeNode)
@@ -688,21 +687,21 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
   getNode<C extends BTNCallback<N, BTNKey>>(
     identifier: BTNKey,
     callback?: C,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType
   ): N | null | undefined;
 
   getNode<C extends BTNCallback<N, N>>(
     identifier: N | null | undefined,
     callback?: C,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType
   ): N | null | undefined;
 
   getNode<C extends BTNCallback<N>>(
     identifier: ReturnType<C>,
     callback: C,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType
   ): N | null | undefined;
 
@@ -730,7 +729,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
   getNode<C extends BTNCallback<N>>(
     identifier: ReturnType<C> | null | undefined,
     callback: C = this._defaultOneParamCallback as C,
-    beginRoot: BTNKey | N | null | undefined = this.root,
+    beginRoot: BTNodeKeyOrNode<N> = this.root,
     iterationType = this.iterationType
   ): N | null | undefined {
     if ((!callback || callback === this._defaultOneParamCallback) && (identifier as any) instanceof BinaryTreeNode)
@@ -789,7 +788,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    */
 
   /**
-   * The function `ensureNotKey` returns the node corresponding to the given key if it is a valid node
+   * The function `ensureNode` returns the node corresponding to the given key if it is a valid node
    * key, otherwise it returns the key itself.
    * @param {BTNKey | N | null | undefined} key - The `key` parameter can be of type `BTNKey`, `N`,
    * `null`, or `undefined`. It represents a key used to identify a node in a binary tree.
@@ -799,28 +798,28 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * @returns either the node corresponding to the given key if it is a valid node key, or the key
    * itself if it is not a valid node key.
    */
-  ensureNotKey(key: BTNKey | N | null | undefined, iterationType = IterationType.ITERATIVE): N | null | undefined {
+  ensureNode(key: BTNodeKeyOrNode<N>, iterationType = IterationType.ITERATIVE): N | null | undefined {
     return this.isNodeKey(key) ? this.getNodeByKey(key, iterationType) : key;
   }
 
   get<C extends BTNCallback<N, BTNKey>>(
     identifier: BTNKey,
     callback?: C,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType
   ): V | undefined;
 
   get<C extends BTNCallback<N, N>>(
     identifier: N | null | undefined,
     callback?: C,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType
   ): V | undefined;
 
   get<C extends BTNCallback<N>>(
     identifier: ReturnType<C>,
     callback: C,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType
   ): V | undefined;
 
@@ -849,7 +848,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
   get<C extends BTNCallback<N>>(
     identifier: ReturnType<C> | null | undefined,
     callback: C = this._defaultOneParamCallback as C,
-    beginRoot: BTNKey | N | null | undefined = this.root,
+    beginRoot: BTNodeKeyOrNode<N> = this.root,
     iterationType = this.iterationType
   ): V | undefined {
     if ((!callback || callback === this._defaultOneParamCallback) && (identifier as any) instanceof BinaryTreeNode)
@@ -893,10 +892,10 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * reversed before returning it. If `isReverse` is set to `false`, the path will be returned as is
    * @returns The function `getPathToRoot` returns an array of nodes (`N[]`).
    */
-  getPathToRoot(beginRoot: BTNKey | N | null | undefined, isReverse = true): N[] {
+  getPathToRoot(beginRoot: BTNodeKeyOrNode<N>, isReverse = true): N[] {
     // TODO to support get path through passing key
     const result: N[] = [];
-    beginRoot = this.ensureNotKey(beginRoot);
+    beginRoot = this.ensureNode(beginRoot);
 
     if (!beginRoot) return result;
 
@@ -930,10 +929,10 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * is no leftmost node, it returns `null` or `undefined` depending on the input.
    */
   getLeftMost(
-    beginRoot: BTNKey | N | null | undefined = this.root,
+    beginRoot: BTNodeKeyOrNode<N> = this.root,
     iterationType = this.iterationType
   ): N | null | undefined {
-    beginRoot = this.ensureNotKey(beginRoot);
+    beginRoot = this.ensureNode(beginRoot);
 
     if (!beginRoot) return beginRoot;
 
@@ -976,11 +975,11 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * is no rightmost node, it returns `null` or `undefined`, depending on the input.
    */
   getRightMost(
-    beginRoot: BTNKey | N | null | undefined = this.root,
+    beginRoot: BTNodeKeyOrNode<N> = this.root,
     iterationType = this.iterationType
   ): N | null | undefined {
     // TODO support get right most by passing key in
-    beginRoot = this.ensureNotKey(beginRoot);
+    beginRoot = this.ensureNode(beginRoot);
     if (!beginRoot) return beginRoot;
 
     if (iterationType === IterationType.RECURSIVE) {
@@ -1018,9 +1017,9 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * possible values:
    * @returns a boolean value.
    */
-  isSubtreeBST(beginRoot: BTNKey | N | null | undefined, iterationType = this.iterationType): boolean {
+  isSubtreeBST(beginRoot: BTNodeKeyOrNode<N>, iterationType = this.iterationType): boolean {
     // TODO there is a bug
-    beginRoot = this.ensureNotKey(beginRoot);
+    beginRoot = this.ensureNode(beginRoot);
     if (!beginRoot) return true;
 
     if (iterationType === IterationType.RECURSIVE) {
@@ -1077,21 +1076,21 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
 
   subTreeTraverse<C extends BTNCallback<N>>(
     callback?: C,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType,
     includeNull?: false
   ): ReturnType<C>[];
 
   subTreeTraverse<C extends BTNCallback<N>>(
     callback?: C,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType,
     includeNull?: undefined
   ): ReturnType<C>[];
 
   subTreeTraverse<C extends BTNCallback<N | null | undefined>>(
     callback?: C,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType,
     includeNull?: true
   ): ReturnType<C>[];
@@ -1120,11 +1119,11 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    */
   subTreeTraverse<C extends BTNCallback<N | null | undefined>>(
     callback: C = this._defaultOneParamCallback as C,
-    beginRoot: BTNKey | N | null | undefined = this.root,
+    beginRoot: BTNodeKeyOrNode<N> = this.root,
     iterationType = this.iterationType,
     includeNull = false
   ): ReturnType<C>[] {
-    beginRoot = this.ensureNotKey(beginRoot);
+    beginRoot = this.ensureNode(beginRoot);
 
     const ans: (ReturnType<BTNCallback<N>> | null | undefined)[] = [];
     if (!beginRoot) return ans;
@@ -1210,7 +1209,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
   dfs<C extends BTNCallback<N>>(
     callback?: C,
     pattern?: DFSOrderPattern,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType,
     includeNull?: false
   ): ReturnType<C>[];
@@ -1218,7 +1217,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
   dfs<C extends BTNCallback<N>>(
     callback?: C,
     pattern?: DFSOrderPattern,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType,
     includeNull?: undefined
   ): ReturnType<C>[];
@@ -1226,7 +1225,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
   dfs<C extends BTNCallback<N | null | undefined>>(
     callback?: C,
     pattern?: DFSOrderPattern,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType,
     includeNull?: true
   ): ReturnType<C>[];
@@ -1257,11 +1256,11 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
   dfs<C extends BTNCallback<N | null | undefined>>(
     callback: C = this._defaultOneParamCallback as C,
     pattern: DFSOrderPattern = 'in',
-    beginRoot: BTNKey | N | null | undefined = this.root,
+    beginRoot: BTNodeKeyOrNode<N> = this.root,
     iterationType: IterationType = IterationType.ITERATIVE,
     includeNull = false
   ): ReturnType<C>[] {
-    beginRoot = this.ensureNotKey(beginRoot);
+    beginRoot = this.ensureNode(beginRoot);
     if (!beginRoot) return [];
     const ans: ReturnType<C>[] = [];
     if (iterationType === IterationType.RECURSIVE) {
@@ -1356,21 +1355,21 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
 
   bfs<C extends BTNCallback<N>>(
     callback?: C,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType,
     includeNull?: false
   ): ReturnType<C>[];
 
   bfs<C extends BTNCallback<N>>(
     callback?: C,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType,
     includeNull?: undefined
   ): ReturnType<C>[];
 
   bfs<C extends BTNCallback<N | null | undefined>>(
     callback?: C,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType,
     includeNull?: true
   ): ReturnType<C>[];
@@ -1398,11 +1397,11 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    */
   bfs<C extends BTNCallback<N | null | undefined>>(
     callback: C = this._defaultOneParamCallback as C,
-    beginRoot: BTNKey | N | null | undefined = this.root,
+    beginRoot: BTNodeKeyOrNode<N> = this.root,
     iterationType = this.iterationType,
     includeNull = false
   ): ReturnType<C>[] {
-    beginRoot = this.ensureNotKey(beginRoot);
+    beginRoot = this.ensureNode(beginRoot);
     if (!beginRoot) return [];
 
     const ans: ReturnType<BTNCallback<N>>[] = [];
@@ -1457,21 +1456,21 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
 
   listLevels<C extends BTNCallback<N>>(
     callback?: C,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType,
     includeNull?: false
   ): ReturnType<C>[][];
 
   listLevels<C extends BTNCallback<N>>(
     callback?: C,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType,
     includeNull?: undefined
   ): ReturnType<C>[][];
 
   listLevels<C extends BTNCallback<N | null | undefined>>(
     callback?: C,
-    beginRoot?: BTNKey | N | null | undefined,
+    beginRoot?: BTNodeKeyOrNode<N>,
     iterationType?: IterationType,
     includeNull?: true
   ): ReturnType<C>[][];
@@ -1499,11 +1498,11 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    */
   listLevels<C extends BTNCallback<N | null | undefined>>(
     callback: C = this._defaultOneParamCallback as C,
-    beginRoot: BTNKey | N | null | undefined = this.root,
+    beginRoot: BTNodeKeyOrNode<N> = this.root,
     iterationType = this.iterationType,
     includeNull = false
   ): ReturnType<C>[][] {
-    beginRoot = this.ensureNotKey(beginRoot);
+    beginRoot = this.ensureNode(beginRoot);
     const levelsNodes: ReturnType<C>[][] = [];
     if (!beginRoot) return levelsNodes;
 
@@ -1557,8 +1556,8 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * `null`, or `undefined`.
    * @returns The function `getPredecessor` returns a value of type `N | undefined`.
    */
-  getPredecessor(node: BTNKey | N | null | undefined): N | undefined {
-    node = this.ensureNotKey(node);
+  getPredecessor(node: BTNodeKeyOrNode<N>): N | undefined {
+    node = this.ensureNode(node);
     if (!this.isRealNode(node)) return undefined;
 
     if (node.left) {
@@ -1581,7 +1580,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * after the given node in the inorder traversal of the binary tree.
    */
   getSuccessor(x?: BTNKey | N | null): N | null | undefined {
-    x = this.ensureNotKey(x);
+    x = this.ensureNode(x);
     if (!x) return undefined;
 
     if (x.right) {
@@ -1617,9 +1616,9 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
   morris<C extends BTNCallback<N>>(
     callback: C = this._defaultOneParamCallback as C,
     pattern: DFSOrderPattern = 'in',
-    beginRoot: BTNKey | N | null | undefined = this.root
+    beginRoot: BTNodeKeyOrNode<N> = this.root
   ): ReturnType<C>[] {
-    beginRoot = this.ensureNotKey(beginRoot);
+    beginRoot = this.ensureNode(beginRoot);
     if (beginRoot === null) return [];
     const ans: ReturnType<BTNCallback<N>>[] = [];
 
@@ -1729,7 +1728,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     const newTree = this.createTree();
     for (const [key, value] of this) {
       if (predicate([key, value], this)) {
-        newTree.add(key, value);
+        newTree.add([key, value]);
       }
     }
     return newTree;
@@ -1744,7 +1743,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
   map(callback: (entry: [BTNKey, V | undefined], tree: this) => V) {
     const newTree = this.createTree();
     for (const [key, value] of this) {
-      newTree.add(key, callback([key, value], this));
+      newTree.add([key, callback([key, value], this)]);
     }
     return newTree;
   }
@@ -1825,9 +1824,9 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * following types:
    * @param {BinaryTreePrintOptions} [options={ isShowUndefined: false, isShowNull: false, isShowRedBlackNIL: false}] - Options object that controls printing behavior. You can specify whether to display undefined, null, or sentinel nodes.
    */
-  print(beginRoot: BTNKey | N | null | undefined = this.root, options?: BinaryTreePrintOptions): void {
+  print(beginRoot: BTNodeKeyOrNode<N> = this.root, options?: BinaryTreePrintOptions): void {
     const opts = { isShowUndefined: false, isShowNull: false, isShowRedBlackNIL: false, ...options };
-    beginRoot = this.ensureNotKey(beginRoot);
+    beginRoot = this.ensureNode(beginRoot);
     if (!beginRoot) return;
 
     if (opts.isShowUndefined) console.log(`U for undefined
@@ -1847,19 +1846,6 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     display(beginRoot);
   }
 
-  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 _displayAux(node: N | null | undefined, options: BinaryTreePrintOptions): NodeDisplayLayout {
     const { isShowNull, isShowUndefined, isShowRedBlackNIL } = options;
     const emptyDisplayLayout = <NodeDisplayLayout>[['─'], 1, 0, 0];
@@ -1918,9 +1904,9 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * @param {N} destNode - The destination node to swap.
    * @returns {N} - The destination node after the swap.
    */
-  protected _swap(srcNode: BTNKey | N | null | undefined, destNode: BTNKey | N | null | undefined): N | undefined {
-    srcNode = this.ensureNotKey(srcNode);
-    destNode = this.ensureNotKey(destNode);
+  protected _swapProperties(srcNode: BTNodeKeyOrNode<N>, destNode: BTNodeKeyOrNode<N>): N | undefined {
+    srcNode = this.ensureNode(srcNode);
+    destNode = this.ensureNode(destNode);
 
     if (srcNode && destNode) {
       const { key, value } = destNode;
@@ -1939,6 +1925,32 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     return undefined;
   }
 
+  /**
+   * The function replaces an old node with a new node in a binary tree.
+   * @param {N} oldNode - The oldNode parameter represents the node that needs to be replaced in the
+   * tree.
+   * @param {N} newNode - The `newNode` parameter is the node that will replace the `oldNode` in the
+   * tree.
+   * @returns The method is returning the newNode.
+   */
+  protected _replaceNode(oldNode: N, newNode: N): N {
+    if (oldNode.parent) {
+      if (oldNode.parent.left === oldNode) {
+        oldNode.parent.left = newNode;
+      } else if (oldNode.parent.right === oldNode) {
+        oldNode.parent.right = newNode;
+      }
+    }
+    newNode.left = oldNode.left;
+    newNode.right = oldNode.right;
+    newNode.parent = oldNode.parent;
+    if (this.root === oldNode) {
+      this._root = newNode;
+    }
+
+    return newNode;
+  }
+
   /**
    * The function `_addTo` adds a new node to a binary tree if there is an available position.
    * @param {N | null | undefined} newNode - The `newNode` parameter represents the node that you want to add to
@@ -1950,7 +1962,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * the binary tree. If neither the left nor right child is available, the function returns undefined.
    * If the parent node is null, the function also returns undefined.
    */
-  protected _addTo(newNode: N | null | undefined, parent: BTNKey | N | null | undefined): N | null | undefined {
+  protected _addTo(newNode: N | null | undefined, parent: BTNodeKeyOrNode<N>): N | null | undefined {
     if (this.isNodeKey(parent)) parent = this.getNode(parent);
 
     if (parent) {