red-black-tree-typed 1.53.7 → 1.54.2

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

@@ -7,50 +7,55 @@
  */
 import { BST, BSTNode } from './bst';
 import type {
-  AVLTreeNested,
-  AVLTreeNodeNested,
   AVLTreeOptions,
   BinaryTreeDeleteResult,
   BSTNOptKeyOrNode,
-  BTNRep
+  BTNRep,
+  EntryCallback,
+  OptNodeOrNull
 } from '../../types';
 import { IBinaryTree } from '../../interfaces';
 
-export class AVLTreeNode<
-  K = any,
-  V = any,
-  NODE extends AVLTreeNode<K, V, NODE> = AVLTreeNodeNested<K, V>
-> extends BSTNode<K, V, NODE> {
+export class AVLTreeNode<K = any, V = any> extends BSTNode<K, V> {
   /**
-   * The constructor function initializes a new instance of a class with a key and an optional value,
-   * and sets the height property to 0.
-   * @param {K} key - The "key" parameter is of type K, which represents the type of the key for the
-   * constructor. It is used to initialize the key property of the object 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 constructor.
+   * This TypeScript constructor function initializes an instance with a key and an optional value.
+   * @param {K} key - The `key` parameter is typically used to uniquely identify an object or element
+   * within a data structure. It serves as a reference or identifier for accessing or manipulating the
+   * associated value or data.
+   * @param {V} [value] - The `value` parameter in the constructor is optional, meaning it does not
+   * have to be provided when creating an instance of the class. If a value is not provided, it will
+   * default to `undefined`.
    */
   constructor(key: K, value?: V) {
     super(key, value);
-    this._height = 0;
   }
 
-  protected _height: number;
+  override parent?: AVLTreeNode<K, V> = undefined;
 
-  /**
-   * The function returns the value of the height property.
-   * @returns The height of the object.
-   */
-  get height(): number {
-    return this._height;
+  override _left?: OptNodeOrNull<AVLTreeNode<K, V>> = undefined;
+
+  override get left(): OptNodeOrNull<AVLTreeNode<K, V>> {
+    return this._left;
   }
 
-  /**
-   * The above function sets the value of the height property.
-   * @param {number} value - The value parameter is a number that represents the new height value to be
-   * set.
-   */
-  set height(value: number) {
-    this._height = value;
+  override set left(v: OptNodeOrNull<AVLTreeNode<K, V>>) {
+    if (v) {
+      v.parent = this;
+    }
+    this._left = v;
+  }
+
+  override _right?: OptNodeOrNull<AVLTreeNode<K, V>> = undefined;
+
+  override get right(): OptNodeOrNull<AVLTreeNode<K, V>> {
+    return this._right;
+  }
+
+  override set right(v: OptNodeOrNull<AVLTreeNode<K, V>>) {
+    if (v) {
+      v.parent = this;
+    }
+    this._right = v;
   }
 }
 
@@ -63,109 +68,114 @@ export class AVLTreeNode<
  * 6. Complex Insertions and Deletions: Due to rebalancing, these operations are more complex than in a regular BST.
  * 7. Path Length: The path length from the root to any leaf is longer compared to an unbalanced BST, but shorter than a linear chain of nodes.
  */
-export class AVLTree<
-    K = any,
-    V = any,
-    R = object,
-    NODE extends AVLTreeNode<K, V, NODE> = AVLTreeNode<K, V, AVLTreeNodeNested<K, V>>,
-    TREE extends AVLTree<K, V, R, NODE, TREE> = AVLTree<K, V, R, NODE, AVLTreeNested<K, V, R, NODE>>
-  >
-  extends BST<K, V, R, NODE, TREE>
-  implements IBinaryTree<K, V, R, NODE, TREE>
+export class AVLTree<K = any, V = any, R = object, MK = any, MV = any, MR = object>
+  extends BST<K, V, R, MK, MV, MR>
+  implements IBinaryTree<K, V, R, MK, MV, MR>
 {
   /**
-   * This is a constructor function for an AVLTree class that initializes the tree with keys, nodes,
-   * entries, or raw elements.
-   * @param keysNodesEntriesOrRaws - The `keysNodesEntriesOrRaws` parameter is an
-   * iterable object that can contain either keys, nodes, entries, or raw elements. These elements will
-   * be used to initialize the AVLTree.
-   * @param [options] - The `options` parameter is an optional object that can be used to customize the
-   * behavior of the AVLTree. It can include properties such as `compareFn` (a function used to compare
-   * keys), `allowDuplicates` (a boolean indicating whether duplicate keys are allowed), and
-   * `nodeBuilder` (
+   * This TypeScript constructor initializes an AVLTree with keys, nodes, entries, or raw data provided
+   * in an iterable format.
+   * @param keysNodesEntriesOrRaws - The `keysNodesEntriesOrRaws` parameter in the constructor is an
+   * iterable that can contain either `BTNRep<K, V, AVLTreeNode<K, V>>` objects or `R` objects. It is
+   * used to initialize the AVLTree with key-value pairs or raw data entries. If provided
+   * @param [options] - The `options` parameter in the constructor is of type `AVLTreeOptions<K, V,
+   * R>`. It is an optional parameter that allows you to specify additional options for configuring the
+   * AVL tree. These options could include things like custom comparators, initial capacity, or any
+   * other configuration settings specific
    */
-  constructor(keysNodesEntriesOrRaws: Iterable<R | BTNRep<K, V, NODE>> = [], options?: AVLTreeOptions<K, V, R>) {
+  constructor(
+    keysNodesEntriesOrRaws: Iterable<BTNRep<K, V, AVLTreeNode<K, V>> | R> = [],
+    options?: AVLTreeOptions<K, V, R>
+  ) {
     super([], options);
     if (keysNodesEntriesOrRaws) super.addMany(keysNodesEntriesOrRaws);
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The function creates a new AVL tree node with the given key and value.
    * @param {K} key - The key parameter is of type K, which represents the key of 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 AVLTreeNode class, casted as the generic
-   * type NODE.
+   * type AVLTreeNode<K, V>.
    */
-  override createNode(key: K, value?: V): NODE {
-    return new AVLTreeNode<K, V, NODE>(key, this._isMapMode ? undefined : value) as NODE;
+  override createNode(key: K, value?: V): AVLTreeNode<K, V> {
+    return new AVLTreeNode<K, V>(key, this._isMapMode ? undefined : value) as AVLTreeNode<K, V>;
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The function creates a new AVL tree with the specified options and returns it.
    * @param {AVLTreeOptions} [options] - The `options` parameter is an optional object that can be
    * passed to the `createTree` function. It is used to customize the behavior of the AVL tree that is
    * being created.
    * @returns a new AVLTree object.
    */
-  override createTree(options?: AVLTreeOptions<K, V, R>): TREE {
-    return new AVLTree<K, V, R, NODE, TREE>([], {
+  override createTree(options?: AVLTreeOptions<K, V, R>) {
+    return new AVLTree<K, V, R, MK, MV, MR>([], {
       iterationType: this.iterationType,
       isMapMode: this._isMapMode,
-      extractComparable: this._extractComparable,
+      specifyComparable: this._specifyComparable,
       toEntryFn: this._toEntryFn,
       isReverse: this._isReverse,
       ...options
-    }) as TREE;
+    });
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The function checks if the input is an instance of AVLTreeNode.
-   * @param {BTNRep<K, V, NODE> | R} keyNodeEntryOrRaw - The parameter
-   * `keyNodeEntryOrRaw` can be of type `R` or `BTNRep<K, V, NODE>`.
-   * @returns a boolean value indicating whether the input parameter `keyNodeEntryOrRaw` is
+   * @param {BTNRep<K, V, AVLTreeNode<K, V>>} keyNodeOrEntry - The parameter
+   * `keyNodeOrEntry` can be of type `R` or `BTNRep<K, V, AVLTreeNode<K, V>>`.
+   * @returns a boolean value indicating whether the input parameter `keyNodeOrEntry` is
    * an instance of the `AVLTreeNode` class.
    */
-  override isNode(keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R): keyNodeEntryOrRaw is NODE {
-    return keyNodeEntryOrRaw instanceof AVLTreeNode;
+  override isNode(keyNodeOrEntry: BTNRep<K, V, AVLTreeNode<K, V>>): keyNodeOrEntry is AVLTreeNode<K, V> {
+    return keyNodeOrEntry instanceof AVLTreeNode;
   }
 
   /**
    * Time Complexity: O(log n)
-   * Space Complexity: O(1)
+   * Space Complexity: O(log n)
    *
    * The function overrides the add method of a class and inserts a key-value pair into a data
    * structure, then balances the path.
-   * @param {BTNRep<K, V, NODE> | R} keyNodeEntryOrRaw - The parameter
-   * `keyNodeEntryOrRaw` can accept values of type `R`, `BTNRep<K, V, NODE>`, or
-   * `RawElement`.
+   * @param {BTNRep<K, V, AVLTreeNode<K, V>>} keyNodeOrEntry - The parameter
+   * `keyNodeOrEntry` can accept values of type `R`, `BTNRep<K, V, AVLTreeNode<K, V>>`
    * @param {V} [value] - The `value` parameter is an optional value that you want to associate with
    * the key or node being added to the data structure.
    * @returns The method is returning a boolean value.
    */
-  override add(keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R, value?: V): boolean {
-    if (keyNodeEntryOrRaw === null) return false;
-    const inserted = super.add(keyNodeEntryOrRaw, value);
-    if (inserted) this._balancePath(keyNodeEntryOrRaw);
+  override add(keyNodeOrEntry: BTNRep<K, V, AVLTreeNode<K, V>>, value?: V): boolean {
+    if (keyNodeOrEntry === null) return false;
+    const inserted = super.add(keyNodeOrEntry, value);
+    if (inserted) this._balancePath(keyNodeOrEntry);
     return inserted;
   }
 
   /**
    * Time Complexity: O(log n)
-   * Space Complexity: O(1)
+   * Space Complexity: O(log n)
    *
    * The function overrides the delete method in a TypeScript class, performs deletion, and then
    * balances the tree if necessary.
-   * @param {BTNRep<K, V, NODE> | R} keyNodeEntryOrRaw - The `keyNodeEntryOrRaw`
+   * @param {BTNRep<K, V, AVLTreeNode<K, V>>} keyNodeOrEntry - The `keyNodeOrEntry`
    * parameter in the `override delete` method can be one of the following types:
    * @returns The `delete` method is being overridden in this code snippet. It first calls the `delete`
    * method from the superclass (presumably a parent class) with the provided `predicate`, which could
    * be a key, node, entry, or a custom predicate. The result of this deletion operation is stored in
    * `deletedResults`, which is an array of `BinaryTreeDeleteResult` objects.
    */
-  override delete(keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R): BinaryTreeDeleteResult<NODE>[] {
-    const deletedResults = super.delete(keyNodeEntryOrRaw);
+  override delete(keyNodeOrEntry: BTNRep<K, V, AVLTreeNode<K, V>>): BinaryTreeDeleteResult<AVLTreeNode<K, V>>[] {
+    const deletedResults = super.delete(keyNodeOrEntry);
     for (const { needBalanced } of deletedResults) {
       if (needBalanced) {
         this._balancePath(needBalanced);
@@ -174,23 +184,70 @@ export class AVLTree<
     return deletedResults;
   }
 
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The `map` function in TypeScript overrides the default map behavior of an AVLTree data structure
+   * by applying a callback function to each entry and creating a new AVLTree with the results.
+   * @param callback - A function that will be called for each entry in the AVLTree. It takes four
+   * arguments: the key, the value (which can be undefined), the index of the entry, and a reference to
+   * the AVLTree itself.
+   * @param [options] - The `options` parameter in the `override map` function is of type
+   * `AVLTreeOptions<MK, MV, MR>`. It is an optional parameter that allows you to specify additional
+   * options for the AVL tree being created during the mapping process. These options could include
+   * custom comparators, initial
+   * @param {any} [thisArg] - The `thisArg` parameter in the `override map` function is used to specify
+   * the value of `this` when executing the `callback` function. It allows you to set the context
+   * (value of `this`) within the callback function. This can be useful when you want to access
+   * properties or
+   * @returns The `map` method is returning a new AVLTree instance (`newTree`) with the entries
+   * modified by the provided callback function.
+   */
+  override map(
+    callback: EntryCallback<K, V | undefined, [MK, MV]>,
+    options?: AVLTreeOptions<MK, MV, MR>,
+    thisArg?: any
+  ): AVLTree<MK, MV, MR> {
+    const newTree = new AVLTree<MK, MV, MR>([], options);
+    let index = 0;
+    for (const [key, value] of this) {
+      newTree.add(callback.call(thisArg, key, value, index++, this));
+    }
+    return newTree;
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The function `clone` overrides the default cloning behavior to create a deep copy of a tree
+   * structure.
+   * @returns A cloned tree object is being returned.
+   */
+  override clone() {
+    const cloned = this.createTree();
+    this._clone(cloned);
+    return cloned;
+  }
+
   /**
    * Time Complexity: O(1)
    * Space Complexity: O(1)
    *
    * The `_swapProperties` function swaps the key, value, and height properties between two nodes in a
    * binary search tree.
-   * @param {R | BSTNOptKeyOrNode<K, NODE>} srcNode - The `srcNode` parameter represents either a node
-   * object (`NODE`) or a key-value pair (`R`) that is being swapped with another node.
-   * @param {R | BSTNOptKeyOrNode<K, NODE>} destNode - The `destNode` parameter is either an instance of
-   * `R` or an instance of `BSTNOptKeyOrNode<K, NODE>`.
+   * @param {BSTNOptKeyOrNode<K, AVLTreeNode<K, V>>} srcNode - The `srcNode` parameter represents either a node
+   * object (`AVLTreeNode<K, V>`) or a key-value pair (`R`) that is being swapped with another node.
+   * @param {BSTNOptKeyOrNode<K, AVLTreeNode<K, V>>} destNode - The `destNode` parameter is either an instance of
+   * `R` or an instance of `BSTNOptKeyOrNode<K, AVLTreeNode<K, V>>`.
    * @returns The method is returning the `destNodeEnsured` object if both `srcNodeEnsured` and
    * `destNodeEnsured` are truthy. Otherwise, it returns `undefined`.
    */
   protected override _swapProperties(
-    srcNode: R | BSTNOptKeyOrNode<K, NODE>,
-    destNode: R | BSTNOptKeyOrNode<K, NODE>
-  ): NODE | undefined {
+    srcNode: BSTNOptKeyOrNode<K, AVLTreeNode<K, V>>,
+    destNode: BSTNOptKeyOrNode<K, AVLTreeNode<K, V>>
+  ): AVLTreeNode<K, V> | undefined {
     const srcNodeEnsured = this.ensureNode(srcNode);
     const destNodeEnsured = this.ensureNode(destNode);
 
@@ -220,12 +277,12 @@ export class AVLTree<
    * Space Complexity: O(1)
    *
    * The function calculates the balance factor of a node in a binary tree.
-   * @param {NODE} node - The parameter "node" is of type "NODE", which likely represents a node in a
+   * @param {AVLTreeNode<K, V>} node - The parameter "node" is of type "AVLTreeNode<K, V>", which likely represents a node in a
    * binary tree data structure.
    * @returns the balance factor of a given node. The balance factor is calculated by subtracting the
    * height of the left subtree from the height of the right subtree.
    */
-  protected _balanceFactor(node: NODE): number {
+  protected _balanceFactor(node: AVLTreeNode<K, V>): number {
     if (!node.right)
       // node has no right subtree
       return -node.height;
@@ -241,9 +298,9 @@ export class AVLTree<
    *
    * The function updates the height of a node in a binary tree based on the heights of its left and
    * right children.
-   * @param {NODE} node - The parameter "node" represents a node in a binary tree data structure.
+   * @param {AVLTreeNode<K, V>} node - The parameter "node" represents a node in a binary tree data structure.
    */
-  protected _updateHeight(node: NODE): void {
+  protected _updateHeight(node: AVLTreeNode<K, V>): void {
     if (!node.left && !node.right) node.height = 0;
     else if (!node.left) {
       const rightHeight = node.right ? node.right.height : 0;
@@ -257,12 +314,12 @@ export class AVLTree<
    * Space Complexity: O(1)
    *
    * The `_balanceLL` function performs a left-left rotation to balance a binary search tree.
-   * @param {NODE} A - A is a node in a binary tree.
+   * @param {AVLTreeNode<K, V>} A - A is a node in a binary tree.
    */
-  protected _balanceLL(A: NODE): void {
+  protected _balanceLL(A: AVLTreeNode<K, V>): void {
     const parentOfA = A.parent;
     const B = A.left;
-    A.parent = B;
+    if (B !== null) A.parent = B;
     if (B && B.right) {
       B.right.parent = A;
     }
@@ -290,21 +347,21 @@ export class AVLTree<
    * Space Complexity: O(1)
    *
    * The `_balanceLR` function performs a left-right rotation to balance a binary tree.
-   * @param {NODE} A - A is a node in a binary tree.
+   * @param {AVLTreeNode<K, V>} A - A is a node in a binary tree.
    */
-  protected _balanceLR(A: NODE): void {
+  protected _balanceLR(A: AVLTreeNode<K, V>): void {
     const parentOfA = A.parent;
     const B = A.left;
     let C = undefined;
     if (B) {
       C = B.right;
     }
-    if (A) A.parent = C;
-    if (B) B.parent = C;
+    if (A && C !== null) A.parent = C;
+    if (B && C !== null) B.parent = C;
 
     if (C) {
       if (C.left) {
-        C.left.parent = B;
+        if (B !== null) C.left.parent = B;
       }
       if (C.right) {
         C.right.parent = A;
@@ -341,12 +398,12 @@ export class AVLTree<
    * Space Complexity: O(1)
    *
    * The function `_balanceRR` performs a right-right rotation to balance a binary tree.
-   * @param {NODE} A - A is a node in a binary tree.
+   * @param {AVLTreeNode<K, V>} A - A is a node in a binary tree.
    */
-  protected _balanceRR(A: NODE): void {
+  protected _balanceRR(A: AVLTreeNode<K, V>): void {
     const parentOfA = A.parent;
     const B = A.right;
-    A.parent = B;
+    if (B !== null) A.parent = B;
     if (B) {
       if (B.left) {
         B.left.parent = A;
@@ -379,9 +436,9 @@ export class AVLTree<
    * Space Complexity: O(1)
    *
    * The function `_balanceRL` performs a right-left rotation to balance a binary tree.
-   * @param {NODE} A - A is a node in a binary tree.
+   * @param {AVLTreeNode<K, V>} A - A is a node in a binary tree.
    */
-  protected _balanceRL(A: NODE): void {
+  protected _balanceRL(A: AVLTreeNode<K, V>): void {
     const parentOfA = A.parent;
     const B = A.right;
     let C = undefined;
@@ -389,15 +446,15 @@ export class AVLTree<
       C = B.left;
     }
 
-    A.parent = C;
-    if (B) B.parent = C;
+    if (C !== null) A.parent = C;
+    if (B && C !== null) B.parent = C;
 
     if (C) {
       if (C.left) {
         C.left.parent = A;
       }
       if (C.right) {
-        C.right.parent = B;
+        if (B !== null) C.right.parent = B;
       }
       C.parent = parentOfA;
     }
@@ -430,10 +487,10 @@ export class AVLTree<
    *
    * The `_balancePath` function is used to update the heights of nodes and perform rotation operations
    * to restore balance in an AVL tree after inserting a node.
-   * @param {BTNRep<K, V, NODE> | R} node - The `node` parameter can be of type `R` or
-   * `BTNRep<K, V, NODE>`.
+   * @param {BTNRep<K, V, AVLTreeNode<K, V>>} node - The `node` parameter can be of type `R` or
+   * `BTNRep<K, V, AVLTreeNode<K, V>>`.
    */
-  protected _balancePath(node: BTNRep<K, V, NODE> | R): void {
+  protected _balancePath(node: BTNRep<K, V, AVLTreeNode<K, V>>): void {
     node = this.ensureNode(node);
     const path = this.getPathToRoot(node, node => node, false); // first O(log n) + O(log n)
     for (let i = 0; i < path.length; i++) {
@@ -481,14 +538,14 @@ export class AVLTree<
    *
    * The function replaces an old node with a new node and sets the height of the new node to be the
    * same as the old node.
-   * @param {NODE} oldNode - The `oldNode` parameter represents the node that needs to be replaced in
+   * @param {AVLTreeNode<K, V>} oldNode - The `oldNode` parameter represents the node that needs to be replaced in
    * the data structure.
-   * @param {NODE} newNode - The `newNode` parameter is the new node that will replace the `oldNode` in
+   * @param {AVLTreeNode<K, V>} newNode - The `newNode` parameter is the new node that will replace the `oldNode` in
    * the data structure.
    * @returns The method is returning the result of calling the `_replaceNode` method from the
    * superclass, with the `oldNode` and `newNode` as arguments.
    */
-  protected override _replaceNode(oldNode: NODE, newNode: NODE): NODE {
+  protected override _replaceNode(oldNode: AVLTreeNode<K, V>, newNode: AVLTreeNode<K, V>): AVLTreeNode<K, V> {
     newNode.height = oldNode.height;
 
     return super._replaceNode(oldNode, newNode);

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

@@ -7,6 +7,9 @@
  */
 import { getMSB } from '../../utils';
 
+/**
+ *
+ */
 export class BinaryIndexedTree {
   protected readonly _freq: number;
   protected readonly _max: number;