bst-typed 2.5.1 → 2.5.2

package/dist/umd/bst-typed.js

@@ -29,7 +29,8 @@ var bstTyped = (() => {
     BinaryTreeNode: () => BinaryTreeNode,
     DFSOperation: () => DFSOperation,
     ERR: () => ERR,
-    Range: () => Range
+    Range: () => Range,
+    raise: () => raise
   });
 
   // src/utils/utils.ts
@@ -83,6 +84,57 @@ var bstTyped = (() => {
     return (...args) => trampoline(fn(...args));
   }
 
+  // src/common/error.ts
+  function raise(ErrorClass, message) {
+    throw new ErrorClass(message);
+  }
+  var ERR = {
+    // Range / index
+    indexOutOfRange: (index, min, max, ctx) => `${ctx ? ctx + ": " : ""}Index ${index} is out of range [${min}, ${max}].`,
+    invalidIndex: (ctx) => `${ctx ? ctx + ": " : ""}Index must be an integer.`,
+    // Type / argument
+    invalidArgument: (reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`,
+    comparatorRequired: (ctx) => `${ctx ? ctx + ": " : ""}Comparator is required for non-number/non-string/non-Date keys.`,
+    invalidKey: (reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`,
+    notAFunction: (name, ctx) => `${ctx ? ctx + ": " : ""}${name} must be a function.`,
+    invalidEntry: (ctx) => `${ctx ? ctx + ": " : ""}Each entry must be a [key, value] tuple.`,
+    invalidNaN: (ctx) => `${ctx ? ctx + ": " : ""}NaN is not a valid key.`,
+    invalidDate: (ctx) => `${ctx ? ctx + ": " : ""}Invalid Date key.`,
+    reduceEmpty: (ctx) => `${ctx ? ctx + ": " : ""}Reduce of empty structure with no initial value.`,
+    callbackReturnType: (expected, got, ctx) => `${ctx ? ctx + ": " : ""}Callback must return ${expected}; got ${got}.`,
+    // State / operation
+    invalidOperation: (reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`,
+    // Matrix
+    matrixDimensionMismatch: (op) => `Matrix: Dimensions must be compatible for ${op}.`,
+    matrixSingular: () => "Matrix: Singular matrix, inverse does not exist.",
+    matrixNotSquare: () => "Matrix: Must be square for inversion.",
+    matrixNotRectangular: () => "Matrix: Must be rectangular for transposition.",
+    matrixRowMismatch: (expected, got) => `Matrix: Expected row length ${expected}, but got ${got}.`,
+    // Order statistic
+    orderStatisticNotEnabled: (method, ctx) => `${ctx ? ctx + ": " : ""}${method}() requires enableOrderStatistic: true.`
+  };
+
+  // src/common/index.ts
+  var DFSOperation = /* @__PURE__ */ ((DFSOperation2) => {
+    DFSOperation2[DFSOperation2["VISIT"] = 0] = "VISIT";
+    DFSOperation2[DFSOperation2["PROCESS"] = 1] = "PROCESS";
+    return DFSOperation2;
+  })(DFSOperation || {});
+  var Range = class {
+    constructor(low, high, includeLow = true, includeHigh = true) {
+      this.low = low;
+      this.high = high;
+      this.includeLow = includeLow;
+      this.includeHigh = includeHigh;
+    }
+    // Determine whether a key is within the range
+    isInRange(key, comparator) {
+      const lowCheck = this.includeLow ? comparator(key, this.low) >= 0 : comparator(key, this.low) > 0;
+      const highCheck = this.includeHigh ? comparator(key, this.high) <= 0 : comparator(key, this.high) < 0;
+      return lowCheck && highCheck;
+    }
+  };
+
   // src/data-structures/base/iterable-element-base.ts
   var IterableElementBase = class {
     /**
@@ -105,7 +157,7 @@ var bstTyped = (() => {
       if (options) {
         const { toElementFn } = options;
         if (typeof toElementFn === "function") this._toElementFn = toElementFn;
-        else if (toElementFn) throw new TypeError("toElementFn must be a function type");
+        else if (toElementFn) raise(TypeError, "toElementFn must be a function type");
       }
     }
     /**
@@ -261,7 +313,7 @@ var bstTyped = (() => {
         acc = initialValue;
       } else {
         const first = iter.next();
-        if (first.done) throw new TypeError("Reduce of empty structure with no initial value");
+        if (first.done) raise(TypeError, "Reduce of empty structure with no initial value");
         acc = first.value;
         index = 1;
       }
@@ -493,52 +545,6 @@ var bstTyped = (() => {
     }
   };
 
-  // src/common/error.ts
-  var ERR = {
-    // Range / index
-    indexOutOfRange: (index, min, max, ctx) => `${ctx ? ctx + ": " : ""}Index ${index} is out of range [${min}, ${max}].`,
-    invalidIndex: (ctx) => `${ctx ? ctx + ": " : ""}Index must be an integer.`,
-    // Type / argument
-    invalidArgument: (reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`,
-    comparatorRequired: (ctx) => `${ctx ? ctx + ": " : ""}Comparator is required for non-number/non-string/non-Date keys.`,
-    invalidKey: (reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`,
-    notAFunction: (name, ctx) => `${ctx ? ctx + ": " : ""}${name} must be a function.`,
-    invalidEntry: (ctx) => `${ctx ? ctx + ": " : ""}Each entry must be a [key, value] tuple.`,
-    invalidNaN: (ctx) => `${ctx ? ctx + ": " : ""}NaN is not a valid key.`,
-    invalidDate: (ctx) => `${ctx ? ctx + ": " : ""}Invalid Date key.`,
-    reduceEmpty: (ctx) => `${ctx ? ctx + ": " : ""}Reduce of empty structure with no initial value.`,
-    callbackReturnType: (expected, got, ctx) => `${ctx ? ctx + ": " : ""}Callback must return ${expected}; got ${got}.`,
-    // State / operation
-    invalidOperation: (reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`,
-    // Matrix
-    matrixDimensionMismatch: (op) => `Matrix: Dimensions must be compatible for ${op}.`,
-    matrixSingular: () => "Matrix: Singular matrix, inverse does not exist.",
-    matrixNotSquare: () => "Matrix: Must be square for inversion.",
-    matrixNotRectangular: () => "Matrix: Must be rectangular for transposition.",
-    matrixRowMismatch: (expected, got) => `Matrix: Expected row length ${expected}, but got ${got}.`
-  };
-
-  // src/common/index.ts
-  var DFSOperation = /* @__PURE__ */ ((DFSOperation2) => {
-    DFSOperation2[DFSOperation2["VISIT"] = 0] = "VISIT";
-    DFSOperation2[DFSOperation2["PROCESS"] = 1] = "PROCESS";
-    return DFSOperation2;
-  })(DFSOperation || {});
-  var Range = class {
-    constructor(low, high, includeLow = true, includeHigh = true) {
-      this.low = low;
-      this.high = high;
-      this.includeLow = includeLow;
-      this.includeHigh = includeHigh;
-    }
-    // Determine whether a key is within the range
-    isInRange(key, comparator) {
-      const lowCheck = this.includeLow ? comparator(key, this.low) >= 0 : comparator(key, this.low) > 0;
-      const highCheck = this.includeHigh ? comparator(key, this.high) <= 0 : comparator(key, this.high) < 0;
-      return lowCheck && highCheck;
-    }
-  };
-
   // src/data-structures/base/iterable-entry-base.ts
   var IterableEntryBase = class {
     /**
@@ -803,6 +809,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -850,6 +859,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -913,6 +925,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -972,6 +987,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -1038,6 +1056,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -1094,6 +1115,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -1143,6 +1167,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -1233,6 +1260,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -1276,6 +1306,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -1342,6 +1375,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -1392,6 +1428,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -1446,6 +1485,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -1714,7 +1756,7 @@ var bstTyped = (() => {
         if (isMapMode !== void 0) this._isMapMode = isMapMode;
         if (isDuplicate !== void 0) this._isDuplicate = isDuplicate;
         if (typeof toEntryFn === "function") this._toEntryFn = toEntryFn;
-        else if (toEntryFn) throw new TypeError(ERR.notAFunction("toEntryFn", "BinaryTree"));
+        else if (toEntryFn) raise(TypeError, ERR.notAFunction("toEntryFn", "BinaryTree"));
       }
       if (keysNodesEntriesOrRaws) this.setMany(keysNodesEntriesOrRaws);
     }
@@ -1947,6 +1989,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -1998,6 +2043,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -2101,6 +2149,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -2140,6 +2191,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -2200,6 +2254,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -2259,6 +2316,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -2396,6 +2456,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -2451,6 +2514,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -2509,6 +2575,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -2554,6 +2623,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -2608,6 +2680,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -2689,6 +2764,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -2747,6 +2825,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -3221,6 +3302,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -3270,6 +3354,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -3323,6 +3410,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -3401,6 +3491,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -4019,6 +4112,7 @@ var bstTyped = (() => {
     constructor(keysNodesEntriesOrRaws = [], options) {
       super([], options);
       __publicField(this, "_root");
+      __publicField(this, "_enableOrderStatistic", false);
       /**
          * The comparator function used to determine the order of keys in the tree.
       
@@ -4031,6 +4125,9 @@ var bstTyped = (() => {
         } else {
           this._comparator = this._createDefaultComparator();
         }
+        if (options.enableOrderStatistic) {
+          this._enableOrderStatistic = true;
+        }
       } else {
         this._comparator = this._createDefaultComparator();
       }
@@ -4200,6 +4297,12 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
+      
+      
+      
       
       
       
@@ -4362,6 +4465,85 @@ var bstTyped = (() => {
       const searchRange = range instanceof Range ? range : new Range(range[0], range[1]);
       return this.search(searchRange, false, callback, startNode, iterationType);
     }
+    getByRank(k, callback = this._DEFAULT_NODE_CALLBACK, iterationType = this.iterationType) {
+      if (!this._enableOrderStatistic) {
+        raise(Error, ERR.orderStatisticNotEnabled("getByRank"));
+      }
+      if (k < 0 || k >= this._size) return void 0;
+      let actualCallback = void 0;
+      let actualIterationType = this.iterationType;
+      if (typeof callback === "string") {
+        actualIterationType = callback;
+      } else if (callback) {
+        actualCallback = callback;
+        if (iterationType) {
+          actualIterationType = iterationType;
+        }
+      }
+      const node = actualIterationType === "RECURSIVE" ? this._getByRankRecursive(this._root, k) : this._getByRankIterative(this._root, k);
+      if (!node) return void 0;
+      return actualCallback ? actualCallback(node) : node.key;
+    }
+    getRank(keyNodeEntryOrPredicate, iterationType = this.iterationType) {
+      var _a;
+      if (!this._enableOrderStatistic) {
+        raise(Error, ERR.orderStatisticNotEnabled("getRank"));
+      }
+      if (!this._root || this._size === 0) return -1;
+      let actualIterationType = this.iterationType;
+      if (iterationType) actualIterationType = iterationType;
+      let key;
+      if (typeof keyNodeEntryOrPredicate === "function") {
+        const results = this.search(keyNodeEntryOrPredicate, true);
+        if (results.length === 0 || results[0] === void 0) return -1;
+        key = results[0];
+      } else if (keyNodeEntryOrPredicate === null || keyNodeEntryOrPredicate === void 0) {
+        return -1;
+      } else if (this.isNode(keyNodeEntryOrPredicate)) {
+        key = keyNodeEntryOrPredicate.key;
+      } else if (Array.isArray(keyNodeEntryOrPredicate)) {
+        key = (_a = keyNodeEntryOrPredicate[0]) != null ? _a : void 0;
+        if (key === void 0 || key === null) return -1;
+      } else {
+        key = keyNodeEntryOrPredicate;
+      }
+      if (key === void 0) return -1;
+      return actualIterationType === "RECURSIVE" ? this._getRankRecursive(this._root, key) : this._getRankIterative(this._root, key);
+    }
+    rangeByRank(start, end, callback = this._DEFAULT_NODE_CALLBACK, iterationType = this.iterationType) {
+      if (!this._enableOrderStatistic) {
+        raise(Error, ERR.orderStatisticNotEnabled("rangeByRank"));
+      }
+      if (this._size === 0) return [];
+      const lo = Math.max(0, start);
+      const hi = Math.min(this._size - 1, end);
+      if (lo > hi) return [];
+      let actualCallback = void 0;
+      let actualIterationType = this.iterationType;
+      if (typeof callback === "string") {
+        actualIterationType = callback;
+      } else if (callback) {
+        actualCallback = callback;
+        if (iterationType) {
+          actualIterationType = iterationType;
+        }
+      }
+      const results = [];
+      const count = hi - lo + 1;
+      const startNode = actualIterationType === "RECURSIVE" ? this._getByRankRecursive(this._root, lo) : this._getByRankIterative(this._root, lo);
+      if (!startNode) return [];
+      let collected = 0;
+      const cb = actualCallback != null ? actualCallback : this._DEFAULT_NODE_CALLBACK;
+      let current = startNode;
+      while (current && collected < count) {
+        results.push(cb(current));
+        collected++;
+        if (collected < count) {
+          current = this._next(current);
+        }
+      }
+      return results;
+    }
     /**
       * Adds a new node to the BST based on key comparison.
       * @remarks Time O(log N), where H is tree height. O(N) worst-case (unbalanced tree), O(log N) average. Space O(1).
@@ -4447,6 +4629,15 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
+      
+      
+      
+      
+      
+      
       
       
       
@@ -4471,6 +4662,7 @@ var bstTyped = (() => {
         this._setRoot(newNode);
         if (this._isMapMode && this.isRealNode(newNode)) this._store.set(newNode.key, newNode);
         this._size++;
+        this._updateCount(newNode);
         return true;
       }
       let current = this._root;
@@ -4484,6 +4676,7 @@ var bstTyped = (() => {
             current.left = newNode;
             if (this._isMapMode && this.isRealNode(newNode)) this._store.set(newNode.key, newNode);
             this._size++;
+            this._updateCountAlongPath(newNode);
             return true;
           }
           if (current.left !== null) current = current.left;
@@ -4492,6 +4685,7 @@ var bstTyped = (() => {
             current.right = newNode;
             if (this._isMapMode && this.isRealNode(newNode)) this._store.set(newNode.key, newNode);
             this._size++;
+            this._updateCountAlongPath(newNode);
             return true;
           }
           if (current.right !== null) current = current.right;
@@ -4556,6 +4750,12 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
+      
+      
+      
       
       
       
@@ -4843,6 +5043,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -4909,6 +5112,9 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
       
       
       
@@ -5022,6 +5228,12 @@ var bstTyped = (() => {
       
       
       
+      
+      
+      
+      
+      
+      
       
       
       
@@ -5103,13 +5315,11 @@ var bstTyped = (() => {
         if (a instanceof Date && b instanceof Date) {
           const ta = a.getTime();
           const tb = b.getTime();
-          if (Number.isNaN(ta) || Number.isNaN(tb)) throw new TypeError(ERR.invalidDate("BST"));
+          if (Number.isNaN(ta) || Number.isNaN(tb)) raise(TypeError, ERR.invalidDate("BST"));
           return ta > tb ? 1 : ta < tb ? -1 : 0;
         }
         if (typeof a === "object" || typeof b === "object") {
-          throw new TypeError(
-            ERR.comparatorRequired("BST")
-          );
+          raise(TypeError, ERR.comparatorRequired("BST"));
         }
         return 0;
       };
@@ -5431,7 +5641,8 @@ var bstTyped = (() => {
     _snapshotOptions() {
       return {
         ...super._snapshotOptions(),
-        comparator: this._comparator
+        comparator: this._comparator,
+        enableOrderStatistic: this._enableOrderStatistic
       };
     }
     /**
@@ -5453,6 +5664,113 @@ var bstTyped = (() => {
      *
      * @param v - The node to set as root.
      */
+    /**
+     * (Protected) Recalculates the subtree count for a single node.
+     * @remarks Time O(1). Only active when enableOrderStatistic is true.
+     */
+    _updateCount(node) {
+      if (!this._enableOrderStatistic) return;
+      node._count = 1 + (this.isRealNode(node.left) ? node.left._count : 0) + (this.isRealNode(node.right) ? node.right._count : 0);
+    }
+    /**
+     * (Protected) Updates subtree counts from a node up to the root.
+     * @remarks Time O(log n). Only active when enableOrderStatistic is true.
+     */
+    _updateCountAlongPath(node) {
+      if (!this._enableOrderStatistic) return;
+      let current = node;
+      while (current) {
+        this._updateCount(current);
+        current = current.parent;
+      }
+    }
+    /**
+     * (Protected) Finds the node at position k in tree order (iterative).
+     * @remarks Time O(log n), Space O(1)
+     */
+    _getByRankIterative(node, k) {
+      let current = node;
+      let remaining = k;
+      while (current) {
+        const leftCount = this.isRealNode(current.left) ? current.left._count : 0;
+        if (remaining < leftCount) {
+          current = current.left;
+        } else if (remaining === leftCount) {
+          return current;
+        } else {
+          remaining = remaining - leftCount - 1;
+          current = current.right;
+        }
+      }
+      return void 0;
+    }
+    /**
+     * (Protected) Finds the node at position k in tree order (recursive).
+     * @remarks Time O(log n), Space O(log n) call stack
+     */
+    _getByRankRecursive(node, k) {
+      if (!node) return void 0;
+      const leftCount = this.isRealNode(node.left) ? node.left._count : 0;
+      if (k < leftCount) return this._getByRankRecursive(node.left, k);
+      if (k === leftCount) return node;
+      return this._getByRankRecursive(node.right, k - leftCount - 1);
+    }
+    /**
+     * (Protected) Computes the rank of a key iteratively.
+     * @remarks Time O(log n), Space O(1)
+     */
+    _getRankIterative(node, key) {
+      let rank = 0;
+      let current = node;
+      while (this.isRealNode(current)) {
+        const cmp = this._compare(current.key, key);
+        if (cmp > 0) {
+          current = current.left;
+        } else if (cmp < 0) {
+          rank += (this.isRealNode(current.left) ? current.left._count : 0) + 1;
+          current = current.right;
+        } else {
+          rank += this.isRealNode(current.left) ? current.left._count : 0;
+          return rank;
+        }
+      }
+      return rank;
+    }
+    /**
+     * (Protected) Computes the rank of a key recursively.
+     * @remarks Time O(log n), Space O(log n) call stack
+     */
+    _getRankRecursive(node, key) {
+      if (!node) return 0;
+      const cmp = this._compare(node.key, key);
+      if (cmp > 0) {
+        return this._getRankRecursive(node.left, key);
+      } else if (cmp < 0) {
+        return (this.isRealNode(node.left) ? node.left._count : 0) + 1 + this._getRankRecursive(node.right, key);
+      } else {
+        return this.isRealNode(node.left) ? node.left._count : 0;
+      }
+    }
+    /**
+     * (Protected) Finds the in-order successor of a node.
+     * @remarks Time O(log n), Space O(1)
+     */
+    _next(node) {
+      if (this.isRealNode(node.right)) {
+        let current2 = node.right;
+        while (this.isRealNode(current2.left)) {
+          current2 = current2.left;
+        }
+        return current2;
+      }
+      let current = node;
+      let parent = current.parent;
+      while (parent && current === parent.right) {
+        current = parent;
+        parent = parent.parent;
+      }
+      return parent;
+    }
     _setRoot(v) {
       if (v) v.parent = void 0;
       this._root = v;
@@ -5499,21 +5817,28 @@ var bstTyped = (() => {
         while (x.left !== void 0 && x.left !== null) x = x.left;
         return x;
       };
+      let countUpdateStart;
       if (node.left === void 0) {
+        countUpdateStart = node.parent;
         transplant(node, node.right);
       } else if (node.right === void 0) {
+        countUpdateStart = node.parent;
         transplant(node, node.left);
       } else {
         const succ = minNode(node.right);
         if (succ.parent !== node) {
+          countUpdateStart = succ.parent;
           transplant(succ, succ.right);
           succ.right = node.right;
           if (succ.right) succ.right.parent = succ;
+        } else {
+          countUpdateStart = succ;
         }
         transplant(node, succ);
         succ.left = node.left;
         if (succ.left) succ.left.parent = succ;
       }
+      this._updateCountAlongPath(countUpdateStart);
       this._size = Math.max(0, this._size - 1);
       return true;
     }