avl-tree-typed 2.5.0 → 2.5.2

package/dist/cjs/index.cjs

@@ -59,6 +59,56 @@ 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 Range = class {
+  constructor(low, high, includeLow = true, includeHigh = true) {
+    this.low = low;
+    this.high = high;
+    this.includeLow = includeLow;
+    this.includeHigh = includeHigh;
+  }
+  static {
+    __name(this, "Range");
+  }
+  // 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 {
   static {
@@ -77,7 +127,7 @@ var IterableElementBase = class {
     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");
     }
   }
   /**
@@ -240,7 +290,7 @@ var IterableElementBase = class {
       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,50 +525,6 @@ var LinearBase = class _LinearBase extends IterableElementBase {
   }
 };
 
-// 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 Range = class {
-  constructor(low, high, includeLow = true, includeHigh = true) {
-    this.low = low;
-    this.high = high;
-    this.includeLow = includeLow;
-    this.includeHigh = includeHigh;
-  }
-  static {
-    __name(this, "Range");
-  }
-  // 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 {
   static {
@@ -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,7 +1229,31 @@ var Queue = class _Queue extends LinearBase {
     
     
     
-     * @example
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
   * // Remove all elements
   *  const q = new Queue<number>([1, 2, 3]);
   *     q.clear();
@@ -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]);
@@ -1434,7 +1728,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);
   }
@@ -1660,6 +1954,30 @@ var BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Add a single node
   *  const tree = new BinaryTree<number>();
@@ -1690,6 +2008,30 @@ var BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // basic BinaryTree creation and insertion
   *  // Create a BinaryTree with entries
@@ -1772,6 +2114,30 @@ var BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Bulk add
   *  const tree = new BinaryTree<number>();
@@ -1790,6 +2156,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>();
@@ -1829,6 +2219,30 @@ var BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Combine trees
   *  const t1 = new BinaryTree<number>([1, 2]);
@@ -1867,21 +2281,45 @@ var BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
-     * @example
-  * // Remove a node
-  *  const tree = new BinaryTree<number>([1, 2, 3, 4, 5]);
-  *     tree.delete(3);
-  *     console.log(tree.has(3)); // false;
-  *     console.log(tree.size); // 4;
-    */
-  delete(keyNodeEntryRawOrPredicate) {
-    const deletedResult = [];
-    if (!this._root) return deletedResult;
-    const curr = this.getNode(keyNodeEntryRawOrPredicate);
-    if (!curr) return deletedResult;
-    const parent = curr?.parent;
-    let needBalanced;
-    let orgCurrent = curr;
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Remove a node
+  *  const tree = new BinaryTree<number>([1, 2, 3, 4, 5]);
+  *     tree.delete(3);
+  *     console.log(tree.has(3)); // false;
+  *     console.log(tree.size); // 4;
+    */
+  delete(keyNodeEntryRawOrPredicate) {
+    const deletedResult = [];
+    if (!this._root) return deletedResult;
+    const curr = this.getNode(keyNodeEntryRawOrPredicate);
+    if (!curr) return deletedResult;
+    const parent = curr?.parent;
+    let needBalanced;
+    let orgCurrent = curr;
     if (!curr.left && !curr.right && !parent) {
       this._setRoot(void 0);
     } else if (curr.left) {
@@ -1983,6 +2421,30 @@ var BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Get node by key
   *  const tree = new BinaryTree<number, string>([[1, 'root'], [2, 'child']]);
@@ -2017,6 +2479,30 @@ var BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Retrieve value by key
   *  const tree = new BinaryTree<number, string>([[1, 'root'], [2, 'left'], [3, 'right']]);
@@ -2053,6 +2539,30 @@ var BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Remove all nodes
   *  const tree = new BinaryTree<number>([1, 2, 3]);
@@ -2077,6 +2587,30 @@ var BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Check empty
   *  console.log(new BinaryTree().isEmpty()); // true;
@@ -2110,6 +2644,30 @@ var BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Check BST property
   *  const tree = new BinaryTree<number>([1, 2, 3]);
@@ -2170,6 +2728,30 @@ var BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Get depth of a node
   *  const tree = new BinaryTree<number>([1, 2, 3, 4, 5]);
@@ -2207,6 +2789,30 @@ var BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Get tree height
   *  const tree = new BinaryTree<number>([1, 2, 3, 4, 5]);
@@ -2660,6 +3266,30 @@ var BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Deep copy
   *  const tree = new BinaryTree<number>([1, 2, 3]);
@@ -2688,6 +3318,30 @@ var BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Filter nodes by condition
   *  const tree = new BinaryTree<number>([1, 2, 3, 4]);
@@ -2720,7 +3374,31 @@ var BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
-     * @example
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
   * // Transform to new tree
   *  const tree = new BinaryTree<number, number>([[1, 10], [2, 20]]);
   *     const mapped = tree.map((v, key) => [key, (v ?? 0) + 1] as [number, number]);
@@ -2777,6 +3455,30 @@ var BinaryTree = class _BinaryTree extends IterableEntryBase {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Display tree
   *  const tree = new BinaryTree<number>([1, 2, 3]);
@@ -3408,12 +4110,16 @@ var BST = class extends BinaryTree {
       } else {
         this._comparator = this._createDefaultComparator();
       }
+      if (options.enableOrderStatistic) {
+        this._enableOrderStatistic = true;
+      }
     } else {
       this._comparator = this._createDefaultComparator();
     }
     if (keysNodesEntriesOrRaws) this.setMany(keysNodesEntriesOrRaws);
   }
   _root = void 0;
+  _enableOrderStatistic = false;
   /**
    * Gets the root node of the tree.
    * @remarks Time O(1)
@@ -3548,6 +4254,54 @@ var BST = class extends BinaryTree {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Get node object by key
   *  const bst = new BST<number, string>([[5, 'root'], [3, 'left'], [7, 'right']]);
@@ -3702,6 +4456,84 @@ var BST = class 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) {
+    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 = keyNodeEntryOrPredicate[0] ?? 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 ?? 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).
@@ -3729,6 +4561,78 @@ var BST = class extends BinaryTree {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
     
     
     
@@ -3748,6 +4652,7 @@ var BST = class 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;
@@ -3761,6 +4666,7 @@ var BST = class 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;
@@ -3769,6 +4675,7 @@ var BST = class 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;
@@ -3798,6 +4705,54 @@ var BST = class extends BinaryTree {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Set multiple key-value pairs
   *  const bst = new BST<number, string>();
@@ -4061,11 +5016,35 @@ var BST = class extends BinaryTree {
     
     
     
-     * @example
-  * // Rebalance the tree
-  *  const bst = new BST<number>();
-  *     // Insert in sorted order (worst case for BST)
-  *     for (let i = 1; i <= 7; i++) bst.add(i);
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Rebalance the tree
+  *  const bst = new BST<number>();
+  *     // Insert in sorted order (worst case for BST)
+  *     for (let i = 1; i <= 7; i++) bst.add(i);
   *     console.log(bst.isAVLBalanced()); // false;
   *     bst.perfectlyBalance();
   *     console.log(bst.isAVLBalanced()); // true;
@@ -4106,6 +5085,30 @@ var BST = class extends BinaryTree {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Check if tree is height-balanced
   *  const bst = new BST<number>([3, 1, 5, 2, 4]);
@@ -4180,6 +5183,54 @@ var BST = class extends BinaryTree {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Transform to new tree
   *  const bst = new BST<number, number>([[1, 10], [2, 20], [3, 30]]);
@@ -4254,13 +5305,11 @@ var BST = class 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;
     };
@@ -4579,7 +5628,8 @@ var BST = class extends BinaryTree {
   _snapshotOptions() {
     return {
       ...super._snapshotOptions(),
-      comparator: this._comparator
+      comparator: this._comparator,
+      enableOrderStatistic: this._enableOrderStatistic
     };
   }
   /**
@@ -4601,6 +5651,113 @@ var BST = class 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;
@@ -4647,21 +5804,28 @@ var BST = class 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;
   }
@@ -4856,6 +6020,102 @@ var AVLTree = class extends BST {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
     
     
     
@@ -4908,6 +6168,78 @@ var AVLTree = class extends BST {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
     
     
     
@@ -4964,6 +6296,54 @@ var AVLTree = class extends BST {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
      * @example
   * // Rebalance the tree
   *  const avl = new AVLTree<number>();
@@ -5026,6 +6406,78 @@ var AVLTree = class extends BST {
     
     
     
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
     
     
      * @example
@@ -5146,6 +6598,8 @@ var AVLTree = class extends BST {
     }
     this._updateHeight(A);
     if (B) this._updateHeight(B);
+    this._updateCount(A);
+    if (B) this._updateCount(B);
   }
   /**
    * (Protected) Performs a Left-Right (LR) double rotation.
@@ -5191,6 +6645,9 @@ var AVLTree = class extends BST {
     this._updateHeight(A);
     if (B) this._updateHeight(B);
     if (C) this._updateHeight(C);
+    this._updateCount(A);
+    if (B) this._updateCount(B);
+    if (C) this._updateCount(C);
   }
   /**
    * (Protected) Performs a Right-Right (RR) rotation (a single left rotation).
@@ -5225,6 +6682,8 @@ var AVLTree = class extends BST {
     }
     this._updateHeight(A);
     if (B) this._updateHeight(B);
+    this._updateCount(A);
+    if (B) this._updateCount(B);
   }
   /**
    * (Protected) Performs a Right-Left (RL) double rotation.
@@ -5268,6 +6727,9 @@ var AVLTree = class extends BST {
     this._updateHeight(A);
     if (B) this._updateHeight(B);
     if (C) this._updateHeight(C);
+    this._updateCount(A);
+    if (B) this._updateCount(B);
+    if (C) this._updateCount(C);
   }
   /**
    * (Protected) Traverses up the tree from the specified node, updating heights and performing rotations as needed.
@@ -5282,6 +6744,7 @@ var AVLTree = class extends BST {
       const A = path[i];
       if (A) {
         this._updateHeight(A);
+        this._updateCount(A);
         switch (this._balanceFactor(A)) {
           case -2:
             if (A && A.left) {