data-structure-typed 2.5.3 → 2.6.1

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

@@ -5,7 +5,6 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-
 import type { GraphOptions, VertexKey } from '../../types';
 import { IGraph } from '../../interfaces';
 import { AbstractEdge, AbstractGraph, AbstractVertex } from './abstract-graph';
@@ -155,7 +154,6 @@ export class UndirectedGraph<
   }
 
   protected _edgeMap: Map<VO, EO[]>;
-
   get edgeMap(): Map<VO, EO[]> {
     return this._edgeMap;
   }
@@ -174,7 +172,10 @@ export class UndirectedGraph<
   static fromKeys<K extends VertexKey>(
     keys: Iterable<K>
   ): UndirectedGraph<K, undefined, UndirectedVertex<K>, UndirectedEdge<undefined>> {
-    const g: UndirectedGraph<K, undefined, UndirectedVertex<K>, UndirectedEdge<undefined>> = new UndirectedGraph<K, undefined>({
+    const g: UndirectedGraph<K, undefined, UndirectedVertex<K>, UndirectedEdge<undefined>> = new UndirectedGraph<
+      K,
+      undefined
+    >({
       vertexValueInitializer: (k: VertexKey) => k as K
     });
     for (const k of keys) g.addVertex(k);
@@ -191,7 +192,10 @@ export class UndirectedGraph<
   static fromEntries<V>(
     entries: Iterable<[VertexKey, V]>
   ): UndirectedGraph<V, undefined, UndirectedVertex<V>, UndirectedEdge<undefined>> {
-    const g: UndirectedGraph<V, undefined, UndirectedVertex<V>, UndirectedEdge<undefined>> = new UndirectedGraph<V, undefined>();
+    const g: UndirectedGraph<V, undefined, UndirectedVertex<V>, UndirectedEdge<undefined>> = new UndirectedGraph<
+      V,
+      undefined
+    >();
     for (const [k, v] of entries) g.addVertex(k, v);
     return g;
   }
@@ -226,62 +230,23 @@ 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;
+   * @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 = [];
-
     if (v1 !== undefined && v2 !== undefined) {
       const vertex1: VO | undefined = this._getVertex(v1);
       const vertex2: VO | undefined = this._getVertex(v2);
-
       if (vertex1 && vertex2) {
         edgeMap = this._edgeMap.get(vertex1)?.filter(e => e.endpoints.includes(vertex2.key));
       }
     }
-
     return edgeMap ? edgeMap[0] || undefined : undefined;
   }
 
@@ -295,11 +260,9 @@ export class UndirectedGraph<
   deleteEdgeBetween(v1: VO | VertexKey, v2: VO | VertexKey): EO | undefined {
     const vertex1: VO | undefined = this._getVertex(v1);
     const vertex2: VO | undefined = this._getVertex(v2);
-
     if (!vertex1 || !vertex2) {
       return undefined;
     }
-
     const v1Edges = this._edgeMap.get(vertex1);
     let removed: EO | undefined = undefined;
     if (v1Edges) {
@@ -318,72 +281,33 @@ 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;
+   * @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;
@@ -398,7 +322,6 @@ export class UndirectedGraph<
       oneSide = this._getVertex(edgeOrOneSideVertexKey.endpoints[0]);
       otherSide = this._getVertex(edgeOrOneSideVertexKey.endpoints[1]);
     }
-
     if (oneSide && otherSide) {
       return this.deleteEdgeBetween(oneSide, otherSide);
     } else {
@@ -411,50 +334,14 @@ 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;
+   * @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;
@@ -474,7 +361,6 @@ export class UndirectedGraph<
      * @remarks Time O(deg), Space O(deg)
      */
     const neighbors = this.getNeighbors(vertexOrKey);
-
     if (vertex) {
       neighbors.forEach(neighbor => {
         const neighborEdges = this._edgeMap.get(neighbor);
@@ -487,7 +373,6 @@ export class UndirectedGraph<
       });
       this._edgeMap.delete(vertex);
     }
-
     return this._vertexMap.delete(vertexKey);
   }
 
@@ -525,49 +410,13 @@ 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;
+   * @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();
@@ -579,79 +428,40 @@ 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';
+   * @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[] = [];
@@ -717,75 +527,34 @@ 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;
+   * @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>();
     const lowMap = new Map<VO, number>();
     const bridges: EO[] = [];
     const cutVertices: VO[] = [];
-
     let time = 0;
-
     const dfs = (vertex: VO, parent: VO | undefined) => {
       dfnMap.set(vertex, time);
       lowMap.set(vertex, time);
       time++;
-
       const neighbors = this.getNeighbors(vertex);
       let childCount = 0;
-
       for (const neighbor of neighbors) {
         if (!dfnMap.has(neighbor)) {
           childCount++;
           dfs(neighbor, vertex);
           lowMap.set(vertex, Math.min(lowMap.get(vertex)!, lowMap.get(neighbor)!));
-
           if (lowMap.get(neighbor)! > dfnMap.get(vertex)!) {
             // Found a bridge
             const edge = this.getEdge(vertex, neighbor);
@@ -793,7 +562,6 @@ export class UndirectedGraph<
               bridges.push(edge);
             }
           }
-
           if (parent !== undefined && lowMap.get(neighbor)! >= dfnMap.get(vertex)!) {
             // Found an articulation point
             cutVertices.push(vertex);
@@ -802,19 +570,16 @@ export class UndirectedGraph<
           lowMap.set(vertex, Math.min(lowMap.get(vertex)!, dfnMap.get(neighbor)!));
         }
       }
-
       if (parent === undefined && childCount > 1) {
         // Special case for root in DFS tree
         cutVertices.push(vertex);
       }
     };
-
     for (const vertex of this.vertexMap.values()) {
       if (!dfnMap.has(vertex)) {
         dfs(vertex, undefined);
       }
     }
-
     return {
       dfnMap,
       lowMap,
@@ -835,25 +600,20 @@ export class UndirectedGraph<
     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) ||
@@ -874,7 +634,6 @@ export class UndirectedGraph<
         }
       }
     };
-
     for (const vertex of this.vertexMap.values()) {
       if (!dfn.has(vertex)) {
         dfs(vertex, undefined);
@@ -885,7 +644,6 @@ export class UndirectedGraph<
         }
       }
     }
-
     return components;
   }
 
@@ -894,57 +652,20 @@ export class UndirectedGraph<
    * 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;
+   * @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)) {
@@ -956,7 +677,6 @@ export class UndirectedGraph<
       }
       return false;
     };
-
     for (const vertex of this.vertexMap.values()) {
       if (!visited.has(vertex)) {
         if (dfs(vertex, undefined)) return true;
@@ -969,52 +689,16 @@ export class UndirectedGraph<
    * 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;
+   * @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;
@@ -1024,53 +708,17 @@ 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';
+   * @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;