data-structure-typed 0.8.18 → 1.12.9

package/src/data-structures/binary-tree/binary-tree.ts

@@ -1,25 +1,32 @@
-import {ThunkOrValue, trampoline} from '../trampoline';
-
-export type BinaryTreeNodePropertyName = 'id' | 'val' | 'count';
-export type NodeOrPropertyName = 'node' | BinaryTreeNodePropertyName;
-export type DFSOrderPattern = 'in' | 'pre' | 'post';
-export type BinaryTreeNodeId = number;
-export type BinaryTreeDeleted<T> = { deleted: BinaryTreeNode<T> | null | undefined, needBalanced: BinaryTreeNode<T> | null };
-export type ResultByProperty<T> = T | BinaryTreeNode<T> | number | BinaryTreeNodeId;
-export type ResultsByProperty<T> = ResultByProperty<T>[];
-
-export interface BinaryTreeNodeObj<T> {
-    id: BinaryTreeNodeId;
-    val: T;
-    count?: number;
-}
+/**
+ * @copyright 2030 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT
+ */
+
+import {trampoline} from '../../utils/trampoline';
+import type {
+    BinaryTreeDeleted,
+    BinaryTreeNodeId,
+    BinaryTreeNodePropertyName,
+    DFSOrderPattern,
+    NodeOrPropertyName,
+    ResultByProperty,
+    ResultsByProperty
+} from '../types';
 
 export enum FamilyPosition {root, left, right}
 
 export enum LoopType { iterative = 1, recursive = 2}
 
 export class BinaryTreeNode<T> {
+    constructor(id: BinaryTreeNodeId, val: T, count?: number) {
+        this._id = id;
+        this._val = val;
+        this._count = count ?? 1;
+    }
+
     protected _id: BinaryTreeNodeId;
+
     get id(): BinaryTreeNodeId {
         return this._id;
     }
@@ -29,6 +36,7 @@ export class BinaryTreeNode<T> {
     }
 
     protected _val: T;
+
     get val(): T {
         return this._val;
     }
@@ -38,6 +46,7 @@ export class BinaryTreeNode<T> {
     }
 
     protected _left?: BinaryTreeNode<T> | null;
+
     get left(): BinaryTreeNode<T> | null | undefined {
         return this._left;
     }
@@ -51,6 +60,7 @@ export class BinaryTreeNode<T> {
     }
 
     protected _right?: BinaryTreeNode<T> | null;
+
     get right(): BinaryTreeNode<T> | null | undefined {
         return this._right;
     }
@@ -63,7 +73,8 @@ export class BinaryTreeNode<T> {
         this._right = v;
     }
 
-    protected _parent: BinaryTreeNode<T> | null | undefined = undefined;
+    protected _parent: BinaryTreeNode<T> | null | undefined;
+
     get parent(): BinaryTreeNode<T> | null | undefined {
         return this._parent;
     }
@@ -73,6 +84,7 @@ export class BinaryTreeNode<T> {
     }
 
     protected _familyPosition: FamilyPosition = FamilyPosition.root;
+
     get familyPosition(): FamilyPosition {
         return this._familyPosition;
     }
@@ -82,6 +94,7 @@ export class BinaryTreeNode<T> {
     }
 
     protected _count = 1;
+
     get count(): number {
         return this._count;
     }
@@ -100,12 +113,6 @@ export class BinaryTreeNode<T> {
         this._height = v;
     }
 
-    constructor(id: BinaryTreeNodeId, val: T, count?: number) {
-        this._id = id;
-        this._val = val;
-        this._count = count ?? 1;
-    }
-
     swapLocation(swapNode: BinaryTreeNode<T>): BinaryTreeNode<T> {
         const {val, count, height} = swapNode;
         const tempNode = new BinaryTreeNode<T>(swapNode.id, val);
@@ -131,8 +138,41 @@ export class BinaryTreeNode<T> {
 }
 
 export class BinaryTree<T> {
+    protected _loopType: LoopType = LoopType.iterative;
+    protected _visitedId: BinaryTreeNodeId[] = [];
+    protected _visitedVal: Array<T> = [];
+    protected _visitedNode: BinaryTreeNode<T>[] = [];
+    protected _visitedCount: number[] = [];
+    protected _visitedLeftSum: number[] = [];
+    private readonly _autoIncrementId: boolean = false;
+    private _maxId: number = -1;
+    private readonly _isDuplicatedVal: boolean = false;
+
+    /**
+     * The constructor function accepts an optional options object and sets the values of loopType, autoIncrementId, and
+     * isDuplicatedVal based on the provided options.
+     * @param [options] - An optional object that can contain the following properties:
+     */
+    constructor(options?: {
+        loopType?: LoopType,
+        autoIncrementId?: boolean,
+        isDuplicatedVal?: boolean
+    }) {
+        if (options !== undefined) {
+            const {
+                loopType = LoopType.iterative,
+                autoIncrementId = false,
+                isDuplicatedVal = false
+            } = options;
+            this._isDuplicatedVal = isDuplicatedVal;
+            this._autoIncrementId = autoIncrementId;
+            this._loopType = loopType;
+        }
+    }
+
     protected _root: BinaryTreeNode<T> | null = null;
-    public get root(): BinaryTreeNode<T> | null {
+
+    get root(): BinaryTreeNode<T> | null {
         return this._root;
     }
 
@@ -145,6 +185,7 @@ export class BinaryTree<T> {
     }
 
     protected _size = 0;
+
     get size(): number {
         return this._size;
     }
@@ -154,6 +195,7 @@ export class BinaryTree<T> {
     }
 
     protected _count = 0;
+
     get count(): number {
         return this._count;
     }
@@ -162,46 +204,25 @@ export class BinaryTree<T> {
         this._count = v;
     }
 
-    private readonly _autoIncrementId: boolean = false;
-    private _maxId: number = -1;
-    private readonly _isDuplicatedVal: boolean = false;
-
-    protected _loopType: LoopType = LoopType.iterative;
-    protected _visitedId: BinaryTreeNodeId[] = [];
-    protected _visitedVal: Array<T> = [];
-    protected _visitedNode: BinaryTreeNode<T>[] = [];
-    protected _visitedCount: number[] = [];
-    protected _visitedLeftSum: number[] = [];
-
-    protected _resetResults() {
-        this._visitedId = [];
-        this._visitedVal = [];
-        this._visitedNode = [];
-        this._visitedCount = [];
-        this._visitedLeftSum = [];
-    }
-
-    constructor(options?: {
-        loopType?: LoopType,
-        autoIncrementId?: boolean,
-        isDuplicatedVal?: boolean
-    }) {
-        if (options !== undefined) {
-            const {
-                loopType = LoopType.iterative,
-                autoIncrementId = false,
-                isDuplicatedVal = false
-            } = options;
-            this._isDuplicatedVal = isDuplicatedVal;
-            this._autoIncrementId = autoIncrementId;
-            this._loopType = loopType;
-        }
-    }
-
+    /**
+     * The function creates a new binary tree node with the given id, value, and count, or returns null if the value is
+     * null.
+     * @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 | null} val - The `val` parameter represents the value to be stored in the binary tree node. It can be of
+     * any type `T` or `null`.
+     * @param {number} [count] - The count parameter is an optional parameter that represents the number of occurrences of
+     * the value in the binary tree node. It is of type number.
+     * @returns The function `createNode` returns a `BinaryTreeNode<T>` object if the `val` parameter is not null.
+     * Otherwise, it returns null.
+     */
     createNode(id: BinaryTreeNodeId, val: T | null, count?: number): BinaryTreeNode<T> | null {
         return val !== null ? new BinaryTreeNode(id, val, count) : null;
     }
 
+    /**
+     * The clear function resets the state of an object by setting its properties to their initial values.
+     */
     clear() {
         this.root = null;
         this.size = 0;
@@ -209,11 +230,23 @@ export class BinaryTree<T> {
         this._maxId = -1;
     }
 
+    /**
+     * The function checks if the size of an object is equal to zero and returns a boolean value.
+     * @returns A boolean value indicating whether the size of the object is 0 or not.
+     */
     isEmpty(): boolean {
         return this.size === 0;
     }
 
-    insertTo({newNode, parent}: { newNode: BinaryTreeNode<T> | null, parent: BinaryTreeNode<T> }) {
+    /**
+     * The function inserts a new node into a binary tree as the left or right child of a given parent node.
+     * @param {BinaryTreeNode<T> | null} newNode - The `newNode` parameter is an instance of the `BinaryTreeNode` class or
+     * `null`. It represents the node that needs to be inserted into the binary tree.
+     * @param parent - The `parent` parameter is a BinaryTreeNode object representing the parent node to which the new node
+     * will be inserted as a child.
+     * @returns The method returns the newly inserted node, either as the left child or the right child of the parent node.
+     */
+    putTo(newNode: BinaryTreeNode<T> | null, parent: BinaryTreeNode<T> ) {
         if (parent) {
             if (parent.left === undefined) {
                 if (newNode) {
@@ -246,6 +279,17 @@ export class BinaryTree<T> {
         }
     }
 
+    /**
+     * The `put` function inserts a new node with a given ID and value into a binary tree, updating the count if the node
+     * already exists.
+     * @param {BinaryTreeNodeId} id - The id parameter is the identifier of the binary tree node. It is used to uniquely
+     * identify each node in the binary tree.
+     * @param {T} val - The value to be inserted into the binary tree.
+     * @param {number} [count] - The `count` parameter is an optional parameter that specifies the number of times the
+     * value should be inserted into the binary tree. If not provided, it defaults to 1.
+     * @returns The function `put` returns a `BinaryTreeNode<T>` object if a new node is inserted, or `null` if no new node
+     * is inserted, or `undefined` if the insertion fails.
+     */
     put(id: BinaryTreeNodeId, val: T, count?: number): BinaryTreeNode<T> | null | undefined {
         count = count ?? 1;
 
@@ -254,7 +298,7 @@ export class BinaryTree<T> {
             while (queue.length > 0) {
                 const cur = queue.shift();
                 if (cur) {
-                    const inserted = this.insertTo({newNode, parent: cur});
+                    const inserted = this.putTo(newNode, cur);
                     if (inserted !== undefined) return inserted;
                     if (cur.left) queue.push(cur.left);
                     if (cur.right) queue.push(cur.right);
@@ -288,6 +332,13 @@ export class BinaryTree<T> {
         return inserted;
     }
 
+    /**
+     * The `insertMany` function inserts multiple items into a binary tree and returns an array of the inserted nodes or
+     * null/undefined values.
+     * @param {T[] | BinaryTreeNode<T>[]} data - The `data` parameter can be either an array of elements of type `T` or an
+     * array of `BinaryTreeNode<T>` objects.
+     * @returns The function `insertMany` returns an array of `BinaryTreeNode<T>`, `null`, or `undefined` values.
+     */
     insertMany(data: T[] | BinaryTreeNode<T>[]): (BinaryTreeNode<T> | null | undefined)[] {
         const inserted: (BinaryTreeNode<T> | null | undefined)[] = [];
         const map: Map<T | BinaryTreeNode<T>, number> = new Map();
@@ -328,11 +379,29 @@ export class BinaryTree<T> {
         return inserted;
     }
 
+    /**
+     * The `fill` function clears the current data and inserts new data, returning a boolean indicating if the insertion
+     * was successful.
+     * @param {T[] | BinaryTreeNode<T>[]} data - The `data` parameter can be either an array of elements of type `T` or an
+     * array of `BinaryTreeNode<T>` objects.
+     * @returns The method is returning a boolean value.
+     */
     fill(data: T[] | BinaryTreeNode<T>[]): boolean {
         this.clear();
         return data.length === this.insertMany(data).length;
     }
 
+    /**
+     * The function removes a node from a binary tree and returns information about the deleted node.
+     * @param {BinaryTreeNodeId} id - The `id` parameter is the identifier of the binary tree node that you want to remove.
+     * It is of type `BinaryTreeNodeId`.
+     * @param {boolean} [ignoreCount] - The `ignoreCount` parameter is an optional boolean parameter that determines
+     * whether to ignore the count of the node being removed. If `ignoreCount` is set to `true`, the count of the node will
+     * not be decremented and the overall count of the binary tree will not be updated. If `
+     * @returns An array of objects is being returned. Each object in the array has two properties: "deleted" and
+     * "needBalanced". The "deleted" property contains the deleted node or undefined if no node was deleted. The
+     * "needBalanced" property is always null.
+     */
     remove(id: BinaryTreeNodeId, ignoreCount?: boolean): BinaryTreeDeleted<T>[] {
         const nodes = this.getNodes(id, 'id', true);
         let node: BinaryTreeNode<T> | null | undefined = nodes[0];
@@ -369,6 +438,12 @@ export class BinaryTree<T> {
         return [{deleted: node, needBalanced: null}];
     }
 
+    /**
+     * The function calculates the depth of a binary tree node by traversing its parent nodes.
+     * @param node - BinaryTreeNode<T> - This is the node for which we want to calculate the depth. It is a generic type,
+     * meaning it can represent any type of data that we want to store in the node.
+     * @returns The depth of the given binary tree node.
+     */
     getDepth(node: BinaryTreeNode<T>): number {
         let depth = 0;
         while (node.parent) {
@@ -378,6 +453,14 @@ export class BinaryTree<T> {
         return depth;
     }
 
+    /**
+     * The `getHeight` function calculates the maximum height of a binary tree using either a recursive or iterative
+     * approach.
+     * @param {BinaryTreeNode<T> | null} [beginRoot] - The `beginRoot` parameter is an optional parameter of type
+     * `BinaryTreeNode<T> | null`. It represents the starting node from which to calculate the height of the binary tree.
+     * If no value is provided for `beginRoot`, the function will use the `root` property of the class instance as
+     * @returns the height of the binary tree.
+     */
     getHeight(beginRoot?: BinaryTreeNode<T> | null): number {
         beginRoot = beginRoot ?? this.root;
         if (!beginRoot) return -1;
@@ -393,8 +476,8 @@ export class BinaryTree<T> {
             return _getMaxHeight(beginRoot);
         } else {
             const stack: BinaryTreeNode<T>[] = [];
-            let node: BinaryTreeNode<T> | null | undefined = beginRoot, last: BinaryTreeNode<T> | null = null,
-                depths: Map<BinaryTreeNode<T>, number> = new Map();
+            let node: BinaryTreeNode<T> | null | undefined = beginRoot, last: BinaryTreeNode<T> | null = null;
+            const depths: Map<BinaryTreeNode<T>, number> = new Map();
 
             while (stack.length > 0 || node) {
                 if (node) {
@@ -405,8 +488,8 @@ export class BinaryTree<T> {
                     if (!node.right || last === node.right) {
                         node = stack.pop();
                         if (node) {
-                            let leftHeight = node.left ? depths.get(node.left) ?? -1 : -1;
-                            let rightHeight = node.right ? depths.get(node.right) ?? -1 : -1;
+                            const leftHeight = node.left ? depths.get(node.left) ?? -1 : -1;
+                            const rightHeight = node.right ? depths.get(node.right) ?? -1 : -1;
                             depths.set(node, 1 + Math.max(leftHeight, rightHeight));
                             last = node;
                             node = null;
@@ -419,6 +502,14 @@ export class BinaryTree<T> {
         }
     }
 
+    /**
+     * The `getMinHeight` function calculates the minimum height of a binary tree using either a recursive or iterative
+     * approach.
+     * @param {BinaryTreeNode<T> | null} [beginRoot] - The `beginRoot` parameter is an optional parameter of type
+     * `BinaryTreeNode<T> | null`. It represents the starting node from which to calculate the minimum height of the binary
+     * tree. If no value is provided for `beginRoot`, the function will use the root node of the binary tree.
+     * @returns The function `getMinHeight` returns the minimum height of the binary tree.
+     */
     getMinHeight(beginRoot?: BinaryTreeNode<T> | null): number {
         beginRoot = beginRoot || this.root;
         if (!beginRoot) return -1;
@@ -435,8 +526,8 @@ export class BinaryTree<T> {
             return _getMinHeight(beginRoot);
         } else {
             const stack: BinaryTreeNode<T>[] = [];
-            let node: BinaryTreeNode<T> | null | undefined = beginRoot, last: BinaryTreeNode<T> | null = null,
-                depths: Map<BinaryTreeNode<T>, number> = new Map();
+            let node: BinaryTreeNode<T> | null | undefined = beginRoot, last: BinaryTreeNode<T> | null = null;
+            const depths: Map<BinaryTreeNode<T>, number> = new Map();
 
             while (stack.length > 0 || node) {
                 if (node) {
@@ -447,8 +538,8 @@ export class BinaryTree<T> {
                     if (!node.right || last === node.right) {
                         node = stack.pop();
                         if (node) {
-                            let leftMinHeight = node.left ? depths.get(node.left) ?? -1 : -1;
-                            let rightMinHeight = node.right ? depths.get(node.right) ?? -1 : -1;
+                            const leftMinHeight = node.left ? depths.get(node.left) ?? -1 : -1;
+                            const rightMinHeight = node.right ? depths.get(node.right) ?? -1 : -1;
                             depths.set(node, 1 + Math.min(leftMinHeight, rightMinHeight));
                             last = node;
                             node = null;
@@ -461,10 +552,28 @@ export class BinaryTree<T> {
         }
     }
 
+    /**
+     * The function checks if a binary tree is balanced by comparing the minimum height and the maximum height of the tree.
+     * @param {BinaryTreeNode<T> | null} [beginRoot] - The `beginRoot` parameter is the root node of a binary tree. It is
+     * of type `BinaryTreeNode<T> | null`, which means it can either be a `BinaryTreeNode` object or `null`.
+     * @returns The method is returning a boolean value.
+     */
     isBalanced(beginRoot?: BinaryTreeNode<T> | null): boolean {
         return (this.getMinHeight(beginRoot) + 1 >= this.getHeight(beginRoot));
     }
 
+    /**
+     * The function `getNodes` returns an array of binary tree nodes that match a given property value, with options for
+     * searching recursively or iteratively.
+     * @param {BinaryTreeNodeId | T} nodeProperty - The `nodeProperty` parameter can be either a `BinaryTreeNodeId` or a
+     * generic type `T`. 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 'id'.
+     * @param {boolean} [onlyOne] - The `onlyOne` parameter is an optional boolean parameter that determines whether to
+     * return only one node that matches the `nodeProperty` or `propertyName` criteria. If `onlyOne` is set to `true`, the
+     * function will stop traversing the tree and return the first matching node. If `
+     * @returns The function `getNodes` returns an array of `BinaryTreeNode<T> | null | undefined` objects.
+     */
     getNodes(nodeProperty: BinaryTreeNodeId | T, propertyName ?: BinaryTreeNodePropertyName, onlyOne ?: boolean) {
         if (!this.root) return [] as null[];
         propertyName = propertyName ?? 'id';
@@ -495,15 +604,40 @@ export class BinaryTree<T> {
         return result;
     }
 
+    /**
+     * The function checks if a binary tree node has a specific property or if any node in the tree has a specific
+     * property.
+     * @param {BinaryTreeNodeId | T} nodeProperty - The `nodeProperty` parameter can be either a `BinaryTreeNodeId` or a
+     * generic type `T`. It represents the property of a 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 check for in the nodes.
+     * @returns a boolean value.
+     */
     has(nodeProperty: BinaryTreeNodeId | T, propertyName ?: BinaryTreeNodePropertyName): boolean {
         return this.getNodes(nodeProperty, propertyName).length > 0;
     }
 
+    /**
+     * The function returns the first binary tree node that matches the given property name and value, or null if no match
+     * is found.
+     * @param {BinaryTreeNodeId | T} nodeProperty - The `nodeProperty` parameter can be either a `BinaryTreeNodeId` or a
+     * generic type `T`. 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 of the binary tree node to search for. If not provided, it defaults to `'id'`.
+     * @returns a BinaryTreeNode object or null.
+     */
     get(nodeProperty: BinaryTreeNodeId | T, propertyName ?: BinaryTreeNodePropertyName): BinaryTreeNode<T> | null {
         propertyName = propertyName ?? 'id';
         return this.getNodes(nodeProperty, propertyName, true)[0] ?? null;
     }
 
+    /**
+     * The function getPathToRoot returns an array of BinaryTreeNode objects representing the path from a given node to the
+     * root of a binary tree.
+     * @param node - The `node` parameter is a BinaryTreeNode object.
+     * @returns The function `getPathToRoot` returns an array of `BinaryTreeNode<T>` objects, representing the path from
+     * the given `node` to the root of the binary tree.
+     */
     getPathToRoot(node: BinaryTreeNode<T>): BinaryTreeNode<T>[] {
         const result: BinaryTreeNode<T>[] = [];
         while (node.parent) {
@@ -514,76 +648,18 @@ export class BinaryTree<T> {
         return result;
     }
 
-    protected _pushByPropertyNameStopOrNot(cur: BinaryTreeNode<T>, result: (BinaryTreeNode<T> | null | undefined)[], nodeProperty: BinaryTreeNodeId | T, propertyName ?: BinaryTreeNodePropertyName, onlyOne ?: boolean) {
-        switch (propertyName) {
-            case 'id':
-                if (cur.id === nodeProperty) {
-                    result.push(cur);
-                    return !!onlyOne;
-                }
-                break;
-            case 'count':
-                if (cur.count === nodeProperty) {
-                    result.push(cur);
-                    return !!onlyOne;
-                }
-                break;
-            case 'val':
-                if (cur.val === nodeProperty) {
-                    result.push(cur);
-                    return !!onlyOne;
-                }
-                break;
-            default:
-                if (cur.id === nodeProperty) {
-                    result.push(cur);
-                    return !!onlyOne;
-                }
-                break;
-        }
-    }
-
-    protected _accumulatedByPropertyName(node: BinaryTreeNode<T>, nodeOrPropertyName ?: NodeOrPropertyName) {
-        nodeOrPropertyName = nodeOrPropertyName ?? 'id';
-
-        switch (nodeOrPropertyName) {
-            case 'id':
-                this._visitedId.push(node.id);
-                break;
-            case 'val':
-                this._visitedVal.push(node.val);
-                break;
-            case 'node':
-                this._visitedNode.push(node);
-                break;
-            case 'count':
-                this._visitedCount.push(node.count);
-                break;
-            default:
-                this._visitedId.push(node.id);
-                break;
-        }
-    }
-
-    protected _getResultByPropertyName(nodeOrPropertyName ?: NodeOrPropertyName): ResultsByProperty<T> {
-        nodeOrPropertyName = nodeOrPropertyName ?? 'id';
-
-        switch (nodeOrPropertyName) {
-            case 'id':
-                return this._visitedId;
-            case 'val':
-                return this._visitedVal;
-            case 'node':
-                return this._visitedNode;
-            case 'count':
-                return this._visitedCount;
-            default:
-                return this._visitedId;
-        }
-    }
-
     getLeftMost(): BinaryTreeNode<T> | null;
+
     getLeftMost(node: BinaryTreeNode<T>): BinaryTreeNode<T>;
+
+    /**
+     * The `getLeftMost` function returns the leftmost node in a binary tree, either recursively or iteratively using tail
+     * recursion optimization.
+     * @param {BinaryTreeNode<T> | null} [node] - The `node` parameter is an optional parameter of type `BinaryTreeNode<T>
+     * | null`. It represents the starting node from which to find the leftmost node in a binary tree. If no node is
+     * provided, the function will use the root node of the binary tree.
+     * @returns The `getLeftMost` function returns the leftmost node in a binary tree.
+     */
     getLeftMost(node?: BinaryTreeNode<T> | null): BinaryTreeNode<T> | null {
         node = node ?? this.root;
         if (!node) return node;
@@ -598,7 +674,7 @@ export class BinaryTree<T> {
             return _traverse(node);
         } else {
             // Indirect implementation of iteration using tail recursion optimization
-            const _traverse = trampoline((cur: BinaryTreeNode<T>): ThunkOrValue<BinaryTreeNode<T> | null> => {
+            const _traverse = trampoline((cur: BinaryTreeNode<T>) => {
                 if (!cur.left) return cur;
                 return _traverse.cont(cur.left);
             });
@@ -608,7 +684,17 @@ export class BinaryTree<T> {
     }
 
     getRightMost(): BinaryTreeNode<T> | null;
+
     getRightMost(node: BinaryTreeNode<T>): BinaryTreeNode<T>;
+
+    /**
+     * The `getRightMost` function returns the rightmost node in a binary tree, either recursively or iteratively using
+     * tail recursion optimization.
+     * @param {BinaryTreeNode<T> | null} [node] - The `node` parameter is an optional parameter of type `BinaryTreeNode<T>
+     * | null`. It represents the starting node from which to find the rightmost node in a binary tree. If no node is
+     * provided, the function will use the root node of the binary tree.
+     * @returns The `getRightMost` function returns the rightmost node in a binary tree.
+     */
     getRightMost(node?: BinaryTreeNode<T> | null): BinaryTreeNode<T> | null {
         node = node ?? this.root;
         if (!node) return node;
@@ -622,7 +708,7 @@ export class BinaryTree<T> {
             return _traverse(node);
         } else {
             // Indirect implementation of iteration using tail recursion optimization
-            const _traverse = trampoline((cur: BinaryTreeNode<T>): ThunkOrValue<BinaryTreeNode<T> | null> => {
+            const _traverse = trampoline((cur: BinaryTreeNode<T>) => {
                 if (!cur.right) return cur;
                 return _traverse.cont(cur.right);
             });
@@ -632,6 +718,14 @@ export class BinaryTree<T> {
     }
 
     // --- start additional methods ---
+    /**
+     * The `isBST` function checks if a binary tree is a binary search tree.
+     * @param {BinaryTreeNode<T> | null} [node] - The `node` parameter is an optional parameter of type `BinaryTreeNode<T>
+     * | null`. It represents the root node of the binary search tree (BST) that we want to check for validity. If no node
+     * is provided, the function will default to using the root node of the BST instance that
+     * @returns The `isBST` function returns a boolean value. It returns `true` if the binary tree is a valid binary search
+     * tree, and `false` otherwise.
+     */
     isBST(node?: BinaryTreeNode<T> | null): boolean {
         node = node ?? this.root;
         if (!node) return true;
@@ -653,7 +747,7 @@ export class BinaryTree<T> {
                     curr = curr.left;
                 }
                 curr = stack.pop()!;
-                if (prev >= curr.id) return false;
+                if (!(curr) || prev >= curr.id) return false;
                 prev = curr.id;
                 curr = curr.right;
             }
@@ -661,6 +755,14 @@ export class BinaryTree<T> {
         }
     }
 
+    /**
+     * The function calculates the size and count of a subtree in a binary tree using either recursive or iterative
+     * traversal.
+     * @param {BinaryTreeNode<T> | null | undefined} subTreeRoot - The `subTreeRoot` parameter is the root node of a binary
+     * tree.
+     * @returns The function `getSubTreeSizeAndCount` returns an array `[number, number]`. The first element of the array
+     * represents the size of the subtree, and the second element represents the count of the nodes in the subtree.
+     */
     getSubTreeSizeAndCount(subTreeRoot: BinaryTreeNode<T> | null | undefined) {
         const res: [number, number] = [0, 0];
         if (!subTreeRoot) return res;
@@ -690,6 +792,16 @@ export class BinaryTree<T> {
         }
     }
 
+    /**
+     * The function `subTreeSum` calculates the sum of a specified property in a binary tree, either recursively or
+     * iteratively.
+     * @param subTreeRoot - The subTreeRoot parameter is the root node of the subtree for which you want to calculate the
+     * sum.
+     * @param {BinaryTreeNodePropertyName} [propertyName] - The `propertyName` parameter is an optional parameter that
+     * specifies the property of the `BinaryTreeNode` object to use for calculating the sum. If `propertyName` is not
+     * provided, it defaults to `'val'`.
+     * @returns a number, which is the sum of the values of the nodes in the subtree rooted at `subTreeRoot`.
+     */
     subTreeSum(subTreeRoot: BinaryTreeNode<T>, propertyName ?: BinaryTreeNodePropertyName): number {
         propertyName = propertyName ?? 'val';
         if (!subTreeRoot) return 0;
@@ -737,6 +849,15 @@ export class BinaryTree<T> {
         return sum;
     }
 
+    /**
+     * The function `subTreeAdd` adds a specified delta value to a property of each node in a binary tree.
+     * @param subTreeRoot - The `subTreeRoot` parameter is the root node of the subtree where the values will be modified.
+     * @param {number} delta - The `delta` parameter is a number that represents the amount by which the property value of
+     * each node in the subtree should be increased or decreased.
+     * @param {BinaryTreeNodePropertyName} [propertyName] - The `propertyName` parameter is an optional parameter that
+     * specifies the property of the `BinaryTreeNode` that should be modified. It defaults to `'id'` if not provided.
+     * @returns a boolean value, which is `true`.
+     */
     subTreeAdd(subTreeRoot: BinaryTreeNode<T>, delta: number, propertyName ?: BinaryTreeNodePropertyName): boolean {
         propertyName = propertyName ?? 'id';
         if (!subTreeRoot) return false;
@@ -779,10 +900,24 @@ export class BinaryTree<T> {
     }
 
     BFS(): BinaryTreeNodeId[];
+
     BFS(nodeOrPropertyName: 'id'): BinaryTreeNodeId[];
+
     BFS(nodeOrPropertyName: 'val'): T[];
+
     BFS(nodeOrPropertyName: 'node'): BinaryTreeNode<T>[];
+
     BFS(nodeOrPropertyName: 'count'): number[];
+
+    /**
+     * The BFS function performs a breadth-first search on a binary tree and returns the results based on a specified node
+     * or property name.
+     * @param {NodeOrPropertyName} [nodeOrPropertyName] - The parameter `nodeOrPropertyName` is an optional parameter that
+     * represents either a node or a property name. If a node is provided, the breadth-first search algorithm will be
+     * performed starting from that node. If a property name is provided, the breadth-first search algorithm will be
+     * performed starting from the root node
+     * @returns an object of type `ResultsByProperty<T>`.
+     */
     BFS(nodeOrPropertyName ?: NodeOrPropertyName): ResultsByProperty<T> {
         nodeOrPropertyName = nodeOrPropertyName ?? 'id';
         this._resetResults();
@@ -801,10 +936,27 @@ export class BinaryTree<T> {
     }
 
     DFS(): BinaryTreeNodeId[];
+
     DFS(pattern?: DFSOrderPattern, nodeOrPropertyName?: 'id'): BinaryTreeNodeId[];
+
     DFS(pattern?: DFSOrderPattern, nodeOrPropertyName?: 'val'): T[];
+
     DFS(pattern?: DFSOrderPattern, nodeOrPropertyName?: 'node'): BinaryTreeNode<T>[];
+
     DFS(pattern?: DFSOrderPattern, nodeOrPropertyName?: 'count'): number[];
+
+    /**
+     * The DFS function performs a depth-first search traversal on a binary tree and returns the results based on the
+     * specified pattern and node or property name.
+     * @param {'in' | 'pre' | 'post'} [pattern] - The "pattern" parameter is used to specify the order in which the nodes
+     * of a binary tree are traversed during the Depth-First Search (DFS) algorithm. It can take one of three values: 'in',
+     * 'pre', or 'post'.
+     * @param {NodeOrPropertyName} [nodeOrPropertyName] - The `nodeOrPropertyName` parameter is a string that represents
+     * either the name of a property in the `BinaryTreeNode` object or the value of the `id` property in the
+     * `BinaryTreeNode` object. This parameter is used to accumulate the results based on the specified property name. If
+     * no value
+     * @returns an object of type `ResultsByProperty<T>`.
+     */
     DFS(pattern ?: 'in' | 'pre' | 'post', nodeOrPropertyName ?: NodeOrPropertyName): ResultsByProperty<T> {
         pattern = pattern ?? 'in';
         nodeOrPropertyName = nodeOrPropertyName ?? 'id';
@@ -834,9 +986,13 @@ export class BinaryTree<T> {
     }
 
     DFSIterative(): BinaryTreeNodeId[];
+
     DFSIterative(pattern?: DFSOrderPattern, nodeOrPropertyName?: 'id'): BinaryTreeNodeId[];
+
     DFSIterative(pattern?: DFSOrderPattern, nodeOrPropertyName?: 'val'): T[];
+
     DFSIterative(pattern?: DFSOrderPattern, nodeOrPropertyName?: 'node'): BinaryTreeNode<T>[];
+
     DFSIterative(pattern?: DFSOrderPattern, nodeOrPropertyName?: 'count'): number[];
 
     /**
@@ -889,10 +1045,27 @@ export class BinaryTree<T> {
     }
 
     levelIterative(node: BinaryTreeNode<T> | null): BinaryTreeNodeId[];
+
     levelIterative(node: BinaryTreeNode<T> | null, nodeOrPropertyName?: 'id'): BinaryTreeNodeId[];
+
     levelIterative(node: BinaryTreeNode<T> | null, nodeOrPropertyName?: 'val'): T[];
+
     levelIterative(node: BinaryTreeNode<T> | null, nodeOrPropertyName?: 'node'): BinaryTreeNode<T>[];
+
     levelIterative(node: BinaryTreeNode<T> | null, nodeOrPropertyName?: 'count'): number[];
+
+    /**
+     * The `levelIterative` function performs a level-order traversal on a binary tree and returns the values of the nodes
+     * in an array, based on a specified property name.
+     * @param {BinaryTreeNode<T> | null} node - The `node` parameter is a BinaryTreeNode object representing the starting
+     * node for the level order traversal. It can be null if no specific node is provided, in which case the root node of
+     * the tree is used as the starting node.
+     * @param {NodeOrPropertyName} [nodeOrPropertyName] - The `nodeOrPropertyName` parameter is an optional parameter that
+     * can be either a `BinaryTreeNode` property name or the string `'id'`. If a property name is provided, the function
+     * will accumulate results based on that property. If no property name is provided, the function will default to
+     * accumulating results
+     * @returns The function `levelIterative` returns an object of type `ResultsByProperty<T>`.
+     */
     levelIterative(node: BinaryTreeNode<T> | null, nodeOrPropertyName ?: NodeOrPropertyName): ResultsByProperty<T> {
         nodeOrPropertyName = nodeOrPropertyName || 'id';
         node = node || this.root;
@@ -918,10 +1091,24 @@ export class BinaryTree<T> {
     }
 
     listLevels(node: BinaryTreeNode<T> | null): BinaryTreeNodeId[][];
+
     listLevels(node: BinaryTreeNode<T> | null, nodeOrPropertyName?: 'id'): BinaryTreeNodeId[][];
+
     listLevels(node: BinaryTreeNode<T> | null, nodeOrPropertyName?: 'val'): T[][];
+
     listLevels(node: BinaryTreeNode<T> | null, nodeOrPropertyName?: 'node'): BinaryTreeNode<T>[][];
+
     listLevels(node: BinaryTreeNode<T> | null, nodeOrPropertyName?: 'count'): number[][];
+
+    /**
+     * The `listLevels` function collects nodes from a binary tree by a specified property and organizes them into levels.
+     * @param {BinaryTreeNode<T> | 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 {NodeOrPropertyName} [nodeOrPropertyName] - The `nodeOrPropertyName` parameter is an optional parameter that
+     * specifies the property of the `BinaryTreeNode` object to collect at each level. It can be one of the following
+     * values:
+     * @returns The function `listLevels` returns a 2D array of `ResultByProperty<T>` objects.
+     */
     listLevels(node: BinaryTreeNode<T> | null, nodeOrPropertyName?: NodeOrPropertyName): ResultByProperty<T>[][] {
         nodeOrPropertyName = nodeOrPropertyName || 'id';
         node = node || this.root;
@@ -975,11 +1162,18 @@ export class BinaryTree<T> {
         return levelsNodes;
     }
 
+    /**
+     * 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.
+     * @returns the predecessor of the given node in a binary tree.
+     */
     getPredecessor(node: BinaryTreeNode<T>): BinaryTreeNode<T> {
         if (node.left) {
-            let predecessor: BinaryTreeNode<T> | null = node.left;
-            while (predecessor.right && predecessor.right !== node) {
-                predecessor = predecessor.right;
+            let predecessor: BinaryTreeNode<T> | null | undefined = node.left;
+            while (!(predecessor) || predecessor.right && predecessor.right !== node) {
+                if (predecessor) {
+                    predecessor = predecessor.right;
+                }
             }
             return predecessor;
         } else {
@@ -988,15 +1182,26 @@ export class BinaryTree<T> {
     }
 
     morris(): BinaryTreeNodeId[];
+
     morris(pattern?: DFSOrderPattern, nodeOrPropertyName?: 'id'): BinaryTreeNodeId[];
+
     morris(pattern?: DFSOrderPattern, nodeOrPropertyName?: 'val'): T[];
+
     morris(pattern?: DFSOrderPattern, nodeOrPropertyName?: 'node'): BinaryTreeNode<T>[];
+
     morris(pattern?: DFSOrderPattern, nodeOrPropertyName?: 'count'): number[];
+
     /**
+     * The `morris` function performs an in-order, pre-order, or post-order traversal on a binary tree using the Morris
+     * traversal algorithm and returns the results based on the specified property name.
      * The time complexity of Morris traversal is O(n), it's may slower than others
      * The space complexity  Morris traversal is O(1) because no using stack
-     * @param pattern
-     * @param nodeOrPropertyName
+     * @param {'in' | 'pre' | 'post'} [pattern] - The `pattern` parameter is an optional parameter that determines the
+     * traversal pattern of the binary tree. It can have one of three values:
+     * @param {NodeOrPropertyName} [nodeOrPropertyName] - The `nodeOrPropertyName` parameter is used to specify the
+     * property of the nodes that you want to retrieve in the results. It can be either the node itself or the name of the
+     * property. If not provided, it defaults to `'id'`.
+     * @returns The function `morris` returns an object of type `ResultsByProperty<T>`.
      */
     morris(pattern?: 'in' | 'pre' | 'post', nodeOrPropertyName?: NodeOrPropertyName): ResultsByProperty<T> {
         if (this.root === null) return [];
@@ -1084,5 +1289,115 @@ export class BinaryTree<T> {
         return this._getResultByPropertyName(nodeOrPropertyName);
     }
 
+    /**
+     * The function resets the values of several arrays used for tracking visited nodes and their properties.
+     */
+    protected _resetResults() {
+        this._visitedId = [];
+        this._visitedVal = [];
+        this._visitedNode = [];
+        this._visitedCount = [];
+        this._visitedLeftSum = [];
+    }
+
+    /**
+     * 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 cur - The current binary tree node that is being checked.
+     * @param {(BinaryTreeNode<T> | null | undefined)[]} result - An array that stores the matching nodes found during the
+     * traversal.
+     * @param {BinaryTreeNodeId | T} nodeProperty - The `nodeProperty` parameter is the value that we are searching for in
+     * the binary tree nodes. It can be either the `id`, `count`, or `val` property of the node.
+     * @param {BinaryTreeNodePropertyName} [propertyName] - The `propertyName` parameter is an optional parameter that
+     * specifies the property of the `BinaryTreeNode` object that you want to compare with the `nodeProperty` value. It can
+     * be one of the following values: 'id', 'count', or 'val'. If no `propertyName` is provided,
+     * @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 or not a node was pushed into the result array.
+     */
+    protected _pushByPropertyNameStopOrNot(cur: BinaryTreeNode<T>, result: (BinaryTreeNode<T> | null | undefined)[], nodeProperty: BinaryTreeNodeId | T, propertyName ?: BinaryTreeNodePropertyName, onlyOne ?: boolean) {
+        switch (propertyName) {
+            case 'id':
+                if (cur.id === nodeProperty) {
+                    result.push(cur);
+                    return !!onlyOne;
+                }
+                break;
+            case 'count':
+                if (cur.count === nodeProperty) {
+                    result.push(cur);
+                    return !!onlyOne;
+                }
+                break;
+            case 'val':
+                if (cur.val === nodeProperty) {
+                    result.push(cur);
+                    return !!onlyOne;
+                }
+                break;
+            default:
+                if (cur.id === nodeProperty) {
+                    result.push(cur);
+                    return !!onlyOne;
+                }
+                break;
+        }
+    }
+
+    /**
+     * The function `_accumulatedByPropertyName` pushes a property value of a binary tree node into an array based on the
+     * provided property name or a default property name.
+     * @param node - The `node` parameter is of type `BinaryTreeNode<T>`, which represents a node in a binary tree.
+     * @param {NodeOrPropertyName} [nodeOrPropertyName] - The parameter `nodeOrPropertyName` 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 of the node that should be accumulated. If it is a node object, it specifies the node itself
+     */
+    protected _accumulatedByPropertyName(node: BinaryTreeNode<T>, nodeOrPropertyName ?: NodeOrPropertyName) {
+        nodeOrPropertyName = nodeOrPropertyName ?? 'id';
+
+        switch (nodeOrPropertyName) {
+            case 'id':
+                this._visitedId.push(node.id);
+                break;
+            case 'val':
+                this._visitedVal.push(node.val);
+                break;
+            case 'node':
+                this._visitedNode.push(node);
+                break;
+            case 'count':
+                this._visitedCount.push(node.count);
+                break;
+            default:
+                this._visitedId.push(node.id);
+                break;
+        }
+    }
+
+    /**
+     * The function `_getResultByPropertyName` returns different results based on the provided property name or defaulting
+     * to 'id'.
+     * @param {NodeOrPropertyName} [nodeOrPropertyName] - The parameter `nodeOrPropertyName` is an optional parameter that
+     * can accept a value of type `NodeOrPropertyName`.
+     * @returns The method returns an object of type `ResultsByProperty<T>`.
+     */
+    protected _getResultByPropertyName(nodeOrPropertyName ?: NodeOrPropertyName): ResultsByProperty<T> {
+        nodeOrPropertyName = nodeOrPropertyName ?? 'id';
+
+        switch (nodeOrPropertyName) {
+            case 'id':
+                return this._visitedId;
+            case 'val':
+                return this._visitedVal;
+            case 'node':
+                return this._visitedNode;
+            case 'count':
+                return this._visitedCount;
+            default:
+                return this._visitedId;
+        }
+    }
+
     // --- end additional methods ---
 }