priority-queue-typed 2.0.5 → 2.1.0

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

@@ -1,3 +1,11 @@
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+
 import type { MapGraphCoordinate, VertexKey } from '../../types';
 import { DirectedEdge, DirectedGraph, DirectedVertex } from './directed-graph';
 
@@ -5,18 +13,6 @@ export class MapVertex<V = any> extends DirectedVertex<V> {
   lat: number;
   long: number;
 
-  /**
-   * The constructor function initializes an object with an key, latitude, longitude, and an optional value.
-   * @param {VertexKey} key - The `key` parameter is of type `VertexKey` and represents the identifier of the vertex.
-   * @param {number} lat - The "lat" parameter represents the latitude of a vertex. Latitude is a geographic coordinate
-   * that specifies the north-south position of a point on the Earth's surface. It is measured in degrees, with positive
-   * values representing points north of the equator and negative values representing points south of the equator.
-   * @param {number} long - The "long" parameter represents the longitude of a location. Longitude is a geographic
-   * coordinate that specifies the east-west position of a point on the Earth's surface. It is measured in degrees, with
-   * values ranging from -180 to 180.
-   * @param {V} [value] - The "value" parameter is an optional value of type V. It is not required to be provided when
-   * creating an instance of the class.
-   */
   constructor(key: VertexKey, value: V, lat: number, long: number) {
     super(key, value);
     this.lat = lat;
@@ -25,23 +21,19 @@ export class MapVertex<V = any> extends DirectedVertex<V> {
 }
 
 export class MapEdge<E = any> extends DirectedEdge<E> {
-  /**
-   * The constructor function initializes a new instance of a class with the given source, destination, 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 is the identifier of the destination vertex for an edge.
-   * @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 is used to store additional
-   * information or data associated with the edge.
-   */
   constructor(src: VertexKey, dest: VertexKey, weight?: number, value?: E) {
     super(src, dest, weight, value);
   }
 }
 
 /**
- *
+ * Directed graph variant carrying geospatial coordinates.
+ * @template V - Vertex value type.
+ * @template E - Edge value type.
+ * @template VO - Concrete vertex class (MapVertex<V>).
+ * @template EO - Concrete edge class (MapEdge<E>).
+ * @remarks Time O(1), Space O(1)
+ * @example examples will be generated by unit test
  */
 export class MapGraph<
   V = any,
@@ -50,13 +42,10 @@ export class MapGraph<
   EO extends MapEdge<E> = MapEdge<E>
 > extends DirectedGraph<V, E, VO, EO> {
   /**
-   * The constructor function initializes the originCoord and bottomRight properties of a MapGraphCoordinate object.
-   * @param {MapGraphCoordinate} originCoord - The `originCoord` parameter is a `MapGraphCoordinate` object that represents the
-   * starting point or reference point of the map graph. It defines the coordinates of the top-left corner of the map
-   * graph.
-   * @param {MapGraphCoordinate} [bottomRight] - The `bottomRight` parameter is an optional parameter of type
-   * `MapGraphCoordinate`. It represents the bottom right coordinate of a map graph. If this parameter is not provided,
-   * it will default to `undefined`.
+   * Construct a MapGraph.
+   * @param originCoord - Origin coordinate `[lat, long]` used as default.
+   * @param bottomRight - Optional bottom-right coordinate for bounding boxes.
+   * @remarks Time O(1), Space O(1)
    */
   constructor(originCoord: MapGraphCoordinate, bottomRight?: MapGraphCoordinate) {
     super();
@@ -77,15 +66,13 @@ export class MapGraph<
   }
 
   /**
-   * The function creates a new vertex with the given key, value, latitude, and longitude.
-   * @param {VertexKey} key - The key parameter is the unique identifier for the vertex. It is of type VertexKey, which could
-   * be a string or a number depending on how you define it in your code.
-   * @param [value] - The `value` parameter is an optional value that can be assigned to the `value` property of the vertex. It
-   * is of type `V`, which means it should be of the same type as the `value` property of the vertex class `VO`.
-   * @param {number} lat - The `lat` parameter represents the latitude of the vertex. It is a number that specifies the
-   * position of the vertex on the Earth's surface in the north-south direction.
-   * @param {number} long - The `long` parameter represents the longitude coordinate of the vertex.
-   * @returns The method is returning a new instance of the `MapVertex` class, casted as type `VO`.
+   * Create a map vertex with optional coordinates.
+   * @param key - Vertex identifier.
+   * @param value - Optional payload.
+   * @param lat - Latitude (defaults to `originCoord[0]`).
+   * @param long - Longitude (defaults to `originCoord[1]`).
+   * @returns MapVertex instance.
+   * @remarks Time O(1), Space O(1)
    */
   override createVertex(
     key: VertexKey,
@@ -97,33 +84,49 @@ export class MapGraph<
   }
 
   /**
-   * The function creates a new instance of a MapEdge with the given source, destination, 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 being
-   * created.
-   * @param {number} [weight] - The `weight` parameter is an optional number that represents the weight of the edge. It
-   * is used to assign a numerical value to the edge, which can be used in algorithms such as shortest path algorithms.
-   * If the weight is not provided, it can be set to a default value or left undefined.
-   * @param [value] - The `value` parameter is an optional value that can be assigned to the edge. It can be of any type,
-   * depending on the specific implementation of the `MapEdge` class.
-   * @returns a new instance of the `MapEdge` class, cast as type `EO`.
+   * Create a map edge (directed) with optional weight/value.
+   * @param src - Source key.
+   * @param dest - Destination key.
+   * @param weight - Edge weight.
+   * @param value - Edge payload.
+   * @returns MapEdge instance.
+   * @remarks Time O(1), Space O(1)
    */
   override createEdge(src: VertexKey, dest: VertexKey, weight?: number, value?: E): EO {
     return new MapEdge(src, dest, weight, value) as EO;
   }
 
   /**
-   * The override function is used to override the default behavior of a function.
-   * In this case, we are overriding the clone() function from Graph&lt;V, E&gt;.
-   * The clone() function returns a new graph that is an exact copy of the original graph.
-   *
-   * @return A mapgraph&lt;v, e, vo, eo&gt;
+   * 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)
+   */
+  override clone(): this {
+    return super.clone();
+  }
+
+  /**
+   * Include `originCoord` and `bottomRight` so `clone()/filter()` preserve geospatial settings.
+   * @returns Options bag extending super snapshot.
+   * @remarks Time O(1), Space O(1)
+   */
+  protected override _snapshotOptions(): Record<string, unknown> {
+    return { ...(super._snapshotOptions() as any), originCoord: this.originCoord, bottomRight: this.bottomRight };
+  }
+
+  /**
+   * Re-create a same-species MapGraph instance from snapshot options.
+   * @param options - Snapshot options providing `originCoord`/`bottomRight`.
+   * @returns Empty MapGraph instance of `this` type.
+   * @remarks Time O(1), Space O(1)
    */
-  override clone(): MapGraph<V, E, VO, EO> {
-    const cloned = new MapGraph<V, E, VO, EO>(this.originCoord, this.bottomRight);
-    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;
+  protected override _createInstance(options?: Partial<Record<string, unknown>>): this {
+    const { originCoord, bottomRight } = (options || {}) as {
+      originCoord?: [number, number];
+      bottomRight?: [number, number] | undefined;
+    };
+    const oc = (originCoord ?? this.originCoord) as [number, number];
+    const br = (bottomRight ?? this.bottomRight) as [number, number] | undefined;
+    return new MapGraph<V, E, VO, EO>(oc, br) as this;
   }
 }

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

@@ -5,19 +5,13 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { VertexKey } from '../../types';
+
+import type { GraphOptions, VertexKey } from '../../types';
 import { IGraph } from '../../interfaces';
 import { AbstractEdge, AbstractGraph, AbstractVertex } from './abstract-graph';
 import { arrayRemove } from '../../utils';
 
 export class UndirectedVertex<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 network.
-   * @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);
   }
@@ -26,16 +20,6 @@ export class UndirectedVertex<V = any> extends AbstractVertex<V> {
 export class UndirectedEdge<E = number> extends AbstractEdge<E> {
   endpoints: [VertexKey, VertexKey];
 
-  /**
-   * The constructor function creates an instance of a class with two vertex IDs, an optional weight, and an optional
-   * value.
-   * @param {VertexKey} v1 - The first vertex ID of the edge.
-   * @param {VertexKey} v2 - The parameter `v2` is a `VertexKey`, which represents the identifier of the second vertex in a
-   * graph edge.
-   * @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 is used to store a value associated
-   * with the edge.
-   */
   constructor(v1: VertexKey, v2: VertexKey, weight?: number, value?: E) {
     super(weight, value);
     this.endpoints = [v1, v2];
@@ -43,7 +27,13 @@ export class UndirectedEdge<E = number> extends AbstractEdge<E> {
 }
 
 /**
- *
+ * Undirected 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 UndirectedGraph<
     V = any,
@@ -55,10 +45,12 @@ export class UndirectedGraph<
   implements IGraph<V, E, VO, EO>
 {
   /**
-   * The constructor initializes a new Map object to store edgeMap.
+   * Construct an undirected 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);
     this._edgeMap = new Map<VO, EO[]>();
   }
 
@@ -73,42 +65,67 @@ export class UndirectedGraph<
   }
 
   /**
-   * 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 used to distinguish one
-   * vertex from another in the graph.
-   * @param [value] - The `value` parameter is an optional value that can be assigned to the vertex. If a value is provided,
-   * it will be used as the value of the vertex. If no value is provided, the `key` parameter will be used as the value of
-   * the vertex.
-   * @returns The method is returning a new instance of the `UndirectedVertex` class, casted as type `VO`.
+   * Construct an undirected graph from keys with value initializer `v => v`.
+   * @template K - Vertex key type.
+   * @param keys - Iterable of vertex keys.
+   * @returns UndirectedGraph with all keys added.
+   * @remarks Time O(V), Space O(V)
    */
-  override createVertex(key: VertexKey, value?: VO['value']): VO {
-    return new UndirectedVertex(key, value ?? key) as VO;
+  static fromKeys<K extends VertexKey>(
+    keys: Iterable<K>
+  ): UndirectedGraph<K, any, UndirectedVertex<K>, UndirectedEdge<any>> {
+    const g: UndirectedGraph<K, any, UndirectedVertex<K>, UndirectedEdge<any>> = new UndirectedGraph<K, any>({
+      vertexValueInitializer: (k: VertexKey) => k as K
+    });
+    for (const k of keys) g.addVertex(k);
+    return g;
   }
 
   /**
-   * The function creates an undirected edge between two vertexMap with an optional weight and value.
-   * @param {VertexKey} v1 - The parameter `v1` represents the first vertex of the edge.
-   * @param {VertexKey} v2 - The parameter `v2` represents the second vertex of 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 the `UndirectedEdge` class, which is casted as type `EO`.
+   * Construct an undirected graph from `[key, value]` entries.
+   * @template V - Vertex value type.
+   * @param entries - Iterable of `[key, value]` pairs.
+   * @returns UndirectedGraph with all vertices added.
+   * @remarks Time O(V), Space O(V)
+   */
+  static fromEntries<V>(
+    entries: Iterable<[VertexKey, V]>
+  ): UndirectedGraph<V, any, UndirectedVertex<V>, UndirectedEdge<any>> {
+    const g: UndirectedGraph<V, any, UndirectedVertex<V>, UndirectedEdge<any>> = new UndirectedGraph<V, any>();
+    for (const [k, v] of entries) g.addVertex(k, v);
+    return g;
+  }
+
+  /**
+   * Create an undirected 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 UndirectedVertex(key, value) as VO;
+  }
+
+  /**
+   * Create an undirected edge instance. Does not insert into the graph.
+   * @param v1 - One endpoint key.
+   * @param v2 - The other endpoint key.
+   * @param weight - Edge weight; defaults to `defaultEdgeWeight`.
+   * @param value - Edge payload.
+   * @returns Concrete edge instance.
+   * @remarks Time O(1), Space O(1)
    */
   override createEdge(v1: VertexKey, v2: VertexKey, weight?: number, value?: EO['value']): EO {
-    return new UndirectedEdge(v1, v2, weight ?? 1, value) as EO;
+    return new UndirectedEdge(v1, v2, weight ?? this.options.defaultEdgeWeight ?? 1, value) as EO;
   }
 
   /**
-   * Time Complexity: O(|E|), where |E| is the number of edgeMap incident to the given vertex.
-   * Space Complexity: O(1)
-   *
-   * The function `getEdge` returns the first edge that connects two endpoints, or undefined if no such edge exists.
-   * @param {VO | VertexKey | undefined} v1 - The parameter `v1` represents a vertex or vertex ID. It can be of type `VO` (vertex
-   * object), `undefined`, or `VertexKey` (a string or number representing the ID of a vertex).
-   * @param {VO | VertexKey | undefined} v2 - The parameter `v2` represents a vertex or vertex ID. It can be of type `VO` (vertex
-   * object), `undefined`, or `VertexKey` (vertex ID).
-   * @returns an edge (EO) or undefined.
+   * Get an undirected edge between two vertices, if present.
+   * @param v1 - One vertex or key.
+   * @param v2 - The other vertex or key.
+   * @returns Edge instance or `undefined`.
+   * @remarks Time O(1) avg, Space O(1)
    */
   getEdge(v1: VO | VertexKey | undefined, v2: VO | VertexKey | undefined): EO | undefined {
     let edgeMap: EO[] | undefined = [];
@@ -126,14 +143,11 @@ export class UndirectedGraph<
   }
 
   /**
-   * Time Complexity: O(|E|), where |E| is the number of edgeMap incident to the given vertex.
-   * Space Complexity: O(1)
-   *
-   * The function removes an edge between two vertexMap in a graph and returns the removed edge.
-   * @param {VO | VertexKey} v1 - The parameter `v1` represents either a vertex object (`VO`) or a vertex ID (`VertexKey`).
-   * @param {VO | VertexKey} v2 - VO | VertexKey - This parameter can be either a vertex object (VO) or a vertex ID
-   * (VertexKey). It represents the second vertex of the edge that needs to be removed.
-   * @returns the removed edge (EO) if it exists, or undefined if either of the endpoints (VO) does not exist.
+   * Delete a single undirected edge between two vertices.
+   * @param v1 - One vertex or key.
+   * @param v2 - The other vertex or key.
+   * @returns Removed edge or `undefined`.
+   * @remarks Time O(1) avg, Space O(1)
    */
   deleteEdgeBetween(v1: VO | VertexKey, v2: VO | VertexKey): EO | undefined {
     const vertex1: VO | undefined = this._getVertex(v1);
@@ -156,17 +170,11 @@ export class UndirectedGraph<
   }
 
   /**
-   * Time Complexity: O(E), where E is the number of edgeMap incident to the given vertex.
-   * Space Complexity: O(1)
-   *
-   * The function `deleteEdge` deletes an edge between two endpoints in a graph.
-   * @param {EO | VertexKey} edgeOrOneSideVertexKey - The parameter `edgeOrOneSideVertexKey` can be
-   * either an edge object or a vertex key.
-   * @param {VertexKey} [otherSideVertexKey] - The parameter `otherSideVertexKey` is an optional
-   * parameter that represents the key of the vertex on the other side of the edge. It is used when the
-   * `edgeOrOneSideVertexKey` parameter is a vertex key, and it specifies the key of the vertex on the
-   * other side of the
-   * @returns The `deleteEdge` function returns either the deleted edge object (EO) or `undefined`.
+   * Delete an edge by instance or by a pair of keys.
+   * @param edgeOrOneSideVertexKey - Edge instance or one endpoint vertex/key.
+   * @param otherSideVertexKey - Required second endpoint when deleting by pair.
+   * @returns Removed edge or `undefined`.
+   * @remarks Time O(1) avg, Space O(1)
    */
   deleteEdge(edgeOrOneSideVertexKey: EO | VertexKey, otherSideVertexKey?: VertexKey): EO | undefined {
     let oneSide: VO | undefined, otherSide: VO | undefined;
@@ -190,13 +198,10 @@ export class UndirectedGraph<
   }
 
   /**
-   * 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.
+   * Delete a vertex and remove it from all neighbor lists.
+   * @param vertexOrKey - Vertex or key.
+   * @returns `true` if removed; otherwise `false`.
+   * @remarks Time O(deg), Space O(1)
    */
   deleteVertex(vertexOrKey: VO | VertexKey): boolean {
     let vertexKey: VertexKey;
@@ -209,6 +214,12 @@ export class UndirectedGraph<
       vertexKey = this._getVertexKey(vertexOrKey);
     }
 
+    /**
+     * All neighbors connected via undirected edges.
+     * @param vertexOrKey - Vertex or key.
+     * @returns Array of neighbor vertices.
+     * @remarks Time O(deg), Space O(deg)
+     */
     const neighbors = this.getNeighbors(vertexOrKey);
 
     if (vertex) {
@@ -228,14 +239,10 @@ export class UndirectedGraph<
   }
 
   /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The function `degreeOf` returns the degree of a vertex in a graph, which is the number of edgeMap connected to that
-   * vertex.
-   * @param {VertexKey | VO} vertexOrKey - The parameter `vertexOrKey` can be either a `VertexKey` or a `VO`.
-   * @returns The function `degreeOf` returns the degree of a vertex in a graph. The degree of a vertex is the number of
-   * edgeMap connected to that vertex.
+   * Degree of a vertex (# of incident undirected edges).
+   * @param vertexOrKey - Vertex or key.
+   * @returns Non-negative integer.
+   * @remarks Time O(1) avg, Space O(1)
    */
   degreeOf(vertexOrKey: VertexKey | VO): number {
     const vertex = this._getVertex(vertexOrKey);
@@ -247,13 +254,10 @@ export class UndirectedGraph<
   }
 
   /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The function returns the edgeMap of a given vertex or vertex ID.
-   * @param {VertexKey | VO} vertexOrKey - The parameter `vertexOrKey` can be either a `VertexKey` or a `VO`. A `VertexKey` is a
-   * unique identifier for a vertex in a graph, while `VO` represents the type of the vertex.
-   * @returns an array of edgeMap.
+   * Incident undirected edges of a vertex.
+   * @param vertexOrKey - Vertex or key.
+   * @returns Array of incident edges.
+   * @remarks Time O(deg), Space O(deg)
    */
   edgesOf(vertexOrKey: VertexKey | VO): EO[] {
     const vertex = this._getVertex(vertexOrKey);
@@ -265,11 +269,9 @@ export class UndirectedGraph<
   }
 
   /**
-   * Time Complexity: O(|V| + |E|), where |V| is the number of vertexMap and |E| is the number of edgeMap.
-   * Space Complexity: O(|E|)
-   *
-   * The function "edgeSet" returns an array of unique edgeMap from a set of edgeMap.
-   * @returns The method `edgeSet()` returns an array of type `EO[]`.
+   * Unique set of undirected edges across endpoints.
+   * @returns Array of edges.
+   * @remarks Time O(E), Space O(E)
    */
   edgeSet(): EO[] {
     const edgeSet: Set<EO> = new Set();
@@ -281,15 +283,6 @@ export class UndirectedGraph<
     return [...edgeSet];
   }
 
-  /**
-   * Time Complexity: O(|V| + |E|), where |V| is the number of vertexMap and |E| is the number of edgeMap.
-   * Space Complexity: O(|E|)
-   *
-   * The function "getNeighbors" returns an array of neighboring endpoints 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 an array of vertexMap (VO[]).
-   */
   getNeighbors(vertexOrKey: VO | VertexKey): VO[] {
     const neighbors: VO[] = [];
     const vertex = this._getVertex(vertexOrKey);
@@ -306,14 +299,10 @@ export class UndirectedGraph<
   }
 
   /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The function "getEndsOfEdge" returns the endpoints at the ends of an edge if the edge 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 endpoints `[VO, VO]` if the edge exists in the
-   * graph. If the edge does not exist, it returns `undefined`.
+   * Resolve an edge's two endpoints to vertex instances.
+   * @param edge - Edge instance.
+   * @returns `[v1, v2]` or `undefined` if either endpoint is missing.
+   * @remarks Time O(1), Space O(1)
    */
   getEndsOfEdge(edge: EO): [VO, VO] | undefined {
     if (!this.hasEdge(edge.endpoints[0], edge.endpoints[1])) {
@@ -329,18 +318,16 @@ export class UndirectedGraph<
   }
 
   /**
-   * The isEmpty function checks if the graph is empty.
-   * @return True if the graph is empty and false otherwise
+   * Whether the graph has no vertices and no edges.
+   * @remarks Time O(1), Space O(1)
    */
   isEmpty(): boolean {
     return this.vertexMap.size === 0 && this.edgeMap.size === 0;
   }
 
   /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The clear function resets the vertex and edge maps to empty maps.
+   * Remove all vertices and edges.
+   * @remarks Time O(V + E), Space O(1)
    */
   clear() {
     this._vertexMap = new Map<VertexKey, VO>();
@@ -348,30 +335,18 @@ export class UndirectedGraph<
   }
 
   /**
-   * The clone function creates a new UndirectedGraph object and copies the
-   * vertexMap and edgeMap from this graph to the new one. This is done by
-   * assigning each of these properties to their respective counterparts in the
-   * cloned graph. The clone function returns a reference to this newly created,
-   * cloned UndirectedGraph object.
-   *
-   * @return A new instance of the undirectedgraph 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(): UndirectedGraph<V, E, VO, EO> {
-    const cloned = new UndirectedGraph<V, E, VO, EO>();
-    cloned.vertexMap = new Map<VertexKey, VO>(this.vertexMap);
-    cloned.edgeMap = new Map<VO, EO[]>(this.edgeMap);
-    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.
-   *  1. Tarjan can find the articulation points and bridges(critical edgeMap) of undirected graphs in linear time
-   *
-   * The function `tarjan` implements the Tarjan's algorithm to find bridges and cut vertices in a
-   * graph.
-   * @returns The function `tarjan()` returns an object with the following properties:
+   * Tarjan-based bridge and articulation point detection.
+   * @returns `{ dfnMap, lowMap, bridges, cutVertices }`.
+   * @remarks Time O(V + E), Space O(V + E)
    */
   tarjan(): { dfnMap: Map<VO, number>; lowMap: Map<VO, number>; bridges: EO[]; cutVertices: VO[] } {
     const dfnMap = new Map<VO, number>();
@@ -433,44 +408,46 @@ export class UndirectedGraph<
   }
 
   /**
-   * The function "getBridges" returns an array of bridges in a graph using the Tarjan's algorithm.
-   * @returns The function `getBridges()` is returning the bridges found using the Tarjan's algorithm.
+   * Get bridges discovered by `tarjan()`.
+   * @returns Array of edges that are bridges.
+   * @remarks Time O(B), Space O(1)
    */
   getBridges() {
     return this.tarjan().bridges;
   }
 
   /**
-   * The function "getCutVertices" returns an array of cut vertices using the Tarjan's algorithm.
-   * @returns the cut vertices found using the Tarjan's algorithm.
+   * Get articulation points discovered by `tarjan()`.
+   * @returns Array of cut vertices.
+   * @remarks Time O(C), Space O(1)
    */
   getCutVertices() {
     return this.tarjan().cutVertices;
   }
 
   /**
-   * The function returns the dfnMap property of the result of the tarjan() function.
-   * @returns the `dfnMap` property of the result of calling the `tarjan()` function.
+   * 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 the lowMap property of the result of the tarjan() function.
-   * @returns the lowMap property of the result of calling the tarjan() function.
+   * 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;
   }
 
   /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The function adds an edge to the graph by updating the adjacency list with the vertexMap of the edge.
-   * @param {EO} edge - The parameter "edge" is of type EO, which represents an edge in a graph.
-   * @returns a boolean value.
+   * Internal hook to attach an undirected edge into adjacency maps.
+   * @param edge - Edge instance.
+   * @returns `true` if both endpoints exist; otherwise `false`.
+   * @remarks Time O(1) avg, Space O(1)
    */
   protected _addEdge(edge: EO): boolean {
     for (const end of edge.endpoints) {