priority-queue-typed 2.0.4 → 2.1.0

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

@@ -5,19 +5,13 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { TopologicalStatus, VertexKey } from '../../types';
+
+import type { GraphOptions, TopologicalStatus, VertexKey } from '../../types';
 import { AbstractEdge, AbstractGraph, AbstractVertex } from './abstract-graph';
 import { IGraph } from '../../interfaces';
 import { arrayRemove } from '../../utils';
 
 export class DirectedVertex<V = any> extends AbstractVertex<V> {
-  /**
-   * The constructor function initializes a vertex with an optional value.
-   * @param {VertexKey} key - The `key` parameter is of type `VertexKey` and represents the identifier of the vertex. It is
-   * used to uniquely identify the vertex within a graph or data structure.
-   * @param {V} [value] - The "value" parameter is an optional parameter of type V. It is used to initialize the value of the
-   * vertex. If no value is provided, the vertex will be initialized with a default value.
-   */
   constructor(key: VertexKey, value?: V) {
     super(key, value);
   }
@@ -27,17 +21,6 @@ export class DirectedEdge<E = any> extends AbstractEdge<E> {
   src: VertexKey;
   dest: VertexKey;
 
-  /**
-   * The constructor function initializes the source and destination vertexMap of an edge, along with an optional weight
-   * and value.
-   * @param {VertexKey} src - The `src` parameter is the source vertex ID. It represents the starting point of an edge in
-   * a graph.
-   * @param {VertexKey} dest - The `dest` parameter represents the destination vertex of an edge. It is of type
-   * `VertexKey`, which is likely a unique identifier for a vertex in a graph.
-   * @param {number} [weight] - The weight parameter is an optional number that represents the weight of the edge.
-   * @param {E} [value] - The `value` parameter is an optional parameter of type `E`. It represents the value associated with
-   * the edge.
-   */
   constructor(src: VertexKey, dest: VertexKey, weight?: number, value?: E) {
     super(weight, value);
     this.src = src;
@@ -46,7 +29,13 @@ export class DirectedEdge<E = any> extends AbstractEdge<E> {
 }
 
 /**
- *
+ * Directed graph implementation.
+ * @template V - Vertex value type.
+ * @template E - Edge value type.
+ * @template VO - Concrete vertex class (extends AbstractVertex<V>).
+ * @template EO - Concrete edge class (extends AbstractEdge<E>).
+ * @remarks Time O(1), Space O(1)
+ * @example examples will be generated by unit test
  */
 export class DirectedGraph<
     V = any,
@@ -58,10 +47,12 @@ export class DirectedGraph<
   implements IGraph<V, E, VO, EO>
 {
   /**
-   * The constructor function initializes an instance of a class.
+   * Construct a directed graph with runtime defaults.
+   * @param options - `GraphOptions<V>` (e.g. `vertexValueInitializer`, `defaultEdgeWeight`).
+   * @remarks Time O(1), Space O(1)
    */
-  constructor() {
-    super();
+  constructor(options?: Partial<GraphOptions<V>>) {
+    super(options);
   }
 
   protected _outEdgeMap: Map<VO, EO[]> = new Map<VO, EO[]>();
@@ -85,42 +76,65 @@ export class DirectedGraph<
   }
 
   /**
-   * The function creates a new vertex with an optional value and returns it.
-   * @param {VertexKey} key - The `key` parameter is the unique identifier for the vertex. It is of type `VertexKey`, which
-   * could be a number or a string depending on how you want to identify your vertexMap.
-   * @param [value] - The 'value' parameter is an optional value that can be assigned to the vertex. If a value is provided,
-   * it will be assigned to the 'value' property of the vertex. If no value is provided, the 'value' property will be
-   * assigned the same value as the 'key' parameter
-   * @returns a new instance of a DirectedVertex object, casted as type VO.
+   * Construct a directed graph from keys with value initializer `v => v`.
+   * @template K - Vertex key type.
+   * @param keys - Iterable of vertex keys.
+   * @returns DirectedGraph with all keys added.
+   * @remarks Time O(V), Space O(V)
    */
-  createVertex(key: VertexKey, value?: V): VO {
+  static fromKeys<K extends VertexKey>(keys: Iterable<K>): DirectedGraph<K, any, DirectedVertex<K>, DirectedEdge<any>> {
+    const g: DirectedGraph<K, any, DirectedVertex<K>, DirectedEdge<any>> = new DirectedGraph<K, any>({
+      vertexValueInitializer: (k: VertexKey) => k as K
+    });
+    for (const k of keys) g.addVertex(k);
+    return g;
+  }
+
+  /**
+   * Construct a directed graph from `[key, value]` entries.
+   * @template V - Vertex value type.
+   * @param entries - Iterable of `[key, value]` pairs.
+   * @returns DirectedGraph with all vertices added.
+   * @remarks Time O(V), Space O(V)
+   */
+  static fromEntries<V>(
+    entries: Iterable<[VertexKey, V]>
+  ): DirectedGraph<V, any, DirectedVertex<V>, DirectedEdge<any>> {
+    const g: DirectedGraph<V, any, DirectedVertex<V>, DirectedEdge<any>> = new DirectedGraph<V, any>();
+    for (const [k, v] of entries) g.addVertex(k, v);
+    return g;
+  }
+
+  /**
+   * Create a directed vertex instance. Does not insert into the graph.
+   * @param key - Vertex identifier.
+   * @param value - Optional payload.
+   * @returns Concrete vertex instance.
+   * @remarks Time O(1), Space O(1)
+   */
+  createVertex(key: VertexKey, value?: VO['value']): VO {
     return new DirectedVertex(key, value) as VO;
   }
 
   /**
-   * The function creates a directed edge between two vertexMap with an optional weight and value.
-   * @param {VertexKey} src - The source vertex ID of the edge. It represents the starting point of the edge.
-   * @param {VertexKey} dest - The `dest` parameter is the identifier of the destination vertex for the edge.
-   * @param {number} [weight] - The weight parameter is an optional number that represents the weight of the edge. If no
-   * weight is provided, it defaults to 1.
-   * @param [value] - The 'value' parameter is an optional value that can be assigned to the edge. It can be of any type and
-   * is used to store additional information or data associated with the edge.
-   * @returns a new instance of a DirectedEdge object, casted as type EO.
+   * Create a directed edge instance. Does not insert into the graph.
+   * @param src - Source vertex key.
+   * @param dest - Destination vertex key.
+   * @param weight - Edge weight; defaults to `defaultEdgeWeight`.
+   * @param value - Edge payload.
+   * @returns Concrete edge instance.
+   * @remarks Time O(1), Space O(1)
    */
   createEdge(src: VertexKey, dest: VertexKey, weight?: number, value?: E): EO {
-    return new DirectedEdge(src, dest, weight ?? 1, value) as EO;
+    return new DirectedEdge(src, dest, weight ?? this.options.defaultEdgeWeight ?? 1, value) as EO;
   }
 
   /**
-   * Time Complexity: O(|V|) where |V| is the number of vertexMap
-   * Space Complexity: O(1)
-   *
-   * The `getEdge` function retrieves an edge between two vertexMap based on their source and destination IDs.
-   * @param {VO | VertexKey | undefined} srcOrKey - The source vertex or its ID. It can be either a vertex object or a vertex ID.
-   * @param {VO | VertexKey | undefined} destOrKey - The `destOrKey` parameter in the `getEdge` function represents the
-   * destination vertex of the edge. It can be either a vertex object (`VO`), a vertex ID (`VertexKey`), or `undefined` if the
-   * destination is not specified.
-   * @returns the first edge found between the source and destination vertexMap, or undefined if no such edge is found.
+   * Get the unique edge from `src` to `dest`, if present.
+   * @param srcOrKey - Source vertex or key.
+   * @param destOrKey - Destination vertex or key.
+   * @returns Edge instance or `undefined`.
+   * @remarks Time O(1) avg, Space O(1)
    */
   getEdge(srcOrKey: VO | VertexKey | undefined, destOrKey: VO | VertexKey | undefined): EO | undefined {
     let edgeMap: EO[] = [];
@@ -141,13 +155,11 @@ export class DirectedGraph<
   }
 
   /**
-   * Time Complexity: O(|E|) where |E| is the number of edgeMap
-   * Space Complexity: O(1)
-   *
-   * The function removes an edge between two vertexMap in a graph and returns the removed edge.
-   * @param {VO | VertexKey} srcOrKey - The source vertex or its ID.
-   * @param {VO | VertexKey} destOrKey - The `destOrKey` parameter represents the destination vertex or its ID.
-   * @returns the removed edge (EO) if it exists, or undefined if either the source or destination vertex does not exist.
+   * Delete edge `src -> dest` if present.
+   * @param srcOrKey - Source vertex or key.
+   * @param destOrKey - Destination vertex or key.
+   * @returns Removed edge or `undefined`.
+   * @remarks Time O(1) avg, Space O(1)
    */
   deleteEdgeSrcToDest(srcOrKey: VO | VertexKey, destOrKey: VO | VertexKey): EO | undefined {
     const src: VO | undefined = this._getVertex(srcOrKey);
@@ -170,17 +182,11 @@ export class DirectedGraph<
   }
 
   /**
-   * Time Complexity: O(E) where E is the number of edgeMap
-   * Space Complexity: O(1)
-   *
-   * The `deleteEdge` function removes an edge from a graph and returns the removed edge.
-   * @param {EO | VertexKey} edgeOrSrcVertexKey - The `edge` parameter can be either an `EO` object (edge object) or
-   * a `VertexKey` (key of a vertex).
-   * @param {VertexKey} [destVertexKey] - The `destVertexKey` parameter is an optional parameter that
-   * represents the key of the destination vertex of the edge. It is used to specify the destination
-   * vertex when the `edge` parameter is a vertex key. If `destVertexKey` is not provided, the function
-   * assumes that the `edge`
-   * @returns the removed edge (EO) or undefined if no edge was removed.
+   * Delete an edge by instance or by `(srcKey, destKey)`.
+   * @param edgeOrSrcVertexKey - Edge instance or source vertex/key.
+   * @param destVertexKey - Optional destination vertex/key when deleting by pair.
+   * @returns Removed edge or `undefined`.
+   * @remarks Time O(1) avg, Space O(1)
    */
   deleteEdge(edgeOrSrcVertexKey: EO | VertexKey, destVertexKey?: VertexKey): EO | undefined {
     let removed: EO | undefined = undefined;
@@ -212,15 +218,6 @@ export class DirectedGraph<
     return removed;
   }
 
-  /**
-   * Time Complexity: O(1) - Constant time for Map operations.
-   * Space Complexity: O(1) - Constant space, as it creates only a few variables.
-   *
-   * The `deleteVertex` function removes a vertex from a graph by its ID or by the vertex object itself.
-   * @param {VO | VertexKey} vertexOrKey - The parameter `vertexOrKey` can be either a vertex object (`VO`) or a vertex ID
-   * (`VertexKey`).
-   * @returns The method is returning a boolean value.
-   */
   deleteVertex(vertexOrKey: VO | VertexKey): boolean {
     let vertexKey: VertexKey;
     let vertex: VO | undefined;
@@ -233,9 +230,14 @@ export class DirectedGraph<
     }
 
     if (vertex) {
+      /**
+       * One-step neighbors following outgoing edges.
+       * @param vertexOrKey - Vertex or key.
+       * @returns Array of neighbor vertices.
+       * @remarks Time O(deg_out), Space O(deg_out)
+       */
       const neighbors = this.getNeighbors(vertex);
       for (const neighbor of neighbors) {
-        // this._inEdgeMap.delete(neighbor);
         this.deleteEdgeSrcToDest(vertex, neighbor);
       }
       this._outEdgeMap.delete(vertex);
@@ -245,17 +247,6 @@ export class DirectedGraph<
     return this._vertexMap.delete(vertexKey);
   }
 
-  /**
-   * Time Complexity: O(|E|) where |E| is the number of edgeMap
-   * Space Complexity: O(1)
-   *
-   * The function removes edgeMap between two vertexMap and returns the removed edgeMap.
-   * @param {VertexKey | VO} v1 - The parameter `v1` can be either a `VertexKey` or a `VO`. A `VertexKey` represents the
-   * unique identifier of a vertex in a graph, while `VO` represents the actual vertex object.
-   * @param {VertexKey | VO} v2 - The parameter `v2` represents either a `VertexKey` or a `VO` object. It is used to specify
-   * the second vertex in the edge that needs to be removed.
-   * @returns an array of removed edgeMap (EO[]).
-   */
   deleteEdgesBetween(v1: VertexKey | VO, v2: VertexKey | VO): EO[] {
     const removed: EO[] = [];
 
@@ -271,13 +262,10 @@ export class DirectedGraph<
   }
 
   /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The function `incomingEdgesOf` returns an array of incoming edgeMap for a given vertex or vertex ID.
-   * @param {VO | VertexKey} vertexOrKey - The parameter `vertexOrKey` can be either a vertex object (`VO`) or a vertex ID
-   * (`VertexKey`).
-   * @returns The method `incomingEdgesOf` returns an array of edgeMap (`EO[]`).
+   * Incoming edges of a vertex.
+   * @param vertexOrKey - Vertex or key.
+   * @returns Array of incoming edges.
+   * @remarks Time O(deg_in), Space O(deg_in)
    */
   incomingEdgesOf(vertexOrKey: VO | VertexKey): EO[] {
     const target = this._getVertex(vertexOrKey);
@@ -288,13 +276,10 @@ export class DirectedGraph<
   }
 
   /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The function `outgoingEdgesOf` returns an array of outgoing edgeMap from a given vertex or vertex ID.
-   * @param {VO | VertexKey} vertexOrKey - The parameter `vertexOrKey` can accept either a vertex object (`VO`) or a vertex ID
-   * (`VertexKey`).
-   * @returns The method `outgoingEdgesOf` returns an array of edgeMap (`EO[]`).
+   * Outgoing edges of a vertex.
+   * @param vertexOrKey - Vertex or key.
+   * @returns Array of outgoing edges.
+   * @remarks Time O(deg_out), Space O(deg_out)
    */
   outgoingEdgesOf(vertexOrKey: VO | VertexKey): EO[] {
     const target = this._getVertex(vertexOrKey);
@@ -305,85 +290,58 @@ export class DirectedGraph<
   }
 
   /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The function "degreeOf" returns the total degree of a vertex, which is the sum of its out-degree and in-degree.
-   * @param {VertexKey | VO} vertexOrKey - The parameter `vertexOrKey` can be either a `VertexKey` or a `VO`.
-   * @returns The sum of the out-degree and in-degree of the specified vertex or vertex ID.
+   * Degree (in + out) of a vertex.
+   * @param vertexOrKey - Vertex or key.
+   * @returns Non-negative integer.
+   * @remarks Time O(1) avg, Space O(1)
    */
   degreeOf(vertexOrKey: VertexKey | VO): number {
+    /**
+     * In-degree of a vertex.
+     * @param vertexOrKey - Vertex or key.
+     * @returns Non-negative integer.
+     * @remarks Time O(1) avg, Space O(1)
+     */
+    /**
+     * Out-degree of a vertex.
+     * @param vertexOrKey - Vertex or key.
+     * @returns Non-negative integer.
+     * @remarks Time O(1) avg, Space O(1)
+     */
     return this.outDegreeOf(vertexOrKey) + this.inDegreeOf(vertexOrKey);
   }
 
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The function "inDegreeOf" returns the number of incoming edgeMap for a given vertex.
-   * @param {VertexKey | VO} vertexOrKey - The parameter `vertexOrKey` can be either a `VertexKey` or a `VO`.
-   * @returns The number of incoming edgeMap of the specified vertex or vertex ID.
-   */
   inDegreeOf(vertexOrKey: VertexKey | VO): number {
     return this.incomingEdgesOf(vertexOrKey).length;
   }
 
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The function `outDegreeOf` returns the number of outgoing edgeMap from a given vertex.
-   * @param {VertexKey | VO} vertexOrKey - The parameter `vertexOrKey` can be either a `VertexKey` or a `VO`.
-   * @returns The number of outgoing edgeMap from the specified vertex or vertex ID.
-   */
   outDegreeOf(vertexOrKey: VertexKey | VO): number {
     return this.outgoingEdgesOf(vertexOrKey).length;
   }
 
   /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The function "edgesOf" returns an array of both outgoing and incoming edgeMap of a given vertex or vertex ID.
-   * @param {VertexKey | VO} vertexOrKey - The parameter `vertexOrKey` can be either a `VertexKey` or a `VO`.
-   * @returns The function `edgesOf` returns an array of edgeMap.
+   * All incident edges of a vertex.
+   * @param vertexOrKey - Vertex or key.
+   * @returns Array of incident edges.
+   * @remarks Time O(deg_in + deg_out), Space O(deg_in + deg_out)
    */
   edgesOf(vertexOrKey: VertexKey | VO): EO[] {
     return [...this.outgoingEdgesOf(vertexOrKey), ...this.incomingEdgesOf(vertexOrKey)];
   }
 
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The function "getEdgeSrc" returns the source vertex of an edge, or undefined if the edge does not exist.
-   * @param {EO} e - The parameter "e" is of type EO, which represents an edge in a graph.
-   * @returns either a vertex object (VO) or undefined.
-   */
   getEdgeSrc(e: EO): VO | undefined {
     return this._getVertex(e.src);
   }
 
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The function "getEdgeDest" returns the destination vertex of an edge.
-   * @param {EO} e - The parameter "e" is of type "EO", which represents an edge in a graph.
-   * @returns either a vertex object of type VO or undefined.
-   */
   getEdgeDest(e: EO): VO | undefined {
     return this._getVertex(e.dest);
   }
 
   /**
-   * Time Complexity: O(|E|) where |E| is the number of edgeMap
-   * Space Complexity: O(1)
-   *
-   * The function `getDestinations` returns an array of destination vertexMap connected to a given vertex.
-   * @param {VO | VertexKey | undefined} vertex - The `vertex` parameter represents the starting vertex from which we want to
-   * find the destinations. It can be either a `VO` object, a `VertexKey` value, or `undefined`.
-   * @returns an array of vertexMap (VO[]).
+   * Direct children reachable by one outgoing edge.
+   * @param vertex - Vertex or key.
+   * @returns Array of neighbor vertices.
+   * @remarks Time O(deg_out), Space O(deg_out)
    */
   getDestinations(vertex: VO | VertexKey | undefined): VO[] {
     if (vertex === undefined) {
@@ -401,20 +359,14 @@ export class DirectedGraph<
   }
 
   /**
-   * Time Complexity: O(|V| + |E|) where |V| is the number of vertexMap and |E| is the number of edgeMap
-   * Space Complexity: O(|V|)
-   *
-   * The `topologicalSort` function performs a topological sort on a graph and returns an array of vertexMap or vertex IDs
-   * in the sorted order, or undefined if the graph contains a cycle.
-   * @param {'vertex' | 'key'} [propertyName] - The `propertyName` parameter is an optional parameter that specifies the
-   * property to use for sorting the vertexMap. It can have two possible values: 'vertex' or 'key'. If 'vertex' is
-   * specified, the vertexMap themselves will be used for sorting. If 'key' is specified, the ids of
-   * @returns an array of vertexMap or vertex IDs in topological order. If there is a cycle in the graph, it returns undefined.
+   * Topological sort if DAG; returns `undefined` if a cycle exists.
+   * @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)
    */
   topologicalSort(propertyName?: 'vertex' | 'key'): Array<VO | VertexKey> | undefined {
     propertyName = propertyName ?? 'key';
-    // 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<VO | VertexKey, TopologicalStatus> = new Map<VO | VertexKey, TopologicalStatus>();
     for (const entry of this.vertexMap) {
       statusMap.set(entry[1], 0);
@@ -449,13 +401,6 @@ export class DirectedGraph<
     return sorted.reverse();
   }
 
-  /**
-   * Time Complexity: O(|E|) where |E| is the number of edgeMap
-   * Space Complexity: O(|E|)
-   *
-   * The `edgeSet` function returns an array of all the edgeMap in the graph.
-   * @returns The `edgeSet()` method returns an array of edgeMap (`EO[]`).
-   */
   edgeSet(): EO[] {
     let edgeMap: EO[] = [];
     this._outEdgeMap.forEach(outEdges => {
@@ -464,15 +409,6 @@ export class DirectedGraph<
     return edgeMap;
   }
 
-  /**
-   * Time Complexity: O(|E|) where |E| is the number of edgeMap
-   * Space Complexity: O(1)
-   *
-   * The function `getNeighbors` returns an array of neighboring vertexMap of a given vertex or vertex ID in a graph.
-   * @param {VO | VertexKey} vertexOrKey - The parameter `vertexOrKey` can be either a vertex object (`VO`) or a vertex ID
-   * (`VertexKey`).
-   * @returns an array of vertexMap (VO[]).
-   */
   getNeighbors(vertexOrKey: VO | VertexKey): VO[] {
     const neighbors: VO[] = [];
     const vertex = this._getVertex(vertexOrKey);
@@ -480,7 +416,7 @@ export class DirectedGraph<
       const outEdges = this.outgoingEdgesOf(vertex);
       for (const outEdge of outEdges) {
         const neighbor = this._getVertex(outEdge.dest);
-        // TODO after no-non-undefined-assertion not ensure the logic
+
         if (neighbor) {
           neighbors.push(neighbor);
         }
@@ -490,14 +426,10 @@ export class DirectedGraph<
   }
 
   /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The function "getEndsOfEdge" returns the source and destination vertexMap of an edge if it exists in the graph,
-   * otherwise it returns undefined.
-   * @param {EO} edge - The parameter `edge` is of type `EO`, which represents an edge in a graph.
-   * @returns The function `getEndsOfEdge` returns an array containing two vertexMap `[VO, VO]` if the edge exists in the
-   * graph. If the edge does not exist, it returns `undefined`.
+   * Resolve an edge's `[src, dest]` endpoints to vertex instances.
+   * @param edge - Edge instance.
+   * @returns `[src, dest]` or `undefined` if either endpoint is missing.
+   * @remarks Time O(1), Space O(1)
    */
   getEndsOfEdge(edge: EO): [VO, VO] | undefined {
     if (!this.hasEdge(edge.src, edge.dest)) {
@@ -513,19 +445,16 @@ export class DirectedGraph<
   }
 
   /**
-   * The isEmpty function checks if the graph is empty.
-   *
-   * @return A boolean value
+   * Whether the graph has no vertices and no edges.
+   * @remarks Time O(1), Space O(1)
    */
   isEmpty(): boolean {
     return this.vertexMap.size === 0 && this.inEdgeMap.size === 0 && this.outEdgeMap.size === 0;
   }
 
   /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The clear function resets the vertex map, in-edge map, and out-edge map.
+   * Remove all vertices and edges.
+   * @remarks Time O(V + E), Space O(1)
    */
   clear() {
     this._vertexMap = new Map<VertexKey, VO>();
@@ -534,28 +463,18 @@ export class DirectedGraph<
   }
 
   /**
-   * The clone function creates a new DirectedGraph object with the same vertices and edges as the original.
-   *
-   * @return A new instance of the directedgraph class
+   * Deep clone as the same concrete class.
+   * @returns A new graph of the same concrete class (`this` type).
+   * @remarks Time O(V + E), Space O(V + E)
    */
-  clone(): DirectedGraph<V, E, VO, EO> {
-    const cloned = new DirectedGraph<V, E, VO, EO>();
-    cloned.vertexMap = new Map<VertexKey, VO>(this.vertexMap);
-    cloned.inEdgeMap = new Map<VO, EO[]>(this.inEdgeMap);
-    cloned.outEdgeMap = new Map<VO, EO[]>(this.outEdgeMap);
-    return cloned;
+  override clone(): this {
+    return super.clone();
   }
 
   /**
-   *  Time Complexity: O(V + E)
-   *  Space Complexity: O(V)
-   *  Tarjan is an algorithm based on dfs,which is used to solve the connectivity problem of graphs.
-   *  Tarjan can find the SSC(strongly connected components), articulation points, and bridges of directed graphs.
-   *
-   * The function `tarjan` implements the Tarjan's algorithm to find strongly connected components in a
-   * graph.
-   * @returns The function `tarjan()` returns an object with three properties: `dfnMap`, `lowMap`, and
-   * `SCCs`.
+   * Tarjan's algorithm for strongly connected components.
+   * @returns `{ dfnMap, lowMap, SCCs }`.
+   * @remarks Time O(V + E), Space O(V + E)
    */
   tarjan(): { dfnMap: Map<VO, number>; lowMap: Map<VO, number>; SCCs: Map<number, VO[]> } {
     const dfnMap = new Map<VO, number>();
@@ -609,45 +528,37 @@ export class DirectedGraph<
   }
 
   /**
-   * Time Complexity: O(V + E) - Depends on the implementation (Tarjan's algorithm).
-   * Space Complexity: O(V) - Depends on the implementation (Tarjan's algorithm).
-   *
-   * The function returns a map that associates each vertex object with its corresponding depth-first
-   * number.
-   * @returns A Map object with keys of type VO and values of type number.
+   * DFN index map computed by `tarjan()`.
+   * @returns Map from vertex to DFN index.
+   * @remarks Time O(V), Space O(V)
    */
   getDFNMap(): Map<VO, number> {
     return this.tarjan().dfnMap;
   }
 
   /**
-   * The function returns a Map object that contains the low values of each vertex in a Tarjan
-   * algorithm.
-   * @returns The method `getLowMap()` is returning a `Map` object with keys of type `VO` and values of
-   * type `number`.
+   * LOW link map computed by `tarjan()`.
+   * @returns Map from vertex to LOW value.
+   * @remarks Time O(V), Space O(V)
    */
   getLowMap(): Map<VO, number> {
     return this.tarjan().lowMap;
   }
 
   /**
-   * The function "getSCCs" returns a map of strongly connected components (SCCs) using the Tarjan
-   * algorithm.
-   * @returns a map where the keys are numbers and the values are arrays of VO objects.
+   * Strongly connected components computed by `tarjan()`.
+   * @returns Map from SCC id to vertices.
+   * @remarks Time O(#SCC + V), Space O(V)
    */
   getSCCs(): Map<number, VO[]> {
     return this.tarjan().SCCs;
   }
 
   /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The function `_addEdge` adds an edge to a graph if the source and destination vertexMap exist.
-   * @param {EO} edge - The parameter `edge` is of type `EO`, which represents an edge in a graph. It is the edge that
-   * needs to be added to the graph.
-   * @returns a boolean value. It returns true if the edge was successfully added to the graph, and false if either the
-   * source or destination vertex does not exist in the graph.
+   * Internal hook to attach a directed edge into adjacency maps.
+   * @param edge - Edge instance.
+   * @returns `true` if inserted; otherwise `false`.
+   * @remarks Time O(1) avg, Space O(1)
    */
   protected _addEdge(edge: EO): boolean {
     if (!(this.hasVertex(edge.src) && this.hasVertex(edge.dest))) {
@@ -657,7 +568,6 @@ export class DirectedGraph<
     const srcVertex = this._getVertex(edge.src);
     const destVertex = this._getVertex(edge.dest);
 
-    // TODO after no-non-undefined-assertion not ensure the logic
     if (srcVertex && destVertex) {
       const srcOutEdges = this._outEdgeMap.get(srcVertex);
       if (srcOutEdges) {