data-structure-typed 2.4.5 → 2.5.0

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>();
@@ -264,6 +217,23 @@ 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[] = [];
@@ -316,6 +286,43 @@ 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;
@@ -347,6 +354,27 @@ 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;
@@ -395,6 +423,24 @@ 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);
@@ -409,6 +455,24 @@ 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);
@@ -492,6 +556,40 @@ 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';
@@ -530,6 +628,25 @@ 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 => {
@@ -538,6 +655,29 @@ 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);
@@ -604,6 +744,28 @@ 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>();
@@ -678,6 +840,26 @@ 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,