data-structure-typed 0.9.16 → 1.12.10

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

@@ -1,3 +1,7 @@
+/**
+ * @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';
@@ -7,7 +11,7 @@ export class AbstractVertex {
         this._id = id;
     }
 
-    private _id: VertexId;
+    protected _id: VertexId;
 
     public get id(): VertexId {
         return this._id;
@@ -58,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;
@@ -85,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) {
@@ -104,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;
@@ -111,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) {
@@ -123,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);
@@ -154,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++) {
@@ -163,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;
 
@@ -208,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;
 
@@ -261,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;
@@ -375,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;
@@ -496,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;
@@ -592,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];
@@ -638,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

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

@@ -1,3 +1,7 @@
+/**
+ * @copyright 2030 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT
+ */
 import {arrayRemove} from '../../utils';
 import {AbstractEdge, AbstractGraph, AbstractVertex} from './abstract-graph';
 import type {IDirectedGraph, TopologicalStatus, VertexId} from '../types';
@@ -46,6 +50,14 @@ export class DirectedGraph<V extends DirectedVertex, E extends DirectedEdge> ext
         super();
     }
 
+    /**
+     * The function `getEdge` returns the first edge between two vertices, given their source and destination.
+     * @param {V | null | VertexId} srcOrId - The `srcOrId` parameter can be either a vertex object (`V`), a vertex ID
+     * (`VertexId`), or `null`. It represents the source vertex of the edge.
+     * @param {V | null | VertexId} destOrId - The `destOrId` parameter is either a vertex object (`V`), a vertex ID
+     * (`VertexId`), or `null`. It represents the destination vertex of the edge.
+     * @returns an edge (E) or null.
+     */
     getEdge(srcOrId: V | null | VertexId, destOrId: V | null | VertexId): E | null {
         let edges: E[] = [];
 
@@ -64,6 +76,13 @@ export class DirectedGraph<V extends DirectedVertex, E extends DirectedEdge> ext
         return edges[0] || null;
     }
 
+    /**
+     * The `addEdge` function adds an edge to a graph if the source and destination vertices exist.
+     * @param {E} edge - The parameter `edge` is of type `E`, which represents an edge in the graph. It contains
+     * information about the source vertex (`src`) and the destination vertex (`dest`) of the edge.
+     * @returns The `addEdge` function returns a boolean value. It returns `true` if the edge was successfully added to the
+     * graph, and `false` if either the source or destination vertices of the edge are not present in the graph.
+     */
     addEdge(edge: E): boolean {
         if (!(this.containsVertex(edge.src) && this.containsVertex(edge.dest))) {
             return false;
@@ -93,6 +112,16 @@ export class DirectedGraph<V extends DirectedVertex, E extends DirectedEdge> ext
         }
     }
 
+    /**
+     * The function removes an edge between two vertices in a directed graph and returns the removed edge.
+     * @param {V | VertexId} srcOrId - The source vertex or its ID.
+     * @param {V | VertexId} destOrId - The `destOrId` parameter in the `removeEdgeBetween` function represents the
+     * destination vertex of the edge that needs to be removed. It can be either a vertex object (`V`) or a vertex ID
+     * (`VertexId`).
+     * @returns The function `removeEdgeBetween` returns the removed edge (`E`) if the edge between the source and
+     * destination vertices is successfully removed. If either the source or destination vertex is not found, or if the
+     * edge does not exist, it returns `null`.
+     */
     removeEdgeBetween(srcOrId: V | VertexId, destOrId: V | VertexId): E | null {
 
         const src: V | null = this.getVertex(srcOrId);
@@ -104,6 +133,14 @@ export class DirectedGraph<V extends DirectedVertex, E extends DirectedEdge> ext
 
         const srcOutEdges = this._outEdgeMap.get(src);
         if (srcOutEdges) {
+    /**
+     * The removeEdge function removes an edge from a graph and returns the removed edge, or null if the edge was not
+     * found.
+     * @param {E} edge - The `edge` parameter represents the edge that you want to remove from the graph. It should be an
+     * object that has `src` and `dest` properties, which represent the source and destination vertices of the edge,
+     * respectively.
+     * @returns The method `removeEdge` returns the removed edge (`E`) if it exists, or `null` if the edge does not exist.
+     */
             arrayRemove<E>(srcOutEdges, (edge: DirectedEdge) => edge.dest === dest.id);
         }
 
@@ -114,7 +151,14 @@ export class DirectedGraph<V extends DirectedVertex, E extends DirectedEdge> ext
         return removed;
     }
 
