data-structure-typed 1.18.8 → 1.19.0

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

@@ -8,25 +8,33 @@
 import { BST, BSTNode } from './bst';
 import type { AVLTreeNodeNested, AVLTreeOptions, BinaryTreeDeletedResult, BinaryTreeNodeId } from '../types';
 import { IAVLTree, IAVLTreeNode } from '../interfaces';
-export declare class AVLTreeNode<T = any, FAMILY extends AVLTreeNode<T, FAMILY> = AVLTreeNodeNested<T>> extends BSTNode<T, FAMILY> implements IAVLTreeNode<T, FAMILY> {
-    createNode(id: BinaryTreeNodeId, val?: T, count?: number): FAMILY;
+export declare class AVLTreeNode<T = any, NEIGHBOR extends AVLTreeNode<T, NEIGHBOR> = AVLTreeNodeNested<T>> extends BSTNode<T, NEIGHBOR> implements IAVLTreeNode<T, NEIGHBOR> {
 }
 export declare class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends BST<N> implements IAVLTree<N> {
+    /**
+     * 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.
+     */
     constructor(options?: AVLTreeOptions);
-    createNode(id: BinaryTreeNodeId, val?: N['val'], count?: number): N;
     /**
-     * The function overrides the add method of a Binary Search Tree to insert a node with a given id and value, and then
-     * balances the tree.
-     * @param {BinaryTreeNodeId} id - The `id` parameter is the identifier of the binary tree node that we want to add or
-     * update in the AVL tree.
-     * @param {N | null} val - The `val` parameter represents the value that you want to assign to the node with the given
-     * `id`. It can be of type `N` (the generic type) or `null`.
-     * @param {number} [count] - The `count` parameter is an optional parameter of type `number`. It represents the number
-     * of times the value `val` should be inserted into the AVL tree. If the `count` parameter is not provided, it defaults
-     * to `1`, indicating that the value should be inserted once.
-     * @returns The method is returning either an N object or null.
+     * The function creates a new AVL tree node with the given id and value.
+     * @param {BinaryTreeNodeId} id - The `id` parameter is the identifier for the binary tree node. It is used to uniquely
+     * identify each node in the tree.
+     * @param [val] - The `val` parameter is an optional value that can be assigned to the node. It represents the value
+     * that will be stored in the node.
+     * @returns a new AVLTreeNode object with the specified id and value.
+     */
+    createNode(id: BinaryTreeNodeId, val?: N['val']): N;
+    /**
+     * The function overrides the add method of a binary tree node and balances the tree after inserting a new node.
+     * @param {BinaryTreeNodeId} id - The `id` parameter is the identifier of the binary tree node that we want to add.
+     * @param [val] - The `val` parameter is an optional value that can be assigned to the node being added. It is of type
+     * `N['val']`, which means it should be of the same type as the `val` property of the nodes in the binary tree.
+     * @returns The method is returning the inserted node, or null or undefined if the insertion was not successful.
      */
-    add(id: BinaryTreeNodeId, val?: N['val'], count?: number): N | null;
+    add(id: BinaryTreeNodeId, val?: N['val']): N | null | undefined;
     /**
      * The function overrides the remove method of the Binary Search Tree class, performs the removal operation, and
      * then balances the tree if necessary.

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

@@ -40,34 +40,40 @@ var AVLTreeNode = /** @class */ (function (_super) {
     function AVLTreeNode() {
         return _super !== null && _super.apply(this, arguments) || this;
     }
-    AVLTreeNode.prototype.createNode = function (id, val, count) {
-        return new AVLTreeNode(id, val, count);
-    };
     return AVLTreeNode;
 }(bst_1.BSTNode));
 exports.AVLTreeNode = AVLTreeNode;
 var AVLTree = /** @class */ (function (_super) {
     __extends(AVLTree, _super);
+    /**
+     * 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.
+     */
     function AVLTree(options) {
         return _super.call(this, options) || this;
     }
-    AVLTree.prototype.createNode = function (id, val, count) {
-        return new AVLTreeNode(id, val, count);
+    /**
+     * The function creates a new AVL tree node with the given id and value.
+     * @param {BinaryTreeNodeId} id - The `id` parameter is the identifier for the binary tree node. It is used to uniquely
+     * identify each node in the tree.
+     * @param [val] - The `val` parameter is an optional value that can be assigned to the node. It represents the value
+     * that will be stored in the node.
+     * @returns a new AVLTreeNode object with the specified id and value.
+     */
+    AVLTree.prototype.createNode = function (id, val) {
+        return new AVLTreeNode(id, val);
     };
     /**
-     * The function overrides the add method of a Binary Search Tree to insert a node with a given id and value, and then
-     * balances the tree.
-     * @param {BinaryTreeNodeId} id - The `id` parameter is the identifier of the binary tree node that we want to add or
-     * update in the AVL tree.
-     * @param {N | null} val - The `val` parameter represents the value that you want to assign to the node with the given
-     * `id`. It can be of type `N` (the generic type) or `null`.
-     * @param {number} [count] - The `count` parameter is an optional parameter of type `number`. It represents the number
-     * of times the value `val` should be inserted into the AVL tree. If the `count` parameter is not provided, it defaults
-     * to `1`, indicating that the value should be inserted once.
-     * @returns The method is returning either an N object or null.
+     * The function overrides the add method of a binary tree node and balances the tree after inserting a new node.
+     * @param {BinaryTreeNodeId} id - The `id` parameter is the identifier of the binary tree node that we want to add.
+     * @param [val] - The `val` parameter is an optional value that can be assigned to the node being added. It is of type
+     * `N['val']`, which means it should be of the same type as the `val` property of the nodes in the binary tree.
+     * @returns The method is returning the inserted node, or null or undefined if the insertion was not successful.
      */
-    AVLTree.prototype.add = function (id, val, count) {
-        var inserted = _super.prototype.add.call(this, id, val, count);
+    AVLTree.prototype.add = function (id, val) {
+        var inserted = _super.prototype.add.call(this, id, val);
         if (inserted)
             this.balancePath(inserted);
         return inserted;

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

@@ -5,40 +5,26 @@
  * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { BinaryTreeNodeId, BinaryTreeNodeNested } from '../types';
-import { BinaryTreeOptions } from '../types';
+import type { BinaryTreeNodeId, BinaryTreeNodeNested, BinaryTreeOptions } from '../types';
 import { AbstractBinaryTree, AbstractBinaryTreeNode } from './abstract-binary-tree';
 import { IBinaryTree, IBinaryTreeNode } from '../interfaces/binary-tree';
-export declare class BinaryTreeNode<T = any, FAMILY extends BinaryTreeNode<T, FAMILY> = BinaryTreeNodeNested<T>> extends AbstractBinaryTreeNode<T, FAMILY> implements IBinaryTreeNode<T, FAMILY> {
-    /**
-     * The function creates a new binary tree node with an optional value and count, and returns it as a specified type.
-     * @param {BinaryTreeNodeId} id - The `id` parameter is the identifier for the binary tree node. It is of type
-     * `BinaryTreeNodeId`, which could be a string or a number depending on how you want to identify your nodes.
-     * @param {T} [val] - The `val` parameter is an optional value that can be assigned to the node. It represents the
-     * value stored in the node.
-     * @param {number} [count] - The count parameter is an optional parameter that represents the number of times the value
-     * appears in the binary tree node.
-     * @returns a new instance of the BinaryTreeNode class, casted as the FAMILY type.
-     */
-    createNode(id: BinaryTreeNodeId, val?: T, count?: number): FAMILY;
+export declare class BinaryTreeNode<T = any, NEIGHBOR extends BinaryTreeNode<T, NEIGHBOR> = BinaryTreeNodeNested<T>> extends AbstractBinaryTreeNode<T, NEIGHBOR> implements IBinaryTreeNode<T, NEIGHBOR> {
 }
 export declare class BinaryTree<N extends BinaryTreeNode<N['val'], N> = BinaryTreeNode> extends AbstractBinaryTree<N> implements IBinaryTree<N> {
     /**
-     * The constructor function accepts an optional options object and sets the values of loopType, autoIncrementId, and
-     * isMergeDuplicatedVal based on the provided options.
-     * @param [options] - An optional object that can contain the following properties:
+     * This is a constructor function for a binary tree class that takes an optional options parameter.
+     * @param {BinaryTreeOptions} [options] - The `options` parameter is an optional object that can be passed to the
+     * constructor of the `BinaryTree` class. It allows you to customize the behavior of the binary tree by providing
+     * different configuration options.
      */
     constructor(options?: BinaryTreeOptions);
     /**
-     * The function creates a new binary tree node with the given id, value, and count if the value is not null, otherwise
-     * it returns null.
+     * The function creates a new binary tree node with an optional value.
      * @param {BinaryTreeNodeId} id - The `id` parameter is the identifier for the binary tree node. It is of type
-     * `BinaryTreeNodeId`.
-     * @param {N | null} val - The `val` parameter represents the value of the node. It can be of type `N` (generic type)
-     * or `null`.
-     * @param {number} [count] - The `count` parameter is an optional parameter of type `number`. It represents the number
-     * of occurrences of the value in the binary tree node. If not provided, the default value is `undefined`.
-     * @returns a BinaryTreeNode object if the value is not null, otherwise it returns null.
+     * `BinaryTreeNodeId`, which represents the unique identifier for each node in the binary tree.
+     * @param [val] - The `val` parameter is an optional value that can be assigned to the node. It represents the value
+     * stored in the node.
+     * @returns a new instance of a BinaryTreeNode with the specified id and value.
      */
-    createNode(id: BinaryTreeNodeId, val?: N['val'], count?: number): N;
+    createNode(id: BinaryTreeNodeId, val?: N['val']): N;
 }

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

@@ -29,45 +29,30 @@ var BinaryTreeNode = /** @class */ (function (_super) {
     function BinaryTreeNode() {
         return _super !== null && _super.apply(this, arguments) || this;
     }
-    /**
-     * The function creates a new binary tree node with an optional value and count, and returns it as a specified type.
-     * @param {BinaryTreeNodeId} id - The `id` parameter is the identifier for the binary tree node. It is of type
-     * `BinaryTreeNodeId`, which could be a string or a number depending on how you want to identify your nodes.
-     * @param {T} [val] - The `val` parameter is an optional value that can be assigned to the node. It represents the
-     * value stored in the node.
-     * @param {number} [count] - The count parameter is an optional parameter that represents the number of times the value
-     * appears in the binary tree node.
-     * @returns a new instance of the BinaryTreeNode class, casted as the FAMILY type.
-     */
-    BinaryTreeNode.prototype.createNode = function (id, val, count) {
-        return new BinaryTreeNode(id, val, count);
-    };
     return BinaryTreeNode;
 }(abstract_binary_tree_1.AbstractBinaryTreeNode));
 exports.BinaryTreeNode = BinaryTreeNode;
 var BinaryTree = /** @class */ (function (_super) {
     __extends(BinaryTree, _super);
     /**
-     * The constructor function accepts an optional options object and sets the values of loopType, autoIncrementId, and
-     * isMergeDuplicatedVal based on the provided options.
-     * @param [options] - An optional object that can contain the following properties:
+     * This is a constructor function for a binary tree class that takes an optional options parameter.
+     * @param {BinaryTreeOptions} [options] - The `options` parameter is an optional object that can be passed to the
+     * constructor of the `BinaryTree` class. It allows you to customize the behavior of the binary tree by providing
+     * different configuration options.
      */
     function BinaryTree(options) {
         return _super.call(this, options) || this;
     }
     /**
-     * The function creates a new binary tree node with the given id, value, and count if the value is not null, otherwise
-     * it returns null.
+     * The function creates a new binary tree node with an optional value.
      * @param {BinaryTreeNodeId} id - The `id` parameter is the identifier for the binary tree node. It is of type
-     * `BinaryTreeNodeId`.
-     * @param {N | null} val - The `val` parameter represents the value of the node. It can be of type `N` (generic type)
-     * or `null`.
-     * @param {number} [count] - The `count` parameter is an optional parameter of type `number`. It represents the number
-     * of occurrences of the value in the binary tree node. If not provided, the default value is `undefined`.
-     * @returns a BinaryTreeNode object if the value is not null, otherwise it returns null.
+     * `BinaryTreeNodeId`, which represents the unique identifier for each node in the binary tree.
+     * @param [val] - The `val` parameter is an optional value that can be assigned to the node. It represents the value
+     * stored in the node.
+     * @returns a new instance of a BinaryTreeNode with the specified id and value.
      */
-    BinaryTree.prototype.createNode = function (id, val, count) {
-        return new BinaryTreeNode(id, val, count);
+    BinaryTree.prototype.createNode = function (id, val) {
+        return new BinaryTreeNode(id, val);
     };
     return BinaryTree;
 }(abstract_binary_tree_1.AbstractBinaryTree));

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

@@ -5,119 +5,107 @@
  * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { BinaryTreeNodeId, BinaryTreeNodePropertyName, BSTComparator, BSTNodeNested } from '../types';
-import { BSTOptions, CP } from '../types';
+import type { BinaryTreeNodeId, BinaryTreeNodePropertyName, BSTComparator, BSTNodeNested, BSTOptions } from '../types';
+import { CP } from '../types';
 import { BinaryTree, BinaryTreeNode } from './binary-tree';
 import { IBST, IBSTNode } from '../interfaces';
-export declare class BSTNode<T = any, FAMILY extends BSTNode<T, FAMILY> = BSTNodeNested<T>> extends BinaryTreeNode<T, FAMILY> implements IBSTNode<T, FAMILY> {
-    /**
-     * The function creates a new binary search tree node with the specified id, value, and count.
-     * @param {BinaryTreeNodeId} id - The id parameter is the identifier for the binary tree node. It is used to uniquely
-     * identify each node in the tree.
-     * @param {T} [val] - The "val" parameter represents the value that will be stored in the binary tree node. It is an
-     * optional parameter, meaning it can be omitted when calling the "createNode" function.
-     * @param {number} [count] - The `count` parameter represents the number of occurrences of the value in the binary
-     * search tree node. It is an optional parameter, so it can be omitted when calling the `createNode` method.
-     * @returns The method is returning a new instance of the BSTNode class, casted as the FAMILY type.
-     */
-    createNode(id: BinaryTreeNodeId, val?: T, count?: number): FAMILY;
+export declare class BSTNode<T = any, NEIGHBOR extends BSTNode<T, NEIGHBOR> = BSTNodeNested<T>> extends BinaryTreeNode<T, NEIGHBOR> implements IBSTNode<T, NEIGHBOR> {
 }
 export declare class BST<N extends BSTNode<N['val'], N> = BSTNode> extends BinaryTree<N> implements IBST<N> {
     /**
-     * The constructor function accepts an optional options object and sets the comparator property if provided.
-     * @param [options] - An optional object that can contain the following properties:
+     * The constructor function initializes a binary search tree object with an optional comparator function.
+     * @param {BSTOptions} [options] - An optional object that contains configuration options for the binary search tree.
      */
     constructor(options?: BSTOptions);
     /**
-     * The function creates a new binary search tree node with the given id, value, and count.
-     * @param {BinaryTreeNodeId} id - The `id` parameter is the identifier for the binary tree node. It is of type
-     * `BinaryTreeNodeId`.
-     * @param {N['val'] | null} [val] - The `val` parameter is the value that will be stored in the node. It can be of any
-     * type `N['val']` or `null`.
-     * @param {number} [count] - The `count` parameter is an optional parameter that represents the number of occurrences
-     * of a particular value in the binary search tree node.
-     * @returns a new instance of the BSTNode class, casted as type N.
+     * The function creates a new binary search tree node with the given id and value.
+     * @param {BinaryTreeNodeId} id - The `id` parameter is the identifier for the binary tree node. It is used to uniquely
+     * identify each node in the binary tree.
+     * @param [val] - The `val` parameter is an optional value that can be assigned to the node. It represents the value
+     * that will be stored in the node.
+     * @returns a new instance of the BSTNode class with the specified id and value.
      */
-    createNode(id: BinaryTreeNodeId, val?: N['val'], count?: number): N;
+    createNode(id: BinaryTreeNodeId, val?: N['val']): N;
     /**
-     * The `add` function inserts a new node into a binary search tree, updating the count and value of an existing node if
-     * the ID matches, and returns the inserted node.
-     * @param {BinaryTreeNodeId} id - The `id` parameter represents the identifier of the binary tree node. It is used to
-     * determine the position of the node in the binary search tree.
-     * @param {N | null} val - The `val` parameter represents the value to be stored in the binary search tree node. It can
-     * be of type `N` (the generic type) or `null`.
-     * @param {number} [count=1] - The `count` parameter represents the number of times the value should be inserted into
-     * the binary search tree. By default, it is set to 1, meaning that if no count is specified, the value will be
-     * inserted once.
-     * @returns The method `add` returns a `N` object or `null`.
+     * The `add` function adds a new node to a binary tree, ensuring that duplicates are not accepted.
+     * @param {BinaryTreeNodeId} id - The `id` parameter is the identifier of the binary tree node that we want to add. It
+     * is of type `BinaryTreeNodeId`.
+     * @param [val] - The `val` parameter is an optional value that can be assigned to the node being added. It represents
+     * the value associated with the node.
+     * @returns The function `add` returns the inserted node (`inserted`) if it was successfully added to the binary tree.
+     * If the node was not added (e.g., due to a duplicate ID), it returns `null` or `undefined`.
      */
-    add(id: BinaryTreeNodeId, val?: N['val'], count?: number): N | null;
+    add(id: BinaryTreeNodeId, val?: N['val']): N | null | undefined;
     /**
-     * The `get` function returns the first node in a binary search tree that matches the given property value or name.
+     * The function returns the first node in a binary tree that matches the given property name and value.
      * @param {BinaryTreeNodeId | N} nodeProperty - The `nodeProperty` parameter can be either a `BinaryTreeNodeId` or a
-     * generic type `N`. It represents the value of the property that you want to search for in the binary search tree.
+     * generic type `N`. It represents the property of the binary tree node that you want to search for.
      * @param {BinaryTreeNodePropertyName} [propertyName] - The `propertyName` parameter is an optional parameter that
-     * specifies the property name to use for searching the binary search tree nodes. If not provided, it defaults to
-     * `'id'`.
-     * @returns The method is returning a N object or null.
+     * specifies the property name to use for searching the binary tree nodes. If not provided, it defaults to `'id'`.
+     * @returns The method is returning either a BinaryTreeNodeId or N (generic type) or null.
      */
     get(nodeProperty: BinaryTreeNodeId | N, propertyName?: BinaryTreeNodePropertyName): N | null;
     /**
      * The function returns the id of the rightmost node if the comparison between two values is less than, the id of the
      * leftmost node if the comparison is greater than, and the id of the rightmost node otherwise.
-     * @returns The function `lastKey()` returns the ID of the rightmost node in a binary tree. If the comparison between
-     * the first two elements in the tree is less than, it returns the ID of the rightmost node. If the comparison is
-     * greater than, it returns the ID of the leftmost node. Otherwise, it also returns the ID of the rightmost node. If
-     * there are no nodes in
+     * @returns The method `lastKey()` returns the id of the rightmost node in the binary tree if the comparison between
+     * the values at index 0 and 1 is less than, otherwise it returns the id of the leftmost node. If the comparison is
+     * equal, it returns the id of the rightmost node. If there are no nodes in the tree, it returns 0.
      */
     lastKey(): BinaryTreeNodeId;
     /**
-     * The function `getNodes` returns an array of binary search tree nodes that match a given property value, with the
-     * option to specify the property name and whether to return only one node.
-     * @param {BinaryTreeNodeId | N} nodeProperty - The `nodeProperty` parameter can be either a `BinaryTreeNodeId` or a
-     * generic type `N`. It represents the property value that you want to search for in the binary search tree.
+     * The function `getNodes` returns an array of nodes in a binary tree that match a given property value.
+     * @param {BinaryTreeNodeId | N} nodeProperty - The `nodeProperty` parameter can be either a `BinaryTreeNodeId` or an
+     * `N` type. It represents the property of the binary tree node that you want to compare with.
      * @param {BinaryTreeNodePropertyName} [propertyName] - The `propertyName` parameter is an optional parameter that
-     * specifies the property of the nodes to compare with the `nodeProperty` parameter. If not provided, it defaults to
-     * `'id'`.
-     * @param {boolean} [onlyOne] - A boolean value indicating whether to return only one node that matches the given
-     * nodeProperty. If set to true, the function will stop traversing the tree and return the first matching node. If set
-     * to false or not provided, the function will return all nodes that match the given nodeProperty.
-     * @returns an array of N objects.
+     * specifies the property name to use for comparison. If not provided, it defaults to `'id'`.
+     * @param {boolean} [onlyOne] - The `onlyOne` parameter is an optional boolean parameter that determines whether to
+     * return only one node that matches the given `nodeProperty` or all nodes that match the `nodeProperty`. If `onlyOne`
+     * is set to `true`, the function will return an array with only one node (if
+     * @returns an array of nodes (type N).
      */
     getNodes(nodeProperty: BinaryTreeNodeId | N, propertyName?: BinaryTreeNodePropertyName, onlyOne?: boolean): N[];
     /**
-     * The `lesserSum` function calculates the sum of property values in a binary tree for nodes that have a lesser value
-     * than a given node.
+     * The `lesserSum` function calculates the sum of property values in a binary tree for nodes that have a property value
+     * less than a given node.
      * @param {N | BinaryTreeNodeId | null} beginNode - The `beginNode` parameter can be one of the following:
      * @param {BinaryTreeNodePropertyName} [propertyName] - The `propertyName` parameter is an optional parameter that
      * specifies the property name to use for calculating the sum. If not provided, it defaults to `'id'`.
-     * @returns The function `lesserSum` returns a number, which represents the sum of the values of the nodes in a binary
-     * tree that have a lesser value than the specified `beginNode` based on the specified `propertyName`.
+     * @returns The function `lesserSum` returns a number, which represents the sum of the values of the nodes in the
+     * binary tree that have a lesser value than the specified `beginNode` based on the `propertyName`.
      */
     lesserSum(beginNode: N | BinaryTreeNodeId | null, propertyName?: BinaryTreeNodePropertyName): number;
     /**
-     * The function `allGreaterNodesAdd` updates the value of a specified property for all nodes in a binary search tree
-     * that have a greater value than a given node.
-     * @param node - The `node` parameter is of type `N`, which represents a node in a binary search tree. It
-     * contains properties such as `id` and `count`.
+     * The `allGreaterNodesAdd` function adds a delta value to the specified property of all nodes in a binary tree that
+     * have a greater value than a given node.
+     * @param {N | BinaryTreeNodeId | null} node - The `node` parameter can be either of type `N` (a generic type),
+     * `BinaryTreeNodeId`, or `null`. It represents the node in the binary tree to which the delta value will be added.
      * @param {number} delta - The `delta` parameter is a number that represents the amount by which the property value of
-     * each node should be increased.
-     * @param {BinaryTreeNodePropertyName} [propertyName] - propertyName is an optional parameter that specifies the
-     * property of the BSTNode to be modified. It can be either 'id' or 'count'. If propertyName is not provided, it
-     * defaults to 'id'.
+     * each greater node should be increased.
+     * @param {BinaryTreeNodePropertyName} [propertyName] - The `propertyName` parameter is an optional parameter that
+     * specifies the property name of the nodes in the binary tree that you want to update. If not provided, it defaults to
+     * 'id'.
      * @returns a boolean value.
      */
     allGreaterNodesAdd(node: N | BinaryTreeNodeId | null, delta: number, propertyName?: BinaryTreeNodePropertyName): boolean;
     /**
-     * The `balance` function takes a sorted array of nodes and builds a balanced binary search tree using either a
-     * recursive or iterative approach.
-     * @returns The `balance()` function returns a boolean value.
+     * Balancing Adjustment:
+     * Perfectly Balanced Binary Tree: Since the balance of a perfectly balanced binary tree is already fixed, no additional balancing adjustment is needed. Any insertion or deletion operation will disrupt the perfect balance, often requiring a complete reconstruction of the tree.
+     * AVL Tree: After insertion or deletion operations, an AVL tree performs rotation adjustments based on the balance factor of nodes to restore the tree's balance. These rotations can be left rotations, right rotations, left-right rotations, or right-left rotations, performed as needed.
+     *
+     * Use Cases and Efficiency:
+     * Perfectly Balanced Binary Tree: Perfectly balanced binary trees are typically used in specific scenarios such as complete binary heaps in heap sort or certain types of Huffman trees. However, they are not suitable for dynamic operations requiring frequent insertions and deletions, as these operations often necessitate full tree reconstruction.
+     * AVL Tree: AVL trees are well-suited for scenarios involving frequent searching, insertion, and deletion operations. Through rotation adjustments, AVL trees maintain their balance, ensuring average and worst-case time complexity of O(log n).
      */
-    balance(): boolean;
     /**
-     * The function `isAVLBalanced` checks if a binary search tree is balanced according to the AVL tree property.
-     * @returns The function `isAVLBalanced()` returns a boolean value. It returns `true` if the binary search tree (BST)
-     * is balanced according to the AVL tree property, and `false` otherwise.
+     * The `perfectlyBalance` function takes a binary tree, performs a depth-first search to sort the nodes, and then
+     * constructs a balanced binary search tree using either a recursive or iterative approach.
+     * @returns The function `perfectlyBalance()` returns a boolean value.
+     */
+    perfectlyBalance(): boolean;
+    /**
+     * The function `isAVLBalanced` checks if a binary tree is balanced according to the AVL tree property.
+     * @returns a boolean value.
      */
     isAVLBalanced(): boolean;
     protected _comparator: BSTComparator;