min-heap-typed 1.42.5 → 1.42.7

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

@@ -7,7 +7,7 @@
  */
 
 import type {BinaryTreeNodeNested, BinaryTreeOptions, BTNCallback, BTNKey} from '../../types';
-import {BinaryTreeDeletedResult, DFSOrderPattern, FamilyPosition, IterationType} from '../../types';
+import {BiTreeDeleteResult, DFSOrderPattern, FamilyPosition, IterationType} from '../../types';
 import {IBinaryTree} from '../../interfaces';
 import {trampoline} from '../../utils';
 import {Queue} from '../queue';
@@ -26,12 +26,12 @@ export class BinaryTreeNode<V = any, N extends BinaryTreeNode<V, N> = BinaryTree
   /**
    * The value stored in the node.
    */
-  value: V | undefined;
+  value?: V;
 
   /**
    * The parent node of the current node.
    */
-  parent: N | null | undefined;
+  parent?: N | null;
 
   /**
    * Creates a new instance of BinaryTreeNode.
@@ -43,7 +43,7 @@ export class BinaryTreeNode<V = any, N extends BinaryTreeNode<V, N> = BinaryTree
     this.value = value;
   }
 
-  protected _left: N | null | undefined;
+  protected _left?: N | null;
 
   /**
    * Get the left child node.
@@ -63,7 +63,7 @@ export class BinaryTreeNode<V = any, N extends BinaryTreeNode<V, N> = BinaryTree
     this._left = v;
   }
 
-  protected _right: N | null | undefined;
+  protected _right?: N | null;
 
   /**
    * Get the right child node.
@@ -117,13 +117,14 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * @param {BinaryTreeOptions} [options] - The options for the binary tree.
    */
   constructor(options?: BinaryTreeOptions) {
-    if (options !== undefined) {
+    if (options) {
       const {iterationType = IterationType.ITERATIVE} = options;
       this.iterationType = iterationType;
     }
+    this._size = 0;
   }
 
-  protected _root: N | null | undefined = undefined;
+  protected _root?: N | null;
 
   /**
    * Get the root node of the binary tree.
@@ -132,7 +133,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     return this._root;
   }
 
-  protected _size = 0;
+  protected _size: number;
 
   /**
    * Get the number of nodes in the binary tree.
@@ -151,22 +152,6 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     return new BinaryTreeNode<V, N>(key, value) as N;
   }
 
-  /**
-   * Clear the binary tree, removing all nodes.
-   */
-  clear() {
-    this._setRoot(undefined);
-    this._size = 0;
-  }
-
-  /**
-   * Check if the binary tree is empty.
-   * @returns {boolean} - True if the binary tree is empty, false otherwise.
-   */
-  isEmpty(): boolean {
-    return this.size === 0;
-  }
-
   /**
    * Add a node with the given key and value to the binary tree.
    * @param {BTNKey | N | null} keyOrNode - The key or node to add to the binary tree.
@@ -192,11 +177,11 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
       return;
     };
 
-    let inserted: N | null | undefined, needInsert: N | null;
+    let inserted: N | null | undefined, needInsert: N | null | undefined;
 
     if (keyOrNode === null) {
       needInsert = null;
-    } else if (typeof keyOrNode === 'number') {
+    } else if (this.isNodeKey(keyOrNode)) {
       needInsert = this.createNode(keyOrNode, value);
     } else if (keyOrNode instanceof BinaryTreeNode) {
       needInsert = keyOrNode;
@@ -204,19 +189,11 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
       return;
     }
 
-    // const key = typeof keyOrNode === 'number' ? keyOrNode : keyOrNode ? keyOrNode.key : undefined;
-    // const existNode = key !== undefined ? this.getNode(key, (node: N) => node.key) : undefined;
-
     if (this.root) {
-      // if (existNode) {
-      //   existNode.value = value;
-      //   inserted = existNode;
-      // } else {
       inserted = _bfs(this.root, needInsert);
-      // }
     } else {
       this._setRoot(needInsert);
-      if (needInsert !== null) {
+      if (needInsert) {
         this._size = 1;
       } else {
         this._size = 0;
@@ -236,7 +213,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * the value of the nodes will be `undefined`.
    * @returns The function `addMany` returns an array of `N`, `null`, or `undefined` values.
    */
-  addMany(keysOrNodes: (BTNKey | null | undefined)[] | (N | null | undefined)[], values?: V[]): (N | null | undefined)[] {
+  addMany(keysOrNodes: (BTNKey | N |null | undefined)[], values?: (V | undefined)[]): (N | null | undefined)[] {
     // TODO not sure addMany not be run multi times
     return keysOrNodes.map((keyOrNode, i) => {
       if (keyOrNode instanceof BinaryTreeNode) {
@@ -256,50 +233,50 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * 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>} [data] - The `data` parameter is an optional array of values that will be assigned to
+   * @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 | null | undefined)[] | (N | null | undefined)[], data?: Array<V>): boolean {
+  refill(keysOrNodes: (BTNKey | N | null | undefined)[], values?: (V | undefined)[]): boolean {
     this.clear();
-    return keysOrNodes.length === this.addMany(keysOrNodes, data).length;
+    return keysOrNodes.length === this.addMany(keysOrNodes, values).length;
   }
 
-  delete<C extends BTNCallback<N, BTNKey>>(identifier: BTNKey, callback?: C): BinaryTreeDeletedResult<N>[];
+  delete<C extends BTNCallback<N, BTNKey>>(identifier: BTNKey, callback?: C): BiTreeDeleteResult<N>[];
 
-  delete<C extends BTNCallback<N, N>>(identifier: N | null | undefined, callback?: C): BinaryTreeDeletedResult<N>[];
+  delete<C extends BTNCallback<N, N>>(identifier: N | null | undefined, callback?: C): BiTreeDeleteResult<N>[];
 
-  delete<C extends BTNCallback<N>>(identifier: ReturnType<C>, callback: C): BinaryTreeDeletedResult<N>[];
+  delete<C extends BTNCallback<N>>(identifier: ReturnType<C>, callback: C): BiTreeDeleteResult<N>[];
 
   /**
    * The `delete` function removes a node from a binary search tree and returns the deleted node along
    * with the parent node that needs to be balanced.
    * a key (`BTNKey`). If it is a key, the function will find the corresponding node in the
    * binary tree.
-   * @returns an array of `BinaryTreeDeletedResult<N>` objects.
+   * @returns an array of `BiTreeDeleteResult<N>` objects.
    * @param {ReturnType<C>} identifier - The `identifier` parameter is either a
    * `BTNKey` or a generic type `N`. It represents the property of the node that we are
    * searching for. It can be a specific key value or any other property of the node.
    * @param callback - The `callback` parameter is a function that takes a node as input and returns a
    * value. This value is compared with the `identifier` parameter to determine if the node should be
    * included in the result. The `callback` parameter has a default value of
-   * `this.defaultOneParamCallback`, which
+   * `this._defaultOneParamCallback`, which
    */
   delete<C extends BTNCallback<N>>(
     identifier: ReturnType<C> | null | undefined,
-    callback: C = this.defaultOneParamCallback as C
-  ): BinaryTreeDeletedResult<N>[] {
-    const bstDeletedResult: BinaryTreeDeletedResult<N>[] = [];
-    if (!this.root) return bstDeletedResult;
+    callback: C = this._defaultOneParamCallback as C
+  ): BiTreeDeleteResult<N>[] {
+    const deletedResult: BiTreeDeleteResult<N>[] = [];
+    if (!this.root) return deletedResult;
     if ((identifier as any) instanceof BinaryTreeNode) callback = (node => node) as C;
 
     const curr = this.getNode(identifier, callback);
-    if (!curr) return bstDeletedResult;
+    if (!curr) return deletedResult;
 
     const parent: N | null | undefined = curr?.parent ? curr.parent : null;
-    let needBalanced: N | null | undefined = null,
-      orgCurrent = curr;
+    let needBalanced: N | null | undefined = undefined;
+    let orgCurrent: N | undefined = curr;
 
     if (!curr.left) {
       if (!parent) {
@@ -329,8 +306,8 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     }
     this._size = this.size - 1;
 
-    bstDeletedResult.push({deleted: orgCurrent, needBalanced});
-    return bstDeletedResult;
+    deletedResult.push({deleted: orgCurrent, needBalanced});
+    return deletedResult;
   }
 
   /**
@@ -346,8 +323,8 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * @returns the depth of the `distNode` relative to the `beginRoot`.
    */
   getDepth(distNode: BTNKey | N | null | undefined, beginRoot: BTNKey | N | null | undefined = this.root): number {
-    if (typeof distNode === 'number') distNode = this.getNode(distNode);
-    if (typeof beginRoot === 'number') beginRoot = this.getNode(beginRoot);
+    distNode = this.ensureNotKey(distNode);
+    beginRoot = this.ensureNotKey(beginRoot);
     let depth = 0;
     while (distNode?.parent) {
       if (distNode === beginRoot) {
@@ -372,7 +349,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * @returns the height of the binary tree.
    */
   getHeight(beginRoot: BTNKey | N | null | undefined = this.root, iterationType = this.iterationType): number {
-    if (typeof beginRoot === 'number') beginRoot = this.getNode(beginRoot);
+    beginRoot = this.ensureNotKey(beginRoot);
     if (!beginRoot) return -1;
 
     if (iterationType === IterationType.RECURSIVE) {
@@ -395,14 +372,9 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
       while (stack.length > 0) {
         const {node, depth} = stack.pop()!;
 
-        if (node.left) {
-          stack.push({node: node.left, depth: depth + 1});
-        }
-
-        if (node.right) {
-          stack.push({node: node.right, depth: depth + 1});
-        }
-
+        if (node.left) stack.push({node: node.left, depth: depth + 1});
+        if (node.right) stack.push({node: node.right, depth: depth + 1});
+        
         maxHeight = Math.max(maxHeight, depth);
       }
 
@@ -420,9 +392,10 @@ 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: N | null | undefined = this.root, iterationType = this.iterationType): number {
+  getMinHeight(beginRoot: BTNKey | N | null | undefined = this.root, iterationType = this.iterationType): number {
+    beginRoot = this.ensureNotKey(beginRoot);
     if (!beginRoot) return -1;
-
+    
     if (iterationType === IterationType.RECURSIVE) {
       const _getMinHeight = (cur: N | null | undefined): number => {
         if (!cur) return 0;
@@ -469,7 +442,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * either be of type `N` (representing a node in a tree) or `null` (representing an empty tree).
    * @returns The method is returning a boolean value.
    */
-  isPerfectlyBalanced(beginRoot: N | null | undefined = this.root): boolean {
+  isPerfectlyBalanced(beginRoot: BTNKey | N | null | undefined = this.root): boolean {
     return this.getMinHeight(beginRoot) + 1 >= this.getHeight(beginRoot);
   }
 
@@ -477,7 +450,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     identifier: BTNKey,
     callback?: C,
     onlyOne?: boolean,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType
   ): N[];
 
@@ -485,7 +458,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     identifier: N | null | undefined,
     callback?: C,
     onlyOne?: boolean,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType
   ): N[];
 
@@ -493,7 +466,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     identifier: ReturnType<C>,
     callback: C,
     onlyOne?: boolean,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType
   ): N[];
 
@@ -506,7 +479,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * @param callback - The `callback` parameter is a function that takes a node as input and returns a
    * value. This value is compared with the `identifier` parameter to determine if the node should be
    * included in the result. The `callback` parameter has a default value of
-   * `this.defaultOneParamCallback`, which
+   * `this._defaultOneParamCallback`, which
    * @param [onlyOne=false] - A boolean value indicating whether to stop searching after finding the
    * first node that matches the identifier. If set to true, the function will return an array with
    * only one element (or an empty array if no matching node is found). If set to false (default), the
@@ -520,13 +493,16 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    */
   getNodes<C extends BTNCallback<N>>(
     identifier: ReturnType<C> | null | undefined,
-    callback: C = this.defaultOneParamCallback as C,
+    callback: C = this._defaultOneParamCallback as C,
     onlyOne = false,
-    beginRoot: N | null | undefined = this.root,
+    beginRoot: BTNKey | N | null | undefined = this.root,
     iterationType = this.iterationType
   ): N[] {
     if (!beginRoot) return [];
     if ((identifier as any) instanceof BinaryTreeNode) callback = (node => node) as C;
+    beginRoot = this.ensureNotKey(beginRoot);
+    if (!beginRoot) return [];
+    
     const ans: N[] = [];
 
     if (iterationType === IterationType.RECURSIVE) {
@@ -562,21 +538,21 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
   has<C extends BTNCallback<N, BTNKey>>(
     identifier: BTNKey,
     callback?: C,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType
   ): boolean;
 
   has<C extends BTNCallback<N, N>>(
     identifier: N | null | undefined,
     callback?: C,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType
   ): boolean;
 
   has<C extends BTNCallback<N>>(
     identifier: ReturnType<C> | null | undefined,
     callback: C,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType
   ): boolean;
 
@@ -588,7 +564,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * @param callback - The `callback` parameter is a function that is used to determine whether a node
    * matches the desired criteria. It takes a node as input and returns a boolean value indicating
    * whether the node matches the criteria or not. The default callback function
-   * `this.defaultOneParamCallback` is used if no callback function is
+   * `this._defaultOneParamCallback` is used if no callback function is
    * @param beginRoot - The `beginRoot` parameter is the starting point for the search. It specifies
    * the node from which the search should begin. By default, it is set to `this.root`, which means the
    * search will start from the root node of the binary tree. However, you can provide a different node
@@ -599,8 +575,8 @@ 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 = this.root,
+    callback: C = this._defaultOneParamCallback as C,
+    beginRoot: BTNKey | N | null | undefined = this.root,
     iterationType = this.iterationType
   ): boolean {
     if ((identifier as any) instanceof BinaryTreeNode) callback = (node => node) as C;
@@ -611,21 +587,21 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
   getNode<C extends BTNCallback<N, BTNKey>>(
     identifier: BTNKey,
     callback?: C,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType
   ): N | null | undefined;
 
   getNode<C extends BTNCallback<N, N>>(
     identifier: N | null | undefined,
     callback?: C,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType
   ): N | null | undefined;
 
   getNode<C extends BTNCallback<N>>(
     identifier: ReturnType<C>,
     callback: C,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType
   ): N | null | undefined;
 
@@ -637,7 +613,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * @param callback - The `callback` parameter is a function that is used to determine whether a node
    * matches the desired criteria. It takes a node as input and returns a boolean value indicating
    * whether the node matches the criteria or not. The default callback function
-   * (`this.defaultOneParamCallback`) is used if no callback function is
+   * (`this._defaultOneParamCallback`) is used if no callback function is
    * @param beginRoot - The `beginRoot` parameter is the starting point for the search. It specifies
    * the root node from which the search should begin.
    * @param iterationType - The `iterationType` parameter specifies the type of iteration to be
@@ -646,8 +622,8 @@ 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 = this.root,
+    callback: C = this._defaultOneParamCallback as C,
+    beginRoot: BTNKey | N | null | undefined = this.root,
     iterationType = this.iterationType
   ): N | null | undefined {
     if ((identifier as any) instanceof BinaryTreeNode) callback = (node => node) as C;
@@ -655,24 +631,75 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     return this.getNodes(identifier, callback, true, beginRoot, iterationType)[0] ?? null;
   }
 
+  /**
+   * The function `getNodeByKey` searches for a node in a binary tree by its key, using either
+   * recursive or iterative iteration.
+   * @param {BTNKey} key - The `key` parameter is the key value that we are searching for in the tree.
+   * It is used to find the node with the matching key value.
+   * @param iterationType - The `iterationType` parameter is used to determine whether the search for
+   * the node with the given key should be performed iteratively or recursively. It has two possible
+   * values:
+   * @returns The function `getNodeByKey` returns a node (`N`) if a node with the specified key is
+   * found in the binary tree. If no node is found, it returns `undefined`.
+   */
+  getNodeByKey(key: BTNKey, iterationType = IterationType.ITERATIVE): N | undefined {
+    if (!this.root) return undefined;
+    if (iterationType === IterationType.RECURSIVE) {
+      const _dfs = (cur: N): N | undefined => {
+        if (cur.key === key) return cur;
+
+        if (!cur.left && !cur.right) return;
+        if (cur.left) return _dfs(cur.left);
+        if (cur.right) return _dfs(cur.right);
+      };
+
+      return _dfs(this.root);
+    } else {
+      const queue = new Queue<N>([this.root]);
+      while (queue.size > 0) {
+        const cur = queue.shift();
+        if (cur) {
+          if (cur.key === key) return cur;
+          cur.left && queue.push(cur.left);
+          cur.right && queue.push(cur.right);
+        }
+      }
+    }
+  }
+
+  /**
+   * The function `ensureNotKey` 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.
+   * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
+   * type of iteration to be used when searching for a node by key. It has a default value of
+   * `IterationType.ITERATIVE`.
+   * @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 {
+    return this.isNodeKey(key) ? this.getNodeByKey(key, iterationType) : key;
+  }
+  
   get<C extends BTNCallback<N, BTNKey>>(
     identifier: BTNKey,
     callback?: C,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType
   ): V | undefined;
 
   get<C extends BTNCallback<N, N>>(
     identifier: N | null | undefined,
     callback?: C,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType
   ): V | undefined;
 
   get<C extends BTNCallback<N>>(
     identifier: ReturnType<C>,
     callback: C,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType
   ): V | undefined;
 
@@ -684,7 +711,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * @param callback - The `callback` parameter is a function that is used to determine whether a node
    * matches the desired criteria. It takes a node as input and returns a boolean value indicating
    * whether the node matches the criteria or not. The default callback function
-   * (`this.defaultOneParamCallback`) is used if no callback function is
+   * (`this._defaultOneParamCallback`) is used if no callback function is
    * @param beginRoot - The `beginRoot` parameter is the starting point for the search. It specifies
    * the root node from which the search should begin.
    * @param iterationType - The `iterationType` parameter specifies the type of iteration to be
@@ -693,15 +720,31 @@ 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 = this.root,
+    callback: C = this._defaultOneParamCallback as C,
+    beginRoot:BTNKey | N | null | undefined = this.root,
     iterationType = this.iterationType
   ): V | undefined {
     if ((identifier as any) instanceof BinaryTreeNode) callback = (node => node) as C;
 
     return this.getNode(identifier, callback, beginRoot, iterationType)?.value ?? undefined;
   }
+  
+  /**
+   * Clear the binary tree, removing all nodes.
+   */
+  clear() {
+    this._setRoot(undefined);
+    this._size = 0;
+  }
 
+  /**
+   * Check if the binary tree is empty.
+   * @returns {boolean} - True if the binary tree is empty, false otherwise.
+   */
+  isEmpty(): boolean {
+    return this.size === 0;
+  }
+  
   /**
    * The function `getPathToRoot` returns an array of nodes starting from a given node and traversing
    * up to the root node, with the option to reverse the order of the nodes.
@@ -712,9 +755,13 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * reversed before returning it. If `isReverse` is set to `false` or not provided, the path will
    * @returns The function `getPathToRoot` returns an array of type `N[]`.
    */
-  getPathToRoot(beginRoot: N, isReverse = true): N[] {
+  getPathToRoot(beginRoot: BTNKey | N | null | undefined, isReverse = true): N[] {
     // TODO to support get path through passing key
     const result: N[] = [];
+    beginRoot = this.ensureNotKey(beginRoot);
+    
+    if (!beginRoot) return result;
+    
     while (beginRoot.parent) {
       // Array.push + Array.reverse is more efficient than Array.unshift
       // TODO may consider using Deque, so far this is not the performance bottleneck
@@ -737,13 +784,13 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * no leftmost node, it returns `null`.
    */
   getLeftMost(beginRoot: BTNKey | N | null | undefined = this.root, iterationType = this.iterationType): N | null | undefined {
-    if (typeof beginRoot === 'number') beginRoot = this.getNode(beginRoot);
+    beginRoot = this.ensureNotKey(beginRoot);
 
     if (!beginRoot) return beginRoot;
 
     if (iterationType === IterationType.RECURSIVE) {
       const _traverse = (cur: N): N => {
-        if (!cur.left) return cur;
+        if (!this.isRealNode(cur.left)) return cur;
         return _traverse(cur.left);
       };
 
@@ -751,7 +798,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     } else {
       // Indirect implementation of iteration using tail recursion optimization
       const _traverse = trampoline((cur: N) => {
-        if (!cur.left) return cur;
+        if (!this.isRealNode(cur.left)) return cur;
         return _traverse.cont(cur.left);
       });
 
@@ -770,13 +817,14 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * @returns The function `getRightMost` returns the rightmost node (`N`) in a binary tree. If the
    * `beginRoot` parameter is `null`, it returns `null`.
    */
-  getRightMost(beginRoot: N | null | undefined = this.root, iterationType = this.iterationType): N | null | undefined {
+  getRightMost(beginRoot: BTNKey | N | null | undefined = this.root, iterationType = this.iterationType): N | null | undefined {
     // TODO support get right most by passing key in
+    beginRoot = this.ensureNotKey(beginRoot);
     if (!beginRoot) return beginRoot;
 
     if (iterationType === IterationType.RECURSIVE) {
       const _traverse = (cur: N): N => {
-        if (!cur.right) return cur;
+        if (!this.isRealNode(cur.right)) return cur;
         return _traverse(cur.right);
       };
 
@@ -784,7 +832,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     } else {
       // Indirect implementation of iteration using tail recursion optimization
       const _traverse = trampoline((cur: N) => {
-        if (!cur.right) return cur;
+        if (!this.isRealNode(cur.right)) return cur;
         return _traverse.cont(cur.right);
       });
 
@@ -801,8 +849,9 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * possible values:
    * @returns The function `isSubtreeBST` returns a boolean value.
    */
-  isSubtreeBST(beginRoot: N | null | undefined, iterationType = this.iterationType): boolean {
+  isSubtreeBST(beginRoot: BTNKey | N | null | undefined, iterationType = this.iterationType): boolean {
     // TODO there is a bug
+    beginRoot = this.ensureNotKey(beginRoot);
     if (!beginRoot) return true;
 
     if (iterationType === IterationType.RECURSIVE) {
@@ -881,12 +930,12 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * @returns The function `subTreeTraverse` returns an array of `ReturnType<BTNCallback<N>>`.
    */
   subTreeTraverse<C extends BTNCallback<N | null | undefined>>(
-    callback: C = this.defaultOneParamCallback as C,
+    callback: C = this._defaultOneParamCallback as C,
     beginRoot: BTNKey | N | null | undefined = this.root,
     iterationType = this.iterationType,
     includeNull = false
   ): ReturnType<C>[] {
-    if (typeof beginRoot === 'number') beginRoot = this.getNode(beginRoot);
+    beginRoot = this.ensureNotKey(beginRoot);
 
     const ans: (ReturnType<BTNCallback<N>> | null | undefined)[] = [];
     if (!beginRoot) return ans;
@@ -926,22 +975,48 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     return ans;
   }
   
-  isNode(node: any): node is N {
+  /**
+   * The function checks if a given node is a real node by verifying if it is an instance of
+   * BinaryTreeNode and its key is not NaN.
+   * @param {any} node - The parameter `node` is of type `any`, which means it can be any data type.
+   * @returns a boolean value.
+   */
+  isRealNode(node: any): node is N {
     return node instanceof BinaryTreeNode && node.key.toString() !== 'NaN';
   }
 
+  /**
+   * The function checks if a given node is a BinaryTreeNode instance and has a key value of NaN.
+   * @param {any} node - The parameter `node` is of type `any`, which means it can be any data type.
+   * @returns a boolean value.
+   */
   isNIL(node: any) {
     return node instanceof BinaryTreeNode && node.key.toString() === 'NaN';
   }
 
+  /**
+   * The function checks if a given node is a real node or null.
+   * @param {any} node - The parameter `node` is of type `any`, which means it can be any data type.
+   * @returns a boolean value.
+   */
   isNodeOrNull(node: any): node is (N | null){
-    return this.isNode(node) || node === null;
+    return this.isRealNode(node) || node === null;
+  }
+
+  /**
+   * The function "isNodeKey" checks if a potential key is a number.
+   * @param {any} potentialKey - The potentialKey parameter is of type any, which means it can be any
+   * data type.
+   * @returns a boolean value indicating whether the potentialKey is of type number or not.
+   */
+  isNodeKey(potentialKey: any) : potentialKey is number {
+    return typeof potentialKey === 'number';
   }
 
   dfs<C extends BTNCallback<N>>(
     callback?: C,
     pattern?: DFSOrderPattern,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType,
     includeNull?: false
   ): ReturnType<C>[];
@@ -949,7 +1024,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
   dfs<C extends BTNCallback<N>>(
     callback?: C,
     pattern?: DFSOrderPattern,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType,
     includeNull?: undefined
   ): ReturnType<C>[];
@@ -957,7 +1032,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
   dfs<C extends BTNCallback<N | null | undefined>>(
     callback?: C,
     pattern?: DFSOrderPattern,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType,
     includeNull?: true
   ): ReturnType<C>[];
@@ -967,7 +1042,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * function on each node according to a specified order pattern.
    * @param callback - The `callback` parameter is a function that will be called on each node during
    * the depth-first search traversal. It takes a node as input and returns a value. The default value
-   * is `this.defaultOneParamCallback`, which is a callback function defined elsewhere in the code.
+   * is `this._defaultOneParamCallback`, which is a callback function defined elsewhere in the code.
    * @param {DFSOrderPattern} [pattern=in] - The `pattern` parameter determines the order in which the
    * nodes are visited during the depth-first search. There are three possible values for `pattern`:
    * @param {N | null | undefined} beginRoot - The `beginRoot` parameter is the starting node for the depth-first
@@ -979,12 +1054,14 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * @returns The function `dfs` returns an array of `ReturnType<BTNCallback<N>>` values.
    */
   dfs<C extends BTNCallback<N | null | undefined>>(
-    callback: C = this.defaultOneParamCallback as C,
+    callback: C = this._defaultOneParamCallback as C,
     pattern: DFSOrderPattern = 'in',
-    beginRoot: N | null | undefined = this.root,
+    beginRoot: BTNKey | N | null | undefined = this.root,
     iterationType: IterationType = IterationType.ITERATIVE,
     includeNull = false
   ): ReturnType<C>[] {
+
+    beginRoot = this.ensureNotKey(beginRoot);
     if (!beginRoot) return [];
     const ans: ReturnType<C>[] = [];
     if (iterationType === IterationType.RECURSIVE) {
@@ -997,7 +1074,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
               if (node && this.isNodeOrNull(node.right)) _traverse(node.right);
             } else {
               if (node && node.left) _traverse(node.left);
-              this.isNode(node) && ans.push(callback(node));
+              this.isRealNode(node) && ans.push(callback(node));
               if (node && node.right) _traverse(node.right);
             }
             break;
@@ -1007,7 +1084,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
               if (node && this.isNodeOrNull(node.left)) _traverse(node.left);
               if (node && this.isNodeOrNull(node.right)) _traverse(node.right);
             } else {
-              this.isNode(node) && ans.push(callback(node));
+              this.isRealNode(node) && ans.push(callback(node));
               if (node && node.left) _traverse(node.left);
               if (node && node.right) _traverse(node.right);
             }
@@ -1020,7 +1097,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
             } else {
               if (node && node.left) _traverse(node.left);
               if (node && node.right) _traverse(node.right);
-              this.isNode(node) && ans.push(callback(node));
+              this.isRealNode(node) && ans.push(callback(node));
             }
 
             break;
@@ -1074,21 +1151,21 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
 
   bfs<C extends BTNCallback<N>>(
     callback?: C,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType,
     includeNull?: false
   ): ReturnType<C>[];
 
   bfs<C extends BTNCallback<N>>(
     callback?: C,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType,
     includeNull?: undefined
   ): ReturnType<C>[];
 
   bfs<C extends BTNCallback<N | null | undefined>>(
     callback?: C,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType,
     includeNull?: true
   ): ReturnType<C>[];
@@ -1098,7 +1175,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * function on each node.
    * @param callback - The `callback` parameter is a function that will be called for each node in the
    * breadth-first search. It takes a node of type `N` as its argument and returns a value of type
-   * `ReturnType<BTNCallback<N>>`. The default value for this parameter is `this.defaultOneParamCallback
+   * `ReturnType<BTNCallback<N>>`. The default value for this parameter is `this._defaultOneParamCallback
    * @param {N | null | undefined} beginRoot - The `beginRoot` parameter is the starting node for the breadth-first
    * search. It determines from which node the search will begin. If `beginRoot` is `null`, the search
    * will not be performed and an empty array will be returned.
@@ -1108,11 +1185,12 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * @returns The function `bfs` returns an array of `ReturnType<BTNCallback<N>>[]`.
    */
   bfs<C extends BTNCallback<N | null | undefined>>(
-    callback: C = this.defaultOneParamCallback as C,
-    beginRoot: N | null | undefined = this.root,
+    callback: C = this._defaultOneParamCallback as C,
+    beginRoot: BTNKey | N | null | undefined = this.root,
     iterationType = this.iterationType,
     includeNull = false
   ): ReturnType<C>[] {
+    beginRoot = this.ensureNotKey(beginRoot);
     if (!beginRoot) return [];
 
     const ans: ReturnType<BTNCallback<N>>[] = [];
@@ -1162,21 +1240,21 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
 
   listLevels<C extends BTNCallback<N>>(
     callback?: C,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType,
     includeNull?: false
   ): ReturnType<C>[][];
 
   listLevels<C extends BTNCallback<N>>(
     callback?: C,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType,
     includeNull?: undefined
   ): ReturnType<C>[][];
 
   listLevels<C extends BTNCallback<N | null | undefined>>(
     callback?: C,
-    beginRoot?: N | null | undefined,
+    beginRoot?: BTNKey | N | null | undefined,
     iterationType?: IterationType,
     includeNull?: true
   ): ReturnType<C>[][];
@@ -1198,13 +1276,14 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * function `C` applied to the nodes at that level.
    */
   listLevels<C extends BTNCallback<N | null | undefined>>(
-    callback: C = this.defaultOneParamCallback as C,
-    beginRoot: N | null | undefined = this.root,
+    callback: C = this._defaultOneParamCallback as C,
+    beginRoot: BTNKey | N | null | undefined = this.root,
     iterationType = this.iterationType,
     includeNull = false
   ): ReturnType<C>[][] {
-    if (!beginRoot) return [];
+    beginRoot = this.ensureNotKey(beginRoot);
     const levelsNodes: ReturnType<C>[][] = [];
+    if (!beginRoot) return levelsNodes;
 
     if (iterationType === IterationType.RECURSIVE) {
       const _recursive = (node: N | null | undefined, level: number) => {
@@ -1243,15 +1322,20 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     return levelsNodes;
   }
 
+  getPredecessor(node: N ): N
+
   /**
    * The function returns the predecessor node of a given node in a binary tree.
    * @param {N} node - The parameter "node" represents a node in a binary tree.
    * @returns The function `getPredecessor` returns the predecessor node of the given node `node`.
    */
-  getPredecessor(node: N): N {
+  getPredecessor(node: BTNKey | N | null | undefined): N | undefined{
+    node = this.ensureNotKey(node);
+    if (!this.isRealNode(node)) return undefined;
+
     if (node.left) {
       let predecessor: N | null | undefined = node.left;
-      while (!predecessor || (predecessor.right && predecessor.right !== node)) {
+      while (!this.isRealNode(predecessor) || (this.isRealNode(predecessor.right) && predecessor.right !== node)) {
         if (predecessor) {
           predecessor = predecessor.right;
         }
@@ -1269,7 +1353,10 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * @returns The function `getSuccessor` returns a value of type `N` (the successor node), or `null`
    * if there is no successor, or `undefined` if the input `x` is `undefined`.
    */
-  getSuccessor(x: N): N | null | undefined {
+  getSuccessor(x?: BTNKey | N | null): N | null | undefined {
+    x = this.ensureNotKey(x);
+    if (!x) return undefined;
+
     if (x.right) {
       return this.getLeftMost(x.right);
     }
@@ -1287,7 +1374,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * algorithm and returns an array of values obtained by applying a callback function to each node.
    * @param callback - The `callback` parameter is a function that will be called on each node in the
    * tree. It takes a node of type `N` as input and returns a value of type `ReturnType<BTNCallback<N>>`. The
-   * default value for this parameter is `this.defaultOneParamCallback`.
+   * default value for this parameter is `this._defaultOneParamCallback`.
    * @param {DFSOrderPattern} [pattern=in] - The `pattern` parameter in the `morris` function
    * determines the order in which the nodes of a binary tree are traversed. It can have one of the
    * following values:
@@ -1297,10 +1384,11 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * @returns The `morris` function returns an array of `ReturnType<BTNCallback<N>>` values.
    */
   morris<C extends BTNCallback<N>>(
-    callback: C = this.defaultOneParamCallback as C,
+    callback: C = this._defaultOneParamCallback as C,
     pattern: DFSOrderPattern = 'in',
-    beginRoot: N | null | undefined = this.root
+    beginRoot: BTNKey | N | null | undefined = this.root
   ): ReturnType<C>[] {
+    beginRoot = this.ensureNotKey(beginRoot);
     if (beginRoot === null) return [];
     const ans: ReturnType<BTNCallback<N>>[] = [];
 
@@ -1425,7 +1513,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     }
   }
 
-  protected defaultOneParamCallback = (node: N) => node.key;
+  protected _defaultOneParamCallback = (node: N) => node.key;
 
   /**
    * Swap the data of two nodes in the binary tree.
@@ -1433,19 +1521,26 @@ 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: N, destNode: N): N {
-    const {key, value} = destNode;
-    const tempNode = this.createNode(key, value);
+  protected _swap(srcNode: BTNKey | N | null | undefined, destNode:BTNKey | N | null | undefined): N | undefined{
+    srcNode = this.ensureNotKey(srcNode);
+    destNode = this.ensureNotKey(destNode);
 
-    if (tempNode) {
-      destNode.key = srcNode.key;
-      destNode.value = srcNode.value;
+    if (srcNode && destNode) {
+      const {key, value} = destNode;
+      const tempNode = this.createNode(key, value);
 
-      srcNode.key = tempNode.key;
-      srcNode.value = tempNode.value;
+      if (tempNode) {
+        destNode.key = srcNode.key;
+        destNode.value = srcNode.value;
+
+        srcNode.key = tempNode.key;
+        srcNode.value = tempNode.value;
+      }
+
+      return destNode;
     }
+    return undefined;
 
-    return destNode;
   }
 
   /**
@@ -1459,7 +1554,9 @@ 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: N): N | null | undefined {
+  protected _addTo(newNode: N | null | undefined, parent: BTNKey | N | null | undefined): N | null | undefined {
+    if (this.isNodeKey(parent)) parent = this.getNode(parent);
+
     if (parent) {
       // When all leaf nodes are null, it will no longer be possible to add new entity nodes to this binary tree.
       // In this scenario, null nodes serve as "sentinel nodes," "virtual nodes," or "placeholder nodes."
@@ -1496,7 +1593,16 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     this._root = v;
   }
 
-  print(beginRoot: N | null | undefined = this.root) {
+  /**
+   * The `print` function is used to display a binary tree structure in a visually appealing way.
+   * @param {N | null | undefined} root - The `root` parameter in the `print` function represents the
+   * root node of a binary tree. It can have one of the following types: `BTNKey`, `N`, `null`, or
+   * `undefined`. The default value is `this.root`, which suggests that `this.root` is the
+   */
+  print(beginRoot: BTNKey | N | null | undefined = this.root): void {
+    beginRoot = this.ensureNotKey(beginRoot);
+    if (!beginRoot) return;
+
     const display = (root: N | null | undefined): void => {
       const [lines, , ,] = _displayAux(root);
       for (const line of lines) {