min-heap-typed 1.50.1 → 1.50.3

package/src/data-structures/base/iterable-base.ts

@@ -154,6 +154,105 @@ export abstract class IterableEntryBase<K = any, V = any> {
    * Time Complexity: O(n)
    * Space Complexity: O(1)
    */
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The `find` function iterates over the entries of a collection and returns the first value for
+   * which the callback function returns true.
+   * @param callbackfn - The callback function that will be called for each entry in the collection. It
+   * takes three arguments: the value of the entry, the key of the entry, and the index of the entry in
+   * the collection. It should return a boolean value indicating whether the current entry matches the
+   * desired condition.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as `this` when executing the `callbackfn` function. If `thisArg` is provided, it will
+   * be passed as the `this` value to the `callbackfn` function. If `thisArg
+   * @returns The method `find` returns the value of the first element in the iterable that satisfies
+   * the provided callback function. If no element satisfies the callback function, `undefined` is
+   * returned.
+   */
+  find(callbackfn: EntryCallback<K, V, [K, V]>, thisArg?: any): [K, V] | undefined {
+    let index = 0;
+    for (const item of this) {
+      const [key, value] = item;
+      if (callbackfn.call(thisArg, value, key, index++, this)) return item;
+    }
+    return;
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   */
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The function checks if a given key exists in a collection.
+   * @param {K} key - The parameter "key" is of type K, which means it can be any type. It represents
+   * the key that we want to check for existence in the data structure.
+   * @returns a boolean value. It returns true if the key is found in the collection, and false
+   * otherwise.
+   */
+  has(key: K): boolean {
+    for (const item of this) {
+      const [itemKey] = item;
+      if (itemKey === key) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   */
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The function checks if a given value exists in a collection.
+   * @param {V} value - The parameter "value" is the value that we want to check if it exists in the
+   * collection.
+   * @returns a boolean value, either true or false.
+   */
+  hasValue(value: V): boolean {
+    for (const [, elementValue] of this) {
+      if (elementValue === value) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   */
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The `get` function retrieves the value associated with a given key from a collection.
+   * @param {K} key - K (the type of the key) - This parameter represents the key that is being
+   * searched for in the collection.
+   * @returns The `get` method returns the value associated with the specified key if it exists in the
+   * collection, otherwise it returns `undefined`.
+   */
+  get(key: K): V | undefined {
+    for (const item of this) {
+      const [itemKey, value] = item;
+      if (itemKey === key) return value;
+    }
+    return;
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   */
+
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(1)
@@ -180,13 +279,6 @@ export abstract class IterableEntryBase<K = any, V = any> {
     return accumulator;
   }
 
-  hasValue(value: V): boolean {
-    for (const [, elementValue] of this) {
-      if (elementValue === value) return true;
-    }
-    return false;
-  }
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(n)
@@ -195,10 +287,20 @@ export abstract class IterableEntryBase<K = any, V = any> {
     console.log([...this]);
   }
 
+  abstract isEmpty(): boolean;
+
+  abstract clear(): void;
+
+  abstract clone(): any;
+
+  abstract map(...args: any[]): any;
+
+  abstract filter(...args: any[]): any;
+
   protected abstract _getIterator(...args: any[]): IterableIterator<[K, V]>;
 }
 
-export abstract class IterableElementBase<V> {
+export abstract class IterableElementBase<E = any, C = any> {
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(1)
@@ -212,7 +314,7 @@ export abstract class IterableElementBase<V> {
    * allows the function to accept any number of arguments as an array. In this case, the `args`
    * parameter is used to pass any number of arguments to the `_getIterator` method.
    */
-  * [Symbol.iterator](...args: any[]): IterableIterator<V> {
+  * [Symbol.iterator](...args: any[]): IterableIterator<E> {
     yield* this._getIterator(...args);
   }
 
@@ -226,7 +328,7 @@ export abstract class IterableElementBase<V> {
    *
    * The function returns an iterator that yields all the values in the object.
    */
-  * values(): IterableIterator<V> {
+  * values(): IterableIterator<E> {
     for (const item of this) {
       yield item;
     }
@@ -250,10 +352,10 @@ export abstract class IterableElementBase<V> {
    * @returns The `every` method is returning a boolean value. It returns `true` if every element in
    * the array satisfies the provided predicate function, and `false` otherwise.
    */
-  every(predicate: ElementCallback<V, boolean>, thisArg?: any): boolean {
+  every(predicate: ElementCallback<E, boolean>, thisArg?: any): boolean {
     let index = 0;
     for (const item of this) {
-      if (!predicate.call(thisArg, item as V, index++, this)) {
+      if (!predicate.call(thisArg, item, index++, this)) {
         return false;
       }
     }
@@ -278,10 +380,10 @@ export abstract class IterableElementBase<V> {
    * @returns a boolean value. It returns true if the predicate function returns true for any element
    * in the collection, and false otherwise.
    */
-  some(predicate: ElementCallback<V, boolean>, thisArg?: any): boolean {
+  some(predicate: ElementCallback<E, boolean>, thisArg?: any): boolean {
     let index = 0;
     for (const item of this) {
-      if (predicate.call(thisArg, item as V, index++, this)) {
+      if (predicate.call(thisArg, item, index++, this)) {
         return true;
       }
     }
@@ -292,6 +394,7 @@ export abstract class IterableElementBase<V> {
    * Time Complexity: O(n)
    * Space Complexity: O(1)
    */
+
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(1)
@@ -305,11 +408,63 @@ export abstract class IterableElementBase<V> {
    * to be used as `this` when executing the `callbackfn` function. If `thisArg` is provided, it will
    * be passed as the `this` value to the `callbackfn` function. If `thisArg
    */
-  forEach(callbackfn: ElementCallback<V, void>, thisArg?: any): void {
+  forEach(callbackfn: ElementCallback<E, void>, thisArg?: any): void {
+    let index = 0;
+    for (const item of this) {
+      callbackfn.call(thisArg, item, index++, this);
+    }
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   */
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The `find` function iterates over the elements of an array-like object and returns the first
+   * element that satisfies the provided callback function.
+   * @param callbackfn - The callbackfn parameter is a function that will be called for each element in
+   * the array. It takes three arguments: the current element being processed, the index of the current
+   * element, and the array itself. The function should return a boolean value indicating whether the
+   * current element matches the desired condition.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as `this` when executing the `callbackfn` function. If `thisArg` is provided, it will
+   * be passed as the `this` value to the `callbackfn` function. If `thisArg
+   * @returns The `find` method returns the first element in the array that satisfies the provided
+   * callback function. If no element satisfies the callback function, `undefined` is returned.
+   */
+  find(callbackfn: ElementCallback<E, boolean>, thisArg?: any): E | undefined {
     let index = 0;
     for (const item of this) {
-      callbackfn.call(thisArg, item as V, index++, this);
+      if (callbackfn.call(thisArg, item, index++, this)) return item;
+    }
+
+    return;
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   */
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The function checks if a given element exists in a collection.
+   * @param {E} element - The parameter "element" is of type E, which means it can be any type. It
+   * represents the element that we want to check for existence in the collection.
+   * @returns a boolean value. It returns true if the element is found in the collection, and false
+   * otherwise.
+   */
+  has(element: E): boolean {
+    for (const ele of this) {
+      if (ele === element) return true;
     }
+    return false;
   }
 
   /**
@@ -329,11 +484,11 @@ export abstract class IterableElementBase<V> {
    * @returns The `reduce` method is returning the final value of the accumulator after iterating over
    * all the elements in the array and applying the callback function to each element.
    */
-  reduce<U>(callbackfn: ReduceElementCallback<V, U>, initialValue: U): U {
+  reduce<U>(callbackfn: ReduceElementCallback<E, U>, initialValue: U): U {
     let accumulator = initialValue;
     let index = 0;
     for (const item of this) {
-      accumulator = callbackfn(accumulator, item as V, index++, this);
+      accumulator = callbackfn(accumulator, item as E, index++, this);
     }
     return accumulator;
   }
@@ -346,5 +501,15 @@ export abstract class IterableElementBase<V> {
     console.log([...this]);
   }
 
-  protected abstract _getIterator(...args: any[]): IterableIterator<V>;
+  abstract isEmpty(): boolean;
+
+  abstract clear(): void;
+
+  abstract clone(): C;
+
+  abstract map(...args: any[]): any;
+
+  abstract filter(...args: any[]): any;
+
+  protected abstract _getIterator(...args: any[]): IterableIterator<E>;
 }

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

@@ -17,16 +17,41 @@ import type {
 } from '../../types';
 import { IBinaryTree } from '../../interfaces';
 
-export class AVLTreeNode<K = any, V = any, N extends AVLTreeNode<K, V, N> = AVLTreeNodeNested<K, V>> extends BSTNode<
-  K,
-  V,
-  N
-> {
-  height: number;
-
+export class AVLTreeNode<
+  K = any,
+  V = any,
+  NODE extends AVLTreeNode<K, V, NODE> = AVLTreeNodeNested<K, V>
+> extends BSTNode<K, V, NODE> {
+  /**
+   * The constructor function initializes a new instance of a class with a key and an optional value,
+   * and sets the height property to 0.
+   * @param {K} key - The "key" parameter is of type K, which represents the type of the key for the
+   * constructor. It is used to initialize the key property of the object being created.
+   * @param {V} [value] - The "value" parameter is an optional parameter of type V. It represents the
+   * value associated with the key in the constructor.
+   */
   constructor(key: K, value?: V) {
     super(key, value);
-    this.height = 0;
+    this._height = 0;
+  }
+
+  protected _height: number;
+
+  /**
+   * The function returns the value of the height property.
+   * @returns The height of the object.
+   */
+  get height(): number {
+    return this._height;
+  }
+
+  /**
+   * The above function sets the value of the height property.
+   * @param {number} value - The value parameter is a number that represents the new height value to be
+   * set.
+   */
+  set height(value: number) {
+    this._height = value;
   }
 }
 
@@ -42,21 +67,21 @@ export class AVLTreeNode<K = any, V = any, N extends AVLTreeNode<K, V, N> = AVLT
 export class AVLTree<
   K = any,
   V = any,
-  N extends AVLTreeNode<K, V, N> = AVLTreeNode<K, V, AVLTreeNodeNested<K, V>>,
-  TREE extends AVLTree<K, V, N, TREE> = AVLTree<K, V, N, AVLTreeNested<K, V, N>>
+  NODE extends AVLTreeNode<K, V, NODE> = AVLTreeNode<K, V, AVLTreeNodeNested<K, V>>,
+  TREE extends AVLTree<K, V, NODE, TREE> = AVLTree<K, V, NODE, AVLTreeNested<K, V, NODE>>
 >
-  extends BST<K, V, N, TREE>
-  implements IBinaryTree<K, V, N, TREE> {
+  extends BST<K, V, NODE, TREE>
+  implements IBinaryTree<K, V, NODE, TREE> {
   /**
    * The constructor function initializes an AVLTree object with optional keysOrNodesOrEntries and options.
-   * @param [keysOrNodesOrEntries] - The `keysOrNodesOrEntries` parameter is an optional iterable of `KeyOrNodeOrEntry<K, V, N>`
+   * @param [keysOrNodesOrEntries] - The `keysOrNodesOrEntries` parameter is an optional iterable of `KeyOrNodeOrEntry<K, V, NODE>`
    * objects. It represents a collection of nodes that will be added to the AVL tree during
    * initialization.
    * @param [options] - The `options` parameter is an optional object that allows you to customize the
    * behavior of the AVL tree. It is of type `Partial<AVLTreeOptions>`, which means that you can
    * provide only a subset of the properties defined in the `AVLTreeOptions` interface.
    */
-  constructor(keysOrNodesOrEntries: Iterable<KeyOrNodeOrEntry<K, V, N>> = [], options?: AVLTreeOptions<K>) {
+  constructor(keysOrNodesOrEntries: Iterable<KeyOrNodeOrEntry<K, V, NODE>> = [], options?: AVLTreeOptions<K>) {
     super([], options);
     if (keysOrNodesOrEntries) super.addMany(keysOrNodesOrEntries);
   }
@@ -67,11 +92,11 @@ export class AVLTree<
    * the new node. It is used to determine the position of the node in the binary search tree.
    * @param [value] - The parameter `value` is an optional value that can be assigned to the node. It is of
    * type `V`, which means it can be any value that is assignable to the `value` property of the
-   * node type `N`.
+   * node type `NODE`.
    * @returns a new AVLTreeNode object with the specified key and value.
    */
-  override createNode(key: K, value?: V): N {
-    return new AVLTreeNode<K, V, N>(key, value) as N;
+  override createNode(key: K, value?: V): NODE {
+    return new AVLTreeNode<K, V, NODE>(key, value) as NODE;
   }
 
   /**
@@ -82,7 +107,7 @@ export class AVLTree<
    * @returns a new AVLTree object.
    */
   override createTree(options?: AVLTreeOptions<K>): TREE {
-    return new AVLTree<K, V, N, TREE>([], {
+    return new AVLTree<K, V, NODE, TREE>([], {
       iterationType: this.iterationType,
       variant: this.variant,
       ...options
@@ -91,10 +116,10 @@ export class AVLTree<
 
   /**
    * The function checks if an keyOrNodeOrEntry is an instance of AVLTreeNode.
-   * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is of type `KeyOrNodeOrEntry<K, V, N>`.
+   * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is of type `KeyOrNodeOrEntry<K, V, NODE>`.
    * @returns a boolean value indicating whether the keyOrNodeOrEntry is an instance of the AVLTreeNode class.
    */
-  override isNode(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, N>): keyOrNodeOrEntry is N {
+  override isNode(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>): keyOrNodeOrEntry is NODE {
     return keyOrNodeOrEntry instanceof AVLTreeNode;
   }
 
@@ -116,7 +141,7 @@ export class AVLTree<
    * being added to the binary tree.
    * @returns The method is returning either the inserted node or undefined.
    */
-  override add(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, N>, value?: V): boolean {
+  override add(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>, value?: V): boolean {
     if (keyOrNodeOrEntry === null) return false;
     const inserted = super.add(keyOrNodeOrEntry, value);
     if (inserted) this._balancePath(keyOrNodeOrEntry);
@@ -140,13 +165,13 @@ export class AVLTree<
    * @param {C} callback - The `callback` parameter is a function that will be called for each node
    * that is deleted from the binary tree. It is an optional parameter and if not provided, it will
    * default to the `_defaultOneParamCallback` function. The `callback` function should have a single
-   * parameter of type `N
-   * @returns The method is returning an array of `BinaryTreeDeleteResult<N>`.
+   * parameter of type `NODE
+   * @returns The method is returning an array of `BinaryTreeDeleteResult<NODE>`.
    */
-  override delete<C extends BTNCallback<N>>(
+  override delete<C extends BTNCallback<NODE>>(
     identifier: ReturnType<C>,
     callback: C = this._defaultOneParamCallback as C
-  ): BinaryTreeDeleteResult<N>[] {
+  ): BinaryTreeDeleteResult<NODE>[] {
     if ((identifier as any) instanceof AVLTreeNode) callback = (node => node) as C;
     const deletedResults = super.delete(identifier, callback);
     for (const { needBalanced } of deletedResults) {
@@ -160,14 +185,17 @@ export class AVLTree<
   /**
    * The `_swapProperties` function swaps the key, value, and height properties between two nodes in a binary
    * tree.
-   * @param {K | N | undefined} srcNode - The `srcNode` parameter represents the source node that
-   * needs to be swapped with the destination node. It can be of type `K`, `N`, or `undefined`.
-   * @param {K | N  | undefined} destNode - The `destNode` parameter represents the destination
+   * @param {K | NODE | undefined} srcNode - The `srcNode` parameter represents the source node that
+   * needs to be swapped with the destination node. It can be of type `K`, `NODE`, or `undefined`.
+   * @param {K | NODE  | undefined} destNode - The `destNode` parameter represents the destination
    * node where the values from the source node will be swapped to.
    * @returns either the `destNode` object if both `srcNode` and `destNode` are defined, or `undefined`
    * if either `srcNode` or `destNode` is undefined.
    */
-  protected override _swapProperties(srcNode: BSTNKeyOrNode<K, N>, destNode: BSTNKeyOrNode<K, N>): N | undefined {
+  protected override _swapProperties(
+    srcNode: BSTNKeyOrNode<K, NODE>,
+    destNode: BSTNKeyOrNode<K, NODE>
+  ): NODE | undefined {
     srcNode = this.ensureNode(srcNode);
     destNode = this.ensureNode(destNode);
 
@@ -195,7 +223,6 @@ export class AVLTree<
   /**
    * Time Complexity: O(1)
    * Space Complexity: O(1)
-   * constant time, as it performs a fixed number of operations. constant space, as it only uses a constant amount of memory.
    */
 
   /**
@@ -203,11 +230,11 @@ export class AVLTree<
    * Space Complexity: O(1)
    *
    * The function calculates the balance factor of a node in a binary tree.
-   * @param {N} node - The parameter "node" represents a node in a binary tree data structure.
+   * @param {NODE} node - The parameter "node" represents a node in a binary tree data structure.
    * @returns the balance factor of a given node. The balance factor is calculated by subtracting the
    * height of the left subtree from the height of the right subtree.
    */
-  protected _balanceFactor(node: N): number {
+  protected _balanceFactor(node: NODE): number {
     if (!node.right)
       // node has no right subtree
       return -node.height;
@@ -220,7 +247,6 @@ export class AVLTree<
   /**
    * Time Complexity: O(1)
    * Space Complexity: O(1)
-   * constant time, as it performs a fixed number of operations. constant space, as it only uses a constant amount of memory.
    */
 
   /**
@@ -229,9 +255,9 @@ export class AVLTree<
    *
    * The function updates the height of a node in a binary tree based on the heights of its left and
    * right children.
-   * @param {N} node - The parameter "node" represents a node in a binary tree data structure.
+   * @param {NODE} node - The parameter "node" represents a node in a binary tree data structure.
    */
-  protected _updateHeight(node: N): void {
+  protected _updateHeight(node: NODE): void {
     if (!node.left && !node.right) node.height = 0;
     else if (!node.left) {
       const rightHeight = node.right ? node.right.height : 0;
@@ -240,65 +266,9 @@ export class AVLTree<
     else node.height = 1 + Math.max(node.right.height, node.left.height);
   }
 
-  /**
-   * Time Complexity: O(log n)
-   * Space Complexity: O(1)
-   * logarithmic time, where "n" is the number of nodes in the tree. The method traverses the path from the inserted node to the root. constant space, as it doesn't use additional data structures that scale with input size.
-   */
-
-  /**
-   * Time Complexity: O(log n)
-   * Space Complexity: O(1)
-   *
-   * The `_balancePath` function is used to update the heights of nodes and perform rotation operations
-   * to restore balance in an AVL tree after inserting a node.
-   * @param {N} node - The `node` parameter in the `_balancePath` function represents the node in the
-   * AVL tree that needs to be balanced.
-   */
-  protected _balancePath(node: KeyOrNodeOrEntry<K, V, N>): void {
-    node = this.ensureNode(node);
-    const path = this.getPathToRoot(node, false); // first O(log n) + O(log n)
-    for (let i = 0; i < path.length; i++) {
-      // second O(log n)
-      const A = path[i];
-      // Update Heights: After inserting a node, backtrack from the insertion point to the root node, updating the height of each node along the way.
-      this._updateHeight(A); // first O(1)
-      // Check Balance: Simultaneously with height updates, check if each node violates the balance property of an AVL tree.
-      // Balance Restoration: If a balance issue is discovered after inserting a node, it requires balance restoration operations. Balance restoration includes four basic cases where rotation operations need to be performed to fix the balance:
-      switch (
-        this._balanceFactor(A) // second O(1)
-        ) {
-        case -2:
-          if (A && A.left) {
-            if (this._balanceFactor(A.left) <= 0) {
-              // second O(1)
-              // Left Rotation (LL Rotation): When the inserted node is in the left subtree of the left subtree, causing an imbalance.
-              this._balanceLL(A);
-            } else {
-              // Left-Right Rotation (LR Rotation): When the inserted node is in the right subtree of the left subtree, causing an imbalance.
-              this._balanceLR(A);
-            }
-          }
-          break;
-        case +2:
-          if (A && A.right) {
-            if (this._balanceFactor(A.right) >= 0) {
-              // Right Rotation (RR Rotation): When the inserted node is in the right subtree of the right subtree, causing an imbalance.
-              this._balanceRR(A);
-            } else {
-              // Right-Left Rotation (RL Rotation): When the inserted node is in the left subtree of the right subtree, causing an imbalance.
-              this._balanceRL(A);
-            }
-          }
-      }
-      // TODO So far, no sure if this is necessary that Recursive Repair: Once rotation operations are executed, it may cause imbalance issues at higher levels of the tree. Therefore, you need to recursively check and repair imbalance problems upwards until you reach the root node.
-    }
-  }
-
   /**
    * Time Complexity: O(1)
    * Space Complexity: O(1)
-   * constant time, as these methods perform a fixed number of operations. constant space, as they only use a constant amount of memory.
    */
 
   /**
@@ -306,9 +276,9 @@ export class AVLTree<
    * Space Complexity: O(1)
    *
    * The function `_balanceLL` performs a left-left rotation to balance a binary tree.
-   * @param {N} A - A is a node in a binary tree.
+   * @param {NODE} A - A is a node in a binary tree.
    */
-  protected _balanceLL(A: N): void {
+  protected _balanceLL(A: NODE): void {
     const parentOfA = A.parent;
     const B = A.left;
     A.parent = B;
@@ -344,9 +314,9 @@ export class AVLTree<
    * Space Complexity: O(1)
    *
    * The `_balanceLR` function performs a left-right rotation to balance a binary tree.
-   * @param {N} A - A is a node in a binary tree.
+   * @param {NODE} A - A is a node in a binary tree.
    */
-  protected _balanceLR(A: N): void {
+  protected _balanceLR(A: NODE): void {
     const parentOfA = A.parent;
     const B = A.left;
     let C = undefined;
@@ -400,9 +370,9 @@ export class AVLTree<
    * Space Complexity: O(1)
    *
    * The function `_balanceRR` performs a right-right rotation to balance a binary tree.
-   * @param {N} A - A is a node in a binary tree.
+   * @param {NODE} A - A is a node in a binary tree.
    */
-  protected _balanceRR(A: N): void {
+  protected _balanceRR(A: NODE): void {
     const parentOfA = A.parent;
     const B = A.right;
     A.parent = B;
@@ -443,9 +413,9 @@ export class AVLTree<
    * Space Complexity: O(1)
    *
    * The function `_balanceRL` performs a right-left rotation to balance a binary tree.
-   * @param {N} A - A is a node in a binary tree.
+   * @param {NODE} A - A is a node in a binary tree.
    */
-  protected _balanceRL(A: N): void {
+  protected _balanceRL(A: NODE): void {
     const parentOfA = A.parent;
     const B = A.right;
     let C = undefined;
@@ -488,7 +458,71 @@ export class AVLTree<
     C && this._updateHeight(C);
   }
 
-  protected _replaceNode(oldNode: N, newNode: N): N {
+  /**
+   * Time Complexity: O(log n)
+   * Space Complexity: O(1)
+   * logarithmic time, where "n" is the number of nodes in the tree. The method traverses the path from the inserted node to the root. constant space, as it doesn't use additional data structures that scale with input size.
+   */
+
+  /**
+   * Time Complexity: O(log n)
+   * Space Complexity: O(1)
+   *
+   * The `_balancePath` function is used to update the heights of nodes and perform rotation operations
+   * to restore balance in an AVL tree after inserting a node.
+   * @param {NODE} node - The `node` parameter in the `_balancePath` function represents the node in the
+   * AVL tree that needs to be balanced.
+   */
+  protected _balancePath(node: KeyOrNodeOrEntry<K, V, NODE>): void {
+    node = this.ensureNode(node);
+    const path = this.getPathToRoot(node, false); // first O(log n) + O(log n)
+    for (let i = 0; i < path.length; i++) {
+      // second O(log n)
+      const A = path[i];
+      // Update Heights: After inserting a node, backtrack from the insertion point to the root node, updating the height of each node along the way.
+      this._updateHeight(A); // first O(1)
+      // Check Balance: Simultaneously with height updates, check if each node violates the balance property of an AVL tree.
+      // Balance Restoration: If a balance issue is discovered after inserting a node, it requires balance restoration operations. Balance restoration includes four basic cases where rotation operations need to be performed to fix the balance:
+      switch (
+        this._balanceFactor(A) // second O(1)
+        ) {
+        case -2:
+          if (A && A.left) {
+            if (this._balanceFactor(A.left) <= 0) {
+              // second O(1)
+              // Left Rotation (LL Rotation): When the inserted node is in the left subtree of the left subtree, causing an imbalance.
+              this._balanceLL(A);
+            } else {
+              // Left-Right Rotation (LR Rotation): When the inserted node is in the right subtree of the left subtree, causing an imbalance.
+              this._balanceLR(A);
+            }
+          }
+          break;
+        case +2:
+          if (A && A.right) {
+            if (this._balanceFactor(A.right) >= 0) {
+              // Right Rotation (RR Rotation): When the inserted node is in the right subtree of the right subtree, causing an imbalance.
+              this._balanceRR(A);
+            } else {
+              // Right-Left Rotation (RL Rotation): When the inserted node is in the left subtree of the right subtree, causing an imbalance.
+              this._balanceRL(A);
+            }
+          }
+      }
+      // TODO So far, no sure if this is necessary that Recursive Repair: Once rotation operations are executed, it may cause imbalance issues at higher levels of the tree. Therefore, you need to recursively check and repair imbalance problems upwards until you reach the root node.
+    }
+  }
+
+  /**
+   * The function replaces an old node with a new node while preserving the height of the old node.
+   * @param {NODE} oldNode - The `oldNode` parameter is the node that you want to replace with the
+   * `newNode`.
+   * @param {NODE} newNode - The `newNode` parameter is the new node that will replace the `oldNode` in
+   * the data structure.
+   * @returns the result of calling the `_replaceNode` method on the superclass, passing in the
+   * `oldNode` and `newNode` as arguments.
+   */
+  protected _replaceNode(oldNode: NODE, newNode: NODE): NODE {
     newNode.height = oldNode.height;
 
     return super._replaceNode(oldNode, newNode);