data-structure-typed 0.8.18 → 1.12.9

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

@@ -1,60 +1,18 @@
+/**
+ * @copyright 2030 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT
+ */
 import {arrayRemove, uuidV4} from '../../utils';
 import {PriorityQueue} from '../priority-queue';
+import type {DijkstraResult, IGraph, VertexId} from '../types';
 
-export type VertexId = string | number;
-export type DijkstraResult<V> =
-    { distMap: Map<V, number>, preMap: Map<V, V | null>, seen: Set<V>, paths: V[][], minDist: number, minPath: V[] }
-    | null;
-
-export interface I_Graph<V, E> {
-
-    containsVertex(vertexOrId: V | VertexId): boolean;
-
-    getVertex(vertexOrId: VertexId | V): V | null;
-
-    getVertexId(vertexOrId: V | VertexId): VertexId;
-
-    vertexSet(): Map<VertexId, V>;
-
-    addVertex(v: V): boolean;
-
-    removeVertex(vertexOrId: V | VertexId): boolean;
-
-    removeAllVertices(vertices: V[] | VertexId[]): boolean;
-
-    degreeOf(vertexOrId: V | VertexId): number;
-
-    edgesOf(vertexOrId: V | VertexId): E[];
-
-    containsEdge(src: V | VertexId, dest: V | VertexId): boolean;
-
-    // containsEdge(e: E): boolean;
-
-    getEdge(srcOrId: V | VertexId, destOrId: V | VertexId): E | null;
-
-    // getAllEdges(src: V, dest: V): E[];
-
-    edgeSet(): E[];
-
-    addEdge(edge: E): boolean;
-
-    removeEdgeBetween(srcOrId: V | VertexId, destOrId: V | VertexId): E | null;
-
-    removeEdge(edge: E): E | null;
-
-    // removeAllEdges(v1: VertexId | V, v2: VertexId | V): (E | null)[];
-
-    // removeAllEdges(edges: E[] | [VertexId, VertexId]): boolean;
-
-    setEdgeWeight(srcOrId: V | VertexId, destOrId: V | VertexId, weight: number): boolean;
-
-    getMinPathBetween(v1: V | VertexId, v2: V | VertexId, isWeight?: boolean): V[] | null;
+export class AbstractVertex {
+    constructor(id: VertexId) {
+        this._id = id;
+    }
 
-    getNeighbors(vertexOrId: V | VertexId): V[];
-}
+    protected _id: VertexId;
 
-export class AbstractVertex {
-    private _id: VertexId;
     public get id(): VertexId {
         return this._id;
     }
@@ -62,15 +20,20 @@ export class AbstractVertex {
     public set id(v: VertexId) {
         this._id = v;
     }
-
-    constructor(id: VertexId) {
-        this._id = id;
-    }
 }
 
 export abstract class AbstractEdge {
 
+    static DEFAULT_EDGE_WEIGHT = 1;
+
+    protected constructor(weight?: number) {
+        if (weight === undefined) weight = AbstractEdge.DEFAULT_EDGE_WEIGHT;
+        this._weight = weight;
+        this._hashCode = uuidV4();
+    }
+
     private _weight: number;
+
     get weight(): number {
         return this._weight;
     }
@@ -88,18 +51,10 @@ export abstract class AbstractEdge {
     set hashCode(v: string) {
         this._hashCode = v;
     }
-
-    protected constructor(weight?: number) {
-        if (weight === undefined) weight = AbstractEdge.DEFAULT_EDGE_WEIGHT;
-        this._weight = weight;
-        this._hashCode = uuidV4();
-    }
-
-    static DEFAULT_EDGE_WEIGHT = 1;
 }
 
 // Connected Component === Largest Connected Sub-Graph
-export abstract class AbstractGraph<V extends AbstractVertex, E extends AbstractEdge> implements I_Graph<V, E> {
+export abstract class AbstractGraph<V extends AbstractVertex, E extends AbstractEdge> implements IGraph<V, E> {
 
     protected _vertices: Map<VertexId, V> = new Map<VertexId, V>();
 
@@ -107,25 +62,55 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
 
     abstract removeEdge(edge: E): E | null;
 
+    /**
+     * The function `getVertex` returns the vertex object associated with a given vertex ID or vertex object, or null if it
+     * does not exist.
+     * @param {VertexId | V} vertexOrId - The parameter `vertexOrId` can be either a `VertexId` or a `V`.
+     * @returns The function `getVertex` returns the vertex object (`V`) corresponding to the given `vertexOrId` parameter.
+     * If the vertex is found in the `_vertices` map, it is returned. Otherwise, `null` is returned.
+     */
     getVertex(vertexOrId: VertexId | V): V | null {
         const vertexId = this.getVertexId(vertexOrId);
         return this._vertices.get(vertexId) || null;
     }
 
+    /**
+     * The function `getVertexId` returns the id of a vertex, whether it is passed as an instance of `AbstractVertex` or as
+     * a `VertexId`.
+     * @param {V | VertexId} vertexOrId - The parameter `vertexOrId` can be either a vertex object (`V`) or a vertex ID
+     * (`VertexId`).
+     * @returns the id of the vertex.
+     */
     getVertexId(vertexOrId: V | VertexId): VertexId {
         return vertexOrId instanceof AbstractVertex ? vertexOrId.id : vertexOrId;
     }
 
+    /**
+     * The function checks if a vertex exists in a graph.
+     * @param {V | VertexId} vertexOrId - The parameter `vertexOrId` can accept either a vertex object (`V`) or a vertex ID
+     * (`VertexId`).
+     * @returns The method `containsVertex` returns a boolean value.
+     */
     containsVertex(vertexOrId: V | VertexId): boolean {
         return this._vertices.has(this.getVertexId(vertexOrId));
     }
 
+    /**
+     * The function `vertexSet()` returns a map of vertices.
+     * @returns The method `vertexSet()` returns a map of vertex IDs to vertex objects.
+     */
     vertexSet(): Map<VertexId, V> {
         return this._vertices;
     }
 
     abstract getEdge(srcOrId: V | null | VertexId, destOrId: V | null | VertexId): E | null;
 
+    /**
+     * The addVertex function adds a new vertex to a graph if it does not already exist.
+     * @param {V} newVertex - The parameter "newVertex" is of type V, which represents a vertex in a graph.
+     * @returns The method is returning a boolean value. If the newVertex is already contained in the graph, it will return
+     * false. Otherwise, it will add the newVertex to the graph and return true.
+     */
     addVertex(newVertex: V): boolean {
         if (this.containsVertex(newVertex)) {
             return false;
@@ -134,11 +119,24 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
         return true;
     }
 
+    /**
+     * The `removeVertex` function removes a vertex from a graph by its ID or by the vertex object itself.
+     * @param {V | VertexId} vertexOrId - The parameter `vertexOrId` can be either a vertex object (`V`) or a vertex ID
+     * (`VertexId`).
+     * @returns The method `removeVertex` returns a boolean value.
+     */
     removeVertex(vertexOrId: V | VertexId): boolean {
         const vertexId = this.getVertexId(vertexOrId);
         return this._vertices.delete(vertexId);
     }
 
+    /**
+     * The function removes all vertices from a graph and returns a boolean indicating if any vertices were removed.
+     * @param {V[] | VertexId[]} vertices - The `vertices` parameter can be either an array of vertices (`V[]`) or an array
+     * of vertex IDs (`VertexId[]`).
+     * @returns a boolean value. It returns true if at least one vertex was successfully removed, and false if no vertices
+     * were removed.
+     */
     removeAllVertices(vertices: V[] | VertexId[]): boolean {
         const removed: boolean[] = [];
         for (const v of vertices) {
@@ -153,6 +151,15 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
 
     abstract edgesOf(vertexOrId: V | VertexId): E[];
 
+    /**
+     * The function checks if there is an edge between two vertices in a graph.
+     * @param {VertexId | V} v1 - The parameter v1 can be either a VertexId or a V. A VertexId represents the identifier of
+     * a vertex in a graph, while V represents the type of the vertex itself.
+     * @param {VertexId | V} v2 - The parameter `v2` represents the second vertex in an edge. It can be either a `VertexId`
+     * or a `V` type.
+     * @returns The function `containsEdge` returns a boolean value. It returns `true` if there is an edge between the
+     * vertices `v1` and `v2`, and `false` otherwise.
+     */
     containsEdge(v1: VertexId | V, v2: VertexId | V): boolean {
         const edge = this.getEdge(v1, v2);
         return !!edge;
@@ -160,6 +167,17 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
 
     abstract addEdge(edge: E): boolean;
 
+    /**
+     * The function sets the weight of an edge between two vertices in a graph.
+     * @param {VertexId | V} srcOrId - The `srcOrId` parameter can be either a `VertexId` or a `V` object. It represents
+     * the source vertex of the edge.
+     * @param {VertexId | V} destOrId - The `destOrId` parameter represents the destination vertex of the edge. It can be
+     * either a `VertexId` or a vertex object `V`.
+     * @param {number} weight - The weight parameter represents the weight of the edge between the source vertex (srcOrId)
+     * and the destination vertex (destOrId).
+     * @returns a boolean value. If the edge exists between the source and destination vertices, the function will update
+     * the weight of the edge and return true. If the edge does not exist, the function will return false.
+     */
     setEdgeWeight(srcOrId: VertexId | V, destOrId: VertexId | V, weight: number): boolean {
         const edge = this.getEdge(srcOrId, destOrId);
         if (edge) {
@@ -172,6 +190,15 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
 
     abstract getNeighbors(vertexOrId: V | VertexId): V[];
 
+    /**
+     * The function `getAllPathsBetween` finds all paths between two vertices in a graph using depth-first search.
+     * @param {V | VertexId} v1 - The parameter `v1` represents either a vertex object (`V`) or a vertex ID (`VertexId`).
+     * It is the starting vertex for finding paths.
+     * @param {V | VertexId} v2 - The parameter `v2` represents the destination vertex or its ID. It is the vertex that we
+     * want to find paths to from the starting vertex `v1`.
+     * @returns an array of arrays of vertices (V[][]). Each inner array represents a path between the given vertices (v1
+     * and v2).
+     */
     getAllPathsBetween(v1: V | VertexId, v2: V | VertexId): V[][] {
         const paths: V[][] = [];
         const vertex1 = this.getVertex(v1);
@@ -192,7 +219,7 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
                 if (!visiting.get(neighbor)) {
                     path.push(neighbor);
                     dfs(neighbor, dest, visiting, path);
-                    arrayRemove(path, vertex => vertex === neighbor);
+                    arrayRemove(path, (vertex: AbstractVertex) => vertex === neighbor);
                 }
             }
 
@@ -203,7 +230,11 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
         return paths;
     }
 
-
+    /**
+     * The function calculates the sum of weights along a given path.
+     * @param {V[]} path - An array of vertices (V) representing a path in a graph.
+     * @returns The function `getPathSumWeight` returns the sum of the weights of the edges in the given path.
+     */
     getPathSumWeight(path: V[]): number {
         let sum = 0;
         for (let i = 0; i < path.length; i++) {
@@ -212,6 +243,20 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
         return sum;
     }
 
+    /**
+     * The function `getMinCostBetween` calculates the minimum cost between two vertices in a graph, either based on edge
+     * weights or using a breadth-first search algorithm.
+     * @param {V | VertexId} v1 - The parameter `v1` represents the starting vertex or vertex ID of the graph.
+     * @param {V | VertexId} v2 - The parameter `v2` represents the second vertex in the graph. It can be either a vertex
+     * object or a vertex ID.
+     * @param {boolean} [isWeight] - isWeight is an optional parameter that indicates whether the graph edges have weights.
+     * If isWeight is set to true, the function will calculate the minimum cost between v1 and v2 based on the weights of
+     * the edges. If isWeight is set to false or not provided, the function will calculate the
+     * @returns The function `getMinCostBetween` returns a number representing the minimum cost between two vertices (`v1`
+     * and `v2`) in a graph. If the `isWeight` parameter is `true`, it calculates the minimum weight between the vertices.
+     * If `isWeight` is `false` or not provided, it calculates the minimum number of edges between the vertices. If the
+     * vertices are not
+     */
     getMinCostBetween(v1: V | VertexId, v2: V | VertexId, isWeight?: boolean): number | null {
         if (isWeight === undefined) isWeight = false;
 
@@ -257,6 +302,18 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
         }
     }
 
+    /**
+     * The function `getMinPathBetween` returns the minimum path between two vertices in a graph, either based on weight or
+     * using a breadth-first search algorithm.
+     * @param {V | VertexId} v1 - The parameter `v1` represents the starting vertex or its ID.
+     * @param {V | VertexId} v2 - The parameter `v2` represents the destination vertex or its ID. It is the vertex that we
+     * want to find the minimum path to from the source vertex `v1`.
+     * @param {boolean} [isWeight] - A boolean flag indicating whether to consider the weight of edges in finding the
+     * minimum path. If set to true, the function will use Dijkstra's algorithm to find the minimum weighted path. If set
+     * to false, the function will use breadth-first search (BFS) to find the minimum path. If
+     * @returns The function `getMinPathBetween` returns an array of vertices (`V[]`) representing the minimum path between
+     * two vertices (`v1` and `v2`). If no path is found, it returns `null`.
+     */
     getMinPathBetween(v1: V | VertexId, v2: V | VertexId, isWeight?: boolean): V[] | null {
         if (isWeight === undefined) isWeight = false;
 
@@ -296,7 +353,7 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
                     if (!visiting.get(neighbor)) {
                         path.push(neighbor);
                         dfs(neighbor, dest, visiting, path);
-                        arrayRemove(path, vertex => vertex === neighbor);
+                        arrayRemove(path, (vertex: AbstractVertex) => vertex === neighbor);
                     }
                 }
 
@@ -310,10 +367,20 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
 
     /**
      * Dijkstra algorithm time: O(VE) space: O(V + E)
-     * @param src
-     * @param dest
-     * @param getMinDist
-     * @param genPaths
+     * The function `dijkstraWithoutHeap` implements Dijkstra's algorithm to find the shortest path between two vertices in
+     * a graph without using a heap data structure.
+     * @param {V | VertexId} src - The source vertex from which to start the Dijkstra's algorithm. It can be either a
+     * vertex object or a vertex ID.
+     * @param {V | VertexId | null} [dest] - The `dest` parameter in the `dijkstraWithoutHeap` function is an optional
+     * parameter that specifies the destination vertex for the Dijkstra algorithm. It can be either a vertex object or its
+     * identifier. If no destination is provided, the value is set to `null`.
+     * @param {boolean} [getMinDist] - The `getMinDist` parameter is a boolean flag that determines whether the minimum
+     * distance from the source vertex to the destination vertex should be calculated and returned in the result. If
+     * `getMinDist` is set to `true`, the `minDist` property in the result will contain the minimum distance
+     * @param {boolean} [genPaths] - The `genPaths` parameter is a boolean flag that determines whether or not to generate
+     * paths in the Dijkstra algorithm. If `genPaths` is set to `true`, the algorithm will calculate and return the
+     * shortest paths from the source vertex to all other vertices in the graph. If `genPaths
+     * @returns The function `dijkstraWithoutHeap` returns an object of type `DijkstraResult<V>`.
      */
     dijkstraWithoutHeap(src: V | VertexId, dest?: V | VertexId | null, getMinDist?: boolean, genPaths?: boolean): DijkstraResult<V> {
         if (getMinDist === undefined) getMinDist = false;
@@ -338,7 +405,8 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
         }
 
         for (const vertex of vertices) {
-            distMap.set(vertex[1], Infinity);
+            const vertexOrId = vertex[1];
+            if (vertexOrId instanceof AbstractVertex) distMap.set(vertexOrId, Infinity);
         }
         distMap.set(srcVertex, 0);
         preMap.set(srcVertex, null);
@@ -359,15 +427,19 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
 
         const getPaths = (minV: V | null) => {
             for (const vertex of vertices) {
-                const path: V[] = [vertex[1]];
-                let parent = preMap.get(vertex[1]);
-                while (parent) {
-                    path.push(parent);
-                    parent = preMap.get(parent);
+                const vertexOrId = vertex[1];
+
+                if (vertexOrId instanceof AbstractVertex) {
+                    const path: V[] = [vertexOrId];
+                    let parent = preMap.get(vertexOrId);
+                    while (parent) {
+                        path.push(parent);
+                        parent = preMap.get(parent);
+                    }
+                    const reversed = path.reverse();
+                    if (vertex[1] === minV) minPath = reversed;
+                    paths.push(reversed);
                 }
-                const reversed = path.reverse();
-                if (vertex[1] === minV) minPath = reversed;
-                paths.push(reversed);
             }
         };
 
@@ -419,13 +491,22 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
         return {distMap, preMap, seen, paths, minDist, minPath};
     }
 
-
     /**
      * Dijkstra algorithm time: O(logVE) space: O(V + E)
-     * @param src
-     * @param dest
-     * @param getMinDist
-     * @param genPaths
+     * The `dijkstra` function implements Dijkstra's algorithm to find the shortest path between a source vertex and an
+     * optional destination vertex, and optionally returns the minimum distance, the paths, and other information.
+     * @param {V | VertexId} src - The `src` parameter represents the source vertex from which the Dijkstra algorithm will
+     * start. It can be either a vertex object or a vertex ID.
+     * @param {V | VertexId | null} [dest] - The `dest` parameter is the destination vertex or vertex ID. It specifies the
+     * vertex to which the shortest path is calculated from the source vertex. If no destination is provided, the algorithm
+     * will calculate the shortest paths to all other vertices from the source vertex.
+     * @param {boolean} [getMinDist] - The `getMinDist` parameter is a boolean flag that determines whether the minimum
+     * distance from the source vertex to the destination vertex should be calculated and returned in the result. If
+     * `getMinDist` is set to `true`, the `minDist` property in the result will contain the minimum distance
+     * @param {boolean} [genPaths] - The `genPaths` parameter is a boolean flag that determines whether or not to generate
+     * paths in the Dijkstra algorithm. If `genPaths` is set to `true`, the algorithm will calculate and return the
+     * shortest paths from the source vertex to all other vertices in the graph. If `genPaths
+     * @returns The function `dijkstra` returns an object of type `DijkstraResult<V>`.
      */
     dijkstra(src: V | VertexId, dest?: V | VertexId | null, getMinDist?: boolean, genPaths?: boolean): DijkstraResult<V> {
         if (getMinDist === undefined) getMinDist = false;
@@ -449,7 +530,8 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
         }
 
         for (const vertex of vertices) {
-            distMap.set(vertex[1], Infinity);
+            const vertexOrId = vertex[1];
+            if (vertexOrId instanceof AbstractVertex) distMap.set(vertexOrId, Infinity);
         }
 
         const heap = new PriorityQueue<{ id: number, val: V }>({comparator: (a, b) => a.id - b.id});
@@ -460,15 +542,19 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
 
         const getPaths = (minV: V | null) => {
             for (const vertex of vertices) {
-                const path: V[] = [vertex[1]];
-                let parent = preMap.get(vertex[1]);
-                while (parent) {
-                    path.push(parent);
-                    parent = preMap.get(parent);
+                const vertexOrId = vertex[1];
+                if (vertexOrId instanceof AbstractVertex) {
+                    const path: V[] = [vertexOrId];
+                    let parent = preMap.get(vertexOrId);
+                    while (parent) {
+                        path.push(parent);
+                        parent = preMap.get(parent);
+                    }
+                    const reversed = path.reverse();
+                    if (vertex[1] === minV) minPath = reversed;
+                    paths.push(reversed);
                 }
-                const reversed = path.reverse();
-                if (vertex[1] === minV) minPath = reversed;
-                paths.push(reversed);
+
             }
         };
 
@@ -535,10 +621,17 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
     /**
      * BellmanFord time:O(VE) space:O(V)
      * one to rest pairs
-     * @param src
-     * @param scanNegativeCycle
-     * @param getMin
-     * @param genPath
+     * The `bellmanFord` function implements the Bellman-Ford algorithm to find the shortest path from a source vertex to
+     * all other vertices in a graph, and optionally detects negative cycles and generates the minimum path.
+     * @param {V | VertexId} src - The `src` parameter is the source vertex from which the Bellman-Ford algorithm will
+     * start calculating the shortest paths. It can be either a vertex object or a vertex ID.
+     * @param {boolean} [scanNegativeCycle] - A boolean flag indicating whether to scan for negative cycles in the graph.
+     * @param {boolean} [getMin] - The `getMin` parameter is a boolean flag that determines whether the algorithm should
+     * calculate the minimum distance from the source vertex to all other vertices in the graph. If `getMin` is set to
+     * `true`, the algorithm will find the minimum distance and update the `min` variable with the minimum
+     * @param {boolean} [genPath] - A boolean flag indicating whether to generate paths for all vertices from the source
+     * vertex.
+     * @returns The function `bellmanFord` returns an object with the following properties:
      */
     bellmanFord(src: V | VertexId, scanNegativeCycle?: boolean, getMin?: boolean, genPath?: boolean) {
         if (getMin === undefined) getMin = false;
@@ -551,7 +644,7 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
         let min = Infinity;
         let minPath: V[] = [];
         // TODO
-        let hasNegativeCycle: boolean | undefined = undefined;
+        let hasNegativeCycle: boolean | undefined;
         if (scanNegativeCycle) hasNegativeCycle = false;
         if (!srcVertex) return {hasNegativeCycle, distMap, preMap, paths, min, minPath};
 
@@ -598,15 +691,18 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
 
         if (genPath) {
             for (const vertex of vertices) {
-                const path: V[] = [vertex[1]];
-                let parent = preMap.get(vertex[1]);
-                while (parent !== undefined) {
-                    path.push(parent);
-                    parent = preMap.get(parent);
+                const vertexOrId = vertex[1];
+                if (vertexOrId instanceof AbstractVertex) {
+                    const path: V[] = [vertexOrId];
+                    let parent = preMap.get(vertexOrId);
+                    while (parent !== undefined) {
+                        path.push(parent);
+                        parent = preMap.get(parent);
+                    }
+                    const reversed = path.reverse();
+                    if (vertex[1] === minDest) minPath = reversed;
+                    paths.push(reversed);
                 }
-                const reversed = path.reverse();
-                if (vertex[1] === minDest) minPath = reversed;
-                paths.push(reversed);
             }
         }
 
@@ -628,6 +724,12 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
     /**
      * Floyd algorithm time: O(V^3) space: O(V^2), not support graph with negative weight cycle
      * all pairs
+     * The function implements the Floyd-Warshall algorithm to find the shortest path between all pairs of vertices in a
+     * graph.
+     * @returns The function `floyd()` returns an object with two properties: `costs` and `predecessor`. The `costs`
+     * property is a 2D array of numbers representing the shortest path costs between vertices in a graph. The
+     * `predecessor` property is a 2D array of vertices (or `null`) representing the predecessor vertices in the shortest
+     * path between vertices in the
      */
     floyd(): { costs: number[][], predecessor: (V | null)[][] } {
         const idAndVertices = [...this._vertices];
@@ -674,6 +776,20 @@ export abstract class AbstractGraph<V extends AbstractVertex, E extends Abstract
      * Tarjan can find the articulation points and bridges(critical edges) of undirected graphs in linear time,
      * Tarjan solve the bi-connected components of undirected graphs;
      * Tarjan can find the SSC(strongly connected components), articulation points, and bridges of directed graphs.
+     * The `tarjan` function is used to perform various graph analysis tasks such as finding articulation points, bridges,
+     * strongly connected components (SCCs), and cycles in a graph.
+     * @param {boolean} [needArticulationPoints] - A boolean value indicating whether or not to calculate and return the
+     * articulation points in the graph. Articulation points are the vertices in a graph whose removal would increase the
+     * number of connected components in the graph.
+     * @param {boolean} [needBridges] - A boolean flag indicating whether the algorithm should find and return the bridges
+     * (edges whose removal would increase the number of connected components in the graph).
+     * @param {boolean} [needSCCs] - A boolean value indicating whether the Strongly Connected Components (SCCs) of the
+     * graph are needed. If set to true, the function will calculate and return the SCCs of the graph. If set to false, the
+     * SCCs will not be calculated or returned.
+     * @param {boolean} [needCycles] - A boolean flag indicating whether the algorithm should find cycles in the graph. If
+     * set to true, the algorithm will return a map of cycles, where the keys are the low values of the SCCs and the values
+     * are arrays of vertices that form cycles within the SCCs.
+     * @returns The function `tarjan` returns an object with the following properties:
      */
     tarjan(needArticulationPoints?: boolean, needBridges?: boolean, needSCCs?: boolean, needCycles?: boolean) {
         // !! in undirected graph we will not let child visit parent when DFS