data-structure-typed 2.4.4 → 2.4.5

package/dist/cjs-legacy/index.cjs

@@ -193,6 +193,54 @@ var _IterableEntryBase = class _IterableEntryBase {
 __name(_IterableEntryBase, "IterableEntryBase");
 var IterableEntryBase = _IterableEntryBase;
 
+// 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-element-base.ts
 var _IterableElementBase = class _IterableElementBase {
   /**
@@ -215,7 +263,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) throw new TypeError(ERR.notAFunction("toElementFn"));
     }
   }
   /**
@@ -371,7 +419,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) throw new TypeError(ERR.reduceEmpty());
       acc = first.value;
       index = 1;
     }
@@ -441,8 +489,10 @@ var getMSB = /* @__PURE__ */ __name((value) => {
   }
   return 1 << 31 - Math.clz32(value);
 }, "getMSB");
-var rangeCheck = /* @__PURE__ */ __name((index, min, max, message = "Index out of bounds.") => {
-  if (index < min || index > max) throw new RangeError(message);
+var rangeCheck = /* @__PURE__ */ __name((index, min, max, message) => {
+  if (index < min || index > max) {
+    throw new RangeError(message != null ? message : `Index ${index} is out of range [${min}, ${max}].`);
+  }
 }, "rangeCheck");
 var throwRangeError = /* @__PURE__ */ __name((message = "The value is off-limits.") => {
   throw new RangeError(message);
@@ -814,8 +864,8 @@ var _LinkedHashMap = class _LinkedHashMap extends IterableEntryBase {
       if (this.isEntry(rawElement)) {
         return rawElement;
       }
-      throw new Error(
-        "If `entryOrRawElements` does not adhere to [key,value], provide `options.toEntryFn` to transform raw records."
+      throw new TypeError(
+        ERR.invalidArgument("If elements do not adhere to [key, value], provide options.toEntryFn to transform raw records.", "HashMap")
       );
     }, "_toEntryFn"));
     __publicField(this, "_size", 0);
@@ -1100,6 +1150,13 @@ var _LinkedHashMap = class _LinkedHashMap extends IterableEntryBase {
     }
   }
   _deleteNode(node) {
+    const key = node.key;
+    if (isWeakKey(key)) {
+      this._objMap.delete(key);
+    } else {
+      const hash = this._hashFn(key);
+      delete this._noObjMap[hash];
+    }
     const { prev, next } = node;
     prev.next = next;
     next.prev = prev;
@@ -3607,17 +3664,16 @@ var LinkedListQueue = _LinkedListQueue;
 
 // src/data-structures/queue/deque.ts
 var _Deque = class _Deque extends LinearBase {
-  /**
-   * Create a Deque and optionally bulk-insert elements.
-   * @remarks Time O(N), Space O(N)
-   * @param [elements] - Iterable (or iterable-like) of elements/records to insert.
-   * @param [options] - Options such as bucketSize, toElementFn, and maxLen.
-   * @returns New Deque instance.
-   */
   constructor(elements = [], options) {
     super(options);
     __publicField(this, "_equals", /* @__PURE__ */ __name((a, b) => Object.is(a, b), "_equals"));
     __publicField(this, "_bucketSize", 1 << 12);
+    __publicField(this, "_autoCompactRatio", 0.5);
+    /**
+     * Counter for shift/pop operations since last compaction check.
+     * Only checks ratio every `_bucketSize` operations to minimize overhead.
+     */
+    __publicField(this, "_compactCounter", 0);
     __publicField(this, "_bucketFirst", 0);
     __publicField(this, "_firstInBucket", 0);
     __publicField(this, "_bucketLast", 0);
@@ -3626,8 +3682,9 @@ var _Deque = class _Deque extends LinearBase {
     __publicField(this, "_buckets", []);
     __publicField(this, "_length", 0);
     if (options) {
-      const { bucketSize } = options;
+      const { bucketSize, autoCompactRatio } = options;
       if (typeof bucketSize === "number") this._bucketSize = bucketSize;
+      if (typeof autoCompactRatio === "number") this._autoCompactRatio = autoCompactRatio;
     }
     let _size;
     if ("length" in elements) {
@@ -3652,6 +3709,24 @@ var _Deque = class _Deque extends LinearBase {
   get bucketSize() {
     return this._bucketSize;
   }
+  /**
+   * Get the auto-compaction ratio.
+   * When `elements / (bucketCount * bucketSize)` drops below this ratio after
+   * enough shift/pop operations, the deque auto-compacts.
+   * @remarks Time O(1), Space O(1)
+   * @returns Current ratio threshold. 0 means auto-compact is disabled.
+   */
+  get autoCompactRatio() {
+    return this._autoCompactRatio;
+  }
+  /**
+   * Set the auto-compaction ratio.
+   * @remarks Time O(1), Space O(1)
+   * @param value - Ratio in [0,1]. 0 disables auto-compact.
+   */
+  set autoCompactRatio(value) {
+    this._autoCompactRatio = value;
+  }
   /**
    * Get the index of the first bucket in use.
    * @remarks Time O(1), Space O(1)
@@ -3783,6 +3858,7 @@ var _Deque = class _Deque extends LinearBase {
       }
     }
     this._length -= 1;
+    this._autoCompact();
     return element;
   }
   /**
@@ -3805,6 +3881,7 @@ var _Deque = class _Deque extends LinearBase {
       }
     }
     this._length -= 1;
+    this._autoCompact();
     return element;
   }
   /**
@@ -4137,11 +4214,40 @@ var _Deque = class _Deque extends LinearBase {
    * @remarks Time O(N), Space O(1)
    * @returns void
    */
+  /**
+   * (Protected) Trigger auto-compaction if space utilization drops below threshold.
+   * Only checks every `_bucketSize` operations to minimize hot-path overhead.
+   * Uses element-based ratio: `elements / (bucketCount * bucketSize)`.
+   */
+  _autoCompact() {
+    if (this._autoCompactRatio <= 0 || this._bucketCount <= 1) return;
+    this._compactCounter++;
+    if (this._compactCounter < this._bucketSize) return;
+    this._compactCounter = 0;
+    const utilization = this._length / (this._bucketCount * this._bucketSize);
+    if (utilization < this._autoCompactRatio) {
+      this.shrinkToFit();
+    }
+  }
+  /**
+   * Compact the deque by removing unused buckets.
+   * @remarks Time O(N), Space O(1)
+   * @returns True if compaction was performed (bucket count reduced).
+   */
+  /**
+   * Compact the deque by removing unused buckets.
+   * @remarks Time O(N), Space O(1)
+   * @returns True if compaction was performed (bucket count reduced).
+   */
+  compact() {
+    const before = this._bucketCount;
+    this.shrinkToFit();
+    return this._bucketCount < before;
+  }
   shrinkToFit() {
     if (this._length === 0) return;
     const newBuckets = [];
-    if (this._bucketFirst === this._bucketLast) return;
-    else if (this._bucketFirst < this._bucketLast) {
+    if (this._bucketFirst <= this._bucketLast) {
       for (let i = this._bucketFirst; i <= this._bucketLast; ++i) {
         newBuckets.push(this._buckets[i]);
       }
@@ -4156,6 +4262,8 @@ var _Deque = class _Deque extends LinearBase {
     this._bucketFirst = 0;
     this._bucketLast = newBuckets.length - 1;
     this._buckets = newBuckets;
+    this._bucketCount = newBuckets.length;
+    this._compactCounter = 0;
   }
   /**
    * Deep clone this deque, preserving options.
@@ -4353,7 +4461,7 @@ var _Heap = class _Heap extends IterableElementBase {
     __publicField(this, "_elements", []);
     __publicField(this, "_DEFAULT_COMPARATOR", /* @__PURE__ */ __name((a, b) => {
       if (typeof a === "object" || typeof b === "object") {
-        throw TypeError("When comparing object types, define a custom comparator in options.");
+        throw new TypeError(ERR.comparatorRequired("Heap"));
       }
       if (a > b) return 1;
       if (a < b) return -1;
@@ -4663,7 +4771,7 @@ var _Heap = class _Heap extends IterableElementBase {
    */
   map(callback, options, thisArg) {
     const { comparator, toElementFn, ...rest } = options != null ? options : {};
-    if (!comparator) throw new TypeError("Heap.map requires options.comparator for EM");
+    if (!comparator) throw new TypeError(ERR.comparatorRequired("Heap.map"));
     const out = this._createLike([], { ...rest, comparator, toElementFn });
     let i = 0;
     for (const x of this) {
@@ -4795,7 +4903,7 @@ var _FibonacciHeap = class _FibonacciHeap {
     __publicField(this, "_comparator");
     this.clear();
     this._comparator = comparator || this._defaultComparator;
-    if (typeof this.comparator !== "function") throw new Error("FibonacciHeap: comparator must be a function.");
+    if (typeof this.comparator !== "function") throw new TypeError(ERR.notAFunction("comparator", "FibonacciHeap"));
   }
   /**
    * Get the circular root list head.
@@ -5006,9 +5114,7 @@ var _MaxHeap = class _MaxHeap extends Heap {
     super(elements, {
       comparator: /* @__PURE__ */ __name((a, b) => {
         if (typeof a === "object" || typeof b === "object") {
-          throw TypeError(
-            `When comparing object types, a custom comparator must be defined in the constructor's options parameter.`
-          );
+          throw new TypeError(ERR.comparatorRequired("MaxHeap"));
         }
         if (a < b) return 1;
         if (a > b) return -1;
@@ -5173,7 +5279,7 @@ var _AbstractGraph = class _AbstractGraph extends IterableEntryBase {
         const newEdge = this.createEdge(srcOrEdge, dest, weight, value);
         return this._addEdge(newEdge);
       } else {
-        throw new Error("dest must be a Vertex or vertex key while srcOrEdge is an Edge");
+        throw new TypeError(ERR.invalidArgument("dest must be a Vertex or vertex key when srcOrEdge is an Edge.", "Graph"));
       }
     }
   }
@@ -5857,6 +5963,94 @@ var _AbstractGraph = class _AbstractGraph extends IterableEntryBase {
   _getVertexKey(vertexOrKey) {
     return vertexOrKey instanceof AbstractVertex ? vertexOrKey.key : vertexOrKey;
   }
+  /**
+   * The edge connector string used in visual output.
+   * Override in subclasses (e.g., '--' for undirected, '->' for directed).
+   */
+  get _edgeConnector() {
+    return "--";
+  }
+  /**
+   * Generate a text-based visual representation of the graph.
+   *
+   * **Adjacency list format:**
+   * ```
+   * Graph (5 vertices, 6 edges):
+   * A -> B (1), C (2)
+   * B -> D (3)
+   * C -> (no outgoing edges)
+   * D -> A (1)
+   * E (isolated)
+   * ```
+   *
+   * @param options - Optional display settings.
+   * @param options.showWeight - Whether to show edge weights (default: true).
+   * @returns The visual string.
+   */
+  toVisual(options) {
+    var _a;
+    const showWeight = (_a = options == null ? void 0 : options.showWeight) != null ? _a : true;
+    const vertices = [...this._vertexMap.values()];
+    const vertexCount = vertices.length;
+    const edgeCount = this.edgeSet().length;
+    const lines = [`Graph (${vertexCount} vertices, ${edgeCount} edges):`];
+    for (const vertex of vertices) {
+      const neighbors = this.getNeighbors(vertex);
+      if (neighbors.length === 0) {
+        lines.push(`  ${vertex.key} (isolated)`);
+      } else {
+        const edgeStrs = neighbors.map((neighbor) => {
+          const edge = this.getEdge(vertex, neighbor);
+          if (edge && showWeight && edge.weight !== void 0 && edge.weight !== 1) {
+            return `${neighbor.key} (${edge.weight})`;
+          }
+          return `${neighbor.key}`;
+        });
+        lines.push(`  ${vertex.key} ${this._edgeConnector} ${edgeStrs.join(", ")}`);
+      }
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Generate DOT language representation for Graphviz.
+   *
+   * @param options - Optional display settings.
+   * @param options.name - Graph name (default: 'G').
+   * @param options.showWeight - Whether to label edges with weight (default: true).
+   * @returns DOT format string.
+   */
+  toDot(options) {
+    var _a, _b;
+    const name = (_a = options == null ? void 0 : options.name) != null ? _a : "G";
+    const showWeight = (_b = options == null ? void 0 : options.showWeight) != null ? _b : true;
+    const isDirected = this._edgeConnector === "->";
+    const graphType = isDirected ? "digraph" : "graph";
+    const edgeOp = isDirected ? "->" : "--";
+    const lines = [`${graphType} ${name} {`];
+    for (const vertex of this._vertexMap.values()) {
+      lines.push(`  "${vertex.key}";`);
+    }
+    const visited = /* @__PURE__ */ new Set();
+    for (const vertex of this._vertexMap.values()) {
+      for (const neighbor of this.getNeighbors(vertex)) {
+        const edgeId = isDirected ? `${vertex.key}->${neighbor.key}` : [vertex.key, neighbor.key].sort().join("--");
+        if (visited.has(edgeId)) continue;
+        visited.add(edgeId);
+        const edge = this.getEdge(vertex, neighbor);
+        const label = edge && showWeight && edge.weight !== void 0 && edge.weight !== 1 ? ` [label="${edge.weight}"]` : "";
+        lines.push(`  "${vertex.key}" ${edgeOp} "${neighbor.key}"${label};`);
+      }
+    }
+    lines.push("}");
+    return lines.join("\n");
+  }
+  /**
+   * Print the graph to console.
+   * @param options - Display settings passed to `toVisual`.
+   */
+  print(options) {
+    console.log(this.toVisual(options));
+  }
 };
 __name(_AbstractGraph, "AbstractGraph");
 var AbstractGraph = _AbstractGraph;
@@ -5891,6 +6085,9 @@ var _DirectedGraph = class _DirectedGraph extends AbstractGraph {
     __publicField(this, "_outEdgeMap", /* @__PURE__ */ new Map());
     __publicField(this, "_inEdgeMap", /* @__PURE__ */ new Map());
   }
+  get _edgeConnector() {
+    return "->";
+  }
   get outEdgeMap() {
     return this._outEdgeMap;
   }
@@ -6671,6 +6868,84 @@ var _UndirectedGraph = class _UndirectedGraph extends AbstractGraph {
       cutVertices
     };
   }
+  /**
+   * Find biconnected components using edge-stack Tarjan variant.
+   * A biconnected component is a maximal biconnected subgraph.
+   * @returns Array of edge arrays, each representing a biconnected component.
+   * @remarks Time O(V + E), Space O(V + E)
+   */
+  getBiconnectedComponents() {
+    const dfn = /* @__PURE__ */ new Map();
+    const low = /* @__PURE__ */ new Map();
+    const edgeStack = [];
+    const components = [];
+    let time = 0;
+    const dfs = /* @__PURE__ */ __name((vertex, parent) => {
+      dfn.set(vertex, time);
+      low.set(vertex, time);
+      time++;
+      const neighbors = this.getNeighbors(vertex);
+      let childCount = 0;
+      for (const neighbor of neighbors) {
+        const edge = this.getEdge(vertex, neighbor);
+        if (!edge) continue;
+        if (!dfn.has(neighbor)) {
+          childCount++;
+          edgeStack.push(edge);
+          dfs(neighbor, vertex);
+          low.set(vertex, Math.min(low.get(vertex), low.get(neighbor)));
+          if (parent === void 0 && childCount > 1 || parent !== void 0 && low.get(neighbor) >= dfn.get(vertex)) {
+            const component = [];
+            let e;
+            do {
+              e = edgeStack.pop();
+              if (e) component.push(e);
+            } while (e && e !== edge);
+            if (component.length > 0) components.push(component);
+          }
+        } else if (neighbor !== parent && dfn.get(neighbor) < dfn.get(vertex)) {
+          edgeStack.push(edge);
+          low.set(vertex, Math.min(low.get(vertex), dfn.get(neighbor)));
+        }
+      }
+    }, "dfs");
+    for (const vertex of this.vertexMap.values()) {
+      if (!dfn.has(vertex)) {
+        dfs(vertex, void 0);
+        if (edgeStack.length > 0) {
+          components.push([...edgeStack]);
+          edgeStack.length = 0;
+        }
+      }
+    }
+    return components;
+  }
+  /**
+   * Detect whether the graph contains a cycle.
+   * Uses DFS with parent tracking.
+   * @returns `true` if a cycle exists, `false` otherwise.
+   * @remarks Time O(V + E), Space O(V)
+   */
+  hasCycle() {
+    const visited = /* @__PURE__ */ new Set();
+    const dfs = /* @__PURE__ */ __name((vertex, parent) => {
+      visited.add(vertex);
+      for (const neighbor of this.getNeighbors(vertex)) {
+        if (!visited.has(neighbor)) {
+          if (dfs(neighbor, vertex)) return true;
+        } else if (neighbor !== parent) {
+          return true;
+        }
+      }
+      return false;
+    }, "dfs");
+    for (const vertex of this.vertexMap.values()) {
+      if (!visited.has(vertex)) {
+        if (dfs(vertex, void 0)) return true;
+      }
+    }
+    return false;
+  }
   /**
    * Get bridges discovered by `tarjan()`.
    * @returns Array of edges that are bridges.
@@ -6823,29 +7098,6 @@ var _MapGraph = class _MapGraph extends DirectedGraph {
 __name(_MapGraph, "MapGraph");
 var MapGraph = _MapGraph;
 
-// 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/binary-tree/binary-tree.ts
 var _BinaryTreeNode = class _BinaryTreeNode {
   /**
@@ -7018,7 +7270,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 TypeError("toEntryFn must be a function type");
+      else if (toEntryFn) throw new TypeError(ERR.notAFunction("toEntryFn", "BinaryTree"));
     }
     if (keysNodesEntriesOrRaws) this.setMany(keysNodesEntriesOrRaws);
   }
@@ -7246,7 +7498,7 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
     if (!this._root) {
       this._setRoot(newNode);
       if (this._isMapMode && newNode !== null && newNode !== void 0) this._store.set(newNode.key, newNode);
-      this._size = 1;
+      if (newNode !== null) this._size = 1;
       return true;
     }
     const queue = new Queue([this._root]);
@@ -7278,7 +7530,7 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
         potentialParent.right = newNode;
       }
       if (this._isMapMode && newNode !== null && newNode !== void 0) this._store.set(newNode.key, newNode);
-      this._size++;
+      if (newNode !== null) this._size++;
       return true;
     }
     return false;
@@ -7847,7 +8099,7 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
   }
   /**
    * Finds all leaf nodes in the tree.
-   * @remarks Time O(N), visits every node. Space O(H) for recursive stack or O(N) for iterative queue.
+   * @remarks Time O(N), visits every node. Space O(H) for recursive or iterative stack.
    *
    * @template C - The type of the callback function.
    * @param [callback=this._DEFAULT_NODE_CALLBACK] - Function to call on each leaf node.
@@ -7870,15 +8122,15 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
       }, "dfs");
       dfs(startNode);
     } else {
-      const queue = new Queue([startNode]);
-      while (queue.length > 0) {
-        const cur = queue.shift();
+      const stack = [startNode];
+      while (stack.length > 0) {
+        const cur = stack.pop();
         if (this.isRealNode(cur)) {
           if (this.isLeaf(cur)) {
             leaves.push(callback(cur));
           }
-          if (this.isRealNode(cur.left)) queue.push(cur.left);
-          if (this.isRealNode(cur.right)) queue.push(cur.right);
+          if (this.isRealNode(cur.right)) stack.push(cur.right);
+          if (this.isRealNode(cur.left)) stack.push(cur.left);
         }
       }
     }
@@ -8334,42 +8586,98 @@ var _BinaryTree = class _BinaryTree extends IterableEntryBase {
   _displayAux(node, options) {
     const { isShowNull, isShowUndefined, isShowRedBlackNIL } = options;
     const emptyDisplayLayout = [["\u2500"], 1, 0, 0];
-    if (node === null && !isShowNull) {
-      return emptyDisplayLayout;
-    } else if (node === void 0 && !isShowUndefined) {
-      return emptyDisplayLayout;
-    } else if (this.isNIL(node) && !isShowRedBlackNIL) {
-      return emptyDisplayLayout;
-    } else if (node !== null && node !== void 0) {
-      const key = node.key, line = this.isNIL(node) ? "S" : String(key), width = line.length;
-      return _buildNodeDisplay(
-        line,
-        width,
-        this._displayAux(node.left, options),
-        this._displayAux(node.right, options)
-      );
-    } else {
-      const line = node === void 0 ? "U" : "N", width = line.length;
-      return _buildNodeDisplay(line, width, [[""], 1, 0, 0], [[""], 1, 0, 0]);
-    }
-    function _buildNodeDisplay(line, width, left, right) {
-      const [leftLines, leftWidth, leftHeight, leftMiddle] = left;
-      const [rightLines, rightWidth, rightHeight, rightMiddle] = right;
-      const firstLine = " ".repeat(Math.max(0, leftMiddle + 1)) + "_".repeat(Math.max(0, leftWidth - leftMiddle - 1)) + line + "_".repeat(Math.max(0, rightMiddle)) + " ".repeat(Math.max(0, rightWidth - rightMiddle));
-      const secondLine = (leftHeight > 0 ? " ".repeat(leftMiddle) + "/" + " ".repeat(leftWidth - leftMiddle - 1) : " ".repeat(leftWidth)) + " ".repeat(width) + (rightHeight > 0 ? " ".repeat(rightMiddle) + "\\" + " ".repeat(rightWidth - rightMiddle - 1) : " ".repeat(rightWidth));
-      const mergedLines = [firstLine, secondLine];
-      for (let i = 0; i < Math.max(leftHeight, rightHeight); i++) {
-        const leftLine = i < leftHeight ? leftLines[i] : " ".repeat(leftWidth);
-        const rightLine = i < rightHeight ? rightLines[i] : " ".repeat(rightWidth);
-        mergedLines.push(leftLine + " ".repeat(width) + rightLine);
+    const newFrame = /* @__PURE__ */ __name((n) => ({
+      node: n,
+      stage: 0,
+      leftLayout: emptyDisplayLayout,
+      rightLayout: emptyDisplayLayout
+    }), "newFrame");
+    const stack = [newFrame(node)];
+    let result = emptyDisplayLayout;
+    const setChildResult = /* @__PURE__ */ __name((layout) => {
+      if (stack.length === 0) {
+        result = layout;
+        return;
+      }
+      const parent = stack[stack.length - 1];
+      if (parent.stage === 1) parent.leftLayout = layout;
+      else parent.rightLayout = layout;
+    }, "setChildResult");
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      const cur = frame.node;
+      if (frame.stage === 0) {
+        if (this._isDisplayLeaf(cur, options)) {
+          stack.pop();
+          const layout = this._resolveDisplayLeaf(cur, options, emptyDisplayLayout);
+          setChildResult(layout);
+          continue;
+        }
+        frame.stage = 1;
+        stack.push(newFrame(cur.left));
+      } else if (frame.stage === 1) {
+        frame.stage = 2;
+        stack.push(newFrame(cur.right));
+      } else {
+        stack.pop();
+        const line = this.isNIL(cur) ? "S" : String(cur.key);
+        const layout = _BinaryTree._buildNodeDisplay(line, line.length, frame.leftLayout, frame.rightLayout);
+        setChildResult(layout);
       }
-      return [
-        mergedLines,
-        leftWidth + width + rightWidth,
-        Math.max(leftHeight, rightHeight) + 2,
-        leftWidth + Math.floor(width / 2)
-      ];
     }
+    return result;
+  }
+  static _buildNodeDisplay(line, width, left, right) {
+    const [leftLines, leftWidth, leftHeight, leftMiddle] = left;
+    const [rightLines, rightWidth, rightHeight, rightMiddle] = right;
+    const firstLine = " ".repeat(Math.max(0, leftMiddle + 1)) + "_".repeat(Math.max(0, leftWidth - leftMiddle - 1)) + line + "_".repeat(Math.max(0, rightMiddle)) + " ".repeat(Math.max(0, rightWidth - rightMiddle));
+    const secondLine = (leftHeight > 0 ? " ".repeat(leftMiddle) + "/" + " ".repeat(leftWidth - leftMiddle - 1) : " ".repeat(leftWidth)) + " ".repeat(width) + (rightHeight > 0 ? " ".repeat(rightMiddle) + "\\" + " ".repeat(rightWidth - rightMiddle - 1) : " ".repeat(rightWidth));
+    const mergedLines = [firstLine, secondLine];
+    for (let i = 0; i < Math.max(leftHeight, rightHeight); i++) {
+      const leftLine = i < leftHeight ? leftLines[i] : " ".repeat(leftWidth);
+      const rightLine = i < rightHeight ? rightLines[i] : " ".repeat(rightWidth);
+      mergedLines.push(leftLine + " ".repeat(width) + rightLine);
+    }
+    return [
+      mergedLines,
+      leftWidth + width + rightWidth,
+      Math.max(leftHeight, rightHeight) + 2,
+      leftWidth + Math.floor(width / 2)
+    ];
+  }
+  /**
+   * Check if a node is a display leaf (empty, null, undefined, NIL, or real leaf).
+   */
+  _isDisplayLeaf(node, options) {
+    const { isShowNull, isShowUndefined, isShowRedBlackNIL } = options;
+    if (node === null && !isShowNull) return true;
+    if (node === void 0 && !isShowUndefined) return true;
+    if (this.isNIL(node) && !isShowRedBlackNIL) return true;
+    if (node === null || node === void 0) return true;
+    const hasDisplayableLeft = this._hasDisplayableChild(node.left, options);
+    const hasDisplayableRight = this._hasDisplayableChild(node.right, options);
+    return !hasDisplayableLeft && !hasDisplayableRight;
+  }
+  _hasDisplayableChild(child, options) {
+    if (child === null) return !!options.isShowNull;
+    if (child === void 0) return !!options.isShowUndefined;
+    if (this.isNIL(child)) return !!options.isShowRedBlackNIL;
+    return true;
+  }
+  /**
+   * Resolve a display leaf node to its layout.
+   */
+  _resolveDisplayLeaf(node, options, emptyDisplayLayout) {
+    const { isShowNull, isShowUndefined, isShowRedBlackNIL } = options;
+    if (node === null && !isShowNull) return emptyDisplayLayout;
+    if (node === void 0 && !isShowUndefined) return emptyDisplayLayout;
+    if (this.isNIL(node) && !isShowRedBlackNIL) return emptyDisplayLayout;
+    if (node !== null && node !== void 0) {
+      const line2 = this.isNIL(node) ? "S" : String(node.key);
+      return _BinaryTree._buildNodeDisplay(line2, line2.length, emptyDisplayLayout, emptyDisplayLayout);
+    }
+    const line = node === void 0 ? "U" : "N";
+    return _BinaryTree._buildNodeDisplay(line, line.length, [[""], 1, 0, 0], [[""], 1, 0, 0]);
   }
   /**
    * (Protected) Swaps the key/value properties of two nodes.
@@ -9375,9 +9683,15 @@ var _BST = class _BST extends BinaryTree {
         if (a < b) return -1;
         return 0;
       }
+      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"));
+        return ta > tb ? 1 : ta < tb ? -1 : 0;
+      }
       if (typeof a === "object" || typeof b === "object") {
-        throw TypeError(
-          `When comparing object type keys, a custom comparator must be provided in the constructor's options!`
+        throw new TypeError(
+          ERR.comparatorRequired("BST")
         );
       }
       return 0;
@@ -9891,7 +10205,7 @@ var _BinaryIndexedTree = class _BinaryIndexedTree {
    */
   read(count) {
     if (!Number.isInteger(count)) {
-      throw new Error("Invalid count");
+      throw new Error(ERR.invalidArgument("count must be an integer", "BinaryIndexedTree"));
     }
     return this._read(Math.max(Math.min(count, this.max), 0));
   }
@@ -9903,7 +10217,7 @@ var _BinaryIndexedTree = class _BinaryIndexedTree {
    */
   lowerBound(sum) {
     if (this.negativeCount > 0) {
-      throw new Error("Sequence is not non-descending");
+      throw new Error(ERR.invalidOperation("Sequence is not non-descending.", "BinaryIndexedTree"));
     }
     return this._binarySearch(sum, (x, y) => x < y);
   }
@@ -9916,7 +10230,7 @@ var _BinaryIndexedTree = class _BinaryIndexedTree {
    */
   upperBound(sum) {
     if (this.negativeCount > 0) {
-      throw new Error("Must not be descending");
+      throw new Error(ERR.invalidOperation("Sequence must not be descending.", "BinaryIndexedTree"));
     }
     return this._binarySearch(sum, (x, y) => x <= y);
   }
@@ -9967,10 +10281,10 @@ var _BinaryIndexedTree = class _BinaryIndexedTree {
    */
   _checkIndex(index) {
     if (!Number.isInteger(index)) {
-      throw new Error("Invalid index: Index must be an integer.");
+      throw new TypeError(ERR.invalidIndex("BinaryIndexedTree"));
     }
     if (index < 0 || index >= this.max) {
-      throw new Error("Index out of range: Index must be within the range [0, this.max).");
+      throw new RangeError(ERR.indexOutOfRange(index, 0, this.max - 1, "BinaryIndexedTree"));
     }
   }
   /**
@@ -11559,6 +11873,24 @@ var _RedBlackTree = class _RedBlackTree extends BST {
    * @param [thisArg] - See parameter type for details.
    * @returns A new RedBlackTree with mapped entries.
    */
+  /**
+   * Red-Black trees are self-balancing — `perfectlyBalance` rebuilds via
+   * sorted bulk insert, which naturally produces a balanced RBT.
+   * @remarks Time O(N), Space O(N)
+   */
+  perfectlyBalance(iterationType) {
+    const entries = [];
+    for (const [key, value] of this) entries.push([key, value]);
+    if (entries.length <= 1) return true;
+    this.clear();
+    this.setMany(
+      entries.map(([k]) => k),
+      entries.map(([, v]) => v),
+      true
+      // isBalanceAdd
+    );
+    return true;
+  }
   map(callback, options, thisArg) {
     const out = this._createLike([], options);
     let index = 0;
@@ -11883,7 +12215,7 @@ var _TreeSet = class _TreeSet {
   static createDefaultComparator() {
     return (a, b) => {
       if (typeof a === "number" && typeof b === "number") {
-        if (Number.isNaN(a) || Number.isNaN(b)) throw new TypeError("TreeSet: NaN is not a valid key");
+        if (Number.isNaN(a) || Number.isNaN(b)) throw new TypeError(ERR.invalidNaN("TreeSet"));
         const aa = Object.is(a, -0) ? 0 : a;
         const bb = Object.is(b, -0) ? 0 : b;
         return aa > bb ? 1 : aa < bb ? -1 : 0;
@@ -11894,10 +12226,10 @@ var _TreeSet = class _TreeSet {
       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("TreeSet: invalid Date key");
+        if (Number.isNaN(ta) || Number.isNaN(tb)) throw new TypeError(ERR.invalidDate("TreeSet"));
         return ta > tb ? 1 : ta < tb ? -1 : 0;
       }
-      throw new TypeError("TreeSet: comparator is required for non-number/non-string/non-Date keys");
+      throw new TypeError(ERR.comparatorRequired("TreeSet"));
     };
   }
   /**
@@ -11915,15 +12247,15 @@ var _TreeSet = class _TreeSet {
   _validateKey(key) {
     if (!__privateGet(this, _isDefaultComparator)) return;
     if (typeof key === "number") {
-      if (Number.isNaN(key)) throw new TypeError("TreeSet: NaN is not a valid key");
+      if (Number.isNaN(key)) throw new TypeError(ERR.invalidNaN("TreeSet"));
       return;
     }
     if (typeof key === "string") return;
     if (key instanceof Date) {
-      if (Number.isNaN(key.getTime())) throw new TypeError("TreeSet: invalid Date key");
+      if (Number.isNaN(key.getTime())) throw new TypeError(ERR.invalidDate("TreeSet"));
       return;
     }
-    throw new TypeError("TreeSet: comparator is required for non-number/non-string/non-Date keys");
+    throw new TypeError(ERR.comparatorRequired("TreeSet"));
   }
   /**
    * Add a key to the set (no-op if already present).
@@ -12246,15 +12578,15 @@ var _TreeMultiMap = class _TreeMultiMap {
   _validateKey(key) {
     if (!__privateGet(this, _isDefaultComparator2)) return;
     if (typeof key === "number") {
-      if (Number.isNaN(key)) throw new TypeError("TreeMultiMap: NaN is not a valid key");
+      if (Number.isNaN(key)) throw new TypeError(ERR.invalidNaN("TreeMultiMap"));
       return;
     }
     if (typeof key === "string") return;
     if (key instanceof Date) {
-      if (Number.isNaN(key.getTime())) throw new TypeError("TreeMultiMap: invalid Date key");
+      if (Number.isNaN(key.getTime())) throw new TypeError(ERR.invalidDate("TreeMultiMap"));
       return;
     }
-    throw new TypeError("TreeMultiMap: comparator is required for non-number/non-string/non-Date keys");
+    throw new TypeError(ERR.comparatorRequired("TreeMultiMap"));
   }
   /**
    * Number of distinct keys.
@@ -12679,7 +13011,7 @@ var _TreeMap = class _TreeMap {
         [k, v] = toEntryFn(item);
       } else {
         if (!Array.isArray(item) || item.length < 2) {
-          throw new TypeError("TreeMap: each entry must be a [key, value] tuple");
+          throw new TypeError(ERR.invalidEntry("TreeMap"));
         }
         k = item[0];
         v = item[1];
@@ -12700,7 +13032,7 @@ var _TreeMap = class _TreeMap {
   static createDefaultComparator() {
     return (a, b) => {
       if (typeof a === "number" && typeof b === "number") {
-        if (Number.isNaN(a) || Number.isNaN(b)) throw new TypeError("TreeMap: NaN is not a valid key");
+        if (Number.isNaN(a) || Number.isNaN(b)) throw new TypeError(ERR.invalidNaN("TreeMap"));
         const aa = Object.is(a, -0) ? 0 : a;
         const bb = Object.is(b, -0) ? 0 : b;
         return aa > bb ? 1 : aa < bb ? -1 : 0;
@@ -12711,24 +13043,24 @@ var _TreeMap = class _TreeMap {
       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("TreeMap: invalid Date key");
+        if (Number.isNaN(ta) || Number.isNaN(tb)) throw new TypeError(ERR.invalidDate("TreeMap"));
         return ta > tb ? 1 : ta < tb ? -1 : 0;
       }
-      throw new TypeError("TreeMap: comparator is required for non-number/non-string/non-Date keys");
+      throw new TypeError(ERR.comparatorRequired("TreeMap"));
     };
   }
   _validateKey(key) {
     if (!__privateGet(this, _isDefaultComparator3)) return;
     if (typeof key === "number") {
-      if (Number.isNaN(key)) throw new TypeError("TreeMap: NaN is not a valid key");
+      if (Number.isNaN(key)) throw new TypeError(ERR.invalidNaN("TreeMap"));
       return;
     }
     if (typeof key === "string") return;
     if (key instanceof Date) {
-      if (Number.isNaN(key.getTime())) throw new TypeError("TreeMap: invalid Date key");
+      if (Number.isNaN(key.getTime())) throw new TypeError(ERR.invalidDate("TreeMap"));
       return;
     }
-    throw new TypeError("TreeMap: comparator is required for non-number/non-string/non-Date keys");
+    throw new TypeError(ERR.comparatorRequired("TreeMap"));
   }
   /**
    * Number of entries in the map.
@@ -13057,22 +13389,22 @@ var _TreeMultiSet = class _TreeMultiSet {
   _validateKey(key) {
     if (!__privateGet(this, _isDefaultComparator4)) return;
     if (typeof key === "number") {
-      if (Number.isNaN(key)) throw new TypeError("TreeMultiSet: NaN is not a valid key");
+      if (Number.isNaN(key)) throw new TypeError(ERR.invalidNaN("TreeMultiSet"));
       return;
     }
     if (typeof key === "string") return;
     if (key instanceof Date) {
-      if (Number.isNaN(key.getTime())) throw new TypeError("TreeMultiSet: invalid Date key");
+      if (Number.isNaN(key.getTime())) throw new TypeError(ERR.invalidDate("TreeMultiSet"));
       return;
     }
-    throw new TypeError("TreeMultiSet: comparator is required for non-number/non-string/non-Date keys");
+    throw new TypeError(ERR.comparatorRequired("TreeMultiSet"));
   }
   /**
    * Validates that count is a non-negative safe integer.
    * @remarks Time O(1), Space O(1)
    */
   _validateCount(n) {
-    if (!Number.isSafeInteger(n) || n < 0) throw new RangeError("TreeMultiSet: count must be a safe integer >= 0");
+    if (!Number.isSafeInteger(n) || n < 0) throw new RangeError(ERR.invalidArgument("count must be a safe integer >= 0.", "TreeMultiSet"));
   }
   /**
    * Total occurrences (sumCounts).
@@ -13500,9 +13832,7 @@ var _MaxPriorityQueue = class _MaxPriorityQueue extends PriorityQueue {
     super(elements, {
       comparator: /* @__PURE__ */ __name((a, b) => {
         if (typeof a === "object" || typeof b === "object") {
-          throw TypeError(
-            `When comparing object types, a custom comparator must be defined in the constructor's options parameter.`
-          );
+          throw new TypeError(ERR.comparatorRequired("MaxPriorityQueue"));
         }
         if (a < b) return 1;
         if (a > b) return -1;
@@ -13643,7 +13973,7 @@ var _Matrix = class _Matrix {
    */
   add(matrix) {
     if (!this.isMatchForCalculate(matrix)) {
-      throw new Error("Matrix dimensions must match for addition.");
+      throw new Error(ERR.matrixDimensionMismatch("addition"));
     }
     const resultData = [];
     for (let i = 0; i < this.rows; i++) {
@@ -13675,7 +14005,7 @@ var _Matrix = class _Matrix {
    */
   subtract(matrix) {
     if (!this.isMatchForCalculate(matrix)) {
-      throw new Error("Matrix dimensions must match for subtraction.");
+      throw new Error(ERR.matrixDimensionMismatch("subtraction"));
     }
     const resultData = [];
     for (let i = 0; i < this.rows; i++) {
@@ -13706,7 +14036,7 @@ var _Matrix = class _Matrix {
    */
   multiply(matrix) {
     if (this.cols !== matrix.rows) {
-      throw new Error("Matrix dimensions must be compatible for multiplication (A.cols = B.rows).");
+      throw new Error(ERR.matrixDimensionMismatch("multiplication (A.cols must equal B.rows)"));
     }
     const resultData = [];
     for (let i = 0; i < this.rows; i++) {
@@ -13740,7 +14070,7 @@ var _Matrix = class _Matrix {
    */
   transpose() {
     if (this.data.some((row) => row.length !== this.rows)) {
-      throw new Error("Matrix must be rectangular for transposition.");
+      throw new Error(ERR.matrixNotRectangular());
     }
     const resultData = [];
     for (let j = 0; j < this.cols; j++) {
@@ -13765,7 +14095,7 @@ var _Matrix = class _Matrix {
   inverse() {
     var _a;
     if (this.rows !== this.cols) {
-      throw new Error("Matrix must be square for inversion.");
+      throw new Error(ERR.matrixNotSquare());
     }
     const augmentedMatrixData = [];
     for (let i = 0; i < this.rows; i++) {
@@ -13787,12 +14117,12 @@ var _Matrix = class _Matrix {
         pivotRow++;
       }
       if (pivotRow === this.rows) {
-        throw new Error("Matrix is singular, and its inverse does not exist.");
+        throw new Error(ERR.matrixSingular());
       }
       augmentedMatrix._swapRows(i, pivotRow);
       const pivotElement = (_a = augmentedMatrix.get(i, i)) != null ? _a : 1;
       if (pivotElement === 0) {
-        throw new Error("Matrix is singular, and its inverse does not exist (division by zero).");
+        throw new Error(ERR.matrixSingular());
       }
       augmentedMatrix._scaleRow(i, 1 / pivotElement);
       for (let j = 0; j < this.rows; j++) {
@@ -13822,9 +14152,7 @@ var _Matrix = class _Matrix {
    */
   dot(matrix) {
     if (this.cols !== matrix.rows) {
-      throw new Error(
-        "Number of columns in the first matrix must be equal to the number of rows in the second matrix for dot product."
-      );
+      throw new Error(ERR.matrixDimensionMismatch("dot product (A.cols must equal B.rows)"));
     }
     const resultData = [];
     for (let i = 0; i < this.rows; i++) {
@@ -14446,7 +14774,7 @@ var _Trie = class _Trie extends IterableElementBase {
     for (const x of this) {
       const v = thisArg === void 0 ? callback(x, i++, this) : callback.call(thisArg, x, i++, this);
       if (typeof v !== "string") {
-        throw new TypeError(`Trie.map callback must return string; got ${typeof v}`);
+        throw new TypeError(ERR.callbackReturnType("string", typeof v, "Trie.map"));
       }
       newTrie.add(v);
     }
@@ -14697,6 +15025,7 @@ exports.DirectedGraph = DirectedGraph;
 exports.DirectedVertex = DirectedVertex;
 exports.DoublyLinkedList = DoublyLinkedList;
 exports.DoublyLinkedListNode = DoublyLinkedListNode;
+exports.ERR = ERR;
 exports.FibonacciHeap = FibonacciHeap;
 exports.FibonacciHeapNode = FibonacciHeapNode;
 exports.HashMap = HashMap;