binary-tree-typed 2.4.5 → 2.5.0

package/dist/types/data-structures/graph/directed-graph.d.ts

@@ -65,53 +65,6 @@ export declare 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>();
@@ -204,6 +157,22 @@ export declare class DirectedGraph<V = any, E = any, VO extends DirectedVertex<V
      * @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;
     /**
@@ -220,8 +189,64 @@ export declare class DirectedGraph<V = any, E = any, VO extends DirectedVertex<V
      * @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;
+    /**
+   * 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;
     deleteEdgesBetween(v1: VertexKey | VO, v2: VertexKey | VO): EO[];
     /**
@@ -229,6 +254,23 @@ export declare class DirectedGraph<V = any, E = any, VO extends DirectedVertex<V
      * @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[];
     /**
@@ -236,6 +278,23 @@ export declare class DirectedGraph<V = any, E = any, VO extends DirectedVertex<V
      * @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[];
     /**
@@ -268,9 +327,82 @@ export declare class DirectedGraph<V = any, E = any, VO extends DirectedVertex<V
      * @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;
+    /**
+   * 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[];
+    /**
+   * 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[];
     /**
      * Resolve an edge's `[src, dest]` endpoints to vertex instances.
@@ -299,6 +431,27 @@ export declare class DirectedGraph<V = any, E = any, VO extends DirectedVertex<V
      * 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>;
@@ -321,6 +474,25 @@ export declare class DirectedGraph<V = any, E = any, VO extends DirectedVertex<V
      * 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[]>;
     /**

package/dist/types/data-structures/graph/map-graph.d.ts

@@ -22,7 +22,65 @@ export declare 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 declare class MapGraph<V = any, E = any, VO extends MapVertex<V> = MapVertex<V>, EO extends MapEdge<E> = MapEdge<E>> extends DirectedGraph<V, E, VO, EO> {
     /**