directed-graph-typed 1.47.5 → 1.47.7

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

@@ -6,22 +6,34 @@
  * @license MIT License
  */
 import { BST, BSTNode } from './bst';
-import type { AVLTreeNested, AVLTreeNodeNested, AVLTreeOptions, BiTreeDeleteResult, BTNKey } 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> {
-    options: AVLTreeOptions;
     /**
-     * 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(options?: 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
@@ -32,6 +44,13 @@ 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.
@@ -41,17 +60,15 @@ export declare class AVLTree<V = any, N extends AVLTreeNode<V, N> = AVLTreeNode<
      * 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 delete method of the superclass (BST) has logarithmic time complexity.
+     * 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.
      */
     /**
@@ -71,7 +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>[];
     /**
-     * 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

@@ -9,7 +9,6 @@ exports.AVLTree = exports.AVLTreeNode = void 0;
  * @license MIT License
  */
 const bst_1 = require("./bst");
-const types_1 = require("../../types");
 class AVLTreeNode extends bst_1.BSTNode {
     constructor(key, value) {
         super(key, value);
@@ -17,21 +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(options) {
-        super(options);
-        if (options) {
-            this.options = Object.assign({ iterationType: types_1.IterationType.ITERATIVE, comparator: (a, b) => a - b }, options);
-        }
-        else {
-            this.options = { iterationType: types_1.IterationType.ITERATIVE, comparator: (a, b) => a - b };
-        }
+    constructor(elements, options) {
+        super([], options);
+        if (elements)
+            super.addMany(elements);
     }
     /**
      * The function creates a new AVL tree node with the specified key and value.
@@ -45,8 +53,15 @@ 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(Object.assign({}, this.options), 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.
@@ -56,24 +71,22 @@ class AVLTree extends bst_1.BST {
      * 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;
     }
     /**
-     * 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.
+     * 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.
      */
     /**
@@ -103,7 +116,7 @@ class AVLTree extends bst_1.BST {
         return deletedResults;
     }
     /**
-     * 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`.
@@ -112,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);
@@ -425,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;