queue-typed 2.0.4 → 2.1.0

package/dist/data-structures/graph/directed-graph.js

@@ -1,33 +1,22 @@
 "use strict";
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DirectedGraph = exports.DirectedEdge = exports.DirectedVertex = void 0;
 const abstract_graph_1 = require("./abstract-graph");
 const utils_1 = require("../../utils");
 class DirectedVertex extends abstract_graph_1.AbstractVertex {
-    /**
-     * 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, value) {
         super(key, value);
     }
 }
 exports.DirectedVertex = DirectedVertex;
 class DirectedEdge extends abstract_graph_1.AbstractEdge {
-    /**
-     * 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, dest, weight, value) {
         super(weight, value);
         this.src = src;
@@ -36,14 +25,22 @@ class DirectedEdge extends abstract_graph_1.AbstractEdge {
 }
 exports.DirectedEdge = DirectedEdge;
 /**
- *
+ * 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
  */
 class DirectedGraph extends abstract_graph_1.AbstractGraph {
     /**
-     * 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) {
+        super(options);
         this._outEdgeMap = new Map();
         this._inEdgeMap = new Map();
     }
@@ -60,40 +57,62 @@ class DirectedGraph extends abstract_graph_1.AbstractGraph {
         this._inEdgeMap = v;
     }
     /**
-     * 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)
+     */
+    static fromKeys(keys) {
+        const g = new DirectedGraph({
+            vertexValueInitializer: (k) => 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(entries) {
+        const g = new DirectedGraph();
+        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, value) {
         return new DirectedVertex(key, value);
     }
     /**
-     * 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, dest, weight, value) {
-        return new DirectedEdge(src, dest, weight !== null && weight !== void 0 ? weight : 1, value);
+        var _a;
+        return new DirectedEdge(src, dest, (_a = weight !== null && weight !== void 0 ? weight : this.options.defaultEdgeWeight) !== null && _a !== void 0 ? _a : 1, value);
     }
     /**
-     * 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, destOrKey) {
         let edgeMap = [];
@@ -110,13 +129,11 @@ class DirectedGraph extends abstract_graph_1.AbstractGraph {
         return edgeMap[0] || undefined;
     }
     /**
-     * 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, destOrKey) {
         const src = this._getVertex(srcOrKey);
@@ -136,17 +153,11 @@ class DirectedGraph extends abstract_graph_1.AbstractGraph {
         return removed;
     }
     /**
-     * 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, destVertexKey) {
         let removed = undefined;
@@ -176,15 +187,6 @@ class DirectedGraph extends abstract_graph_1.AbstractGraph {
         }
         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) {
         let vertexKey;
         let vertex;
@@ -197,9 +199,14 @@ class DirectedGraph extends abstract_graph_1.AbstractGraph {
             vertexKey = this._getVertexKey(vertexOrKey);
         }
         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);
@@ -207,17 +214,6 @@ class DirectedGraph extends abstract_graph_1.AbstractGraph {
         }
         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, v2) {
         const removed = [];
         if (v1 && v2) {
@@ -231,13 +227,10 @@ class DirectedGraph extends abstract_graph_1.AbstractGraph {
         return removed;
     }
     /**
-     * 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) {
         const target = this._getVertex(vertexOrKey);
@@ -247,13 +240,10 @@ class DirectedGraph extends abstract_graph_1.AbstractGraph {
         return [];
     }
     /**
-     * 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) {
         const target = this._getVertex(vertexOrKey);
@@ -263,79 +253,52 @@ class DirectedGraph extends abstract_graph_1.AbstractGraph {
         return [];
     }
     /**
-     * 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) {
+        /**
+         * 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) {
         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) {
         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) {
         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) {
         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) {
         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) {
         if (vertex === undefined) {
@@ -352,20 +315,13 @@ class DirectedGraph extends abstract_graph_1.AbstractGraph {
         return destinations;
     }
     /**
-     * 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) {
         propertyName = propertyName !== null && propertyName !== void 0 ? 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 = new Map();
         for (const entry of this.vertexMap) {
             statusMap.set(entry[1], 0);
@@ -398,13 +354,6 @@ class DirectedGraph extends abstract_graph_1.AbstractGraph {
             sorted = sorted.map(vertex => (vertex instanceof DirectedVertex ? vertex.key : vertex));
         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() {
         let edgeMap = [];
         this._outEdgeMap.forEach(outEdges => {
@@ -412,15 +361,6 @@ class DirectedGraph extends abstract_graph_1.AbstractGraph {
         });
         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) {
         const neighbors = [];
         const vertex = this._getVertex(vertexOrKey);
@@ -428,7 +368,6 @@ class DirectedGraph extends abstract_graph_1.AbstractGraph {
             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);
                 }
@@ -437,14 +376,10 @@ class DirectedGraph extends abstract_graph_1.AbstractGraph {
         return neighbors;
     }
     /**
-     * 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) {
         if (!this.hasEdge(edge.src, edge.dest)) {
@@ -460,18 +395,15 @@ class DirectedGraph extends abstract_graph_1.AbstractGraph {
         }
     }
     /**
-     * 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() {
         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();
@@ -479,27 +411,17 @@ class DirectedGraph extends abstract_graph_1.AbstractGraph {
         this._outEdgeMap = new Map();
     }
     /**
-     * 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() {
-        const cloned = new DirectedGraph();
-        cloned.vertexMap = new Map(this.vertexMap);
-        cloned.inEdgeMap = new Map(this.inEdgeMap);
-        cloned.outEdgeMap = new Map(this.outEdgeMap);
-        return cloned;
+        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() {
         const dfnMap = new Map();
@@ -543,42 +465,34 @@ class DirectedGraph extends abstract_graph_1.AbstractGraph {
         return { dfnMap, lowMap, SCCs };
     }
     /**
-     * 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() {
         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() {
         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() {
         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)
      */
     _addEdge(edge) {
         if (!(this.hasVertex(edge.src) && this.hasVertex(edge.dest))) {
@@ -586,7 +500,6 @@ class DirectedGraph extends abstract_graph_1.AbstractGraph {
         }
         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) {