bst-typed 2.5.0 → 2.5.2

package/dist/cjs-legacy/index.cjs

@@ -61,6 +61,60 @@ function makeTrampoline(fn) {
 }
 __name(makeTrampoline, "makeTrampoline");
 
+// src/common/error.ts
+function raise(ErrorClass, message) {
+  throw new ErrorClass(message);
+}
+__name(raise, "raise");
+var ERR = {
+  // Range / index
+  indexOutOfRange: /* @__PURE__ */ __name((index, min, max, ctx) => `${ctx ? ctx + ": " : ""}Index ${index} is out of range [${min}, ${max}].`, "indexOutOfRange"),
+  invalidIndex: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Index must be an integer.`, "invalidIndex"),
+  // Type / argument
+  invalidArgument: /* @__PURE__ */ __name((reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`, "invalidArgument"),
+  comparatorRequired: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Comparator is required for non-number/non-string/non-Date keys.`, "comparatorRequired"),
+  invalidKey: /* @__PURE__ */ __name((reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`, "invalidKey"),
+  notAFunction: /* @__PURE__ */ __name((name, ctx) => `${ctx ? ctx + ": " : ""}${name} must be a function.`, "notAFunction"),
+  invalidEntry: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Each entry must be a [key, value] tuple.`, "invalidEntry"),
+  invalidNaN: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}NaN is not a valid key.`, "invalidNaN"),
+  invalidDate: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Invalid Date key.`, "invalidDate"),
+  reduceEmpty: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Reduce of empty structure with no initial value.`, "reduceEmpty"),
+  callbackReturnType: /* @__PURE__ */ __name((expected, got, ctx) => `${ctx ? ctx + ": " : ""}Callback must return ${expected}; got ${got}.`, "callbackReturnType"),
+  // State / operation
+  invalidOperation: /* @__PURE__ */ __name((reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`, "invalidOperation"),
+  // Matrix
+  matrixDimensionMismatch: /* @__PURE__ */ __name((op) => `Matrix: Dimensions must be compatible for ${op}.`, "matrixDimensionMismatch"),
+  matrixSingular: /* @__PURE__ */ __name(() => "Matrix: Singular matrix, inverse does not exist.", "matrixSingular"),
+  matrixNotSquare: /* @__PURE__ */ __name(() => "Matrix: Must be square for inversion.", "matrixNotSquare"),
+  matrixNotRectangular: /* @__PURE__ */ __name(() => "Matrix: Must be rectangular for transposition.", "matrixNotRectangular"),
+  matrixRowMismatch: /* @__PURE__ */ __name((expected, got) => `Matrix: Expected row length ${expected}, but got ${got}.`, "matrixRowMismatch"),
+  // Order statistic
+  orderStatisticNotEnabled: /* @__PURE__ */ __name((method, ctx) => `${ctx ? ctx + ": " : ""}${method}() requires enableOrderStatistic: true.`, "orderStatisticNotEnabled")
+};
+
+// src/common/index.ts
+var DFSOperation = /* @__PURE__ */ ((DFSOperation2) => {
+  DFSOperation2[DFSOperation2["VISIT"] = 0] = "VISIT";
+  DFSOperation2[DFSOperation2["PROCESS"] = 1] = "PROCESS";
+  return DFSOperation2;
+})(DFSOperation || {});
+var _Range = class _Range {
+  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;
+  }
+};
+__name(_Range, "Range");
+var Range = _Range;
+
 // src/data-structures/base/iterable-element-base.ts
 var _IterableElementBase = class _IterableElementBase {
   /**
@@ -83,7 +137,7 @@ var _IterableElementBase = class _IterableElementBase {
     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");
     }
   }
   /**
@@ -239,7 +293,7 @@ var _IterableElementBase = class _IterableElementBase {
       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;
     }
@@ -475,54 +529,6 @@ var _LinearBase = class _LinearBase extends IterableElementBase {
 __name(_LinearBase, "LinearBase");
 var LinearBase = _LinearBase;
 
-// src/common/error.ts
-var ERR = {
-  // Range / index
-  indexOutOfRange: /* @__PURE__ */ __name((index, min, max, ctx) => `${ctx ? ctx + ": " : ""}Index ${index} is out of range [${min}, ${max}].`, "indexOutOfRange"),
-  invalidIndex: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Index must be an integer.`, "invalidIndex"),
-  // Type / argument
-  invalidArgument: /* @__PURE__ */ __name((reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`, "invalidArgument"),
-  comparatorRequired: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Comparator is required for non-number/non-string/non-Date keys.`, "comparatorRequired"),
-  invalidKey: /* @__PURE__ */ __name((reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`, "invalidKey"),
-  notAFunction: /* @__PURE__ */ __name((name, ctx) => `${ctx ? ctx + ": " : ""}${name} must be a function.`, "notAFunction"),
-  invalidEntry: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Each entry must be a [key, value] tuple.`, "invalidEntry"),
-  invalidNaN: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}NaN is not a valid key.`, "invalidNaN"),
-  invalidDate: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Invalid Date key.`, "invalidDate"),
-  reduceEmpty: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Reduce of empty structure with no initial value.`, "reduceEmpty"),
-  callbackReturnType: /* @__PURE__ */ __name((expected, got, ctx) => `${ctx ? ctx + ": " : ""}Callback must return ${expected}; got ${got}.`, "callbackReturnType"),
-  // State / operation
-  invalidOperation: /* @__PURE__ */ __name((reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`, "invalidOperation"),
-  // Matrix
-  matrixDimensionMismatch: /* @__PURE__ */ __name((op) => `Matrix: Dimensions must be compatible for ${op}.`, "matrixDimensionMismatch"),
-  matrixSingular: /* @__PURE__ */ __name(() => "Matrix: Singular matrix, inverse does not exist.", "matrixSingular"),
-  matrixNotSquare: /* @__PURE__ */ __name(() => "Matrix: Must be square for inversion.", "matrixNotSquare"),
-  matrixNotRectangular: /* @__PURE__ */ __name(() => "Matrix: Must be rectangular for transposition.", "matrixNotRectangular"),
-  matrixRowMismatch: /* @__PURE__ */ __name((expected, got) => `Matrix: Expected row length ${expected}, but got ${got}.`, "matrixRowMismatch")
-};
-
-// src/common/index.ts
-var DFSOperation = /* @__PURE__ */ ((DFSOperation2) => {
-  DFSOperation2[DFSOperation2["VISIT"] = 0] = "VISIT";
-  DFSOperation2[DFSOperation2["PROCESS"] = 1] = "PROCESS";
-  return DFSOperation2;
-})(DFSOperation || {});
-var _Range = class _Range {
-  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;
-  }
-};
-__name(_Range, "Range");
-var Range = _Range;
-
 // src/data-structures/base/iterable-entry-base.ts
 var _IterableEntryBase = class _IterableEntryBase {
   /**
@@ -772,6 +778,30 @@ var _Queue = class _Queue extends LinearBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Track queue length
   *  const q = new Queue<number>();
@@ -798,6 +828,30 @@ var _Queue = class _Queue extends LinearBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // View the front element
   *  const q = new Queue<string>(['first', 'second', 'third']);
@@ -840,6 +894,30 @@ var _Queue = class _Queue extends LinearBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Queue for...of iteration and isEmpty check
   *  const queue = new Queue<string>(['A', 'B', 'C', 'D']);
@@ -878,6 +956,30 @@ var _Queue = class _Queue extends LinearBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // basic Queue creation and push operation
   *  // Create a simple Queue with initial values
@@ -923,6 +1025,30 @@ var _Queue = class _Queue extends LinearBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Queue shift and peek operations
   *  const queue = new Queue<number>([10, 20, 30, 40]);
@@ -958,6 +1084,30 @@ var _Queue = class _Queue extends LinearBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Remove specific element
   *  const q = new Queue<number>([1, 2, 3, 2]);
@@ -986,6 +1136,30 @@ var _Queue = class _Queue extends LinearBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Access element by index
   *  const q = new Queue<string>(['a', 'b', 'c']);
@@ -1055,6 +1229,30 @@ var _Queue = class _Queue extends LinearBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Remove all elements
   *  const q = new Queue<number>([1, 2, 3]);
@@ -1077,6 +1275,30 @@ var _Queue = class _Queue extends LinearBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Reclaim unused memory
   *  const q = new Queue<number>([1, 2, 3, 4, 5]);
@@ -1122,6 +1344,30 @@ var _Queue = class _Queue extends LinearBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Create independent copy
   *  const q = new Queue<number>([1, 2, 3]);
@@ -1151,6 +1397,30 @@ var _Queue = class _Queue extends LinearBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Filter elements
   *  const q = new Queue<number>([1, 2, 3, 4, 5]);
@@ -1184,6 +1454,30 @@ var _Queue = class _Queue extends LinearBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Transform elements
   *  const q = new Queue<number>([1, 2, 3]);
@@ -1452,7 +1746,7 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
       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);
   }
@@ -1668,6 +1962,30 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Add a single node
   *  const tree = new BinaryTree<number>();
@@ -1698,6 +2016,30 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // basic BinaryTree creation and insertion
   *  // Create a BinaryTree with entries
@@ -1780,6 +2122,30 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Bulk add
   *  const tree = new BinaryTree<number>();
@@ -1798,6 +2164,30 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
     * @returns An array of booleans indicating the success of each individual `set` operation.
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Set multiple entries
   *  const tree = new BinaryTree<number, string>();
@@ -1837,6 +2227,30 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Combine trees
   *  const t1 = new BinaryTree<number>([1, 2]);
@@ -1875,6 +2289,30 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Remove a node
   *  const tree = new BinaryTree<number>([1, 2, 3, 4, 5]);
@@ -1991,6 +2429,30 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Get node by key
   *  const tree = new BinaryTree<number, string>([[1, 'root'], [2, 'child']]);
@@ -2025,6 +2487,30 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Retrieve value by key
   *  const tree = new BinaryTree<number, string>([[1, 'root'], [2, 'left'], [3, 'right']]);
@@ -2062,6 +2548,30 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Remove all nodes
   *  const tree = new BinaryTree<number>([1, 2, 3]);
@@ -2086,6 +2596,30 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Check empty
   *  console.log(new BinaryTree().isEmpty()); // true;
@@ -2119,6 +2653,30 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Check BST property
   *  const tree = new BinaryTree<number>([1, 2, 3]);
@@ -2179,6 +2737,30 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Get depth of a node
   *  const tree = new BinaryTree<number>([1, 2, 3, 4, 5]);
@@ -2216,6 +2798,30 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Get tree height
   *  const tree = new BinaryTree<number>([1, 2, 3, 4, 5]);
@@ -2669,6 +3275,30 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Deep copy
   *  const tree = new BinaryTree<number>([1, 2, 3]);
@@ -2697,6 +3327,30 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Filter nodes by condition
   *  const tree = new BinaryTree<number>([1, 2, 3, 4]);
@@ -2729,6 +3383,30 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Transform to new tree
   *  const tree = new BinaryTree<number, number>([[1, 10], [2, 20]]);
@@ -2786,6 +3464,30 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Display tree
   *  const tree = new BinaryTree<number>([1, 2, 3]);
@@ -3404,6 +4106,7 @@ var _BST = class _BST extends BinaryTree {
   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.
     
@@ -3416,6 +4119,9 @@ var _BST = class _BST extends BinaryTree {
       } else {
         this._comparator = this._createDefaultComparator();
       }
+      if (options.enableOrderStatistic) {
+        this._enableOrderStatistic = true;
+      }
     } else {
       this._comparator = this._createDefaultComparator();
     }
@@ -3550,6 +4256,54 @@ var _BST = class _BST extends BinaryTree {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Get node object by key
   *  const bst = new BST<number, string>([[5, 'root'], [3, 'left'], [7, 'right']]);
@@ -3705,6 +4459,85 @@ var _BST = class _BST extends BinaryTree {
     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).
@@ -3732,6 +4565,78 @@ var _BST = class _BST extends BinaryTree {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
     
     
     
@@ -3751,6 +4656,7 @@ var _BST = class _BST extends BinaryTree {
       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;
@@ -3764,6 +4670,7 @@ var _BST = class _BST extends BinaryTree {
           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;
@@ -3772,6 +4679,7 @@ var _BST = class _BST extends BinaryTree {
           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;
@@ -3801,6 +4709,54 @@ var _BST = class _BST extends BinaryTree {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Set multiple key-value pairs
   *  const bst = new BST<number, string>();
@@ -4064,6 +5020,30 @@ var _BST = class _BST extends BinaryTree {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Rebalance the tree
   *  const bst = new BST<number>();
@@ -4109,6 +5089,30 @@ var _BST = class _BST extends BinaryTree {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Check if tree is height-balanced
   *  const bst = new BST<number>([3, 1, 5, 2, 4]);
@@ -4183,6 +5187,54 @@ var _BST = class _BST extends BinaryTree {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Transform to new tree
   *  const bst = new BST<number, number>([[1, 10], [2, 20], [3, 30]]);
@@ -4257,13 +5309,11 @@ var _BST = class _BST extends BinaryTree {
       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;
     };
@@ -4585,7 +5635,8 @@ var _BST = class _BST extends BinaryTree {
   _snapshotOptions() {
     return {
       ...super._snapshotOptions(),
-      comparator: this._comparator
+      comparator: this._comparator,
+      enableOrderStatistic: this._enableOrderStatistic
     };
   }
   /**
@@ -4607,6 +5658,113 @@ var _BST = class _BST extends BinaryTree {
    *
    * @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;
@@ -4653,21 +5811,28 @@ var _BST = class _BST extends BinaryTree {
       while (x.left !== void 0 && x.left !== null) x = x.left;
       return x;
     }, "minNode");
+    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;
   }
@@ -4689,5 +5854,6 @@ exports.BinaryTreeNode = BinaryTreeNode;
 exports.DFSOperation = DFSOperation;
 exports.ERR = ERR;
 exports.Range = Range;
+exports.raise = raise;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map