tree-multimap-typed 2.1.1 → 2.2.0

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

@@ -390,7 +390,7 @@ export class BinaryTree<K = any, V = any, R = any>
    * @param [value] - The value for the new node (used if not in Map mode).
    * @returns The newly created node.
    */
-  _createNode(key: K, value?: V): BinaryTreeNode<K, V> {
+  createNode(key: K, value?: V): BinaryTreeNode<K, V> {
     return new BinaryTreeNode<K, V>(key, this._isMapMode ? undefined : value);
   }
 
@@ -2019,10 +2019,10 @@ export class BinaryTree<K = any, V = any, R = any>
       if (key === undefined) return [undefined, undefined];
       else if (key === null) return [null, undefined];
       const finalValue = value ?? entryValue;
-      return [this._createNode(key, finalValue), finalValue];
+      return [this.createNode(key, finalValue), finalValue];
     }
 
-    return [this._createNode(keyNodeOrEntry, value), value];
+    return [this.createNode(keyNodeOrEntry, value), value];
   }
 
   /**
@@ -2147,7 +2147,7 @@ export class BinaryTree<K = any, V = any, R = any>
 
     if (srcNode && destNode) {
       const { key, value } = destNode;
-      const tempNode = this._createNode(key, value); // Use a temp node to hold dest properties
+      const tempNode = this.createNode(key, value); // Use a temp node to hold dest properties
 
       if (tempNode) {
         // Copy src to dest

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';
+  }
 }
 
 /**
@@ -268,7 +359,7 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    * @param [value] - The value for the new node (used if not in Map mode).
    * @returns The newly created BSTNode.
    */
