data-structure-typed 2.4.4 → 2.4.5

package/dist/umd/data-structure-typed.js

@@ -48,6 +48,7 @@ var dataStructureTyped = (() => {
     DirectedVertex: () => DirectedVertex,
     DoublyLinkedList: () => DoublyLinkedList,
     DoublyLinkedListNode: () => DoublyLinkedListNode,
+    ERR: () => ERR,
     FibonacciHeap: () => FibonacciHeap,
     FibonacciHeapNode: () => FibonacciHeapNode,
     HashMap: () => HashMap,
@@ -285,6 +286,52 @@ var dataStructureTyped = (() => {
     }
   };
 
+  // src/common/error.ts
+  var ERR = {
+    // Range / index
+    indexOutOfRange: (index, min, max, ctx) => `${ctx ? ctx + ": " : ""}Index ${index} is out of range [${min}, ${max}].`,
+    invalidIndex: (ctx) => `${ctx ? ctx + ": " : ""}Index must be an integer.`,
+    // Type / argument
+    invalidArgument: (reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`,
+    comparatorRequired: (ctx) => `${ctx ? ctx + ": " : ""}Comparator is required for non-number/non-string/non-Date keys.`,
+    invalidKey: (reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`,
+    notAFunction: (name, ctx) => `${ctx ? ctx + ": " : ""}${name} must be a function.`,
+    invalidEntry: (ctx) => `${ctx ? ctx + ": " : ""}Each entry must be a [key, value] tuple.`,
+    invalidNaN: (ctx) => `${ctx ? ctx + ": " : ""}NaN is not a valid key.`,
+    invalidDate: (ctx) => `${ctx ? ctx + ": " : ""}Invalid Date key.`,
+    reduceEmpty: (ctx) => `${ctx ? ctx + ": " : ""}Reduce of empty structure with no initial value.`,
+    callbackReturnType: (expected, got, ctx) => `${ctx ? ctx + ": " : ""}Callback must return ${expected}; got ${got}.`,
+    // State / operation
+    invalidOperation: (reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`,
+    // Matrix
+    matrixDimensionMismatch: (op) => `Matrix: Dimensions must be compatible for ${op}.`,
+    matrixSingular: () => "Matrix: Singular matrix, inverse does not exist.",
+    matrixNotSquare: () => "Matrix: Must be square for inversion.",
+    matrixNotRectangular: () => "Matrix: Must be rectangular for transposition.",
+    matrixRowMismatch: (expected, got) => `Matrix: Expected row length ${expected}, but got ${got}.`
+  };
+
+  // src/common/index.ts
+  var DFSOperation = /* @__PURE__ */ ((DFSOperation2) => {
+    DFSOperation2[DFSOperation2["VISIT"] = 0] = "VISIT";
+    DFSOperation2[DFSOperation2["PROCESS"] = 1] = "PROCESS";
+    return DFSOperation2;
+  })(DFSOperation || {});
+  var Range = class {
+    constructor(low, high, includeLow = true, includeHigh = true) {
+      this.low = low;
+      this.high = high;
+      this.includeLow = includeLow;
+      this.includeHigh = includeHigh;
+    }
+    // Determine whether a key is within the range
+    isInRange(key, comparator) {
+      const lowCheck = this.includeLow ? comparator(key, this.low) >= 0 : comparator(key, this.low) > 0;
+      const highCheck = this.includeHigh ? comparator(key, this.high) <= 0 : comparator(key, this.high) < 0;
+      return lowCheck && highCheck;
+    }
+  };
+
   // src/data-structures/base/iterable-element-base.ts
   var IterableElementBase = class {
     /**
@@ -307,7 +354,7 @@ var dataStructureTyped = (() => {
       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"));
       }
     }
     /**
@@ -463,7 +510,7 @@ var dataStructureTyped = (() => {
         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;
       }
@@ -531,8 +578,10 @@ var dataStructureTyped = (() => {
     }
     return 1 << 31 - Math.clz32(value);
   };
-  var rangeCheck = (index, min, max, message = "Index out of bounds.") => {
-    if (index < min || index > max) throw new RangeError(message);
+  var rangeCheck = (index, min, max, message) => {
+    if (index < min || index > max) {
+      throw new RangeError(message != null ? message : `Index ${index} is out of range [${min}, ${max}].`);
+    }
   };
   var throwRangeError = (message = "The value is off-limits.") => {
     throw new RangeError(message);
@@ -894,8 +943,8 @@ var dataStructureTyped = (() => {
         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")
         );
       });
       __publicField(this, "_size", 0);
@@ -1180,6 +1229,13 @@ var dataStructureTyped = (() => {
       }
     }
     _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;
@@ -3660,17 +3716,16 @@ var dataStructureTyped = (() => {
 
   // src/data-structures/queue/deque.ts
   var Deque = class 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", (a, b) => Object.is(a, b));
       __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);
@@ -3679,8 +3734,9 @@ var dataStructureTyped = (() => {
       __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) {
@@ -3705,6 +3761,24 @@ var dataStructureTyped = (() => {
     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)
@@ -3836,6 +3910,7 @@ var dataStructureTyped = (() => {
         }
       }
       this._length -= 1;
+      this._autoCompact();
       return element;
     }
     /**
@@ -3858,6 +3933,7 @@ var dataStructureTyped = (() => {
         }
       }
       this._length -= 1;
+      this._autoCompact();
       return element;
     }
     /**
@@ -4190,11 +4266,40 @@ var dataStructureTyped = (() => {
      * @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]);
         }
@@ -4209,6 +4314,8 @@ var dataStructureTyped = (() => {
       this._bucketFirst = 0;
       this._bucketLast = newBuckets.length - 1;
       this._buckets = newBuckets;
+      this._bucketCount = newBuckets.length;
+      this._compactCounter = 0;
     }
     /**
      * Deep clone this deque, preserving options.
@@ -4404,7 +4511,7 @@ var dataStructureTyped = (() => {
       __publicField(this, "_elements", []);
       __publicField(this, "_DEFAULT_COMPARATOR", (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;
@@ -4714,7 +4821,7 @@ var dataStructureTyped = (() => {
      */
     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) {
@@ -4842,7 +4949,7 @@ var dataStructureTyped = (() => {
       __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.
@@ -5051,9 +5158,7 @@ var dataStructureTyped = (() => {
       super(elements, {
         comparator: (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;
@@ -5210,7 +5315,7 @@ var dataStructureTyped = (() => {
           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"));
         }
       }
     }
@@ -5894,6 +5999,94 @@ var dataStructureTyped = (() => {
     _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));
+    }
   };
 
   // src/data-structures/graph/directed-graph.ts
@@ -5922,6 +6115,9 @@ var dataStructureTyped = (() => {
       __publicField(this, "_outEdgeMap", /* @__PURE__ */ new Map());
       __publicField(this, "_inEdgeMap", /* @__PURE__ */ new Map());
     }
+    get _edgeConnector() {
+      return "->";
+    }
     get outEdgeMap() {
       return this._outEdgeMap;
     }
@@ -6696,6 +6892,84 @@ var dataStructureTyped = (() => {
         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 = (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)));
+          }
+        }
+      };
+      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 = (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;
+      };
+      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.
@@ -6840,27 +7114,6 @@ var dataStructureTyped = (() => {
     }
   };
 
-  // src/common/index.ts
-  var DFSOperation = /* @__PURE__ */ ((DFSOperation2) => {
-    DFSOperation2[DFSOperation2["VISIT"] = 0] = "VISIT";
-    DFSOperation2[DFSOperation2["PROCESS"] = 1] = "PROCESS";
-    return DFSOperation2;
-  })(DFSOperation || {});
-  var Range = class {
-    constructor(low, high, includeLow = true, includeHigh = true) {
-      this.low = low;
-      this.high = high;
-      this.includeLow = includeLow;
-      this.includeHigh = includeHigh;
-    }
-    // Determine whether a key is within the range
-    isInRange(key, comparator) {
-      const lowCheck = this.includeLow ? comparator(key, this.low) >= 0 : comparator(key, this.low) > 0;
-      const highCheck = this.includeHigh ? comparator(key, this.high) <= 0 : comparator(key, this.high) < 0;
-      return lowCheck && highCheck;
-    }
-  };
-
   // src/data-structures/binary-tree/binary-tree.ts
   var BinaryTreeNode = class {
     /**
@@ -6996,7 +7249,7 @@ var dataStructureTyped = (() => {
       return "MAL_NODE";
     }
   };
-  var BinaryTree = class extends IterableEntryBase {
+  var BinaryTree = class _BinaryTree extends IterableEntryBase {
     /**
      * Creates an instance of BinaryTree.
      * @remarks Time O(N * M), where N is the number of items in `keysNodesEntriesOrRaws` and M is the tree size at insertion time (due to O(M) `set` operation). Space O(N) for storing the nodes.
@@ -7031,7 +7284,7 @@ var dataStructureTyped = (() => {
         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);
     }
@@ -7259,7 +7512,7 @@ var dataStructureTyped = (() => {
       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]);
@@ -7291,7 +7544,7 @@ var dataStructureTyped = (() => {
           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;
@@ -7860,7 +8113,7 @@ var dataStructureTyped = (() => {
     }
     /**
      * 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.
@@ -7883,15 +8136,15 @@ var dataStructureTyped = (() => {
         };
         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);
           }
         }
       }
@@ -8347,42 +8600,98 @@ var dataStructureTyped = (() => {
     _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 = (n) => ({
+        node: n,
+        stage: 0,
+        leftLayout: emptyDisplayLayout,
+        rightLayout: emptyDisplayLayout
+      });
+      const stack = [newFrame(node)];
+      let result = emptyDisplayLayout;
+      const setChildResult = (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;
+      };
+      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.
@@ -9384,9 +9693,15 @@ var dataStructureTyped = (() => {
           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;
@@ -9898,7 +10213,7 @@ var dataStructureTyped = (() => {
      */
     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));
     }
@@ -9910,7 +10225,7 @@ var dataStructureTyped = (() => {
      */
     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);
     }
@@ -9923,7 +10238,7 @@ var dataStructureTyped = (() => {
      */
     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);
     }
@@ -9974,10 +10289,10 @@ var dataStructureTyped = (() => {
      */
     _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"));
       }
     }
     /**
@@ -11554,6 +11869,24 @@ var dataStructureTyped = (() => {
      * @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;
@@ -11876,7 +12209,7 @@ var dataStructureTyped = (() => {
     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;
@@ -11887,10 +12220,10 @@ var dataStructureTyped = (() => {
         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"));
       };
     }
     /**
@@ -11908,15 +12241,15 @@ var dataStructureTyped = (() => {
     _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).
@@ -12236,15 +12569,15 @@ var dataStructureTyped = (() => {
     _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.
@@ -12668,7 +13001,7 @@ var dataStructureTyped = (() => {
           [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];
@@ -12689,7 +13022,7 @@ var dataStructureTyped = (() => {
     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;
@@ -12700,24 +13033,24 @@ var dataStructureTyped = (() => {
         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.
@@ -13045,22 +13378,22 @@ var dataStructureTyped = (() => {
     _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).
@@ -13483,9 +13816,7 @@ var dataStructureTyped = (() => {
       super(elements, {
         comparator: (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;
@@ -13624,7 +13955,7 @@ var dataStructureTyped = (() => {
      */
     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++) {
@@ -13656,7 +13987,7 @@ var dataStructureTyped = (() => {
      */
     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++) {
@@ -13687,7 +14018,7 @@ var dataStructureTyped = (() => {
      */
     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++) {
@@ -13721,7 +14052,7 @@ var dataStructureTyped = (() => {
      */
     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++) {
@@ -13746,7 +14077,7 @@ var dataStructureTyped = (() => {
     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++) {
@@ -13768,12 +14099,12 @@ var dataStructureTyped = (() => {
           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++) {
@@ -13803,9 +14134,7 @@ var dataStructureTyped = (() => {
      */
     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++) {
@@ -14419,7 +14748,7 @@ var dataStructureTyped = (() => {
       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);
       }