-    removeEdge(edge: E): E | null {
+    /**
+     * The removeEdge function removes an edge from a graph and returns the removed edge, or null if the edge was not
+     * found.
+     * @param {E} edge - The `edge` parameter is an object that represents an edge in a graph. It has two properties: `src`
+     * and `dest`, which represent the source and destination vertices of the edge, respectively.
+     * @returns The method `removeEdge` returns the removed edge (`E`) if it exists, or `null` if the edge does not exist.
+     */
+    removeEdge(edge: E ): E | null {
         let removed: E | null = null;
         const src = this.getVertex(edge.src);
         const dest = this.getVertex(edge.dest);
@@ -134,10 +178,24 @@ export class DirectedGraph<V extends DirectedVertex, E extends DirectedEdge> ext
         return removed;
     }
 
+    /**
+     * The function removeAllEdges removes all edges between two vertices.
+     * @param {VertexId | V} src - The `src` parameter represents the source vertex from which the edges will be removed.
+     * It can be either a `VertexId` or a `V` type, which represents the identifier or object of the vertex.
+     * @param {VertexId | V} dest - The `dest` parameter represents the destination vertex of an edge. It can be either a
+     * `VertexId` or a vertex object `V`.
+     * @returns An empty array is being returned.
+     */
     removeAllEdges(src: VertexId | V, dest: VertexId | V): E[] {
         return [];
     }
 
+    /**
+     * The function `incomingEdgesOf` returns an array of incoming edges for a given vertex or vertex ID.
+     * @param {V | VertexId} vertexOrId - The parameter `vertexOrId` can be either a vertex object (`V`) or a vertex ID
+     * (`VertexId`).
+     * @returns The method `incomingEdgesOf` returns an array of edges (`E[]`).
+     */
     incomingEdgesOf(vertexOrId: V | VertexId): E[] {
         const target = this.getVertex(vertexOrId);
         if (target) {
@@ -146,6 +204,12 @@ export class DirectedGraph<V extends DirectedVertex, E extends DirectedEdge> ext
         return [];
     }
 
+    /**
+     * The function `outgoingEdgesOf` returns an array of outgoing edges from a given vertex or vertex ID.
+     * @param {V | VertexId} vertexOrId - The parameter `vertexOrId` can accept either a vertex object (`V`) or a vertex ID
+     * (`VertexId`).
+     * @returns The method `outgoingEdgesOf` returns an array of outgoing edges from a given vertex or vertex ID.
+     */
     outgoingEdgesOf(vertexOrId: V | VertexId): E[] {
         const target = this.getVertex(vertexOrId);
         if (target) {
@@ -154,30 +218,67 @@ export class DirectedGraph<V extends DirectedVertex, E extends DirectedEdge> ext
         return [];
     }
 
+    /**
+     * The function "degreeOf" returns the total degree of a vertex, which is the sum of its out-degree and in-degree.
+     * @param {VertexId | V} vertexOrId - The parameter `vertexOrId` can be either a `VertexId` or a `V`.
+     * @returns the sum of the out-degree and in-degree of the specified vertex or vertex ID.
+     */
     degreeOf(vertexOrId: VertexId | V): number {
         return this.outDegreeOf(vertexOrId) + this.inDegreeOf(vertexOrId);
     }
 
+    /**
+     * The function "inDegreeOf" returns the number of incoming edges for a given vertex.
+     * @param {VertexId | V} vertexOrId - The parameter `vertexOrId` can be either a `VertexId` or a `V`.
+     * @returns The number of incoming edges of the specified vertex or vertex ID.
+     */
     inDegreeOf(vertexOrId: VertexId | V): number {
         return this.incomingEdgesOf(vertexOrId).length;
     }
 
+    /**
+     * The function `outDegreeOf` returns the number of outgoing edges from a given vertex.
+     * @param {VertexId | V} vertexOrId - The parameter `vertexOrId` can be either a `VertexId` or a `V`.
+     * @returns The number of outgoing edges from the specified vertex or vertex ID.
+     */
     outDegreeOf(vertexOrId: VertexId | V): number {
         return this.outgoingEdgesOf(vertexOrId).length;
     }
 
+    /**
+     * The function "edgesOf" returns an array of both outgoing and incoming edges of a given vertex or vertex ID.
+     * @param {VertexId | V} vertexOrId - The parameter `vertexOrId` can be either a `VertexId` or a `V`.
+     * @returns The function `edgesOf` returns an array of edges.
+     */
     edgesOf(vertexOrId: VertexId | V): E[] {
         return [...this.outgoingEdgesOf(vertexOrId), ...this.incomingEdgesOf(vertexOrId)];
     }
 
+    /**
+     * The function "getEdgeSrc" returns the source vertex of an edge, or null if the edge does not exist.
+     * @param {E} e - E - an edge object
+     * @returns the source vertex of the given edge, or null if the edge does not exist.
+     */
     getEdgeSrc(e: E): V | null {
         return this.getVertex(e.src);
     }
 
+    /**
+     * The function "getEdgeDest" returns the vertex associated with the destination of an edge.
+     * @param {E} e - The parameter `e` is of type `E`, which represents an edge in a graph.
+     * @returns either a vertex object (of type V) or null.
+     */
     getEdgeDest(e: E): V | null {
         return this.getVertex(e.dest);
     }
 
+    /**
+     * The function `getDestinations` returns an array of destination vertices connected to a given vertex.
+     * @param {V | VertexId | null} vertex - The `vertex` parameter represents the starting vertex from which we want to
+     * find the destinations. It can be either a `V` object, a `VertexId` (which is a unique identifier for a vertex), or
+     * `null` if we want to find destinations from all vertices.
+     * @returns an array of vertices (V[]).
+     */
     getDestinations(vertex: V | VertexId | null): V[] {
         if (vertex === null) {
             return [];
@@ -198,8 +299,12 @@ export class DirectedGraph<V extends DirectedVertex, E extends DirectedEdge> ext
     /**
      * when stored with adjacency list time: O(V+E)
      * when stored with adjacency matrix time: O(V^2)
+     * The `topologicalSort` function performs a topological sort on a directed graph and returns the sorted vertices in
+     * reverse order, or null if the graph contains a cycle.
+     * @returns The function `topologicalSort()` returns an array of vertices in topological order if there is no cycle in
+     * the graph. If there is a cycle in the graph, it returns `null`.
      */
-    topologicalSort(): (V | VertexId)[] | null {
+    topologicalSort(): V[] | null {
         // vector<vector<int>> g;
         // vector<int> color;
         // int last;
@@ -231,14 +336,14 @@ export class DirectedGraph<V extends DirectedVertex, E extends DirectedEdge> ext
         // }
         // When judging whether there is a cycle in the undirected graph, all nodes with degree of **<= 1** are enqueued
         // When judging whether there is a cycle in the directed graph, all nodes with **in degree = 0** are enqueued
-        const statusMap: Map<V | VertexId, TopologicalStatus> = new Map<V, TopologicalStatus>();
+        const statusMap: Map<V, TopologicalStatus> = new Map<V, TopologicalStatus>();
         for (const entry of this._vertices) {
             statusMap.set(entry[1], 0);
         }
 
-        const sorted: (V | VertexId)[] = [];
+        const sorted: (V)[] = [];
         let hasCycle = false;
-        const dfs = (cur: V | VertexId) => {
+        const dfs = (cur: V) => {
             statusMap.set(cur, 1);
             const children = this.getDestinations(cur);
             for (const child of children) {
@@ -267,6 +372,10 @@ export class DirectedGraph<V extends DirectedVertex, E extends DirectedEdge> ext
 
     /**--- end find cycles --- */
 
+    /**
+     * The `edgeSet` function returns an array of all the edges in the graph.
+     * @returns The `edgeSet()` method returns an array of edges (`E[]`).
+     */
     edgeSet(): E[] {
         let edges: E[] = [];
         this._outEdgeMap.forEach(outEdges => {
@@ -275,6 +384,12 @@ export class DirectedGraph<V extends DirectedVertex, E extends DirectedEdge> ext
         return edges;
     }
 
+    /**
+     * The function `getNeighbors` returns an array of neighboring vertices for a given vertex or vertex ID.
+     * @param {V | VertexId} vertexOrId - The parameter `vertexOrId` can be either a vertex object (`V`) or a vertex ID
+     * (`VertexId`).
+     * @returns an array of vertices (V[]).
+     */
     getNeighbors(vertexOrId: V | VertexId): V[] {
         const neighbors: V[] = [];
         const vertex = this.getVertex(vertexOrId);
@@ -291,6 +406,13 @@ export class DirectedGraph<V extends DirectedVertex, E extends DirectedEdge> ext
         return neighbors;
     }
 
+    /**
+     * The function "getEndsOfEdge" returns the source and destination vertices of an edge if it exists in the graph,
+     * otherwise it returns null.
+     * @param {E} edge - The parameter "edge" is of type E, which represents an edge in a graph.
+     * @returns an array containing two vertices [V, V] if the edge is found in the graph. If the edge is not found, it
+     * returns null.
+     */
     getEndsOfEdge(edge: E): [V, V] | null {
         if (!this.containsEdge(edge.src, edge.dest)) {
             return null;