undirected-graph-typed 2.4.4 → 2.4.5

package/dist/cjs/index.cjs

@@ -24,6 +24,55 @@ var arrayRemove = /* @__PURE__ */ __name(function(array, predicate) {
   return result;
 }, "arrayRemove");
 
+// 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 {
+  constructor(low, high, includeLow = true, includeHigh = true) {
+    this.low = low;
+    this.high = high;
+    this.includeLow = includeLow;
+    this.includeHigh = includeHigh;
+  }
+  static {
+    __name(this, "Range");
+  }
+  // Determine whether a key is within the range
+  isInRange(key, comparator) {
+    const lowCheck = this.includeLow ? comparator(key, this.low) >= 0 : comparator(key, this.low) > 0;
+    const highCheck = this.includeHigh ? comparator(key, this.high) <= 0 : comparator(key, this.high) < 0;
+    return lowCheck && highCheck;
+  }
+};
+
 // src/data-structures/base/iterable-entry-base.ts
 var IterableEntryBase = class {
   static {
@@ -224,7 +273,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"));
     }
   }
   /**
@@ -387,7 +436,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;
     }
@@ -747,7 +796,7 @@ var Heap = class _Heap extends IterableElementBase {
    */
   map(callback, options, thisArg) {
     const { comparator, toElementFn, ...rest } = 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) {
@@ -774,7 +823,7 @@ var Heap = class _Heap extends IterableElementBase {
   }
   _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;
@@ -1561,7 +1610,7 @@ var AbstractGraph = class 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"));
       }
     }
   }
@@ -2241,6 +2290,92 @@ var AbstractGraph = class 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) {
+    const showWeight = options?.showWeight ?? 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) {
+    const name = options?.name ?? "G";
+    const showWeight = options?.showWeight ?? 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/undirected-graph.ts
@@ -2577,6 +2712,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.
@@ -2631,30 +2844,6 @@ var UndirectedGraph = class _UndirectedGraph extends AbstractGraph {
     return true;
   }
 };
-
-// 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;
-  }
-  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;
-  }
-};
 /**
  * data-structure-typed
  *
@@ -2664,6 +2853,7 @@ var Range = class {
  */
 
 exports.DFSOperation = DFSOperation;
+exports.ERR = ERR;
 exports.Range = Range;
 exports.UndirectedEdge = UndirectedEdge;
 exports.UndirectedGraph = UndirectedGraph;