-  override _createNode(key: K, value?: V): BSTNode<K, V> {
+  override createNode(key: K, value?: V): BSTNode<K, V> {
     return new BSTNode<K, V>(key, this._isMapMode ? undefined : value);
   }
 

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

@@ -11,15 +11,18 @@ import type {
   BinaryTreeOptions,
   CRUD,
   EntryCallback,
+  FamilyPosition,
   OptNode,
   RBTNColor,
   RedBlackTreeOptions
 } from '../../types';
-import { BST, BSTNode } from './bst';
+import { BST } from './bst';
 import { IBinaryTree } from '../../interfaces';
 
-export class RedBlackTreeNode<K = any, V = any> extends BSTNode<K, V> {
-  override parent?: RedBlackTreeNode<K, V> = undefined;
+export class RedBlackTreeNode<K = any, V = any> {
+  key: K;
+  value?: V;
+  parent?: RedBlackTreeNode<K, V> = undefined;
 
   /**
    * Create a Red-Black Tree and optionally bulk-insert items.
@@ -31,11 +34,12 @@ export class RedBlackTreeNode<K = any, V = any> extends BSTNode<K, V> {
    */
 
   constructor(key: K, value?: V, color: RBTNColor = 'BLACK') {
-    super(key, value);
-    this._color = color;
+    this.key = key;
+    this.value = value;
+    this.color = color;
   }
 
-  override _left?: RedBlackTreeNode<K, V> | null | undefined = undefined;
+  _left?: RedBlackTreeNode<K, V> | null | undefined = undefined;
 
   /**
    * Get the left child pointer.
@@ -43,7 +47,7 @@ export class RedBlackTreeNode<K = any, V = any> extends BSTNode<K, V> {
    * @returns Left child node, or null/undefined.
    */
 
-  override get left(): RedBlackTreeNode<K, V> | null | undefined {
+  get left(): RedBlackTreeNode<K, V> | null | undefined {
     return this._left;
   }
 
@@ -54,14 +58,14 @@ export class RedBlackTreeNode<K = any, V = any> extends BSTNode<K, V> {
    * @returns void
    */
 
-  override set left(v: RedBlackTreeNode<K, V> | null | undefined) {
+  set left(v: RedBlackTreeNode<K, V> | null | undefined) {
     if (v) {
       v.parent = this;
     }
     this._left = v;
   }
 
-  override _right?: RedBlackTreeNode<K, V> | null | undefined = undefined;
+  _right?: RedBlackTreeNode<K, V> | null | undefined = undefined;
 
   /**
    * Get the right child pointer.
@@ -69,7 +73,7 @@ export class RedBlackTreeNode<K = any, V = any> extends BSTNode<K, V> {
    * @returns Right child node, or null/undefined.
    */
 
-  override get right(): RedBlackTreeNode<K, V> | null | undefined {
+  get right(): RedBlackTreeNode<K, V> | null | undefined {
     return this._right;
   }
 
@@ -80,21 +84,107 @@ export class RedBlackTreeNode<K = any, V = any> extends BSTNode<K, V> {
    * @returns void
    */
 
-  override set right(v: RedBlackTreeNode<K, V> | null | undefined) {
+  set right(v: RedBlackTreeNode<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';
+  }
 }
 
 /**
- * RRRRRRRRRRRRRRRRRRRed-Black Tree (self-balancing BST) supporting map-like mode and stable O(log n) updates.
+ * Represents a Red-Black Tree (self-balancing BST) supporting map-like mode and stable O(log n) updates.
  * @remarks Time O(1), Space O(1)
  * @template K
  * @template V
  * @template R
- * 1. Efficient self-balancing, but not completely balanced. Compared with AVLTree, the addition and deletion efficiency is high but the query efficiency is slightly lower.
+ * 1. Efficient self-balancing, but not completely balanced. Compared with AVLTree, the addition and deletion efficiency is high, but the query efficiency is slightly lower.
  * 2. It is BST itself. Compared with Heap which is not completely ordered, RedBlackTree is completely ordered.
  * @example
  * // using Red-Black Tree as a price-based index for stock data
@@ -176,7 +266,7 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
    * @param color - See parameter type for details.
    * @returns A new RedBlackTreeNode instance.
    */
-  override _createNode(key: K, value?: V, color: RBTNColor = 'BLACK'): RedBlackTreeNode<K, V> {
+  override createNode(key: K, value?: V, color: RBTNColor = 'BLACK'): RedBlackTreeNode<K, V> {
     return new RedBlackTreeNode<K, V>(key, this._isMapMode ? undefined : value, color);
   }
 
@@ -380,10 +470,10 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
    */
 
   protected _insert(node: RedBlackTreeNode<K, V>): CRUD {
-    let current = this.root;
+    let current = this.root ?? this.NIL;
     let parent: RedBlackTreeNode<K, V> | undefined = undefined;
 
-    while (this.isRealNode(current)) {
+    while (current !== this.NIL) {
       parent = current;
       const compared = this._compare(node.key, current.key);
       if (compared < 0) {
@@ -459,7 +549,7 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
             this._leftRotate(z);
           }
 
-          if (z && this.isRealNode(z.parent) && this.isRealNode(z.parent.parent)) {
+          if (z && z.parent && z.parent.parent) {
             z.parent.color = 'BLACK';
             z.parent.parent.color = 'RED';
             this._rightRotate(z.parent.parent);
@@ -478,7 +568,7 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
             this._rightRotate(z);
           }
 
-          if (z && this.isRealNode(z.parent) && this.isRealNode(z.parent.parent)) {
+          if (z && z.parent && z.parent.parent) {
             z.parent.color = 'BLACK';
             z.parent.parent.color = 'RED';
             this._leftRotate(z.parent.parent);
@@ -575,7 +665,7 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
     const y = x.right;
     x.right = y.left;
 
-    if (this.isRealNode(y.left)) {
+    if (y.left && y.left !== this.NIL) {
       y.left.parent = x;
     }
 
@@ -608,7 +698,7 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
     const x = y.left;
     y.left = x.right;
 
-    if (this.isRealNode(x.right)) {
+    if (x.right && x.right !== this.NIL) {
       x.right.parent = y;
     }
 

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

@@ -11,6 +11,7 @@ import type {
   BinaryTreeOptions,
   BSTNOptKeyOrNode,
   EntryCallback,
+  FamilyPosition,
   IterationType,
   OptNode,
   RBTNColor,
@@ -19,7 +20,7 @@ import type {
 import { BSTOptions } from '../../types';
 import { BSTNode } from './bst';
 import { IBinaryTree } from '../../interfaces';
-import { RedBlackTree, RedBlackTreeNode } from './red-black-tree';
+import { RedBlackTree } from './red-black-tree';
 
 /**
  * RB-tree node with an extra 'count' field; keeps parent/child links.
@@ -27,8 +28,10 @@ import { RedBlackTree, RedBlackTreeNode } from './red-black-tree';
  * @template K
  * @template V
  */
-export class TreeCounterNode<K = any, V = any> extends RedBlackTreeNode<K, V> {
-  override parent?: TreeCounterNode<K, V> = undefined;
+export class TreeCounterNode<K = any, V = any> {
+  key: K;
+  value?: V;
+  parent?: TreeCounterNode<K, V> = undefined;
 
   /**
    * Create a tree counter node.
@@ -40,18 +43,20 @@ export class TreeCounterNode<K = any, V = any> extends RedBlackTreeNode<K, V> {
    * @returns New TreeCounterNode instance.
    */
   constructor(key: K, value?: V, count = 1, color: RBTNColor = 'BLACK') {
-    super(key, value, color);
+    this.key = key;
+    this.value = value;
+    this.color = color;
     this.count = count;
   }
 
-  override _left?: TreeCounterNode<K, V> | null | undefined = undefined;
+  _left?: TreeCounterNode<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(): TreeCounterNode<K, V> | null | undefined {
+  get left(): TreeCounterNode<K, V> | null | undefined {
     return this._left;
   }
 
@@ -61,21 +66,21 @@ export class TreeCounterNode<K = any, V = any> extends RedBlackTreeNode<K, V> {
    * @param v - New left child node, or null/undefined.
    * @returns void
    */
-  override set left(v: TreeCounterNode<K, V> | null | undefined) {
+  set left(v: TreeCounterNode<K, V> | null | undefined) {
     if (v) {
       v.parent = this;
     }
     this._left = v;
   }
 
-  override _right?: TreeCounterNode<K, V> | null | undefined = undefined;
+  _right?: TreeCounterNode<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(): TreeCounterNode<K, V> | null | undefined {
+  get right(): TreeCounterNode<K, V> | null | undefined {
     return this._right;
   }
 
@@ -85,12 +90,98 @@ export class TreeCounterNode<K = any, V = any> extends RedBlackTreeNode<K, V> {
    * @param v - New right child node, or null/undefined.
    * @returns void
    */
-  override set right(v: TreeCounterNode<K, V> | null | undefined) {
+  set right(v: TreeCounterNode<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';
+  }
 }
 
 /**
@@ -142,7 +233,7 @@ export class TreeCounter<K = any, V = any, R = any> extends RedBlackTree<K, V, R
     return sum;
   }
 
-  override _createNode(key: K, value?: V, color: RBTNColor = 'BLACK', count?: number): TreeCounterNode<K, V> {
+  override createNode(key: K, value?: V, color: RBTNColor = 'BLACK', count?: number): TreeCounterNode<K, V> {
     return new TreeCounterNode(key, this._isMapMode ? undefined : value, count, color) as TreeCounterNode<K, V>;
   }
 
@@ -427,10 +518,10 @@ export class TreeCounter<K = any, V = any, R = any> extends RedBlackTree<K, V, R
       const [key, entryValue] = keyNodeOrEntry;
       if (key === undefined || key === null) return [undefined, undefined];
       const finalValue = value ?? entryValue;
-      return [this._createNode(key, finalValue, 'BLACK', count), finalValue];
+      return [this.createNode(key, finalValue, 'BLACK', count), finalValue];
     }
 
-    return [this._createNode(keyNodeOrEntry, value, 'BLACK', count), value];
+    return [this.createNode(keyNodeOrEntry, value, 'BLACK', count), value];
   }
 
   /**
@@ -448,7 +539,7 @@ export class TreeCounter<K = any, V = any, R = any> extends RedBlackTree<K, V, R
     destNode = this.ensureNode(destNode);
     if (srcNode && destNode) {
       const { key, value, count, color } = destNode;
-      const tempNode = this._createNode(key, value, color, count);
+      const tempNode = this.createNode(key, value, color, count);
       if (tempNode) {
         tempNode.color = color;