avl-tree-typed 2.4.3 → 2.4.5

package/dist/esm/index.mjs

@@ -57,6 +57,50 @@ function makeTrampoline(fn) {
 }
 __name(makeTrampoline, "makeTrampoline");
 
+// 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-element-base.ts
 var IterableElementBase = class {
   static {
@@ -75,7 +119,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) throw new TypeError(ERR.notAFunction("toElementFn"));
     }
   }
   /**
@@ -238,7 +282,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) throw new TypeError(ERR.reduceEmpty());
       acc = first.value;
       index = 1;
     }
@@ -1023,25 +1067,6 @@ var IterableEntryBase = class {
   }
 };
 
-// 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/binary-tree/binary-tree.ts
 var BinaryTreeNode = class {
   static {
@@ -1180,7 +1205,7 @@ var BinaryTreeNode = class {
     return "MAL_NODE";
   }
 };
-var BinaryTree = class extends IterableEntryBase {
+var BinaryTree = class _BinaryTree extends IterableEntryBase {
   static {
     __name(this, "BinaryTree");
   }
@@ -1200,7 +1225,7 @@ var BinaryTree = class 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);
   }
@@ -1438,7 +1463,7 @@ var BinaryTree = class 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]);
@@ -1470,7 +1495,7 @@ var BinaryTree = class 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;
@@ -2038,7 +2063,7 @@ var BinaryTree = class 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.
@@ -2061,15 +2086,15 @@ var BinaryTree = class 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);
         }
       }
     }
@@ -2438,7 +2463,7 @@ var BinaryTree = class extends IterableEntryBase {
    * @param node - The node.
    * @returns The node's key or undefined.
    */
-  _DEFAULT_NODE_CALLBACK = /* @__PURE__ */ __name((node) => node ? node.key : void 0, "_DEFAULT_NODE_CALLBACK");
+  _DEFAULT_NODE_CALLBACK = /* @__PURE__ */ __name((node) => node?.key, "_DEFAULT_NODE_CALLBACK");
   /**
    * (Protected) Snapshots the current tree's configuration options.
    * @remarks Time O(1)
@@ -2531,42 +2556,98 @@ var BinaryTree = class 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.
@@ -3572,9 +3653,15 @@ var BST = class 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;