min-heap-typed 1.50.2 → 1.50.4

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

@@ -34,10 +34,19 @@ export class BSTNode<K = any, V = any, NODE extends BSTNode<K, V, NODE> = BSTNod
 
   protected override _left?: NODE;
 
+  /**
+   * The function returns the value of the `_left` property.
+   * @returns The `_left` property of the current object is being returned.
+   */
   override get left(): NODE | undefined {
     return this._left;
   }
 
+  /**
+   * 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`.
+   */
   override set left(v: NODE | undefined) {
     if (v) {
       v.parent = this as unknown as NODE;
@@ -47,10 +56,20 @@ export class BSTNode<K = any, V = any, NODE extends BSTNode<K, V, NODE> = BSTNod
 
   protected override _right?: 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`.
+   */
   override get right(): NODE | undefined {
     return this._right;
   }
 
+  /**
+   * 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`.
+   */
   override set right(v: NODE | undefined) {
     if (v) {
       v.parent = this as unknown as NODE;
@@ -77,10 +96,10 @@ export class BST<
   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:
    */
@@ -99,23 +118,31 @@ export class BST<
 
   protected override _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`.
+   */
   override get root(): NODE | undefined {
     return this._root;
   }
 
   protected _variant = BSTVariant.STANDARD;
 
+  /**
+   * The function returns the value of the _variant property.
+   * @returns The value of the `_variant` property.
+   */
   get variant() {
     return this._variant;
   }
 
   /**
-   * 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.
    */
   override createNode(key: K, value?: V): NODE {
     return new BSTNode<K, V, NODE>(key, value) as NODE;
@@ -124,9 +151,10 @@ export class BST<
   /**
    * 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.
    */
   override createTree(options?: Partial<BSTOptions<K>>): TREE {
     return new BST<K, V, NODE, TREE>([], {
@@ -680,9 +708,8 @@ export class BST<
         const compared = this._compare(cur.key, targetKey);
         if (compared === lesserOrGreater) ans.push(callback(cur));
 
-        if (!cur.left && !cur.right) return;
-        if (cur.left && this._compare(cur.left.key, targetKey) === lesserOrGreater) _traverse(cur.left);
-        if (cur.right && this._compare(cur.right.key, targetKey) === lesserOrGreater) _traverse(cur.right);
+        if (this.isRealNode(cur.left)) _traverse(cur.left);
+        if (this.isRealNode(cur.right)) _traverse(cur.right);
       };
 
       _traverse(this.root);
@@ -691,12 +718,12 @@ export class BST<
       const queue = new Queue<NODE>([this.root]);
       while (queue.size > 0) {
         const cur = queue.shift();
-        if (cur) {
+        if (this.isRealNode(cur)) {
           const compared = this._compare(cur.key, targetKey);
           if (compared === lesserOrGreater) ans.push(callback(cur));
 
-          if (cur.left && this._compare(cur.left.key, targetKey) === lesserOrGreater) queue.push(cur.left);
-          if (cur.right && this._compare(cur.right.key, targetKey) === lesserOrGreater) queue.push(cur.right);
+          if (this.isRealNode(cur.left)) queue.push(cur.left);
+          if (this.isRealNode(cur.right)) queue.push(cur.right);
         }
       }
       return ans;
@@ -824,6 +851,11 @@ export class BST<
     return balanced;
   }
 
+  /**
+   * 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) {
     if (v) {
       v.parent = undefined;

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

@@ -4,4 +4,5 @@ export * from './binary-indexed-tree';
 export * from './segment-tree';
 export * from './avl-tree';
 export * from './rb-tree';
-export * from './tree-multimap';
+export * from './avl-tree-multi-map';
+export * from './tree-multi-map';

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

@@ -24,11 +24,38 @@ export class RedBlackTreeNode<
   V = any,
   NODE extends RedBlackTreeNode<K, V, NODE> = RedBlackTreeNodeNested<K, V>
 > extends BSTNode<K, V, NODE> {
-  color: RBTNColor;
-
+  /**
+   * The constructor function initializes a Red-Black Tree Node with a key, an optional value, and a
+   * color.
+   * @param {K} key - The key parameter is of type K and represents the key of the node in the
+   * Red-Black Tree.
+   * @param {V} [value] - The `value` parameter is an optional parameter that represents the value
+   * associated with the key in the Red-Black Tree Node. It is not required and can be omitted when
+   * creating a new instance of the Red-Black Tree Node.
+   * @param {RBTNColor} color - The `color` parameter is used to specify the color of the Red-Black
+   * Tree Node. It is an optional parameter with a default value of `RBTNColor.BLACK`.
+   */
   constructor(key: K, value?: V, color: RBTNColor = RBTNColor.BLACK) {
     super(key, value);
-    this.color = color;
+    this._color = color;
+  }
+
+  protected _color: RBTNColor;
+
+  /**
+   * The function returns the color value of a variable.
+   * @returns The color value stored in the protected variable `_color`.
+   */
+  get color(): RBTNColor {
+    return this._color;
+  }
+
+  /**
+   * The function sets the color property to the specified value.
+   * @param {RBTNColor} value - The value parameter is of type RBTNColor.
+   */
+  set color(value: RBTNColor) {
+    this._color = value;
   }
 }
 
@@ -47,8 +74,6 @@ export class RedBlackTree<
 >
   extends BST<K, V, NODE, TREE>
   implements IBinaryTree<K, V, NODE, TREE> {
-  Sentinel: NODE = new RedBlackTreeNode<K, V>(NaN as K) as unknown as NODE;
-
   /**
    * This is the constructor function for a Red-Black Tree data structure in TypeScript, which
    * initializes the tree with optional nodes and options.
@@ -63,18 +88,36 @@ export class RedBlackTree<
   constructor(keysOrNodesOrEntries: Iterable<KeyOrNodeOrEntry<K, V, NODE>> = [], options?: RBTreeOptions<K>) {
     super([], options);
 
-    this._root = this.Sentinel;
+    this._root = this._Sentinel;
     if (keysOrNodesOrEntries) super.addMany(keysOrNodesOrEntries);
   }
 
+  protected _Sentinel: NODE = new RedBlackTreeNode<K, V>(NaN as K) as unknown as NODE;
+
+  /**
+   * The function returns the value of the `_Sentinel` property.
+   * @returns The method is returning the value of the `_Sentinel` property.
+   */
+  get Sentinel(): NODE {
+    return this._Sentinel;
+  }
+
   protected _root: NODE;
 
+  /**
+   * The function returns the root node.
+   * @returns The root node of the data structure.
+   */
   get root(): NODE {
     return this._root;
   }
 
   protected _size: number = 0;
 
+  /**
+   * The function returns the size of an object.
+   * @returns The size of the object, which is a number.
+   */
   get size(): number {
     return this._size;
   }
@@ -149,8 +192,14 @@ export class RedBlackTree<
     return keyOrNodeOrEntry instanceof RedBlackTreeNode;
   }
 
+  /**
+   * The function checks if a given node is a real node in a Red-Black Tree.
+   * @param {NODE | undefined} node - The `node` parameter is of type `NODE | undefined`, which means
+   * it can either be of type `NODE` or `undefined`.
+   * @returns a boolean value.
+   */
   override isRealNode(node: NODE | undefined): node is NODE {
-    if (node === this.Sentinel || node === undefined) return false;
+    if (node === this._Sentinel || node === undefined) return false;
     return node instanceof RedBlackTreeNode;
   }
 
@@ -176,13 +225,13 @@ export class RedBlackTree<
     const newNode = this.keyValueOrEntryToNode(keyOrNodeOrEntry, value);
     if (newNode === undefined) return false;
 
-    newNode.left = this.Sentinel;
-    newNode.right = this.Sentinel;
+    newNode.left = this._Sentinel;
+    newNode.right = this._Sentinel;
 
     let y: NODE | undefined = undefined;
     let x: NODE | undefined = this.root;
 
-    while (x !== this.Sentinel) {
+    while (x !== this._Sentinel) {
       y = x;
       if (x) {
         if (newNode.key < x.key) {
@@ -250,9 +299,9 @@ export class RedBlackTree<
     const ans: BinaryTreeDeleteResult<NODE>[] = [];
     if (identifier === null) return ans;
     const helper = (node: NODE | undefined): void => {
-      let z: NODE = this.Sentinel;
+      let z: NODE = this._Sentinel;
       let x: NODE | undefined, y: NODE;
-      while (node !== this.Sentinel) {
+      while (node !== this._Sentinel) {
         if (node && callback(node) === identifier) {
           z = node;
         }
@@ -264,17 +313,17 @@ export class RedBlackTree<
         }
       }
 
-      if (z === this.Sentinel) {
+      if (z === this._Sentinel) {
         this._size--;
         return;
       }
 
       y = z;
       let yOriginalColor: number = y.color;
-      if (z.left === this.Sentinel) {
+      if (z.left === this._Sentinel) {
         x = z.right;
         this._rbTransplant(z, z.right!);
-      } else if (z.right === this.Sentinel) {
+      } else if (z.right === this._Sentinel) {
         x = z.left;
         this._rbTransplant(z, z.left!);
       } else {
@@ -346,8 +395,14 @@ export class RedBlackTree<
    * Space Complexity: O(1)
    */
 
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The "clear" function sets the root node to the sentinel node and resets the size to 0.
+   */
   override clear() {
-    this._root = this.Sentinel;
+    this._root = this._Sentinel;
     this._size = 0;
   }
 
@@ -379,6 +434,12 @@ export class RedBlackTree<
     return y!;
   }
 
+  /**
+   * The function sets the root node of a tree structure and updates the parent property of the new
+   * root node.
+   * @param {NODE} v - The parameter "v" is of type "NODE", which represents a node in a data
+   * structure.
+   */
   protected override _setRoot(v: NODE) {
     if (v) {
       v.parent = undefined;
@@ -402,7 +463,7 @@ export class RedBlackTree<
     if (x.right) {
       const y: NODE = x.right;
       x.right = y.left;
-      if (y.left !== this.Sentinel) {
+      if (y.left !== this._Sentinel) {
         if (y.left) y.left.parent = x;
       }
       y.parent = x.parent;
@@ -435,7 +496,7 @@ export class RedBlackTree<
     if (x.left) {
       const y: NODE = x.left;
       x.left = y.right;
-      if (y.right !== this.Sentinel) {
+      if (y.right !== this._Sentinel) {
         if (y.right) y.right.parent = x;
       }
       y.parent = x.parent;
@@ -466,12 +527,14 @@ export class RedBlackTree<
    */
   protected _fixInsert(k: NODE): void {
     let u: NODE | undefined;
-    while (k.parent && k.parent.color === 1) {
+    while (k.parent && k.parent.color === RBTNColor.RED) {
       if (k.parent.parent && k.parent === k.parent.parent.right) {
         u = k.parent.parent.left;
-        if (u && u.color === 1) {
-          u.color = RBTNColor.BLACK;
+
+        if (u && u.color === RBTNColor.RED) {
+          // Delay color flip
           k.parent.color = RBTNColor.BLACK;
+          u.color = RBTNColor.BLACK;
           k.parent.parent.color = RBTNColor.RED;
           k = k.parent.parent;
         } else {
@@ -480,16 +543,20 @@ export class RedBlackTree<
             this._rightRotate(k);
           }
 
-          k.parent!.color = RBTNColor.BLACK;
-          k.parent!.parent!.color = RBTNColor.RED;
+          // Check color before rotation
+          if (k.parent!.color === RBTNColor.RED) {
+            k.parent!.color = RBTNColor.BLACK;
+            k.parent!.parent!.color = RBTNColor.RED;
+          }
           this._leftRotate(k.parent!.parent!);
         }
       } else {
-        u = k.parent.parent!.right;
+        u = k.parent!.parent!.right;
 
-        if (u && u.color === 1) {
-          u.color = RBTNColor.BLACK;
+        if (u && u.color === RBTNColor.RED) {
+          // Delay color flip
           k.parent.color = RBTNColor.BLACK;
+          u.color = RBTNColor.BLACK;
           k.parent.parent!.color = RBTNColor.RED;
           k = k.parent.parent!;
         } else {
@@ -498,11 +565,15 @@ export class RedBlackTree<
             this._leftRotate(k);
           }
 
-          k.parent!.color = RBTNColor.BLACK;
-          k.parent!.parent!.color = RBTNColor.RED;
+          // Check color before rotation
+          if (k.parent!.color === RBTNColor.RED) {
+            k.parent!.color = RBTNColor.BLACK;
+            k.parent!.parent!.color = RBTNColor.RED;
+          }
           this._rightRotate(k.parent!.parent!);
         }
       }
+
       if (k === this.root) {
         break;
       }

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

@@ -9,18 +9,136 @@
 import type { SegmentTreeNodeVal } from '../../types';
 
 export class SegmentTreeNode {
-  start = 0;
-  end = 0;
-  value: SegmentTreeNodeVal | undefined = undefined;
-  sum = 0;
-  left: SegmentTreeNode | undefined = undefined;
-  right: SegmentTreeNode | undefined = undefined;
-
+  /**
+   * The constructor initializes the properties of a SegmentTreeNode object.
+   * @param {number} start - The `start` parameter represents the starting index of the segment covered
+   * by this node in a segment tree.
+   * @param {number} end - The `end` parameter represents the end index of the segment covered by this
+   * node in a segment tree.
+   * @param {number} sum - The `sum` parameter represents the sum of the values in the range covered by
+   * the segment tree node.
+   * @param {SegmentTreeNodeVal | undefined} [value] - The `value` parameter is an optional parameter
+   * of type `SegmentTreeNodeVal`. It represents the value associated with the segment tree node.
+   */
   constructor(start: number, end: number, sum: number, value?: SegmentTreeNodeVal | undefined) {
-    this.start = start;
-    this.end = end;
-    this.sum = sum;
-    this.value = value || undefined;
+    this._start = start;
+    this._end = end;
+    this._sum = sum;
+    this._value = value || undefined;
+  }
+
+  protected _start = 0;
+
+  /**
+   * The function returns the value of the protected variable _start.
+   * @returns The start value, which is of type number.
+   */
+  get start(): number {
+    return this._start;
+  }
+
+  /**
+   * The above function sets the value of the "start" property.
+   * @param {number} value - The value parameter is of type number.
+   */
+  set start(value: number) {
+    this._start = value;
+  }
+
+  protected _end = 0;
+
+  /**
+   * The function returns the value of the protected variable `_end`.
+   * @returns The value of the protected property `_end`.
+   */
+  get end(): number {
+    return this._end;
+  }
+
+  /**
+   * The above function sets the value of the "end" property.
+   * @param {number} value - The value parameter is a number that represents the new value for the end
+   * property.
+   */
+  set end(value: number) {
+    this._end = value;
+  }
+
+  protected _value: SegmentTreeNodeVal | undefined = undefined;
+
+  /**
+   * The function returns the value of a segment tree node.
+   * @returns The value being returned is either a `SegmentTreeNodeVal` object or `undefined`.
+   */
+  get value(): SegmentTreeNodeVal | undefined {
+    return this._value;
+  }
+
+  /**
+   * The function sets the value of a segment tree node.
+   * @param {SegmentTreeNodeVal | undefined} value - The `value` parameter is of type
+   * `SegmentTreeNodeVal` or `undefined`.
+   */
+  set value(value: SegmentTreeNodeVal | undefined) {
+    this._value = value;
+  }
+
+  protected _sum = 0;
+
+  /**
+   * The function returns the value of the sum property.
+   * @returns The method is returning the value of the variable `_sum`.
+   */
+  get sum(): number {
+    return this._sum;
+  }
+
+  /**
+   * The above function sets the value of the sum property.
+   * @param {number} value - The parameter "value" is of type "number".
+   */
+  set sum(value: number) {
+    this._sum = value;
+  }
+
+  protected _left: SegmentTreeNode | undefined = undefined;
+
+  /**
+   * The function returns the left child of a segment tree node.
+   * @returns The `left` property of the `SegmentTreeNode` object is being returned. It is of type
+   * `SegmentTreeNode` or `undefined`.
+   */
+  get left(): SegmentTreeNode | undefined {
+    return this._left;
+  }
+
+  /**
+   * The function sets the value of the left property of a SegmentTreeNode object.
+   * @param {SegmentTreeNode | undefined} value - The value parameter is of type SegmentTreeNode or
+   * undefined.
+   */
+  set left(value: SegmentTreeNode | undefined) {
+    this._left = value;
+  }
+
+  protected _right: SegmentTreeNode | undefined = undefined;
+
+  /**
+   * The function returns the right child of a segment tree node.
+   * @returns The `getRight()` method is returning a value of type `SegmentTreeNode` or `undefined`.
+   */
+  get right(): SegmentTreeNode | undefined {
+    return this._right;
+  }
+
+  /**
+   * The function sets the right child of a segment tree node.
+   * @param {SegmentTreeNode | undefined} value - The `value` parameter is of type `SegmentTreeNode |
+   * undefined`. This means that it can accept either a `SegmentTreeNode` object or `undefined` as its
+   * value.
+   */
+  set right(value: SegmentTreeNode | undefined) {
+    this._right = value;
   }
 }
 
@@ -51,24 +169,40 @@ export class SegmentTree {
 
   protected _values: number[] = [];
 
+  /**
+   * The function returns an array of numbers.
+   * @returns An array of numbers is being returned.
+   */
   get values(): number[] {
     return this._values;
   }
 
   protected _start = 0;
 
+  /**
+   * The function returns the value of the protected variable _start.
+   * @returns The start value, which is of type number.
+   */
   get start(): number {
     return this._start;
   }
 
   protected _end: number;
 
+  /**
+   * The function returns the value of the protected variable `_end`.
+   * @returns The value of the protected property `_end`.
+   */
   get end(): number {
     return this._end;
   }
 
   protected _root: SegmentTreeNode | undefined;
 
+  /**
+   * The function returns the root node of a segment tree.
+   * @returns The `root` property of the class `SegmentTreeNode` or `undefined` if it is not defined.
+   */
   get root(): SegmentTreeNode | undefined {
     return this._root;
   }