graph-typed 1.47.6 → 1.47.7

package/dist/data-structures/binary-tree/avl-tree.d.ts

@@ -6,21 +6,34 @@
  * @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 declare class AVLTreeNode<V = any, N extends AVLTreeNode<V, N> = AVLTreeNodeNested<V>> extends BSTNode<V, N> {
     height: number;
     constructor(key: BTNKey, value?: V);
 }
+/**
+ * 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 declare 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>);
     /**
      * The function creates a new AVL tree node with the specified key and value.
      * @param {BTNKey} key - The key parameter is the key value that will be associated with
@@ -31,20 +44,29 @@ export declare class AVLTree<V = any, N extends AVLTreeNode<V, N> = AVLTreeNode<
      * @returns a new AVLTreeNode object with the specified key and value.
      */
     createNode(key: BTNKey, value?: V): 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.
+     */
     createTree(options?: AVLTreeOptions): 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`.
      */
-    add(keyOrNode: BTNKey | N | null | undefined, value?: V): N | undefined;
+    add(keyOrNodeOrEntry: BTNodeExemplar<V, N>): N | undefined;
     /**
      * 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.
@@ -66,12 +88,7 @@ export declare class AVLTree<V = any, N extends AVLTreeNode<V, N> = AVLTreeNode<
      */
     delete<C extends BTNCallback<N>>(identifier: ReturnType<C>, callback?: C): BiTreeDeleteResult<N>[];
     /**
-     * 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;
-    /**
-     * 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`.
@@ -80,7 +97,7 @@ export declare class AVLTree<V = any, N extends AVLTreeNode<V, N> = AVLTreeNode<
      * @returns either the `destNode` object if both `srcNode` and `destNode` are defined, or `undefined`
      * if either `srcNode` or `destNode` is undefined.
      */
-    protected _swap(srcNode: BTNKey | N | undefined, destNode: BTNKey | N | undefined): N | undefined;
+    protected _swapProperties(srcNode: BSTNodeKeyOrNode<N>, destNode: BSTNodeKeyOrNode<N>): N | undefined;
     /**
      * Time Complexity: O(1) - constant time, as it performs a fixed number of operations.
      * Space Complexity: O(1) - constant space, as it only uses a constant amount of memory.
@@ -170,4 +187,5 @@ export declare class AVLTree<V = any, N extends AVLTreeNode<V, N> = AVLTreeNode<
      * @param {N} A - A is a node in a binary tree.
      */
     protected _balanceRL(A: N): void;
+    protected _replaceNode(oldNode: N, newNode: N): N;
 }

package/dist/data-structures/binary-tree/avl-tree.js

@@ -16,17 +16,30 @@ class AVLTreeNode extends bst_1.BSTNode {
     }
 }
 exports.AVLTreeNode = AVLTreeNode;
+/**
+ * 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.
+ */
 class AVLTree extends bst_1.BST {
     /**
-     * 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, options) {
         super([], options);
         if (elements)
-            this.init(elements);
+            super.addMany(elements);
     }
     /**
      * The function creates a new AVL tree node with the specified key and value.
@@ -40,25 +53,34 @@ class AVLTree extends bst_1.BST {
     createNode(key, value) {
         return new AVLTreeNode(key, value);
     }
+    /**
+     * 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.
+     */
     createTree(options) {
         return new AVLTree([], Object.assign({ iterationType: this.iterationType, comparator: this.comparator }, options));
     }
+    /**
+     * 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`.
      */
-    add(keyOrNode, value) {
-        if (keyOrNode === null)
+    add(keyOrNodeOrEntry) {
+        if (keyOrNodeOrEntry === null)
             return undefined;
-        const inserted = super.add(keyOrNode, value);
+        const inserted = super.add(keyOrNodeOrEntry);
         if (inserted)
             this._balancePath(inserted);
         return inserted;
@@ -94,24 +116,7 @@ class AVLTree extends bst_1.BST {
         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) {
-        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`.
@@ -120,9 +125,9 @@ class AVLTree extends bst_1.BST {
      * @returns either the `destNode` object if both `srcNode` and `destNode` are defined, or `undefined`
      * if either `srcNode` or `destNode` is undefined.
      */
-    _swap(srcNode, destNode) {
-        srcNode = this.ensureNotKey(srcNode);
-        destNode = this.ensureNotKey(destNode);
+    _swapProperties(srcNode, destNode) {
+        srcNode = this.ensureNode(srcNode);
+        destNode = this.ensureNode(destNode);
         if (srcNode && destNode) {
             const { key, value, height } = destNode;
             const tempNode = this.createNode(key, value);
@@ -433,5 +438,9 @@ class AVLTree extends bst_1.BST {
         B && this._updateHeight(B);
         C && this._updateHeight(C);
     }
+    _replaceNode(oldNode, newNode) {
+        newNode.height = oldNode.height;
+        return super._replaceNode(oldNode, newNode);
+    }
 }
 exports.AVLTree = AVLTree;