deque-typed 1.47.6 → 1.47.8

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

@@ -6,8 +6,16 @@
  * @license MIT License
  */
 import { BST, BSTNode } from './bst';
-import type { AVLTreeNested, AVLTreeNodeNested, AVLTreeOptions, BiTreeDeleteResult, BTNKey } from '../../types';
-import { BTNCallback, IterableEntriesOrKeys } from '../../types';
+import type {
+  AVLTreeNested,
+  AVLTreeNodeNested,
+  AVLTreeOptions,
+  BiTreeDeleteResult,
+  BSTNodeKeyOrNode,
+  BTNKey,
+  BTNodeExemplar
+} from '../../types';
+import { BTNCallback } from '../../types';
 import { IBinaryTree } from '../../interfaces';
 
 export class AVLTreeNode<V = any, N extends AVLTreeNode<V, N> = AVLTreeNodeNested<V>> extends BSTNode<V, N> {
@@ -19,19 +27,32 @@ export class AVLTreeNode<V = any, N extends AVLTreeNode<V, N> = AVLTreeNodeNeste
   }
 }
 
+/**
+ * 1. Height-Balanced: Each node's left and right subtrees differ in height by no more than one.
+ * 2. Automatic Rebalancing: AVL trees rebalance themselves automatically during insertions and deletions.
+ * 3. Rotations for Balancing: Utilizes rotations (single or double) to maintain balance after updates.
+ * 4. Order Preservation: Maintains the binary search tree property where left child values are less than the parent, and right child values are greater.
+ * 5. Efficient Lookups: Offers O(log n) search time, where 'n' is the number of nodes, due to its balanced nature.
+ * 6. Complex Insertions and Deletions: Due to rebalancing, these operations are more complex than in a regular BST.
+ * 7. Path Length: The path length from the root to any leaf is longer compared to an unbalanced BST, but shorter than a linear chain of nodes.
+ * 8. Memory Overhead: Stores balance factors (or heights) at each node, leading to slightly higher memory usage compared to a regular BST.
+ */
 export class AVLTree<V = any, N extends AVLTreeNode<V, N> = AVLTreeNode<V, AVLTreeNodeNested<V>>, TREE extends AVLTree<V, N, TREE> = AVLTree<V, N, AVLTreeNested<V, N>>>
   extends BST<V, N, TREE>
   implements IBinaryTree<V, N, TREE> {
 
   /**
-   * This is a constructor function for an AVL tree data structure in TypeScript.
-   * @param {AVLTreeOptions} [options] - The `options` parameter is an optional object that can be passed to the
-   * constructor of the AVLTree class. It allows you to customize the behavior of the AVL tree by providing different
-   * options.
+   * The constructor function initializes an AVLTree object with optional elements and options.
+   * @param [elements] - The `elements` parameter is an optional iterable of `BTNodeExemplar<V, N>`
+   * objects. It represents a collection of elements 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(elements?: IterableEntriesOrKeys<V>, options?: Partial<AVLTreeOptions>) {
+  constructor(elements?: Iterable<BTNodeExemplar<V, N>>, options?: Partial<AVLTreeOptions>) {
     super([], options);
-    if (elements) this.init(elements);
+    if (elements) super.addMany(elements);
   }
 
   /**
@@ -47,6 +68,13 @@ export class AVLTree<V = any, N extends AVLTreeNode<V, N> = AVLTreeNode<V, AVLTr
     return new AVLTreeNode<V, N>(key, value) as N;
   }
 
+  /**
+   * The function creates a new AVL tree with the specified options and returns it.
+   * @param {AVLTreeOptions} [options] - The `options` parameter is an optional object that can be
+   * passed to the `createTree` function. It is used to customize the behavior of the AVL tree that is
+   * being created.
+   * @returns a new AVLTree object.
+   */
   override createTree(options?: AVLTreeOptions): TREE {
     return new AVLTree<V, N, TREE>([], {
       iterationType: this.iterationType,
@@ -54,21 +82,24 @@ export class AVLTree<V = any, N extends AVLTreeNode<V, N> = AVLTreeNode<V, AVLTr
     }) as TREE;
   }
 
+  /**
+   * Time Complexity: O(log n) - logarithmic time, where "n" is the number of nodes in the tree. The add method of the superclass (BST) has logarithmic time complexity.
+   * Space Complexity: O(1) - constant space, as it doesn't use additional data structures that scale with input size.
+   */
+
   /**
    * Time Complexity: O(log n) - logarithmic time, where "n" is the number of nodes in the tree. The add method of the superclass (BST) has logarithmic time complexity.
    * Space Complexity: O(1) - constant space, as it doesn't use additional data structures that scale with input size.
    *
-   * The function overrides the add method of a class, adds a key-value pair to a data structure, and
-   * balances the structure if necessary.
-   * @param {BTNKey | N | null | undefined} keyOrNode - The `keyOrNode` parameter can be of type
-   * `BTNKey`, `N`, `null`, or `undefined`.
-   * @param {V} [value] - The `value` parameter is the value associated with the key that is being
-   * added to the binary search tree.
-   * @returns The method is returning either a node (N) or undefined.
+   * The function overrides the add method of a binary tree node and balances the tree after inserting
+   * a new node.
+   * @param keyOrNodeOrEntry - The parameter `keyOrNodeOrEntry` can be either a key, a node, or an
+   * entry.
+   * @returns The method is returning either the inserted node or `undefined`.
    */
-  override add(keyOrNode: BTNKey | N | null | undefined, value?: V): N | undefined {
-    if (keyOrNode === null) return undefined;
-    const inserted = super.add(keyOrNode, value);
+  override add(keyOrNodeOrEntry: BTNodeExemplar<V, N>): N | undefined {
+    if (keyOrNodeOrEntry === null) return undefined;
+    const inserted = super.add(keyOrNodeOrEntry);
     if (inserted) this._balancePath(inserted);
     return inserted;
   }
@@ -107,26 +138,9 @@ export class AVLTree<V = any, N extends AVLTreeNode<V, N> = AVLTreeNode<V, AVLTr
     return deletedResults;
   }
 
-  /**
-   * Time Complexity: O(log n) - logarithmic time, where "n" is the number of nodes in the tree. The delete method of the superclass (BST) has logarithmic time complexity.
-   * Space Complexity: O(1) - constant space, as it doesn't use additional data structures that scale with input size.
-   */
-
-  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);
-        }
-      }
-    }
-  }
 
   /**
-   * The `_swap` function swaps the key, value, and height properties between two nodes in a binary
+   * The `_swapProperties` function swaps the key, value, and height properties between two nodes in a binary
    * tree.
    * @param {BTNKey | N | undefined} srcNode - The `srcNode` parameter represents the source node that
    * needs to be swapped with the destination node. It can be of type `BTNKey`, `N`, or `undefined`.
@@ -135,9 +149,9 @@ export class AVLTree<V = any, N extends AVLTreeNode<V, N> = AVLTreeNode<V, AVLTr
    * @returns either the `destNode` object if both `srcNode` and `destNode` are defined, or `undefined`
    * if either `srcNode` or `destNode` is undefined.
    */
-  protected override _swap(srcNode: BTNKey | N | undefined, destNode: BTNKey | N | undefined): N | undefined {
-    srcNode = this.ensureNotKey(srcNode);
-    destNode = this.ensureNotKey(destNode);
+  protected override _swapProperties(srcNode: BSTNodeKeyOrNode<N>, destNode: BSTNodeKeyOrNode<N>): N | undefined {
+    srcNode = this.ensureNode(srcNode);
+    destNode = this.ensureNode(destNode);
 
     if (srcNode && destNode) {
       const { key, value, height } = destNode;
@@ -450,4 +464,10 @@ export class AVLTree<V = any, N extends AVLTreeNode<V, N> = AVLTreeNode<V, AVLTr
     B && this._updateHeight(B);
     C && this._updateHeight(C);
   }
+
+  protected _replaceNode(oldNode: N, newNode: N): N {
+    newNode.height = oldNode.height;
+
+    return super._replaceNode(oldNode, newNode)
+  }
 }