min-heap-typed 1.50.1 → 1.50.3

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

@@ -9,29 +9,34 @@ import type { BSTNested, BSTNodeNested, BSTOptions, BTNCallback, KeyOrNodeOrEntr
 import { BSTVariant, CP, DFSOrderPattern, IterationType } from '../../types';
 import { BinaryTree, BinaryTreeNode } from './binary-tree';
 import { IBinaryTree } from '../../interfaces';
-export declare class BSTNode<K = any, V = any, N extends BSTNode<K, V, N> = BSTNodeNested<K, V>> extends BinaryTreeNode<K, V, N> {
-    parent?: N;
+export declare class BSTNode<K = any, V = any, NODE extends BSTNode<K, V, NODE> = BSTNodeNested<K, V>> extends BinaryTreeNode<K, V, NODE> {
+    parent?: NODE;
     constructor(key: K, value?: V);
-    protected _left?: N;
+    protected _left?: NODE;
     /**
-     * Get the left child node.
+     * The function returns the value of the `_left` property.
+     * @returns The `_left` property of the current object is being returned.
      */
-    get left(): N | undefined;
+    get left(): NODE | undefined;
     /**
-     * Set the left child node.
-     * @param {N | undefined} v - The left child node.
+     * The function sets the left child of a node and updates the parent reference of the child.
+     * @param {NODE | undefined} v - The parameter `v` is of type `NODE | undefined`. It can either be an
+     * instance of the `NODE` class or `undefined`.
      */
-    set left(v: N | undefined);
-    protected _right?: N;
+    set left(v: NODE | undefined);
+    protected _right?: NODE;
     /**
-     * Get the right child node.
+     * The function returns the right node of a binary tree or undefined if there is no right node.
+     * @returns The method is returning the value of the `_right` property, which is of type `NODE` or
+     * `undefined`.
      */
-    get right(): N | undefined;
+    get right(): NODE | undefined;
     /**
-     * Set the right child node.
-     * @param {N | undefined} v - The right child node.
+     * The function sets the right child of a node and updates the parent reference of the child.
+     * @param {NODE | undefined} v - The parameter `v` is of type `NODE | undefined`. It can either be a
+     * `NODE` object or `undefined`.
      */
-    set right(v: N | undefined);
+    set right(v: NODE | undefined);
 }
 /**
  * 1. Node Order: Each node's left child has a lesser value, and the right child has a greater value.
@@ -42,50 +47,58 @@ export declare class BSTNode<K = any, V = any, N extends BSTNode<K, V, N> = BSTN
  * 6. Balance Variability: Can become unbalanced; special types maintain balance.
  * 7. No Auto-Balancing: Standard BSTs don't automatically balance themselves.
  */
-export declare class BST<K = any, V = any, N extends BSTNode<K, V, N> = BSTNode<K, V, BSTNodeNested<K, V>>, TREE extends BST<K, V, N, TREE> = BST<K, V, N, BSTNested<K, V, N>>> extends BinaryTree<K, V, N, TREE> implements IBinaryTree<K, V, N, TREE> {
+export declare class BST<K = any, V = any, NODE extends BSTNode<K, V, NODE> = BSTNode<K, V, BSTNodeNested<K, V>>, TREE extends BST<K, V, NODE, TREE> = BST<K, V, NODE, BSTNested<K, V, NODE>>> extends BinaryTree<K, V, NODE, TREE> implements IBinaryTree<K, V, NODE, TREE> {
     /**
-     * This is the constructor function for a binary search tree class in TypeScript, which initializes
-     * the tree with optional keysOrNodesOrEntries and options.
-     * @param [keysOrNodesOrEntries] - An optional iterable of KeyOrNodeOrEntry objects that will be added to the
-     * binary search tree.
+     * This is the constructor function for a TypeScript class that initializes a binary search tree with
+     * optional keys or nodes or entries and options.
+     * @param keysOrNodesOrEntries - An iterable object that contains keys, nodes, or entries. It is used
+     * to initialize the binary search tree with the provided keys, nodes, or entries.
      * @param [options] - The `options` parameter is an optional object that can contain additional
      * configuration options for the binary search tree. It can have the following properties:
      */
-    constructor(keysOrNodesOrEntries?: Iterable<KeyOrNodeOrEntry<K, V, N>>, options?: BSTOptions<K>);
-    protected _root?: N;
-    get root(): N | undefined;
+    constructor(keysOrNodesOrEntries?: Iterable<KeyOrNodeOrEntry<K, V, NODE>>, options?: BSTOptions<K>);
+    protected _root?: NODE;
+    /**
+     * The function returns the root node of a tree structure.
+     * @returns The `_root` property of the object, which is of type `NODE` or `undefined`.
+     */
+    get root(): NODE | undefined;
     protected _variant: BSTVariant;
+    /**
+     * The function returns the value of the _variant property.
+     * @returns The value of the `_variant` property.
+     */
     get variant(): BSTVariant;
     /**
-     * The function creates a new binary search tree node with the given key and value.
-     * @param {K} key - The key parameter is the key value that will be associated with
-     * 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
-     * represents the value associated with the node in a binary search tree.
-     * @returns a new instance of the BSTNode class with the specified key and value.
+     * The function creates a new BSTNode with the given key and value and returns it.
+     * @param {K} key - The key parameter is of type K, which represents the type of the key for the node
+     * 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 node being created.
+     * @returns The method is returning a new instance of the BSTNode class, casted as the NODE type.
      */
-    createNode(key: K, value?: V): N;
+    createNode(key: K, value?: V): NODE;
     /**
      * The function creates a new binary search tree with the specified options.
      * @param [options] - The `options` parameter is an optional object that allows you to customize the
-     * behavior of the `createTree` method. It accepts a partial `BSTOptions` object, which is a type
-     * that defines various options for creating a binary search tree.
-     * @returns a new instance of the BST class with the specified options.
+     * behavior of the `createTree` method. It is of type `Partial<BSTOptions<K>>`, which means it is a
+     * partial object of type `BSTOptions<K>`.
+     * @returns a new instance of the BST class, with the provided options merged with the default
+     * options. The returned value is casted as TREE.
      */
     createTree(options?: Partial<BSTOptions<K>>): TREE;
     /**
-     * The function `exemplarToNode` takes an keyOrNodeOrEntry and returns a node if the keyOrNodeOrEntry is valid,
+     * The function `keyValueOrEntryToNode` takes an keyOrNodeOrEntry and returns a node if the keyOrNodeOrEntry is valid,
      * otherwise it returns undefined.
-     * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is of type `KeyOrNodeOrEntry<K, V, N>`, where:
+     * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is of type `KeyOrNodeOrEntry<K, V, NODE>`, where:
      * @param {V} [value] - The `value` parameter is an optional value that can be passed to the
-     * `exemplarToNode` function. It represents the value associated with the keyOrNodeOrEntry node.
-     * @returns a node of type N or undefined.
+     * `keyValueOrEntryToNode` function. It represents the value associated with the keyOrNodeOrEntry node.
+     * @returns a node of type NODE or undefined.
      */
-    exemplarToNode(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, N>, value?: V): N | undefined;
+    keyValueOrEntryToNode(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>, value?: V): NODE | undefined;
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(log n)
-     * Average case for a balanced tree. Space for the recursive call stack in the worst case.
      */
     /**
      * Time Complexity: O(log n)
@@ -93,23 +106,22 @@ export declare class BST<K = any, V = any, N extends BSTNode<K, V, N> = BSTNode<
      *
      * The function `ensureNode` returns the node corresponding to the given key if it is a node key,
      * otherwise it returns the key itself.
-     * @param {K | N | undefined} keyOrNodeOrEntry - The `key` parameter can be of type `K`, `N`, or
+     * @param {K | NODE | undefined} keyOrNodeOrEntry - The `key` parameter can be of type `K`, `NODE`, or
      * `undefined`.
      * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
      * type of iteration to be performed. It has a default value of `IterationType.ITERATIVE`.
-     * @returns either a node object (N) or undefined.
+     * @returns either a node object (NODE) or undefined.
      */
-    ensureNode(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, N>, iterationType?: IterationType): N | undefined;
+    ensureNode(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>, iterationType?: IterationType): NODE | undefined;
     /**
      * The function checks if an keyOrNodeOrEntry is an instance of BSTNode.
-     * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is a variable of type `KeyOrNodeOrEntry<K, V, N>`.
+     * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is a variable of type `KeyOrNodeOrEntry<K, V, NODE>`.
      * @returns a boolean value indicating whether the keyOrNodeOrEntry is an instance of the BSTNode class.
      */
-    isNode(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, N>): keyOrNodeOrEntry is N;
+    isNode(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>): keyOrNodeOrEntry is NODE;
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
-     *  - Average case for a balanced tree. In the worst case (unbalanced tree), it can be O(n).
      */
     /**
      * Time Complexity: O(log n)
@@ -123,15 +135,14 @@ export declare class BST<K = any, V = any, N extends BSTNode<K, V, N> = BSTNode<
      * @returns The method `add` returns either the newly added node (`newNode`) or `undefined` if the
      * node was not added.
      */
-    add(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, N>, value?: V): boolean;
+    add(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>, value?: V): boolean;
     /**
      * Time Complexity: O(k log n)
-     * Space Complexity: O(k)
-     * Adding each element individually in a balanced tree. Additional space is required for the sorted array.
+     * Space Complexity: O(k + log n)
      */
     /**
      * Time Complexity: O(k log n)
-     * Space Complexity: O(k)
+     * Space Complexity: O(k + log n)
      *
      * The `addMany` function in TypeScript adds multiple keys or nodes to a binary tree, optionally
      * balancing the tree after each addition.
@@ -147,9 +158,9 @@ export declare class BST<K = any, V = any, N extends BSTNode<K, V, N> = BSTNode<
      * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
      * type of iteration to use when adding multiple keys or nodes. It has a default value of
      * `this.iterationType`, which suggests that it is a property of the current object.
-     * @returns The function `addMany` returns an array of nodes (`N`) or `undefined` values.
+     * @returns The function `addMany` returns an array of nodes (`NODE`) or `undefined` values.
      */
-    addMany(keysOrNodesOrEntries: Iterable<KeyOrNodeOrEntry<K, V, N>>, values?: Iterable<V | undefined>, isBalanceAdd?: boolean, iterationType?: IterationType): boolean[];
+    addMany(keysOrNodesOrEntries: Iterable<KeyOrNodeOrEntry<K, V, NODE>>, values?: Iterable<V | undefined>, isBalanceAdd?: boolean, iterationType?: IterationType): boolean[];
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
@@ -165,40 +176,39 @@ export declare class BST<K = any, V = any, N extends BSTNode<K, V, N> = BSTNode<
      * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
      * type of iteration to use when searching for a node in the binary tree. It can have two possible
      * values:
-     * @returns The function `getNodeByKey` returns a node (`N`) if a node with the specified key is
+     * @returns The function `getNodeByKey` returns a node (`NODE`) if a node with the specified key is
      * found in the binary tree. If no node is found, it returns `undefined`.
      */
-    getNodeByKey(key: K, iterationType?: IterationType): N | undefined;
+    getNodeByKey(key: K, iterationType?: IterationType): NODE | undefined;
     /**
      * Time Complexity: O(log n)
-     * Space Complexity: O(log n)
-     * Average case for a balanced tree. O(n) - Visiting each node once when identifier is not node's key. Space for the recursive call stack in the worst case.
+     * Space Complexity: O(k + log n)
      * /
   
      /**
      * Time Complexity: O(log n)
-     * Space Complexity: O(log n)
+     * Space Complexity: O(k + log n)
      *
      * The function `getNodes` returns an array of nodes that match a given identifier, using either a
      * recursive or iterative approach.
      * @param {ReturnType<C> | undefined} identifier - The `identifier` parameter is the value that you
      * want to search for in the nodes of the binary tree. It can be of any type that is returned by the
      * callback function `C`.
-     * @param {C} callback - The `callback` parameter is a function that takes a node of type `N` as its
+     * @param {C} callback - The `callback` parameter is a function that takes a node of type `NODE` as its
      * argument and returns a value of type `ReturnType<C>`. The `C` type parameter represents a callback
-     * function type that extends the `BTNCallback<N>` type. The `BTNCallback<N>` type is
+     * function type that extends the `BTNCallback<NODE>` type. The `BTNCallback<NODE>` type is
      * @param [onlyOne=false] - A boolean flag indicating whether to stop searching after finding the
      * first node that matches the identifier. If set to true, the function will return an array
      * containing only the first matching node. If set to false (default), the function will continue
      * searching for all nodes that match the identifier and return an array containing
-     * @param {K | N | undefined} beginRoot - The `beginRoot` parameter represents the starting node
+     * @param {K | NODE | undefined} beginRoot - The `beginRoot` parameter represents the starting node
      * for the traversal. It can be either a key value or a node object. If it is undefined, the
      * traversal will start from the root of the tree.
      * @param iterationType - The `iterationType` parameter determines the type of iteration to be
      * performed on the binary tree. It can have two possible values:
-     * @returns The method returns an array of nodes (`N[]`).
+     * @returns The method returns an array of nodes (`NODE[]`).
      */
-    getNodes<C extends BTNCallback<N>>(identifier: ReturnType<C> | undefined, callback?: C, onlyOne?: boolean, beginRoot?: KeyOrNodeOrEntry<K, V, N>, iterationType?: IterationType): N[];
+    getNodes<C extends BTNCallback<NODE>>(identifier: ReturnType<C> | undefined, callback?: C, onlyOne?: boolean, beginRoot?: KeyOrNodeOrEntry<K, V, NODE>, iterationType?: IterationType): NODE[];
     /**
      * Time complexity: O(n)
      * Space complexity: O(n)
@@ -222,7 +232,7 @@ export declare class BST<K = any, V = any, N extends BSTNode<K, V, N> = BSTNode<
      * following values:
      * @returns The method is returning an array of the return type of the callback function.
      */
-    dfs<C extends BTNCallback<N>>(callback?: C, pattern?: DFSOrderPattern, beginRoot?: KeyOrNodeOrEntry<K, V, N>, iterationType?: IterationType): ReturnType<C>[];
+    dfs<C extends BTNCallback<NODE>>(callback?: C, pattern?: DFSOrderPattern, beginRoot?: KeyOrNodeOrEntry<K, V, NODE>, iterationType?: IterationType): ReturnType<C>[];
     /**
      * Time complexity: O(n)
      * Space complexity: O(n)
@@ -244,7 +254,7 @@ export declare class BST<K = any, V = any, N extends BSTNode<K, V, N> = BSTNode<
      * nodes are visited.
      * @returns The method is returning an array of the return type of the callback function.
      */
-    bfs<C extends BTNCallback<N>>(callback?: C, beginRoot?: KeyOrNodeOrEntry<K, V, N>, iterationType?: IterationType): ReturnType<C>[];
+    bfs<C extends BTNCallback<NODE>>(callback?: C, beginRoot?: KeyOrNodeOrEntry<K, V, NODE>, iterationType?: IterationType): ReturnType<C>[];
     /**
      * Time complexity: O(n)
      * Space complexity: O(n)
@@ -256,7 +266,7 @@ export declare class BST<K = any, V = any, N extends BSTNode<K, V, N> = BSTNode<
      * The function overrides the listLevels method and returns an array of arrays containing the return
      * type of the callback function for each level of the tree.
      * @param {C} callback - The `callback` parameter is a generic type `C` that extends
-     * `BTNCallback<N>`. It represents a callback function that will be called for each node in the tree
+     * `BTNCallback<NODE>`. It represents a callback function that will be called for each node in the tree
      * during the level listing process.
      * @param beginRoot - The `beginRoot` parameter is used to specify the starting point for listing the
      * levels of a binary tree. It can be either a key, a node, or an entry in the binary tree. If not
@@ -267,30 +277,28 @@ export declare class BST<K = any, V = any, N extends BSTNode<K, V, N> = BSTNode<
      * @returns The method is returning a two-dimensional array of the return type of the callback
      * function.
      */
-    listLevels<C extends BTNCallback<N>>(callback?: C, beginRoot?: KeyOrNodeOrEntry<K, V, N>, iterationType?: IterationType): ReturnType<C>[][];
+    listLevels<C extends BTNCallback<NODE>>(callback?: C, beginRoot?: KeyOrNodeOrEntry<K, V, NODE>, iterationType?: IterationType): ReturnType<C>[][];
     /**
-     * Time Complexity: O(n log n)
-     * Space Complexity: O(n)
-     * Adding each element individually in a balanced tree. Additional space is required for the sorted array.
+     * Time Complexity: O(log n)
+     * Space Complexity: O(1)
      */
     /**
-     * Time Complexity: O(n log n)
-     * Space Complexity: O(n)
+     * Time Complexity: O(log n)
+     * Space Complexity: O(1)
      *
      * The `lastKey` function returns the key of the rightmost node in a binary tree, or the key of the
      * leftmost node if the comparison result is greater than.
-     * @param {K | N | undefined} beginRoot - The `beginRoot` parameter is optional and can be of
-     * type `K`, `N`, or `undefined`. It represents the starting point for finding the last key in
+     * @param {K | NODE | undefined} beginRoot - The `beginRoot` parameter is optional and can be of
+     * type `K`, `NODE`, or `undefined`. It represents the starting point for finding the last key in
      * the binary tree. If not provided, it defaults to the root of the binary tree (`this.root`).
      * @returns the key of the rightmost node in the binary tree if the comparison result is less than,
      * the key of the leftmost node if the comparison result is greater than, and the key of the
      * rightmost node otherwise. If no node is found, it returns 0.
      */
-    lastKey(beginRoot?: KeyOrNodeOrEntry<K, V, N>): K | undefined;
+    lastKey(beginRoot?: KeyOrNodeOrEntry<K, V, NODE>): K | undefined;
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(log n)
-     * Average case for a balanced tree. O(n) - Visiting each node once when identifier is not node's key. Space for the recursive call stack in the worst case.
      */
     /**
      * Time Complexity: O(log n)
@@ -300,12 +308,12 @@ export declare class BST<K = any, V = any, N extends BSTNode<K, V, N> = BSTNode<
      * are either lesser or greater than a target node, depending on the specified comparison type.
      * @param {C} callback - The `callback` parameter is a function that will be called for each node
      * that satisfies the condition specified by the `lesserOrGreater` parameter. It takes a single
-     * parameter of type `N` (the node type) and returns a value of any type.
+     * parameter of type `NODE` (the node type) and returns a value of any type.
      * @param {CP} lesserOrGreater - The `lesserOrGreater` parameter is used to determine whether to
      * traverse nodes that are lesser than, greater than, or equal to the `targetNode`. It is of type
      * `CP`, which is a custom type representing the comparison operator. The possible values for
      * `lesserOrGreater` are
-     * @param {K | N | undefined} targetNode - The `targetNode` parameter represents the node in the
+     * @param {K | NODE | undefined} targetNode - The `targetNode` parameter represents the node in the
      * binary tree that you want to traverse from. It can be specified either by its key, by the node
      * object itself, or it can be left undefined to start the traversal from the root of the tree.
      * @param iterationType - The `iterationType` parameter determines the type of traversal to be
@@ -313,7 +321,7 @@ export declare class BST<K = any, V = any, N extends BSTNode<K, V, N> = BSTNode<
      * @returns The function `lesserOrGreaterTraverse` returns an array of values of type
      * `ReturnType<C>`, which is the return type of the callback function passed as an argument.
      */
-    lesserOrGreaterTraverse<C extends BTNCallback<N>>(callback?: C, lesserOrGreater?: CP, targetNode?: KeyOrNodeOrEntry<K, V, N>, iterationType?: IterationType): ReturnType<C>[];
+    lesserOrGreaterTraverse<C extends BTNCallback<NODE>>(callback?: C, lesserOrGreater?: CP, targetNode?: KeyOrNodeOrEntry<K, V, NODE>, iterationType?: IterationType): ReturnType<C>[];
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(log n)
@@ -340,8 +348,8 @@ export declare class BST<K = any, V = any, N extends BSTNode<K, V, N> = BSTNode<
      * 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).
      */
     /**
-     * Time Complexity: O(n) - Building a balanced tree from a sorted array.
-     * Space Complexity: O(n) - Additional space is required for the sorted array.
+     * Time Complexity: O(n)
+     * Space Complexity: O(log n)
      */
     /**
      * Time Complexity: O(n)
@@ -353,7 +361,12 @@ export declare class BST<K = any, V = any, N extends BSTNode<K, V, N> = BSTNode<
      * @returns a boolean value.
      */
     isAVLBalanced(iterationType?: IterationType): boolean;
-    protected _setRoot(v: N | undefined): void;
+    /**
+     * The function sets the root property of an object and updates the parent property of the new root.
+     * @param {NODE | undefined} v - The parameter `v` is of type `NODE | undefined`. This means that it
+     * can either be an object of type `NODE` or it can be `undefined`.
+     */
+    protected _setRoot(v: NODE | undefined): void;
     /**
      * The function compares two values using a comparator function and returns whether the first value
      * is greater than, less than, or equal to the second value.