data-structure-typed 2.5.3 → 2.6.1

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

@@ -5,7 +5,6 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-
 import type { GraphOptions, TopologicalStatus, VertexKey } from '../../types';
 import { AbstractEdge, AbstractGraph, AbstractVertex } from './abstract-graph';
 import { IGraph } from '../../interfaces';
@@ -133,10 +132,6 @@ export class DirectedGraph<
     super(options);
   }
 
-  protected override get _edgeConnector(): string {
-    return '->';
-  }
-
   protected _outEdgeMap: Map<VO, EO[]> = new Map<VO, EO[]>();
 
   get outEdgeMap(): Map<VO, EO[]> {
@@ -157,6 +152,10 @@ export class DirectedGraph<
     this._inEdgeMap = v;
   }
 
+  protected override get _edgeConnector(): string {
+    return '->';
+  }
+
   /**
    * Construct a directed graph from keys with value initializer `v => v`.
    * @template K - Vertex key type.
@@ -164,7 +163,9 @@ export class DirectedGraph<
    * @returns DirectedGraph with all keys added.
    * @remarks Time O(V), Space O(V)
    */
-  static fromKeys<K extends VertexKey>(keys: Iterable<K>): DirectedGraph<K, undefined, DirectedVertex<K>, DirectedEdge<undefined>> {
+  static fromKeys<K extends VertexKey>(
+    keys: Iterable<K>
+  ): DirectedGraph<K, undefined, DirectedVertex<K>, DirectedEdge<undefined>> {
     const g: DirectedGraph<K, undefined, DirectedVertex<K>, DirectedEdge<undefined>> = new DirectedGraph<K, undefined>({
       vertexValueInitializer: (k: VertexKey) => k as K
     });
@@ -182,7 +183,10 @@ export class DirectedGraph<
   static fromEntries<V>(
     entries: Iterable<[VertexKey, V]>
   ): DirectedGraph<V, undefined, DirectedVertex<V>, DirectedEdge<undefined>> {
-    const g: DirectedGraph<V, undefined, DirectedVertex<V>, DirectedEdge<undefined>> = new DirectedGraph<V, undefined>();
+    const g: DirectedGraph<V, undefined, DirectedVertex<V>, DirectedEdge<undefined>> = new DirectedGraph<
+      V,
+      undefined
+    >();
     for (const [k, v] of entries) g.addVertex(k, v);
     return g;
   }
@@ -217,58 +221,20 @@ export class DirectedGraph<
    * @param destOrKey - Destination vertex or key.
    * @returns Edge instance or `undefined`.
    * @remarks Time O(1) avg, Space O(1)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Get edge between vertices
- *  const g = new DirectedGraph();
- *     g.addVertex('A');
- *     g.addVertex('B');
- *     g.addEdge('A', 'B', 5);
- *     const edge = g.getEdge('A', 'B');
- *     console.log(edge?.weight); // 5;
+   * @example
+   * // Get edge between vertices
+   *  const g = new DirectedGraph();
+   *     g.addVertex('A');
+   *     g.addVertex('B');
+   *     g.addEdge('A', 'B', 5);
+   *     const edge = g.getEdge('A', 'B');
+   *     console.log(edge?.weight); // 5;
    */
   getEdge(srcOrKey: VO | VertexKey | undefined, destOrKey: VO | VertexKey | undefined): EO | undefined {
     let edgeMap: EO[] = [];
-
     if (srcOrKey !== undefined && destOrKey !== undefined) {
       const src: VO | undefined = this._getVertex(srcOrKey);
       const dest: VO | undefined = this._getVertex(destOrKey);
-
       if (src && dest) {
         const srcOutEdges = this._outEdgeMap.get(src);
         if (srcOutEdges) {
@@ -276,7 +242,6 @@ export class DirectedGraph<
         }
       }
     }
-
     return edgeMap[0] || undefined;
   }
 
@@ -294,12 +259,10 @@ export class DirectedGraph<
     if (!src || !dest) {
       return undefined;
     }
-
     const srcOutEdges = this._outEdgeMap.get(src);
     if (srcOutEdges) {
       arrayRemove<EO>(srcOutEdges, (edge: EO) => edge.dest === dest.key);
     }
-
     const destInEdges = this._inEdgeMap.get(dest);
     if (destInEdges) {
       removed = arrayRemove<EO>(destInEdges, (edge: EO) => edge.src === src.key)[0] || undefined;
@@ -313,70 +276,31 @@ export class DirectedGraph<
    * @param destVertexKey - Optional destination vertex/key when deleting by pair.
    * @returns Removed edge or `undefined`.
    * @remarks Time O(1) avg, Space O(1)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // DirectedGraph deleteEdge and vertex operations
- *  const graph = new DirectedGraph<string>();
- *
- *     // Build a small graph
- *     graph.addVertex('X');
- *     graph.addVertex('Y');
- *     graph.addVertex('Z');
- *     graph.addEdge('X', 'Y', 1);
- *     graph.addEdge('Y', 'Z', 2);
- *
- *     // Delete an edge
- *     graph.deleteEdgeSrcToDest('X', 'Y');
- *     console.log(graph.hasEdge('X', 'Y')); // false;
- *
- *     // Edge in other direction should not exist
- *     console.log(graph.hasEdge('Y', 'X')); // false;
- *
- *     // Other edges should remain
- *     console.log(graph.hasEdge('Y', 'Z')); // true;
- *
- *     // Delete a vertex
- *     graph.deleteVertex('Y');
- *     console.log(graph.hasVertex('Y')); // false;
- *     console.log(graph.size); // 2;
+   * @example
+   * // DirectedGraph deleteEdge and vertex operations
+   *  const graph = new DirectedGraph<string>();
+   *
+   *     // Build a small graph
+   *     graph.addVertex('X');
+   *     graph.addVertex('Y');
+   *     graph.addVertex('Z');
+   *     graph.addEdge('X', 'Y', 1);
+   *     graph.addEdge('Y', 'Z', 2);
+   *
+   *     // Delete an edge
+   *     graph.deleteEdgeSrcToDest('X', 'Y');
+   *     console.log(graph.hasEdge('X', 'Y')); // false;
+   *
+   *     // Edge in other direction should not exist
+   *     console.log(graph.hasEdge('Y', 'X')); // false;
+   *
+   *     // Other edges should remain
+   *     console.log(graph.hasEdge('Y', 'Z')); // true;
+   *
+   *     // Delete a vertex
+   *     graph.deleteVertex('Y');
+   *     console.log(graph.hasVertex('Y')); // false;
+   *     console.log(graph.size); // 2;
    */
   deleteEdge(edgeOrSrcVertexKey: EO | VertexKey, destVertexKey?: VertexKey): EO | undefined {
     let removed: EO | undefined = undefined;
@@ -392,69 +316,30 @@ export class DirectedGraph<
       src = this._getVertex(edgeOrSrcVertexKey.src);
       dest = this._getVertex(edgeOrSrcVertexKey.dest);
     }
-
     if (src && dest) {
       const srcOutEdges = this._outEdgeMap.get(src);
       if (srcOutEdges && srcOutEdges.length > 0) {
         arrayRemove(srcOutEdges, (edge: EO) => edge.src === src!.key && edge.dest === dest?.key);
       }
-
       const destInEdges = this._inEdgeMap.get(dest);
       if (destInEdges && destInEdges.length > 0) {
         removed = arrayRemove(destInEdges, (edge: EO) => edge.src === src!.key && edge.dest === dest!.key)[0];
       }
     }
-
     return removed;
   }
 
-    /**
+  /**
    * Remove a vertex
-  
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Remove a vertex
- *  const g = new DirectedGraph();
- *     g.addVertex('A');
- *     g.addVertex('B');
- *     g.addEdge('A', 'B');
- *     g.deleteVertex('A');
- *     console.log(g.hasVertex('A')); // false;
- *     console.log(g.hasEdge('A', 'B')); // false;
+   * @example
+   * // Remove a vertex
+   *  const g = new DirectedGraph();
+   *     g.addVertex('A');
+   *     g.addVertex('B');
+   *     g.addEdge('A', 'B');
+   *     g.deleteVertex('A');
+   *     console.log(g.hasVertex('A')); // false;
+   *     console.log(g.hasEdge('A', 'B')); // false;
    */
   deleteVertex(vertexOrKey: VO | VertexKey): boolean {
     let vertexKey: VertexKey;
@@ -466,7 +351,6 @@ export class DirectedGraph<
       vertex = vertexOrKey;
       vertexKey = this._getVertexKey(vertexOrKey);
     }
-
     if (vertex) {
       /**
        * One-step neighbors following outgoing edges.
@@ -481,21 +365,17 @@ export class DirectedGraph<
       this._outEdgeMap.delete(vertex);
       this._inEdgeMap.delete(vertex);
     }
-
     return this._vertexMap.delete(vertexKey);
   }
 
   deleteEdgesBetween(v1: VertexKey | VO, v2: VertexKey | VO): EO[] {
     const removed: EO[] = [];
-
     if (v1 && v2) {
       const v1ToV2 = this.deleteEdgeSrcToDest(v1, v2);
       const v2ToV1 = this.deleteEdgeSrcToDest(v2, v1);
-
       if (v1ToV2) removed.push(v1ToV2);
       if (v2ToV1) removed.push(v2ToV1);
     }
-
     return removed;
   }
 
@@ -504,51 +384,15 @@ export class DirectedGraph<
    * @param vertexOrKey - Vertex or key.
    * @returns Array of incoming edges.
    * @remarks Time O(deg_in), Space O(deg_in)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Get incoming edges
- *  const g = new DirectedGraph();
- *     g.addVertex('A');
- *     g.addVertex('B');
- *     g.addVertex('C');
- *     g.addEdge('A', 'C');
- *     g.addEdge('B', 'C');
- *     console.log(g.incomingEdgesOf('C').length); // 2;
+   * @example
+   * // Get incoming edges
+   *  const g = new DirectedGraph();
+   *     g.addVertex('A');
+   *     g.addVertex('B');
+   *     g.addVertex('C');
+   *     g.addEdge('A', 'C');
+   *     g.addEdge('B', 'C');
+   *     console.log(g.incomingEdgesOf('C').length); // 2;
    */
   incomingEdgesOf(vertexOrKey: VO | VertexKey): EO[] {
     const target = this._getVertex(vertexOrKey);
@@ -563,51 +407,15 @@ export class DirectedGraph<
    * @param vertexOrKey - Vertex or key.
    * @returns Array of outgoing edges.
    * @remarks Time O(deg_out), Space O(deg_out)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Get outgoing edges
- *  const g = new DirectedGraph();
- *     g.addVertex('A');
- *     g.addVertex('B');
- *     g.addVertex('C');
- *     g.addEdge('A', 'B');
- *     g.addEdge('A', 'C');
- *     console.log(g.outgoingEdgesOf('A').length); // 2;
+   * @example
+   * // Get outgoing edges
+   *  const g = new DirectedGraph();
+   *     g.addVertex('A');
+   *     g.addVertex('B');
+   *     g.addVertex('C');
+   *     g.addEdge('A', 'B');
+   *     g.addEdge('A', 'C');
+   *     console.log(g.outgoingEdgesOf('A').length); // 2;
    */
   outgoingEdgesOf(vertexOrKey: VO | VertexKey): EO[] {
     const target = this._getVertex(vertexOrKey);
@@ -691,76 +499,35 @@ export class DirectedGraph<
    * @param propertyName - `'key'` to map to keys; `'vertex'` to keep instances.
    * @returns Array of keys/vertices, or `undefined` when cycle is found.
    * @remarks Time O(V + E), Space O(V)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // DirectedGraph topologicalSort for task scheduling
- *  const graph = new DirectedGraph<string>();
- *
- *     // Build a DAG (Directed Acyclic Graph) for task dependencies
- *     graph.addVertex('Design');
- *     graph.addVertex('Implement');
- *     graph.addVertex('Test');
- *     graph.addVertex('Deploy');
- *
- *     // Add dependency edges
- *     graph.addEdge('Design', 'Implement', 1); // Design must come before Implement
- *     graph.addEdge('Implement', 'Test', 1); // Implement must come before Test
- *     graph.addEdge('Test', 'Deploy', 1); // Test must come before Deploy
- *
- *     // Topological sort gives valid execution order
- *     const executionOrder = graph.topologicalSort();
- *     console.log(executionOrder); // defined;
- *     console.log(executionOrder); // ['Design', 'Implement', 'Test', 'Deploy'];
- *
- *     // All vertices should be included
- *     console.log(executionOrder?.length); // 4;
+   * @example
+   * // DirectedGraph topologicalSort for task scheduling
+   *  const graph = new DirectedGraph<string>();
+   *
+   *     // Build a DAG (Directed Acyclic Graph) for task dependencies
+   *     graph.addVertex('Design');
+   *     graph.addVertex('Implement');
+   *     graph.addVertex('Test');
+   *     graph.addVertex('Deploy');
+   *
+   *     // Add dependency edges
+   *     graph.addEdge('Design', 'Implement', 1); // Design must come before Implement
+   *     graph.addEdge('Implement', 'Test', 1); // Implement must come before Test
+   *     graph.addEdge('Test', 'Deploy', 1); // Test must come before Deploy
+   *
+   *     // Topological sort gives valid execution order
+   *     const executionOrder = graph.topologicalSort();
+   *     console.log(executionOrder); // defined;
+   *     console.log(executionOrder); // ['Design', 'Implement', 'Test', 'Deploy'];
+   *
+   *     // All vertices should be included
+   *     console.log(executionOrder?.length); // 4;
    */
   topologicalSort(propertyName?: 'vertex' | 'key'): Array<VO | VertexKey> | undefined {
     propertyName = propertyName ?? 'key';
-
     const statusMap: Map<VO | VertexKey, TopologicalStatus> = new Map<VO | VertexKey, TopologicalStatus>();
     for (const entry of this.vertexMap) {
       statusMap.set(entry[1], 0);
     }
-
     let sorted: (VO | VertexKey)[] = [];
     let hasCycle = false;
     const dfs = (cur: VO | VertexKey) => {
@@ -777,64 +544,25 @@ export class DirectedGraph<
       statusMap.set(cur, 2);
       sorted.push(cur);
     };
-
     for (const entry of this.vertexMap) {
       if (statusMap.get(entry[1]) === 0) {
         dfs(entry[1]);
       }
     }
-
     if (hasCycle) return undefined;
-
     if (propertyName === 'key') sorted = sorted.map(vertex => (vertex instanceof DirectedVertex ? vertex.key : vertex));
     return sorted.reverse();
   }
 
-    /**
+  /**
    * Get all edges
-  
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Get all edges
- *  const g = new DirectedGraph();
- *     g.addVertex('A');
- *     g.addVertex('B');
- *     g.addEdge('A', 'B', 3);
- *     console.log(g.edgeSet().length); // 1;
+   * @example
+   * // Get all edges
+   *  const g = new DirectedGraph();
+   *     g.addVertex('A');
+   *     g.addVertex('B');
+   *     g.addEdge('A', 'B', 3);
+   *     console.log(g.edgeSet().length); // 1;
    */
   edgeSet(): EO[] {
     let edgeMap: EO[] = [];
@@ -844,55 +572,18 @@ export class DirectedGraph<
     return edgeMap;
   }
 
-    /**
+  /**
    * Get outgoing neighbors
-  
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Get outgoing neighbors
- *  const g = new DirectedGraph();
- *     g.addVertex('A');
- *     g.addVertex('B');
- *     g.addVertex('C');
- *     g.addEdge('A', 'B');
- *     g.addEdge('A', 'C');
- *     const neighbors = g.getNeighbors('A');
- *     console.log(neighbors.map(v => v.key).sort()); // ['B', 'C'];
+   * @example
+   * // Get outgoing neighbors
+   *  const g = new DirectedGraph();
+   *     g.addVertex('A');
+   *     g.addVertex('B');
+   *     g.addVertex('C');
+   *     g.addEdge('A', 'B');
+   *     g.addEdge('A', 'C');
+   *     const neighbors = g.getNeighbors('A');
+   *     console.log(neighbors.map(v => v.key).sort()); // ['B', 'C'];
    */
   getNeighbors(vertexOrKey: VO | VertexKey): VO[] {
     const neighbors: VO[] = [];
@@ -901,7 +592,6 @@ export class DirectedGraph<
       const outEdges = this.outgoingEdgesOf(vertex);
       for (const outEdge of outEdges) {
         const neighbor = this._getVertex(outEdge.dest);
-
         if (neighbor) {
           neighbors.push(neighbor);
         }
@@ -960,74 +650,33 @@ export class DirectedGraph<
    * Tarjan's algorithm for strongly connected components.
    * @returns `{ dfnMap, lowMap, SCCs }`.
    * @remarks Time O(V + E), Space O(V + E)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Find strongly connected components
- *  const g = new DirectedGraph();
- *     g.addVertex('A');
- *     g.addVertex('B');
- *     g.addVertex('C');
- *     g.addEdge('A', 'B');
- *     g.addEdge('B', 'C');
- *     g.addEdge('C', 'A');
- *     const { SCCs } = g.tarjan();
- *     // A→B→C→A forms one SCC with 3 members
- *     const sccArrays = [...SCCs.values()];
- *     console.log(sccArrays.some(scc => scc.length === 3)); // true;
+   * @example
+   * // Find strongly connected components
+   *  const g = new DirectedGraph();
+   *     g.addVertex('A');
+   *     g.addVertex('B');
+   *     g.addVertex('C');
+   *     g.addEdge('A', 'B');
+   *     g.addEdge('B', 'C');
+   *     g.addEdge('C', 'A');
+   *     const { SCCs } = g.tarjan();
+   *     // A→B→C→A forms one SCC with 3 members
+   *     const sccArrays = [...SCCs.values()];
+   *     console.log(sccArrays.some(scc => scc.length === 3)); // true;
    */
   tarjan(): { dfnMap: Map<VO, number>; lowMap: Map<VO, number>; SCCs: Map<number, VO[]> } {
     const dfnMap = new Map<VO, number>();
     const lowMap = new Map<VO, number>();
     const SCCs = new Map<number, VO[]>();
-
     let time = 0;
-
     const stack: VO[] = [];
     const inStack: Set<VO> = new Set();
-
     const dfs = (vertex: VO) => {
       dfnMap.set(vertex, time);
       lowMap.set(vertex, time);
       time++;
-
       stack.push(vertex);
       inStack.add(vertex);
-
       const neighbors = this.getNeighbors(vertex);
       for (const neighbor of neighbors) {
         if (!dfnMap.has(neighbor)) {
@@ -1037,27 +686,22 @@ export class DirectedGraph<
           lowMap.set(vertex, Math.min(lowMap.get(vertex)!, dfnMap.get(neighbor)!));
         }
       }
-
       if (dfnMap.get(vertex) === lowMap.get(vertex)) {
         const SCC: VO[] = [];
         let poppedVertex: VO | undefined;
-
         do {
           poppedVertex = stack.pop();
           inStack.delete(poppedVertex!);
           SCC.push(poppedVertex!);
         } while (poppedVertex !== vertex);
-
         SCCs.set(SCCs.size, SCC);
       }
     };
-
     for (const vertex of this.vertexMap.values()) {
       if (!dfnMap.has(vertex)) {
         dfs(vertex);
       }
     }
-
     return { dfnMap, lowMap, SCCs };
   }
 
@@ -1083,53 +727,17 @@ export class DirectedGraph<
    * Strongly connected components computed by `tarjan()`.
    * @returns Map from SCC id to vertices.
    * @remarks Time O(#SCC + V), Space O(V)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Get strongly connected components
- *  const g = new DirectedGraph();
- *     g.addVertex(1);
- *     g.addVertex(2);
- *     g.addVertex(3);
- *     g.addEdge(1, 2);
- *     g.addEdge(2, 3);
- *     g.addEdge(3, 1);
- *     const sccs = g.getSCCs(); // Map<number, VO[]>
- *     console.log(sccs.size); // >= 1;
+   * @example
+   * // Get strongly connected components
+   *  const g = new DirectedGraph();
+   *     g.addVertex(1);
+   *     g.addVertex(2);
+   *     g.addVertex(3);
+   *     g.addEdge(1, 2);
+   *     g.addEdge(2, 3);
+   *     g.addEdge(3, 1);
+   *     const sccs = g.getSCCs(); // Map<number, VO[]>
+   *     console.log(sccs.size); // >= 1;
    */
   getSCCs(): Map<number, VO[]> {
     return this.tarjan().SCCs;
@@ -1145,10 +753,8 @@ export class DirectedGraph<
     if (!(this.hasVertex(edge.src) && this.hasVertex(edge.dest))) {
       return false;
     }
-
     const srcVertex = this._getVertex(edge.src);
     const destVertex = this._getVertex(edge.dest);
-
     if (srcVertex && destVertex) {
       const srcOutEdges = this._outEdgeMap.get(srcVertex);
       if (srcOutEdges) {
@@ -1156,7 +762,6 @@ export class DirectedGraph<
       } else {
         this._outEdgeMap.set(srcVertex, [edge]);
       }
-
       const destInEdges = this._inEdgeMap.get(destVertex);
       if (destInEdges) {
         destInEdges.push(edge);