stack-typed 2.0.4 → 2.1.0

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

@@ -1,32 +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.UndirectedGraph = exports.UndirectedEdge = exports.UndirectedVertex = void 0;
 const abstract_graph_1 = require("./abstract-graph");
 const utils_1 = require("../../utils");
 class UndirectedVertex 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 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, value) {
         super(key, value);
     }
 }
 exports.UndirectedVertex = UndirectedVertex;
 class UndirectedEdge extends abstract_graph_1.AbstractEdge {
-    /**
-     * 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, v2, weight, value) {
         super(weight, value);
         this.endpoints = [v1, v2];
@@ -34,14 +24,22 @@ class UndirectedEdge extends abstract_graph_1.AbstractEdge {
 }
 exports.UndirectedEdge = UndirectedEdge;
 /**
- *
+ * 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
  */
 class UndirectedGraph extends abstract_graph_1.AbstractGraph {
     /**
-     * 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) {
+        super(options);
         this._edgeMap = new Map();
     }
     get edgeMap() {
@@ -51,40 +49,62 @@ class UndirectedGraph extends abstract_graph_1.AbstractGraph {
         this._edgeMap = 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 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)
+     */
+    static fromKeys(keys) {
+        const g = new UndirectedGraph({
+            vertexValueInitializer: (k) => k
+        });
+        for (const k of keys)
+            g.addVertex(k);
+        return g;
+    }
+    /**
+     * 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(entries) {
+        const g = new UndirectedGraph();
+        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, value) {
-        return new UndirectedVertex(key, value !== null && value !== void 0 ? value : key);
+        return new UndirectedVertex(key, value);
     }
     /**
-     * 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`.
+     * 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)
      */
     createEdge(v1, v2, weight, value) {
-        return new UndirectedEdge(v1, v2, weight !== null && weight !== void 0 ? weight : 1, value);
+        var _a;
+        return new UndirectedEdge(v1, v2, (_a = weight !== null && weight !== void 0 ? weight : this.options.defaultEdgeWeight) !== null && _a !== void 0 ? _a : 1, value);
     }
     /**
-     * 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, v2) {
         var _a;
@@ -99,14 +119,11 @@ class UndirectedGraph extends abstract_graph_1.AbstractGraph {
         return edgeMap ? edgeMap[0] || undefined : undefined;
     }
     /**
-     * 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, v2) {
         const vertex1 = this._getVertex(v1);
@@ -126,17 +143,11 @@ class UndirectedGraph extends abstract_graph_1.AbstractGraph {
         return removed;
     }
     /**
-     * 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, otherSideVertexKey) {
         let oneSide, otherSide;
@@ -161,13 +172,10 @@ class UndirectedGraph extends abstract_graph_1.AbstractGraph {
         }
     }
     /**
-     * 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) {
         let vertexKey;
@@ -180,6 +188,12 @@ class UndirectedGraph extends abstract_graph_1.AbstractGraph {
             vertex = vertexOrKey;
             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) {
             neighbors.forEach(neighbor => {
@@ -196,14 +210,10 @@ class UndirectedGraph extends abstract_graph_1.AbstractGraph {
         return this._vertexMap.delete(vertexKey);
     }
     /**
-     * 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) {
         var _a;
@@ -216,13 +226,10 @@ class UndirectedGraph extends abstract_graph_1.AbstractGraph {
         }
     }
     /**
-     * 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) {
         const vertex = this._getVertex(vertexOrKey);
@@ -234,11 +241,9 @@ class UndirectedGraph extends abstract_graph_1.AbstractGraph {
         }
     }
     /**
-     * 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() {
         const edgeSet = new Set();
@@ -249,15 +254,6 @@ class UndirectedGraph extends abstract_graph_1.AbstractGraph {
         });
         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) {
         const neighbors = [];
         const vertex = this._getVertex(vertexOrKey);
@@ -273,14 +269,10 @@ class UndirectedGraph extends abstract_graph_1.AbstractGraph {
         return neighbors;
     }
     /**
-     * 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) {
         if (!this.hasEdge(edge.endpoints[0], edge.endpoints[1])) {
@@ -296,46 +288,32 @@ class UndirectedGraph extends abstract_graph_1.AbstractGraph {
         }
     }
     /**
-     * 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() {
         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();
         this._edgeMap = new Map();
     }
     /**
-     * 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() {
-        const cloned = new UndirectedGraph();
-        cloned.vertexMap = new Map(this.vertexMap);
-        cloned.edgeMap = new Map(this.edgeMap);
-        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.
-     *  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() {
         const dfnMap = new Map();
@@ -388,40 +366,42 @@ class UndirectedGraph extends abstract_graph_1.AbstractGraph {
         };
     }
     /**
-     * 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)
      */
     _addEdge(edge) {
         for (const end of edge.endpoints) {