data-structure-typed 1.37.0 → 1.37.2

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

@@ -5,8 +5,8 @@
  * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { BinaryTreeNodeKey, BinaryTreeNodeNested, BinaryTreeNodeProperties, BinaryTreeOptions } from '../../types';
-import { BinaryTreeDeletedResult, BinaryTreeNodePropertyName, DFSOrderPattern, FamilyPosition, LoopType, NodeOrPropertyName } from '../../types';
+import type { BFSCallback, BFSCallbackReturn, BinaryTreeNodeKey, BinaryTreeNodeNested, BinaryTreeOptions, MapCallback, MapCallbackReturn } from '../../types';
+import { BinaryTreeDeletedResult, DFSOrderPattern, FamilyPosition, LoopType } from '../../types';
 import { IBinaryTree } from '../../interfaces';
 export declare class BinaryTreeNode<V = any, FAMILY extends BinaryTreeNode<V, FAMILY> = BinaryTreeNodeNested<V>> {
     /**
@@ -56,9 +56,6 @@ export declare class BinaryTree<N extends BinaryTreeNode<N['val'], N> = BinaryTr
     private _loopType;
     get loopType(): LoopType;
     set loopType(v: LoopType);
-    visitedKey: BinaryTreeNodeKey[];
-    visitedVal: N['val'][];
-    visitedNode: N[];
     /**
      * The `_swap` function swaps the location of two nodes in a binary tree.
      * @param {N} srcNode - The source node that you want to _swap with the destination node.
@@ -134,6 +131,7 @@ export declare class BinaryTree<N extends BinaryTreeNode<N['val'], N> = BinaryTr
      * @returns the height of the binary tree.
      */
     getHeight(beginRoot?: N | BinaryTreeNodeKey | null): number;
+    protected _defaultCallbackByKey: MapCallback<N>;
     /**
      * The `getMinHeight` function calculates the minimum height of a binary tree using either a recursive or iterative
      * approach.
@@ -153,88 +151,72 @@ export declare class BinaryTree<N extends BinaryTreeNode<N['val'], N> = BinaryTr
     isPerfectlyBalanced(beginRoot?: N | null): boolean;
     /**
      * The function `getNodes` returns an array of nodes that match a given property name and value in a binary tree.
+     * @param callback
      * @param {BinaryTreeNodeKey | N} nodeProperty - The `nodeProperty` parameter can be either a `BinaryTreeNodeKey` or a
      * 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 when searching for nodes. If not provided, it defaults to 'key'.
      * @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 `propertyName`. If `onlyOne` is set to `true`, the
      * function will stop traversing the tree and return the first matching node. If `only
+     * @param beginRoot
      * @returns an array of nodes (type N).
      */
-    getNodes(nodeProperty: BinaryTreeNodeKey | N, propertyName?: BinaryTreeNodePropertyName, onlyOne?: boolean): N[];
+    getNodes(nodeProperty: BinaryTreeNodeKey | N, callback?: MapCallback<N>, onlyOne?: boolean, beginRoot?: N | null): N[];
     /**
      * The function checks if a binary tree node has a specific property.
+     * @param callback - The `callback` parameter is a function that takes a node as a parameter and returns a value.
      * @param {BinaryTreeNodeKey | N} nodeProperty - The `nodeProperty` parameter can be either a `BinaryTreeNodeKey` or `N`.
      * It represents the property of the binary tree node that you want to check.
-     * @param {BinaryTreeNodePropertyName} [propertyName] - The `propertyName` parameter is an optional parameter that
      * specifies the name of the property to be checked in the nodes. If not provided, it defaults to 'key'.
      * @returns a boolean value.
      */
-    has(nodeProperty: BinaryTreeNodeKey | N, propertyName?: BinaryTreeNodePropertyName): boolean;
+    has(nodeProperty: BinaryTreeNodeKey | N, callback?: MapCallback<N>): boolean;
     /**
      * The function returns the first node that matches the given property name and value, or null if no matching node is
      * found.
+     * @param callback - The `callback` parameter is a function that takes a node as a parameter and returns a value.
      * @param {BinaryTreeNodeKey | N} nodeProperty - The `nodeProperty` parameter can be either a `BinaryTreeNodeKey` or `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 be used for searching the binary tree nodes. If this parameter is not provided, the
      * default value is set to `'key'`.
      * @returns either the value of the specified property of the node, or the node itself if no property name is provided.
      * If no matching node is found, it returns null.
      */
-    get(nodeProperty: BinaryTreeNodeKey | N, propertyName?: BinaryTreeNodePropertyName): N | null;
+    get(nodeProperty: BinaryTreeNodeKey | N, callback?: MapCallback<N>): N | null;
     /**
      * The function `getPathToRoot` returns an array of nodes representing the path from a given node to the root node, with
      * an option to reverse the order of the nodes.
-     * @param {N} node - The `node` parameter represents a node in a tree structure. It is of type `N`, which could be any
      * type that represents a node in your specific implementation.
+     * @param beginRoot   - The `beginRoot` parameter is of type `N` and represents the starting node from which you want to
      * @param {boolean} [isReverse=true] - The `isReverse` parameter is a boolean flag that determines whether the resulting
      * path should be reversed or not. If `isReverse` is set to `true`, the path will be reversed before returning it. If
      * `isReverse` is set to `false` or not provided, the path will
      * @returns The function `getPathToRoot` returns an array of nodes (`N[]`).
      */
-    getPathToRoot(node: N, isReverse?: boolean): N[];
-    /**
-     * The function `getLeftMost` returns the leftmost node in a binary tree, starting from a specified node or the root if
-     * no node is specified.
-     * generic type representing a node in a binary tree, `BinaryTreeNodeKey` (a type representing the ID of a binary tree
-     * node), or `null`.
-     * @returns The function `getLeftMost` returns the leftmost node in a binary tree. If the `beginRoot` parameter is
-     * provided, it starts the traversal from that node. If `beginRoot` is not provided or is `null`, it starts the traversal
-     * from the root of the binary tree. The function returns the leftmost node found during the traversal. If no leftmost
-     * node is found (
-     */
-    getLeftMost(): N | null;
+    getPathToRoot(beginRoot: N, isReverse?: boolean): N[];
     /**
      * The function `getLeftMost` returns the leftmost node in a binary tree, starting from a specified node or the root if
      * no node is specified.
-     * @param {N | BinaryTreeNodeKey | null} [node] - The `beginRoot` parameter is optional and can be of type `N` (a
+     * @param {N | BinaryTreeNodeKey | null} [beginRoot] - The `beginRoot` parameter is optional and can be of type `N` (a
      * generic type representing a node in a binary tree), `BinaryTreeNodeKey` (a type representing the ID of a binary tree
-     * node).
+     * node), or `null`.
      * @returns The function `getLeftMost` returns the leftmost node in a binary tree. If the `beginRoot` parameter is
      * provided, it starts the traversal from that node. If `beginRoot` is not provided or is `null`, it starts the traversal
      * from the root of the binary tree. The function returns the leftmost node found during the traversal. If no leftmost
      * node is found (
      */
-    getLeftMost(node: N): N;
-    /**
-     * The `getRightMost` function returns the rightmost node in a binary tree, either recursively or iteratively using tail
-     * recursion optimization.
-     * @returns The `getRightMost` function returns the rightmost node in a binary tree. It returns the
-     * rightmost node starting from the root of the binary tree.
-     */
-    getRightMost(): N | null;
+    getLeftMost(beginRoot?: N | BinaryTreeNodeKey | null): N | null;
     /**
      * The `getRightMost` function returns the rightmost node in a binary tree, either recursively or iteratively using tail
      * recursion optimization.
      * @param {N | null} [beginRoot] - The `node` parameter is an optional parameter of type `N` or `null`. It represents the
      * starting node from which we want to find the rightmost node. If no node is provided, the function will default to
      * using the root node of the data structure.
-     * @returns The `getRightMost` function returns the rightmost node in a binary tree. It returns the rightmost node
-     * starting from that node.
+     * @returns The `getRightMost` function returns the rightmost node in a binary tree. If the `node` parameter is provided,
+     * it returns the rightmost node starting from that node. If the `node` parameter is not provided, it returns the
+     * rightmost node starting from the root of the binary tree.
      */
-    getRightMost(beginRoot: N): N;
+    getRightMost(beginRoot?: N | null): N | null;
     /**
      * The function checks if a binary search tree is valid by traversing it either recursively or iteratively.
      * @param {N | null} subTreeRoot - The `node` parameter represents the root node of a binary search tree (BST).
@@ -247,111 +229,31 @@ export declare class BinaryTree<N extends BinaryTreeNode<N['val'], N> = BinaryTr
      */
     isBST(): boolean;
     /**
-     * The function calculates the size of a subtree by traversing it either recursively or iteratively.
-     * @param {N | null | undefined} subTreeRoot - The `subTreeRoot` parameter represents the root node of a subtree in a
-     * binary tree.
-     * @returns the size of the subtree rooted at `subTreeRoot`.
-     */
-    getSubTreeSize(subTreeRoot: N | null | undefined): number;
-    /**
-     * The function `subTreeForeach` adds a delta value to a specified property of each node in a subtree.
+     * The function `subTreeTraverse` adds a delta value to a specified property of each node in a subtree.
      * @param {N | BinaryTreeNodeKey | null} subTreeRoot - The `subTreeRoot` parameter represents the root node of a binary
      * tree or the ID of a node in the binary tree. It can also be `null` if there is no subtree to add to.
      * @param callback - The `callback` parameter is a function that takes a node as a parameter and returns a value.
      * specifies the property of the binary tree node that should be modified. If not provided, it defaults to 'key'.
      * @returns a boolean value.
      */
-    subTreeForeach(subTreeRoot: N | BinaryTreeNodeKey | null, callback: (node: N) => any): boolean;
-    /**
-     * Performs a breadth-first search (bfs) on a binary tree, accumulating properties of each node based on their 'key' property.
-     * @returns An array of binary tree node IDs.
-     */
-    bfs(): BinaryTreeNodeKey[];
-    /**
-     * Performs a breadth-first search (bfs) on a binary tree, accumulating properties of each node based on the specified property name.
-     * @param {'key'} nodeOrPropertyName - The name of the property to accumulate.
-     * @returns An array of values corresponding to the specified property.
-     */
-    bfs(nodeOrPropertyName: 'key'): BinaryTreeNodeKey[];
-    /**
-     * Performs a breadth-first search (bfs) on a binary tree, accumulating the 'val' property of each node.
-     * @param {'val'} nodeOrPropertyName - The name of the property to accumulate.
-     * @returns An array of 'val' properties from each node.
-     */
-    bfs(nodeOrPropertyName: 'val'): N['val'][];
-    /**
-     * Performs a breadth-first search (bfs) on a binary tree, accumulating nodes themselves.
-     * @param {'node'} nodeOrPropertyName - The name of the property to accumulate.
-     * @returns An array of binary tree nodes.
-     */
-    bfs(nodeOrPropertyName: 'node'): N[];
-    /**
-     * Performs a depth-first search (dfs) traversal on a binary tree and accumulates properties of each node based on their 'key' property.
-     * @returns An array of binary tree node IDs.
-     */
-    dfs(): BinaryTreeNodeKey[];
-    /**
-     * Performs a depth-first search (dfs) traversal on a binary tree and accumulates properties of each node based on the specified property name.
-     * @param {'in' | 'pre' | 'post'} [pattern] - The traversal pattern: 'in' (in-order), 'pre' (pre-order), or 'post' (post-order).
-     * @returns An array of values corresponding to the specified property.
-     */
-    dfs(pattern: DFSOrderPattern): BinaryTreeNodeKey[];
-    /**
-     * Performs a depth-first search (dfs) traversal on a binary tree and accumulates properties of each node based on the specified property name.
-     * @param {'in' | 'pre' | 'post'} [pattern] - The traversal pattern: 'in' (in-order), 'pre' (pre-order), or 'post' (post-order).
-     * @param {string} nodeOrPropertyName - The name of the property to accumulate.
-     * @param loopType - The type of loop to use for the depth-first search traversal. The default value is `LoopType.ITERATIVE`.
-     * @returns An array of values corresponding to the specified property.
-     */
-    dfs(pattern: DFSOrderPattern, nodeOrPropertyName: 'key', loopType?: LoopType): BinaryTreeNodeKey[];
+    subTreeTraverse(callback?: MapCallback<N>, subTreeRoot?: N | BinaryTreeNodeKey | null): MapCallbackReturn<N>[];
     /**
-     * Performs a depth-first search (dfs) traversal on a binary tree and accumulates the 'val' property of each node.
+     * The dfs function performs a depth-first search traversal on a binary tree and returns the accumulated properties of
+     * each node based on the specified pattern and property name.
+     * @param callback
+     * @param beginRoot - The `beginRoot` parameter is an optional parameter of type `N` or `null`. It represents the
      * @param {'in' | 'pre' | 'post'} [pattern] - The traversal pattern: 'in' (in-order), 'pre' (pre-order), or 'post' (post-order).
-     * @param {'val'} nodeOrPropertyName - The name of the property to accumulate.
      * @param loopType - The type of loop to use for the depth-first search traversal. The default value is `LoopType.ITERATIVE`.
-     * @returns An array of 'val' properties from each node.
-     */
-    dfs(pattern: DFSOrderPattern, nodeOrPropertyName: 'val', loopType?: LoopType): N[];
-    /**
-     * Performs a depth-first search (dfs) traversal on a binary tree and accumulates nodes themselves.
-     * @param {'in' | 'pre' | 'post'} [pattern] - The traversal pattern: 'in' (in-order), 'pre' (pre-order), or 'post' (post-order).
-     * @param {'node'} nodeOrPropertyName - The name of the property to accumulate.
-     * @param loopType - The type of loop to use for the depth-first search traversal. The default value is `LoopType.ITERATIVE`.
-     * @returns An array of binary tree nodes.
-     */
-    dfs(pattern: DFSOrderPattern, nodeOrPropertyName: 'node', loopType?: LoopType): N[];
-    /**
-     * Collects nodes from a binary tree by a specified property and organizes them into levels.
-     * @returns A 2D array of AbstractBinaryTreeNodeProperty<N> objects.
-     */
-    listLevels(): BinaryTreeNodeKey[][];
-    /**
-     * Collects nodes from a binary tree by a specified property and organizes them into levels.
-     * @param {N | null} node - The root node of the binary tree or null. If null, the function will use the root node of the current binary tree instance.
-     * @returns A 2D array of AbstractBinaryTreeNodeProperty<N> objects.
-     */
-    listLevels(node: N | null): BinaryTreeNodeKey[][];
-    /**
-     * Collects nodes from a binary tree by a specified property and organizes them into levels.
-     * @param {N | null} node - The root node of the binary tree or null. If null, the function will use the root node of the current binary tree instance.
-     * @param {'key} nodeOrPropertyName - The property of the BinaryTreeNode object to collect at each level.
-     * @returns A 2D array of values corresponding to the specified property.
-     */
-    listLevels(node: N | null, nodeOrPropertyName: 'key'): BinaryTreeNodeKey[][];
-    /**
-     * Collects nodes from a binary tree by a specified property and organizes them into levels.
-     * @param {N | null} node - The root node of the binary tree or null. If null, the function will use the root node of the current binary tree instance.
-     * @param {'val'} nodeOrPropertyName - The property of the BinaryTreeNode object to collect at each level.
-     * @returns A 2D array of 'val' properties from each node.
+     * @returns an instance of the BinaryTreeNodeProperties class, which contains the accumulated properties of the binary tree nodes based on the specified pattern and node or property name.
      */
-    listLevels(node: N | null, nodeOrPropertyName: 'val'): N['val'][][];
+    dfs(callback?: MapCallback<N>, pattern?: DFSOrderPattern, beginRoot?: N | null, loopType?: LoopType): MapCallbackReturn<N>[];
     /**
-     * Collects nodes from a binary tree by a specified property and organizes them into levels.
-     * @param {N | null} node - The root node of the binary tree or null. If null, the function will use the root node of the current binary tree instance.
-     * @param {'node'} nodeOrPropertyName - The property of the BinaryTreeNode object to collect at each level.
-     * @returns A 2D array of binary tree nodes.
+     * The `listLevels` function collects nodes from a binary tree by a specified property and organizes them into levels.
+     * @param {N | null} node - The `node` parameter is a BinaryTreeNode object or null. It represents the root node of a binary tree. If it is null, the function will use the root node of the current binary tree instance.
+     * @param callback - The `callback` parameter is a function that takes a node and a level as parameters and returns a value.
+     * @param withLevel - The `withLevel` parameter is a boolean flag that determines whether to include the level of each node in the result. If `withLevel` is set to `true`, the function will include the level of each node in the result. If `withLevel` is set to `false` or not provided, the function will not include the level of each node in the result.
      */
-    listLevels(node: N | null, nodeOrPropertyName: 'node'): N[][];
+    bfs(callback?: BFSCallback<N>, withLevel?: boolean, node?: N | null): BFSCallbackReturn<N>[];
     /**
      * The function returns the predecessor of a given node in a binary tree.
      * @param node - The parameter `node` is a BinaryTreeNode object, representing a node in a binary tree.
@@ -363,37 +265,12 @@ export declare class BinaryTree<N extends BinaryTreeNode<N['val'], N> = BinaryTr
      * Space complexity of Iterative dfs equals to recursive dfs which is O(n) because of the stack
      */
     /**
-     * Performs an in-order, pre-order, or post-order traversal on a binary tree using the Morris traversal algorithm.
-     * @returns An array of binary tree node IDs.
-     */
-    morris(): BinaryTreeNodeKey[];
-    /**
-     * Performs an in-order, pre-order, or post-order traversal on a binary tree using the Morris traversal algorithm and accumulates properties of each node based on the specified property name.
-     * @param {'in' | 'pre' | 'post'} [pattern] - The traversal pattern: 'in' (in-order), 'pre' (pre-order), or 'post' (post-order).
-     * @param {'key'} nodeOrPropertyName - The name of the property to accumulate.
-     * @returns An array of values corresponding to the specified property.
-     */
-    morris(pattern: DFSOrderPattern, nodeOrPropertyName: 'key'): BinaryTreeNodeKey[];
-    /**
-     * Performs an in-order, pre-order, or post-order traversal on a binary tree using the Morris traversal algorithm and accumulates properties of each node based on the specified property name.
+     * The `morris` function performs an in-order, pre-order, or post-order traversal on a binary tree using the Morris traversal algorithm.
      * @param {'in' | 'pre' | 'post'} [pattern] - The traversal pattern: 'in' (in-order), 'pre' (pre-order), or 'post' (post-order).
-     * @returns An array of values corresponding to the specified property.
+     * @param callback  - The `callback` parameter is a function that takes a node as a parameter and returns a value.
+     * @returns An array of BinaryTreeNodeProperties<N> objects.
      */
-    morris(pattern: DFSOrderPattern): BinaryTreeNodeKey[];
-    /**
-     * Performs an in-order, pre-order, or post-order traversal on a binary tree using the Morris traversal algorithm and accumulates the 'val' property of each node.
-     * @param {'in' | 'pre' | 'post'} [pattern] - The traversal pattern: 'in' (in-order), 'pre' (pre-order), or 'post' (post-order).
-     * @param {'val'} nodeOrPropertyName - The property of the BinaryTreeNode object to collect at each level.
-     * @returns An array of 'val' properties from each node.
-     */
-    morris(pattern: DFSOrderPattern, nodeOrPropertyName: 'val'): N[];
-    /**
-     * Performs an in-order, pre-order, or post-order traversal on a binary tree using the Morris traversal algorithm and accumulates nodes themselves.
-     * @param {'in' | 'pre' | 'post'} [pattern] - The traversal pattern: 'in' (in-order), 'pre' (pre-order), or 'post' (post-order).
-     * @param {'node'} nodeOrPropertyName - The property of the BinaryTreeNode object to collect at each level.
-     * @returns An array of binary tree nodes.
-     */
-    morris(pattern: DFSOrderPattern, nodeOrPropertyName: 'node'): N[];
+    morris(callback?: MapCallback<N>, pattern?: DFSOrderPattern): MapCallbackReturn<N>[];
     /**
      * The function adds a new node to a binary tree if there is an available position.
      * @param {N | null} newNode - The `newNode` parameter is of type `N | null`, which means it can either be a node of
@@ -416,45 +293,4 @@ export declare class BinaryTree<N extends BinaryTreeNode<N['val'], N> = BinaryTr
      * @param {number} v - number
      */
     protected _setSize(v: number): void;
-    /**
-     * The function `_clearResults` resets the values of several arrays used for tracking visited nodes and their
-     * properties.
-     */
-    protected _clearResults(): void;
-    /**
-     * The function checks if a given property of a binary tree node matches a specified value, and if so, adds the node to
-     * a result array.
-     * @param {N} cur - The current node being processed.
-     * @param {(N | null | undefined)[]} result - An array that stores the matching nodes.
-     * @param {BinaryTreeNodeKey | N} nodeProperty - The `nodeProperty` parameter is either a `BinaryTreeNodeKey` or a `N`
-     * type. It represents the property value that we are comparing against in the switch statement.
-     * @param {BinaryTreeNodePropertyName} [propertyName] - The `propertyName` parameter is an optional parameter that
-     * specifies the property name to compare against when pushing nodes into the `result` array. It can be either `'key'`
-     * or `'val'`. If it is not provided or is not equal to `'key'` or `'val'`, the
-     * @param {boolean} [onlyOne] - The `onlyOne` parameter is an optional boolean parameter that determines whether to
-     * stop after finding the first matching node or continue searching for all matching nodes. If `onlyOne` is set to
-     * `true`, the function will stop after finding the first matching node and return `true`. If `onlyOne
-     * @returns a boolean value indicating whether only one matching node should be pushed into the result array.
-     */
-    protected _pushByPropertyNameStopOrNot(cur: N, result: (N | null | undefined)[], nodeProperty: BinaryTreeNodeKey | N, propertyName?: BinaryTreeNodePropertyName, onlyOne?: boolean): boolean | undefined;
-    /**
-     * The function `_accumulatedByPropertyName` accumulates values from a given node based on the specified property name.
-     * @param {N} node - The `node` parameter is of type `N`, which represents a node in a data structure.
-     * @param {NodeOrPropertyName} [nodeOrPropertyName] - The `nodeOrPropertyName` parameter is an optional parameter that
-     * can be either a string representing a property name or a reference to a `Node` object. If it is a string, it
-     * specifies the property name to be used for accumulating values. If it is a `Node` object, it specifies
-     */
-    protected _accumulatedByPropertyName(node: N, nodeOrPropertyName?: NodeOrPropertyName): void;
-    /**
-     * The time complexity of Morris traversal is O(n), it may slower than others
-     * The space complexity  Morris traversal is O(1) because no using stack
-     */
-    /**
-     * The function `_getResultByPropertyName` returns the corresponding property value based on the given node or property
-     * name.
-     * @param {NodeOrPropertyName} [nodeOrPropertyName] - The parameter `nodeOrPropertyName` is an optional parameter that
-     * can accept either a `NodeOrPropertyName` type or be undefined.
-     * @returns The method `_getResultByPropertyName` returns an instance of `BinaryTreeNodeProperties<N>`.
-     */
-    protected _getResultByPropertyName(nodeOrPropertyName?: NodeOrPropertyName): BinaryTreeNodeProperties<N>;
 }