max-heap-typed 2.1.2 → 2.2.1

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

@@ -12,7 +12,9 @@ import type {
   BTNOptKeyOrNull,
   ElemOf,
   EntryCallback,
-  IterationType
+  FamilyPosition,
+  IterationType,
+  RBTNColor
 } from '../../types';
 import { AVLTree, AVLTreeNode } from './avl-tree';
 import { IBinaryTree } from '../../interfaces';
@@ -23,8 +25,10 @@ import { IBinaryTree } from '../../interfaces';
  * @template K
  * @template V
  */
-export class AVLTreeMultiMapNode<K = any, V = any> extends AVLTreeNode<K, V[]> {
-  override parent?: AVLTreeMultiMapNode<K, V> = undefined;
+export class AVLTreeMultiMapNode<K = any, V = any> {
+  key: K;
+  value?: V[];
+  parent?: AVLTreeMultiMapNode<K, V> = undefined;
 
   /**
    * Create an AVLTreeMultiMap node with a value bucket.
@@ -33,18 +37,19 @@ export class AVLTreeMultiMapNode<K = any, V = any> extends AVLTreeNode<K, V[]> {
    * @param value - Initial array of values.
    * @returns New AVLTreeMultiMapNode instance.
    */
-  constructor(key: K, value: V[]) {
-    super(key, value);
+  constructor(key: K, value: V[] = []) {
+    this.key = key;
+    this.value = value;
   }
 
-  override _left?: AVLTreeMultiMapNode<K, V> | null | undefined = undefined;
+  _left?: AVLTreeMultiMapNode<K, V> | null | undefined = undefined;
 
   /**
    * Get the left child pointer.
    * @remarks Time O(1), Space O(1)
    * @returns Left child node, or null/undefined.
    */
-  override get left(): AVLTreeMultiMapNode<K, V> | null | undefined {
+  get left(): AVLTreeMultiMapNode<K, V> | null | undefined {
     return this._left;
   }
 
@@ -54,21 +59,21 @@ export class AVLTreeMultiMapNode<K = any, V = any> extends AVLTreeNode<K, V[]> {
    * @param v - New left child node, or null/undefined.
    * @returns void
    */
-  override set left(v: AVLTreeMultiMapNode<K, V> | null | undefined) {
+  set left(v: AVLTreeMultiMapNode<K, V> | null | undefined) {
     if (v) {
       v.parent = this;
     }
     this._left = v;
   }
 
-  override _right?: AVLTreeMultiMapNode<K, V> | null | undefined = undefined;
+  _right?: AVLTreeMultiMapNode<K, V> | null | undefined = undefined;
 
   /**
    * Get the right child pointer.
    * @remarks Time O(1), Space O(1)
    * @returns Right child node, or null/undefined.
    */
-  override get right(): AVLTreeMultiMapNode<K, V> | null | undefined {
+  get right(): AVLTreeMultiMapNode<K, V> | null | undefined {
     return this._right;
   }
 
@@ -78,12 +83,98 @@ export class AVLTreeMultiMapNode<K = any, V = any> extends AVLTreeNode<K, V[]> {
    * @param v - New right child node, or null/undefined.
    * @returns void
    */
-  override set right(v: AVLTreeMultiMapNode<K, V> | null | undefined) {
+  set right(v: AVLTreeMultiMapNode<K, V> | null | undefined) {
     if (v) {
       v.parent = this;
     }
     this._right = v;
   }
+
+  _height: number = 0;
+
+  /**
+   * Gets the height of the node (used in self-balancing trees).
+   * @remarks Time O(1), Space O(1)
+   *
+   * @returns The height.
+   */
+  get height(): number {
+    return this._height;
+  }
+
+  /**
+   * Sets the height of the node.
+   * @remarks Time O(1), Space O(1)
+   *
+   * @param value - The new height.
+   */
+  set height(value: number) {
+    this._height = value;
+  }
+
+  _color: RBTNColor = 'BLACK';
+
+  /**
+   * Gets the color of the node (used in Red-Black trees).
+   * @remarks Time O(1), Space O(1)
+   *
+   * @returns The node's color.
+   */
+  get color(): RBTNColor {
+    return this._color;
+  }
+
+  /**
+   * Sets the color of the node.
+   * @remarks Time O(1), Space O(1)
+   *
+   * @param value - The new color.
+   */
+  set color(value: RBTNColor) {
+    this._color = value;
+  }
+
+  _count: number = 1;
+
+  /**
+   * Gets the count of nodes in the subtree rooted at this node (used in order-statistic trees).
+   * @remarks Time O(1), Space O(1)
+   *
+   * @returns The subtree node count.
+   */
+  get count(): number {
+    return this._count;
+  }
+
+  /**
+   * Sets the count of nodes in the subtree.
+   * @remarks Time O(1), Space O(1)
+   *
+   * @param value - The new count.
+   */
+  set count(value: number) {
+    this._count = value;
+  }
+
+  /**
+   * Gets the position of the node relative to its parent.
+   * @remarks Time O(1), Space O(1)
+   *
+   * @returns The family position (e.g., 'ROOT', 'LEFT', 'RIGHT').
+   */
+  get familyPosition(): FamilyPosition {
+    if (!this.parent) {
+      return this.left || this.right ? 'ROOT' : 'ISOLATED';
+    }
+
+    if (this.parent.left === this) {
+      return this.left || this.right ? 'ROOT_LEFT' : 'LEFT';
+    } else if (this.parent.right === this) {
+      return this.left || this.right ? 'ROOT_RIGHT' : 'RIGHT';
+    }
+
+    return 'MAL_NODE';
+  }
 }
 
 /**
@@ -117,6 +208,19 @@ export class AVLTreeMultiMap<K = any, V = any, R = any> extends AVLTree<K, V[],
     return new AVLTreeMultiMapNode<K, V>(key, this._isMapMode ? [] : value);
   }
 
+  /**
+   * Checks if the given item is a `AVLTreeMultiMapNode` instance.
+   * @remarks Time O(1), Space O(1)
+   *
+   * @param keyNodeOrEntry - The item to check.
+   * @returns True if it's a AVLTreeMultiMapNode, false otherwise.
+   */
+  override isNode(
+    keyNodeOrEntry: K | AVLTreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined
+  ): keyNodeOrEntry is AVLTreeMultiMapNode<K, V> {
+    return keyNodeOrEntry instanceof AVLTreeMultiMapNode;
+  }
+
   override add(
     keyNodeOrEntry: K | AVLTreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined
   ): boolean;
@@ -289,7 +393,7 @@ export class AVLTreeMultiMap<K = any, V = any, R = any> extends AVLTree<K, V[],
   ): AVLTree<MK, MV, MR> {
     const out = this._createLike<MK, MV, MR>([], options);
     let i = 0;
-    for (const [k, v] of this) out.add(callback.call(thisArg, k, v, i++, this));
+    for (const [k, v] of this) out.add(callback.call(thisArg, v, k, i++, this));
     return out;
   }
 

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

@@ -6,14 +6,16 @@
  * @license MIT License
  */
 
-import { BST, BSTNode } from './bst';
+import { BST } from './bst';
 import type {
   AVLTreeOptions,
   BinaryTreeDeleteResult,
   BinaryTreeOptions,
   BSTNOptKeyOrNode,
   EntryCallback,
-  IterationType
+  FamilyPosition,
+  IterationType,
+  RBTNColor
 } from '../../types';
 import { BSTOptions } from '../../types';
 import { IBinaryTree } from '../../interfaces';
@@ -25,8 +27,10 @@ import { IBinaryTree } from '../../interfaces';
  * @template K - The type of the key.
  * @template V - The type of the value.
  */
-export class AVLTreeNode<K = any, V = any> extends BSTNode<K, V> {
-  override parent?: AVLTreeNode<K, V> = undefined;
+export class AVLTreeNode<K = any, V = any> {
+  key: K;
+  value?: V;
+  parent?: AVLTreeNode<K, V> = undefined;
 
   /**
    * Creates an instance of AVLTreeNode.
@@ -36,10 +40,11 @@ export class AVLTreeNode<K = any, V = any> extends BSTNode<K, V> {
    * @param [value] - The value associated with the key.
    */
   constructor(key: K, value?: V) {
-    super(key, value);
+    this.key = key;
+    this.value = value;
   }
 
-  override _left?: AVLTreeNode<K, V> | null | undefined = undefined;
+  _left?: AVLTreeNode<K, V> | null | undefined = undefined;
 
   /**
    * Gets the left child of the node.
@@ -47,7 +52,7 @@ export class AVLTreeNode<K = any, V = any> extends BSTNode<K, V> {
    *
    * @returns The left child.
    */
-  override get left(): AVLTreeNode<K, V> | null | undefined {
+  get left(): AVLTreeNode<K, V> | null | undefined {
     return this._left;
   }
 
@@ -57,14 +62,14 @@ export class AVLTreeNode<K = any, V = any> extends BSTNode<K, V> {
    *
    * @param v - The node to set as the left child.
    */
-  override set left(v: AVLTreeNode<K, V> | null | undefined) {
+  set left(v: AVLTreeNode<K, V> | null | undefined) {
     if (v) {
       v.parent = this;
     }
     this._left = v;
   }
 
-  override _right?: AVLTreeNode<K, V> | null | undefined = undefined;
+  _right?: AVLTreeNode<K, V> | null | undefined = undefined;
 
   /**
    * Gets the right child of the node.
@@ -72,7 +77,7 @@ export class AVLTreeNode<K = any, V = any> extends BSTNode<K, V> {
    *
    * @returns The right child.
    */
-  override get right(): AVLTreeNode<K, V> | null | undefined {
+  get right(): AVLTreeNode<K, V> | null | undefined {
     return this._right;
   }
 
@@ -82,12 +87,98 @@ export class AVLTreeNode<K = any, V = any> extends BSTNode<K, V> {
    *
    * @param v - The node to set as the right child.
    */
-  override set right(v: AVLTreeNode<K, V> | null | undefined) {
+  set right(v: AVLTreeNode<K, V> | null | undefined) {
     if (v) {
       v.parent = this;
     }
     this._right = v;
   }
+
+  _height: number = 0;
+
+  /**
+   * Gets the height of the node (used in self-balancing trees).
+   * @remarks Time O(1), Space O(1)
+   *
+   * @returns The height.
+   */
+  get height(): number {
+    return this._height;
+  }
+
+  /**
+   * Sets the height of the node.
+   * @remarks Time O(1), Space O(1)
+   *
+   * @param value - The new height.
+   */
+  set height(value: number) {
+    this._height = value;
+  }
+
+  _color: RBTNColor = 'BLACK';
+
+  /**
+   * Gets the color of the node (used in Red-Black trees).
+   * @remarks Time O(1), Space O(1)
+   *
+   * @returns The node's color.
+   */
+  get color(): RBTNColor {
+    return this._color;
+  }
+
+  /**
+   * Sets the color of the node.
+   * @remarks Time O(1), Space O(1)
+   *
+   * @param value - The new color.
+   */
+  set color(value: RBTNColor) {
+    this._color = value;
+  }
+
+  _count: number = 1;
+
+  /**
+   * Gets the count of nodes in the subtree rooted at this node (used in order-statistic trees).
+   * @remarks Time O(1), Space O(1)
+   *
+   * @returns The subtree node count.
+   */
+  get count(): number {
+    return this._count;
+  }
+
+  /**
+   * Sets the count of nodes in the subtree.
+   * @remarks Time O(1), Space O(1)
+   *
+   * @param value - The new count.
+   */
+  set count(value: number) {
+    this._count = value;
+  }
+
+  /**
+   * Gets the position of the node relative to its parent.
+   * @remarks Time O(1), Space O(1)
+   *
+   * @returns The family position (e.g., 'ROOT', 'LEFT', 'RIGHT').
+   */
+  get familyPosition(): FamilyPosition {
+    if (!this.parent) {
+      return this.left || this.right ? 'ROOT' : 'ISOLATED';
+    }
+
+    if (this.parent.left === this) {
+      return this.left || this.right ? 'ROOT_LEFT' : 'LEFT';
+    } else if (this.parent.right === this) {
+      return this.left || this.right ? 'ROOT_RIGHT' : 'RIGHT';
+    }
+
+    return 'MAL_NODE';
+  }
 }
 
 /**
@@ -104,7 +195,9 @@ export class AVLTreeNode<K = any, V = any> extends BSTNode<K, V> {
  * 4. Order Preservation: Maintains the binary search tree property where left child values are less than the parent, and right child values are greater.
  * 5. Efficient Lookups: Offers O(log n) search time, where 'n' is the number of nodes, due to its balanced nature.
  * 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.@example
+ * 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.
+ *
+ * @example
  * // Find elements in a range
  *     // In interval queries, AVL trees, with their strictly balanced structure and lower height, offer better query efficiency, making them ideal for frequent and high-performance interval queries. In contrast, Red-Black trees, with lower update costs, are more suitable for scenarios involving frequent insertions and deletions where the requirements for interval queries are less demanding.
  *     type Datum = { timestamp: Date; temperature: number };
@@ -312,7 +405,7 @@ export class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> implements
     // Iterates in-order
     for (const [key, value] of this) {
       // `add` on the new tree will be O(log N) and will self-balance.
-      out.add(callback.call(thisArg, key, value, index++, this));
+      out.add(callback.call(thisArg, value, key, index++, this));
     }
     return out;
   }
@@ -327,7 +420,7 @@ export class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> implements
    */
   protected override _createInstance<TK = K, TV = V, TR = R>(options?: Partial<BSTOptions<TK, TV, TR>>): this {
     const Ctor = this.constructor as unknown as new (
-      iter?: Iterable<TK | BSTNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>,
+      iter?: Iterable<TK | AVLTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>,
       opts?: BSTOptions<TK, TV, TR>
     ) => this;
     return new Ctor([], { ...this._snapshotOptions<TK, TV, TR>(), ...(options ?? {}) }) as unknown as this;
@@ -343,11 +436,11 @@ export class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> implements
    * @returns A new AVLTree.
    */
   protected override _createLike<TK = K, TV = V, TR = R>(
-    iter: Iterable<TK | BSTNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR> = [],
+    iter: Iterable<TK | AVLTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR> = [],
     options?: Partial<BSTOptions<TK, TV, TR>>
   ): AVLTree<TK, TV, TR> {
     const Ctor = this.constructor as unknown as new (
-      iter?: Iterable<TK | BSTNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>,
+      iter?: Iterable<TK | AVLTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>,
       opts?: BSTOptions<TK, TV, TR>
     ) => AVLTree<TK, TV, TR>;
     return new Ctor(iter, { ...this._snapshotOptions<TK, TV, TR>(), ...(options ?? {}) });

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

@@ -203,6 +203,7 @@ export class BinaryTreeNode<K = any, V = any> {
  * 3. Depth and Height: Depth is the number of edges from the root to a node; height is the maximum depth in the tree.
  * 4. Subtrees: Each child of a node forms the root of a subtree.
  * 5. Leaf Nodes: Nodes without children are leaves.
+ *
  * @example
  * // determine loan approval using a decision tree
  *     // Decision tree structure
@@ -1673,7 +1674,7 @@ export class BinaryTree<K = any, V = any, R = any>
   filter(predicate: EntryCallback<K, V | undefined, boolean>, thisArg?: unknown): this {
     const out = this._createInstance<K, V, R>();
     let i = 0;
-    for (const [k, v] of this) if (predicate.call(thisArg, k, v, i++, this)) out.add([k, v]);
+    for (const [k, v] of this) if (predicate.call(thisArg, v, k, i++, this)) out.add([k, v]);
     return out;
   }
 
@@ -1696,7 +1697,7 @@ export class BinaryTree<K = any, V = any, R = any>
   ): BinaryTree<MK, MV, MR> {
     const out = this._createLike<MK, MV, MR>([], options);
     let i = 0;
-    for (const [k, v] of this) out.add(cb.call(thisArg, k, v, i++, this));
+    for (const [k, v] of this) out.add(cb.call(thisArg, v, k, i++, this));
     return out;
   }
 

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

@@ -16,12 +16,14 @@ import type {
   CP,
   DFSOrderPattern,
   EntryCallback,
+  FamilyPosition,
   IterationType,
   NodeCallback,
   NodePredicate,
-  OptNode
+  OptNode,
+  RBTNColor
 } from '../../types';
-import { BinaryTree, BinaryTreeNode } from './binary-tree';
+import { BinaryTree } from './binary-tree';
 import { IBinaryTree } from '../../interfaces';
 import { Queue } from '../queue';
 import { isComparable } from '../../utils';
@@ -33,8 +35,10 @@ import { Range } from '../../common';
  * @template K - The type of the key.
  * @template V - The type of the value.
  */
-export class BSTNode<K = any, V = any> extends BinaryTreeNode<K, V> {
-  override parent?: BSTNode<K, V> = undefined;
+export class BSTNode<K = any, V = any> {
+  key: K;
+  value?: V;
+  parent?: BSTNode<K, V> = undefined;
 
   /**
    * Creates an instance of BSTNode.
@@ -44,10 +48,11 @@ export class BSTNode<K = any, V = any> extends BinaryTreeNode<K, V> {
    * @param [value] - The value associated with the key.
    */
   constructor(key: K, value?: V) {
-    super(key, value);
+    this.key = key;
+    this.value = value;
   }
 
-  override _left?: BSTNode<K, V> | null | undefined = undefined;
+  _left?: BSTNode<K, V> | null | undefined = undefined;
 
   /**
    * Gets the left child of the node.
@@ -55,7 +60,7 @@ export class BSTNode<K = any, V = any> extends BinaryTreeNode<K, V> {
    *
    * @returns The left child.
    */
-  override get left(): BSTNode<K, V> | null | undefined {
+  get left(): BSTNode<K, V> | null | undefined {
     return this._left;
   }
 
@@ -65,12 +70,12 @@ export class BSTNode<K = any, V = any> extends BinaryTreeNode<K, V> {
    *
    * @param v - The node to set as the left child.
    */
-  override set left(v: BSTNode<K, V> | null | undefined) {
+  set left(v: BSTNode<K, V> | null | undefined) {
     if (v) v.parent = this;
     this._left = v;
   }
 
-  override _right?: BSTNode<K, V> | null | undefined = undefined;
+  _right?: BSTNode<K, V> | null | undefined = undefined;
 
   /**
    * Gets the right child of the node.
@@ -78,7 +83,7 @@ export class BSTNode<K = any, V = any> extends BinaryTreeNode<K, V> {
    *
    * @returns The right child.
    */
-  override get right(): BSTNode<K, V> | null | undefined {
+  get right(): BSTNode<K, V> | null | undefined {
     return this._right;
   }
 
@@ -88,10 +93,96 @@ export class BSTNode<K = any, V = any> extends BinaryTreeNode<K, V> {
    *
    * @param v - The node to set as the right child.
    */
-  override set right(v: BSTNode<K, V> | null | undefined) {
+  set right(v: BSTNode<K, V> | null | undefined) {
     if (v) v.parent = this;
     this._right = v;
   }
+
+  _height: number = 0;
+
+  /**
+   * Gets the height of the node (used in self-balancing trees).
+   * @remarks Time O(1), Space O(1)
+   *
+   * @returns The height.
+   */
+  get height(): number {
+    return this._height;
+  }
+
+  /**
+   * Sets the height of the node.
+   * @remarks Time O(1), Space O(1)
+   *
+   * @param value - The new height.
+   */
+  set height(value: number) {
+    this._height = value;
+  }
+
+  _color: RBTNColor = 'BLACK';
+
+  /**
+   * Gets the color of the node (used in Red-Black trees).
+   * @remarks Time O(1), Space O(1)
+   *
+   * @returns The node's color.
+   */
+  get color(): RBTNColor {
+    return this._color;
+  }
+
+  /**
+   * Sets the color of the node.
+   * @remarks Time O(1), Space O(1)
+   *
+   * @param value - The new color.
+   */
+  set color(value: RBTNColor) {
+    this._color = value;
+  }
+
+  _count: number = 1;
+
+  /**
+   * Gets the count of nodes in the subtree rooted at this node (used in order-statistic trees).
+   * @remarks Time O(1), Space O(1)
+   *
+   * @returns The subtree node count.
+   */
+  get count(): number {
+    return this._count;
+  }
+
+  /**
+   * Sets the count of nodes in the subtree.
+   * @remarks Time O(1), Space O(1)
+   *
+   * @param value - The new count.
+   */
+  set count(value: number) {
+    this._count = value;
+  }
+
+  /**
+   * Gets the position of the node relative to its parent.
+   * @remarks Time O(1), Space O(1)
+   *
+   * @returns The family position (e.g., 'ROOT', 'LEFT', 'RIGHT').
+   */
+  get familyPosition(): FamilyPosition {
+    if (!this.parent) {
+      return this.left || this.right ? 'ROOT' : 'ISOLATED';
+    }
+
+    if (this.parent.left === this) {
+      return this.left || this.right ? 'ROOT_LEFT' : 'LEFT';
+    } else if (this.parent.right === this) {
+      return this.left || this.right ? 'ROOT_RIGHT' : 'RIGHT';
+    }
+
+    return 'MAL_NODE';
+  }
 }
 
 /**
@@ -108,6 +199,7 @@ export class BSTNode<K = any, V = any> extends BinaryTreeNode<K, V> {
  * 5. Logarithmic Operations: Ideal operations like insertion, deletion, and searching are O(log n) time-efficient.
  * 6. Balance Variability: Can become unbalanced; special types maintain balance.
  * 7. No Auto-Balancing: Standard BSTs don't automatically balance themselves.
+ *
  * @example
  * // Merge 3 sorted datasets
  *     const dataset1 = new BST<number, string>([
@@ -817,7 +909,7 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     let index = 0;
     // Iterates in-order
     for (const [key, value] of this) {
-      out.add(callback.call(thisArg, key, value, index++, this));
+      out.add(callback.call(thisArg, value, key, index++, this));
     }
     return out;
   }