binary-tree-typed 2.4.4 → 2.5.0

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

@@ -8,6 +8,7 @@
 
 import type { DijkstraResult, EntryCallback, GraphOptions, VertexKey } from '../../types';
 import { uuidV4 } from '../../utils';
+import { ERR } from '../../common';
 import { IterableEntryBase } from '../base';
 import { IGraph } from '../../interfaces';
 import { Heap } from '../heap';
@@ -274,7 +275,7 @@ export abstract class AbstractGraph<
         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'));
       }
     }
   }
@@ -1078,4 +1079,108 @@ export abstract class AbstractGraph<
   protected _getVertexKey(vertexOrKey: VO | VertexKey): VertexKey {
     return vertexOrKey instanceof AbstractVertex ? vertexOrKey.key : vertexOrKey;
   }
+
+  /**
+   * The edge connector string used in visual output.
+   * Override in subclasses (e.g., '--' for undirected, '->' for directed).
+   */
+  protected get _edgeConnector(): string {
+    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.
+   */
+  override toVisual(options?: { showWeight?: boolean }): string {
+    const showWeight = options?.showWeight ?? true;
+    const vertices = [...this._vertexMap.values()];
+    const vertexCount = vertices.length;
+    const edgeCount = this.edgeSet().length;
+
+    const lines: string[] = [`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 !== undefined && 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?: { name?: string; showWeight?: boolean }): string {
+    const name = options?.name ?? 'G';
+    const showWeight = options?.showWeight ?? true;
+    const isDirected = this._edgeConnector === '->';
+    const graphType = isDirected ? 'digraph' : 'graph';
+    const edgeOp = isDirected ? '->' : '--';
+
+    const lines: string[] = [`${graphType} ${name} {`];
+
+    // Add all vertices (ensures isolated vertices appear)
+    for (const vertex of this._vertexMap.values()) {
+      lines.push(`  "${vertex.key}";`);
+    }
+
+    // Add edges
+    const visited = new Set<string>();
+    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 !== undefined && 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`.
+   */
+  override print(options?: { showWeight?: boolean }): void {
+    console.log(this.toVisual(options));
+  }
 }

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

@@ -77,53 +77,6 @@ export class DirectedEdge<E = any> extends AbstractEdge<E> {
  *     console.log(neighborsA[0].key); // 'B';
  *     console.log(neighborsA[1].key); // 'C';
  * @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 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 dijkstra shortest path for network routing
  *  // Build a weighted directed graph representing network nodes and costs
  *     const network = new DirectedGraph<string>();
@@ -180,6 +133,10 @@ 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[]> {
@@ -260,6 +217,22 @@ 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;
    */
   getEdge(srcOrKey: VO | VertexKey | undefined, destOrKey: VO | VertexKey | undefined): EO | undefined {
     let edgeMap: EO[] = [];
@@ -312,6 +285,42 @@ 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;
    */
   deleteEdge(edgeOrSrcVertexKey: EO | VertexKey, destVertexKey?: VertexKey): EO | undefined {
     let removed: EO | undefined = undefined;
@@ -343,6 +352,26 @@ export class DirectedGraph<
     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;
+   */
   deleteVertex(vertexOrKey: VO | VertexKey): boolean {
     let vertexKey: VertexKey;
     let vertex: VO | undefined;
@@ -391,6 +420,23 @@ 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;
    */
   incomingEdgesOf(vertexOrKey: VO | VertexKey): EO[] {
     const target = this._getVertex(vertexOrKey);
@@ -405,6 +451,23 @@ 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;
    */
   outgoingEdgesOf(vertexOrKey: VO | VertexKey): EO[] {
     const target = this._getVertex(vertexOrKey);
@@ -488,6 +551,39 @@ 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;
    */
   topologicalSort(propertyName?: 'vertex' | 'key'): Array<VO | VertexKey> | undefined {
     propertyName = propertyName ?? 'key';
@@ -526,6 +622,24 @@ export class DirectedGraph<
     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;
+   */
   edgeSet(): EO[] {
     let edgeMap: EO[] = [];
     this._outEdgeMap.forEach(outEdges => {
@@ -534,6 +648,28 @@ 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'];
+   */
   getNeighbors(vertexOrKey: VO | VertexKey): VO[] {
     const neighbors: VO[] = [];
     const vertex = this._getVertex(vertexOrKey);
@@ -600,6 +736,27 @@ 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;
    */
   tarjan(): { dfnMap: Map<VO, number>; lowMap: Map<VO, number>; SCCs: Map<number, VO[]> } {
     const dfnMap = new Map<VO, number>();
@@ -674,6 +831,25 @@ 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;
    */
   getSCCs(): Map<number, VO[]> {
     return this.tarjan().SCCs;

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

@@ -33,7 +33,65 @@ export class MapEdge<E = any> extends DirectedEdge<E> {
  * @template VO - Concrete vertex class (MapVertex<V>).
  * @template EO - Concrete edge class (MapEdge<E>).
  * @remarks Time O(1), Space O(1)
- * @example examples will be generated by unit test
+ * @example
+ * // City navigation with shortest path
+ *  const map = new MapGraph([0, 0], [10, 10]);
+ *
+ *     map.addVertex(new MapVertex('Home', '', 0, 0));
+ *     map.addVertex(new MapVertex('Office', '', 3, 4));
+ *     map.addVertex(new MapVertex('Cafe', '', 1, 2));
+ *     map.addVertex(new MapVertex('Park', '', 2, 1));
+ *
+ *     map.addEdge('Home', 'Cafe', 2.2);
+ *     map.addEdge('Cafe', 'Office', 3.5);
+ *     map.addEdge('Home', 'Park', 2.0);
+ *     map.addEdge('Park', 'Office', 4.0);
+ *     map.addEdge('Home', 'Office', 7.0);
+ *
+ *     // Find shortest path
+ *     const result = map.dijkstra('Home', 'Office', true, true);
+ *     console.log(result?.minDist); // 5.7; // Home → Cafe → Office
+ *     console.log(result?.minPath.map(v => v.key)); // ['Home', 'Cafe', 'Office'];
+ * @example
+ * // Delivery route optimization
+ *  const routes = new MapGraph([0, 0], [10, 10]);
+ *
+ *     routes.addVertex(new MapVertex('Warehouse', '', 0, 0));
+ *     routes.addVertex(new MapVertex('Customer A', '', 2, 3));
+ *     routes.addVertex(new MapVertex('Customer B', '', 5, 1));
+ *     routes.addVertex(new MapVertex('Customer C', '', 3, 5));
+ *
+ *     routes.addEdge('Warehouse', 'Customer A', 3.6);
+ *     routes.addEdge('Warehouse', 'Customer B', 5.1);
+ *     routes.addEdge('Customer A', 'Customer C', 2.2);
+ *     routes.addEdge('Customer A', 'Customer B', 3.6);
+ *     routes.addEdge('Customer B', 'Customer C', 4.5);
+ *
+ *     // Check outgoing neighbors of Customer A
+ *     const neighbors = routes.getNeighbors('Customer A');
+ *     console.log(neighbors.map(n => n.key).sort()); // ['Customer B', 'Customer C'];
+ *
+ *     // Shortest path from Warehouse to Customer C
+ *     const path = routes.getMinPathBetween('Warehouse', 'Customer C', true);
+ *     console.log(path?.map(v => v.key)); // ['Warehouse', 'Customer A', 'Customer C'];
+ * @example
+ * // Campus map with building connections
+ *  const campus = new MapGraph([0, 0], [5, 5]);
+ *
+ *     campus.addVertex(new MapVertex('Library', '', 0, 0));
+ *     campus.addVertex(new MapVertex('Lab', '', 1, 1));
+ *     campus.addVertex(new MapVertex('Cafeteria', '', 2, 0));
+ *
+ *     campus.addEdge('Library', 'Lab', 5);
+ *     campus.addEdge('Lab', 'Cafeteria', 3);
+ *     campus.addEdge('Library', 'Cafeteria', 10);
+ *
+ *     console.log(campus.hasVertex('Library')); // true;
+ *     console.log(campus.hasVertex('Gym')); // false;
+ *
+ *     // Direct distance vs shortest path
+ *     const direct = campus.dijkstra('Library', 'Cafeteria', true, true);
+ *     console.log(direct?.minDist); // 8;
  */
 export class MapGraph<
   V = any,