binary-tree-typed 2.4.4 → 2.5.0

package/src/data-structures/graph/undirected-graph.ts

@@ -77,65 +77,6 @@ export class UndirectedEdge<E = number> extends AbstractEdge<E> {
  *     console.log(neighborsA[0].key); // 'B';
  *     console.log(neighborsA[1].key); // 'C';
  * @example
- * // UndirectedGraph deleteEdge and vertex operations
- *  const graph = new UndirectedGraph<string>();
- *
- *     // Build a simple undirected graph
- *     graph.addVertex('X');
- *     graph.addVertex('Y');
- *     graph.addVertex('Z');
- *     graph.addEdge('X', 'Y', 1);
- *     graph.addEdge('Y', 'Z', 2);
- *     graph.addEdge('X', 'Z', 3);
- *
- *     // Delete an edge
- *     graph.deleteEdge('X', 'Y');
- *     console.log(graph.hasEdge('X', 'Y')); // false;
- *
- *     // Bidirectional deletion confirmed
- *     console.log(graph.hasEdge('Y', 'X')); // false;
- *
- *     // Other edges should remain
- *     console.log(graph.hasEdge('Y', 'Z')); // true;
- *     console.log(graph.hasEdge('Z', 'Y')); // true;
- *
- *     // Delete a vertex
- *     graph.deleteVertex('Y');
- *     console.log(graph.hasVertex('Y')); // false;
- *     console.log(graph.size); // 2;
- * @example
- * // UndirectedGraph connectivity and neighbors
- *  const graph = new UndirectedGraph<string>();
- *
- *     // Build a friendship network
- *     const people = ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve'];
- *     for (const person of people) {
- *       graph.addVertex(person);
- *     }
- *
- *     // Add friendships (undirected edges)
- *     graph.addEdge('Alice', 'Bob', 1);
- *     graph.addEdge('Alice', 'Charlie', 1);
- *     graph.addEdge('Bob', 'Diana', 1);
- *     graph.addEdge('Charlie', 'Eve', 1);
- *     graph.addEdge('Diana', 'Eve', 1);
- *
- *     // Get friends of each person
- *     const aliceFriends = graph.getNeighbors('Alice');
- *     console.log(aliceFriends[0].key); // 'Bob';
- *     console.log(aliceFriends[1].key); // 'Charlie';
- *     console.log(aliceFriends.length); // 2;
- *
- *     const dianaFriends = graph.getNeighbors('Diana');
- *     console.log(dianaFriends[0].key); // 'Bob';
- *     console.log(dianaFriends[1].key); // 'Eve';
- *     console.log(dianaFriends.length); // 2;
- *
- *     // Verify bidirectional friendship
- *     const bobFriends = graph.getNeighbors('Bob');
- *     console.log(bobFriends[0].key); // 'Alice'; // Alice -> Bob -> Alice ✓
- *     console.log(bobFriends[1].key); // 'Diana';
- * @example
  * // UndirectedGraph for social network connectivity analysis
  *  interface Person {
  *       id: number;
@@ -285,6 +226,21 @@ export class UndirectedGraph<
    * @param v2 - The other vertex or key.
    * @returns Edge instance or `undefined`.
    * @remarks Time O(1) avg, Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Get edge between vertices
+ *  const g = new UndirectedGraph();
+ *     g.addVertex('A');
+ *     g.addVertex('B');
+ *     g.addEdge('A', 'B', 7);
+ *     console.log(g.getEdge('A', 'B')?.weight); // 7;
    */
   getEdge(v1: VO | VertexKey | undefined, v2: VO | VertexKey | undefined): EO | undefined {
     let edgeMap: EO[] | undefined = [];
@@ -334,6 +290,44 @@ export class UndirectedGraph<
    * @param otherSideVertexKey - Required second endpoint when deleting by pair.
    * @returns Removed edge or `undefined`.
    * @remarks Time O(1) avg, Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // UndirectedGraph deleteEdge and vertex operations
+ *  const graph = new UndirectedGraph<string>();
+ *
+ *     // Build a simple undirected graph
+ *     graph.addVertex('X');
+ *     graph.addVertex('Y');
+ *     graph.addVertex('Z');
+ *     graph.addEdge('X', 'Y', 1);
+ *     graph.addEdge('Y', 'Z', 2);
+ *     graph.addEdge('X', 'Z', 3);
+ *
+ *     // Delete an edge
+ *     graph.deleteEdge('X', 'Y');
+ *     console.log(graph.hasEdge('X', 'Y')); // false;
+ *
+ *     // Bidirectional deletion confirmed
+ *     console.log(graph.hasEdge('Y', 'X')); // false;
+ *
+ *     // Other edges should remain
+ *     console.log(graph.hasEdge('Y', 'Z')); // true;
+ *     console.log(graph.hasEdge('Z', 'Y')); // true;
+ *
+ *     // Delete a vertex
+ *     graph.deleteVertex('Y');
+ *     console.log(graph.hasVertex('Y')); // false;
+ *     console.log(graph.size); // 2;
    */
   deleteEdge(edgeOrOneSideVertexKey: EO | VertexKey, otherSideVertexKey?: VertexKey): EO | undefined {
     let oneSide: VO | undefined, otherSide: VO | undefined;
@@ -361,6 +355,22 @@ export class UndirectedGraph<
    * @param vertexOrKey - Vertex or key.
    * @returns `true` if removed; otherwise `false`.
    * @remarks Time O(deg), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove vertex and edges
+ *  const g = new UndirectedGraph();
+ *     g.addVertex('A');
+ *     g.addVertex('B');
+ *     g.addEdge('A', 'B');
+ *     g.deleteVertex('A');
+ *     console.log(g.hasVertex('A')); // false;
    */
   deleteVertex(vertexOrKey: VO | VertexKey): boolean {
     let vertexKey: VertexKey;
@@ -431,6 +441,21 @@ export class UndirectedGraph<
    * Unique set of undirected edges across endpoints.
    * @returns Array of edges.
    * @remarks Time O(E), Space O(E)
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Get all edges
+ *  const g = new UndirectedGraph();
+ *     g.addVertex('A');
+ *     g.addVertex('B');
+ *     g.addEdge('A', 'B');
+ *     console.log(g.edgeSet().length); // 1;
    */
   edgeSet(): EO[] {
     const edgeSet: Set<EO> = new Set();
@@ -442,6 +467,52 @@ export class UndirectedGraph<
     return [...edgeSet];
   }
 
+    /**
+   * UndirectedGraph connectivity and neighbors
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // UndirectedGraph connectivity and neighbors
+ *  const graph = new UndirectedGraph<string>();
+ *
+ *     // Build a friendship network
+ *     const people = ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve'];
+ *     for (const person of people) {
+ *       graph.addVertex(person);
+ *     }
+ *
+ *     // Add friendships (undirected edges)
+ *     graph.addEdge('Alice', 'Bob', 1);
+ *     graph.addEdge('Alice', 'Charlie', 1);
+ *     graph.addEdge('Bob', 'Diana', 1);
+ *     graph.addEdge('Charlie', 'Eve', 1);
+ *     graph.addEdge('Diana', 'Eve', 1);
+ *
+ *     // Get friends of each person
+ *     const aliceFriends = graph.getNeighbors('Alice');
+ *     console.log(aliceFriends[0].key); // 'Bob';
+ *     console.log(aliceFriends[1].key); // 'Charlie';
+ *     console.log(aliceFriends.length); // 2;
+ *
+ *     const dianaFriends = graph.getNeighbors('Diana');
+ *     console.log(dianaFriends[0].key); // 'Bob';
+ *     console.log(dianaFriends[1].key); // 'Eve';
+ *     console.log(dianaFriends.length); // 2;
+ *
+ *     // Verify bidirectional friendship
+ *     const bobFriends = graph.getNeighbors('Bob');
+ *     console.log(bobFriends[0].key); // 'Alice'; // Alice -> Bob -> Alice ✓
+ *     console.log(bobFriends[1].key); // 'Diana';
+   */
   getNeighbors(vertexOrKey: VO | VertexKey): VO[] {
     const neighbors: VO[] = [];
     const vertex = this._getVertex(vertexOrKey);
@@ -506,6 +577,24 @@ export class UndirectedGraph<
    * Tarjan-based bridge and articulation point detection.
    * @returns `{ dfnMap, lowMap, bridges, cutVertices }`.
    * @remarks Time O(V + E), Space O(V + E)
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Find articulation points and bridges
+ *  const g = new UndirectedGraph();
+ *     g.addVertex('A');
+ *     g.addVertex('B');
+ *     g.addVertex('C');
+ *     g.addEdge('A', 'B');
+ *     g.addEdge('B', 'C');
+ *     const result = g.tarjan();
+ *     console.log(result); // defined;
    */
   tarjan(): { dfnMap: Map<VO, number>; lowMap: Map<VO, number>; bridges: EO[]; cutVertices: VO[] } {
     const dfnMap = new Map<VO, number>();
@@ -566,10 +655,142 @@ export class UndirectedGraph<
     };
   }
 
+  /**
+   * 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(): EO[][] {
+    const dfn = new Map<VO, number>();
+    const low = new Map<VO, number>();
+    const edgeStack: EO[] = [];
+    const components: EO[][] = [];
+    let time = 0;
+
+    const dfs = (vertex: VO, parent: VO | undefined) => {
+      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)!));
+
+          // Articulation point found — pop edges to form a component
+          if (
+            (parent === undefined && childCount > 1) ||
+            (parent !== undefined && low.get(neighbor)! >= dfn.get(vertex)!)
+          ) {
+            const component: EO[] = [];
+            let e: EO | undefined;
+            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)!) {
+          // Back edge (only push once per undirected edge)
+          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, undefined);
+        // Remaining edges form a component
+        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)
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Detect cycle
+ *  const g = new UndirectedGraph();
+ *     g.addVertex('A');
+ *     g.addVertex('B');
+ *     g.addVertex('C');
+ *     g.addEdge('A', 'B');
+ *     g.addEdge('B', 'C');
+ *     console.log(g.hasCycle()); // false;
+ *     g.addEdge('C', 'A');
+ *     console.log(g.hasCycle()); // true;
+   */
+  hasCycle(): boolean {
+    const visited = new Set<VO>();
+
+    const dfs = (vertex: VO, parent: VO | undefined): boolean => {
+      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; // back edge = cycle
+        }
+      }
+      return false;
+    };
+
+    for (const vertex of this.vertexMap.values()) {
+      if (!visited.has(vertex)) {
+        if (dfs(vertex, undefined)) return true;
+      }
+    }
+    return false;
+  }
+
   /**
    * Get bridges discovered by `tarjan()`.
    * @returns Array of edges that are bridges.
    * @remarks Time O(B), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Find bridge edges
+ *  const g = new UndirectedGraph();
+ *     g.addVertex('A');
+ *     g.addVertex('B');
+ *     g.addVertex('C');
+ *     g.addEdge('A', 'B');
+ *     g.addEdge('B', 'C');
+ *     const bridges = g.getBridges();
+ *     console.log(bridges.length); // 2;
    */
   getBridges() {
     return this.tarjan().bridges;
@@ -579,6 +800,25 @@ export class UndirectedGraph<
    * Get articulation points discovered by `tarjan()`.
    * @returns Array of cut vertices.
    * @remarks Time O(C), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Find articulation points
+ *  const g = new UndirectedGraph();
+ *     g.addVertex('A');
+ *     g.addVertex('B');
+ *     g.addVertex('C');
+ *     g.addEdge('A', 'B');
+ *     g.addEdge('B', 'C');
+ *     const cuts = g.getCutVertices();
+ *     console.log(cuts.length); // 1;
+ *     console.log(cuts[0].key); // 'B';
    */
   getCutVertices() {
     return this.tarjan().cutVertices;