data-structure-typed 2.0.5 → 2.1.1

package/dist/types/data-structures/graph/abstract-graph.d.ts

@@ -0,0 +1,340 @@
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+import type { DijkstraResult, EntryCallback, GraphOptions, VertexKey } from '../../types';
+import { IterableEntryBase } from '../base';
+import { IGraph } from '../../interfaces';
+export declare abstract class AbstractVertex<V = any> {
+    key: VertexKey;
+    value: V | undefined;
+    protected constructor(key: VertexKey, value?: V);
+}
+export declare abstract class AbstractEdge<E = any> {
+    value: E | undefined;
+    weight: number;
+    protected constructor(weight?: number, value?: E);
+    protected _hashCode: string;
+    get hashCode(): string;
+}
+/**
+ * Abstract graph over vertices and edges.
+ * @template V - Vertex value type.
+ * @template E - Edge value type.
+ * @template VO - Concrete vertex subclass (extends AbstractVertex<V>).
+ * @template EO - Concrete edge subclass (extends AbstractEdge<E>).
+ * @remarks Time O(1), Space O(1)
+ * @example examples will be generated by unit test
+ */
+export declare abstract class AbstractGraph<V = any, E = any, VO extends AbstractVertex<V> = AbstractVertex<V>, EO extends AbstractEdge<E> = AbstractEdge<E>> extends IterableEntryBase<VertexKey, V | undefined> implements IGraph<V, E, VO, EO> {
+    /**
+     * Construct a graph with runtime defaults.
+     * @param options - `GraphOptions<V>` in `options.graph` (e.g. `vertexValueInitializer`, `defaultEdgeWeight`).
+     * @remarks Time O(1), Space O(1)
+     */
+    constructor(options?: Partial<Record<string, unknown>>);
+    protected _options: GraphOptions<V>;
+    get options(): Readonly<GraphOptions<V>>;
+    protected _vertexMap: Map<VertexKey, VO>;
+    get vertexMap(): Map<VertexKey, VO>;
+    set vertexMap(v: Map<VertexKey, VO>);
+    get size(): number;
+    /**
+     * Create a new vertex instance (implementation specific).
+     * @param key - Vertex identifier.
+     * @param value - Optional payload.
+     * @returns Concrete vertex instance.
+     * @remarks Time O(1), Space O(1)
+     */
+    abstract createVertex(key: VertexKey, value?: V): VO;
+    /**
+     * Create a new edge instance (implementation specific).
+     * @param srcOrV1 - Source/endpoint A key.
+     * @param destOrV2 - Destination/endpoint B key.
+     * @param weight - Edge weight (defaults may apply).
+     * @param value - Edge payload.
+     * @returns Concrete edge instance.
+     * @remarks Time O(1), Space O(1)
+     */
+    abstract createEdge(srcOrV1: VertexKey, destOrV2: VertexKey, weight?: number, value?: E): EO;
+    /**
+     * Delete an edge by instance.
+     * @param edge - Edge instance.
+     * @returns Removed edge or `undefined`.
+     * @remarks Time O(1) avg, Space O(1)
+     */
+    abstract deleteEdge(edge: EO): EO | undefined;
+    /**
+     * Get an edge between two vertices if present.
+     * @param srcOrKey - Source/endpoint A vertex or key.
+     * @param destOrKey - Destination/endpoint B vertex or key.
+     * @returns Edge instance or `undefined`.
+     * @remarks Time O(1) avg, Space O(1)
+     */
+    abstract getEdge(srcOrKey: VO | VertexKey, destOrKey: VO | VertexKey): EO | undefined;
+    /**
+     * Degree of a vertex in this graph model.
+     * @param vertexOrKey - Vertex or key.
+     * @returns Non-negative integer degree.
+     * @remarks Time O(1) avg, Space O(1)
+     */
+    abstract degreeOf(vertexOrKey: VO | VertexKey): number;
+    /**
+     * All edges in the graph (unique, order not guaranteed).
+     * @returns Array of edges.
+     * @remarks Time O(E), Space O(E)
+     */
+    abstract edgeSet(): EO[];
+    /**
+     * Incident edges of a vertex.
+     * @param vertexOrKey - Vertex or key.
+     * @returns Array of incident edges.
+     * @remarks Time O(deg), Space O(deg)
+     */
+    abstract edgesOf(vertexOrKey: VO | VertexKey): EO[];
+    /**
+     * One-step neighbors of a vertex.
+     * @param vertexOrKey - Vertex or key.
+     * @returns Array of neighbor vertices.
+     * @remarks Time O(deg), Space O(deg)
+     */
+    abstract getNeighbors(vertexOrKey: VO | VertexKey): VO[];
+    /**
+     * Resolve endpoints of an edge to vertex instances.
+     * @param edge - Edge instance.
+     * @returns `[v1, v2]` or `undefined` if missing.
+     * @remarks Time O(1), Space O(1)
+     */
+    abstract getEndsOfEdge(edge: EO): [VO, VO] | undefined;
+    /**
+     * Get vertex instance by key.
+     * @param vertexKey - Vertex key.
+     * @returns Vertex instance or `undefined`.
+     * @remarks Time O(1), Space O(1)
+     */
+    getVertex(vertexKey: VertexKey): VO | undefined;
+    /**
+     * Whether a vertex exists.
+     * @param vertexOrKey - Vertex or key.
+     * @returns `true` if present, otherwise `false`.
+     * @remarks Time O(1) avg, Space O(1)
+     */
+    hasVertex(vertexOrKey: VO | VertexKey): boolean;
+    addVertex(vertex: VO): boolean;
+    addVertex(key: VertexKey, value?: V): boolean;
+    /**
+     * Type guard: check if a value is a valid vertex key.
+     * @param potentialKey - Value to test.
+     * @returns `true` if string/number; else `false`.
+     * @remarks Time O(1), Space O(1)
+     */
+    isVertexKey(potentialKey: any): potentialKey is VertexKey;
+    /**
+     * Delete a vertex and its incident edges.
+     * @param vertexOrKey - Vertex or key.
+     * @returns `true` if removed; otherwise `false`.
+     * @remarks Time O(deg), Space O(1)
+     */
+    abstract deleteVertex(vertexOrKey: VO | VertexKey): boolean;
+    /**
+     * Delete multiple vertices.
+     * @param vertexMap - Array of vertices or keys.
+     * @returns `true` if any vertex was removed.
+     * @remarks Time O(sum(deg)), Space O(1)
+     */
+    removeManyVertices(vertexMap: VO[] | VertexKey[]): boolean;
+    /**
+     * Whether an edge exists between two vertices.
+     * @param v1 - Endpoint A vertex or key.
+     * @param v2 - Endpoint B vertex or key.
+     * @returns `true` if present; otherwise `false`.
+     * @remarks Time O(1) avg, Space O(1)
+     */
+    hasEdge(v1: VertexKey | VO, v2: VertexKey | VO): boolean;
+    addEdge(edge: EO): boolean;
+    addEdge(src: VO | VertexKey, dest: VO | VertexKey, weight?: number, value?: E): boolean;
+    /**
+     * Set the weight of an existing edge.
+     * @param srcOrKey - Source vertex or key.
+     * @param destOrKey - Destination vertex or key.
+     * @param weight - New weight.
+     * @returns `true` if updated; otherwise `false`.
+     * @remarks Time O(1) avg, Space O(1)
+     */
+    setEdgeWeight(srcOrKey: VertexKey | VO, destOrKey: VertexKey | VO, weight: number): boolean;
+    /**
+     * Enumerate simple paths up to a limit.
+     * @param v1 - Source vertex or key.
+     * @param v2 - Destination vertex or key.
+     * @param limit - Maximum number of paths to collect.
+     * @returns Array of paths (each path is an array of vertices).
+     * @remarks Time O(paths) worst-case exponential, Space O(V + paths)
+     */
+    getAllPathsBetween(v1: VO | VertexKey, v2: VO | VertexKey, limit?: number): VO[][];
+    /**
+     * Sum the weights along a vertex path.
+     * @param path - Sequence of vertices.
+     * @returns Path weight sum (0 if empty or edge missing).
+     * @remarks Time O(L), Space O(1) where L is path length
+     */
+    getPathSumWeight(path: VO[]): number;
+    /**
+     * Minimum hops/weight between two vertices.
+     * @param v1 - Source vertex or key.
+     * @param v2 - Destination vertex or key.
+     * @param isWeight - If `true`, compare by path weight; otherwise by hop count.
+     * @returns Minimum cost or `undefined` if missing/unreachable.
+     * @remarks Time O((V + E) log V) weighted / O(V + E) unweighted, Space O(V + E)
+     */
+    getMinCostBetween(v1: VO | VertexKey, v2: VO | VertexKey, isWeight?: boolean): number | undefined;
+    /**
+     * Minimum path (as vertex sequence) between two vertices.
+     * @param v1 - Source vertex or key.
+     * @param v2 - Destination vertex or key.
+     * @param isWeight - If `true`, compare by path weight; otherwise by hop count.
+     * @param isDFS - For weighted mode only: if `true`, brute-force all paths; if `false`, use Dijkstra.
+     * @returns Vertex sequence, or `undefined`/empty when unreachable depending on branch.
+     * @remarks Time O((V + E) log V) weighted / O(V + E) unweighted, Space O(V + E)
+     */
+    getMinPathBetween(v1: VO | VertexKey, v2: VO | VertexKey, isWeight?: boolean, isDFS?: boolean): VO[] | undefined;
+    /**
+     * Dijkstra without heap (array-based selection).
+     * @param src - Source vertex or key.
+     * @param dest - Optional destination for early stop.
+     * @param getMinDist - If `true`, compute global minimum distance.
+     * @param genPaths - If `true`, also generate path arrays.
+     * @returns Result bag or `undefined` if source missing.
+     * @remarks Time O(V^2 + E), Space O(V + E)
+     */
+    dijkstraWithoutHeap(src: VO | VertexKey, dest?: VO | VertexKey | undefined, getMinDist?: boolean, genPaths?: boolean): DijkstraResult<VO> | undefined;
+    dijkstra(src: VO | VertexKey, dest?: VO | VertexKey | undefined, getMinDist?: boolean, genPaths?: boolean): DijkstraResult<VO> | undefined;
+    /**
+     * Bellman-Ford single-source shortest paths with option to scan negative cycles.
+     * @param src - Source vertex or key.
+     * @param scanNegativeCycle - If `true`, also detect negative cycles.
+     * @param getMin - If `true`, compute global minimum distance.
+     * @param genPath - If `true`, generate path arrays via predecessor map.
+     * @returns Result bag including distances, predecessors, and optional cycle flag.
+     * @remarks Time O(V * E), Space O(V + E)
+     */
+    bellmanFord(src: VO | VertexKey, scanNegativeCycle?: boolean, getMin?: boolean, genPath?: boolean): {
+        hasNegativeCycle: boolean | undefined;
+        distMap: Map<VO, number>;
+        preMap: Map<VO, VO>;
+        paths: VO[][];
+        min: number;
+        minPath: VO[];
+    };
+    /**
+     * Floyd–Warshall all-pairs shortest paths.
+     * @returns `{ costs, predecessor }` matrices.
+     * @remarks Time O(V^3), Space O(V^2)
+     */
+    floydWarshall(): {
+        costs: number[][];
+        predecessor: (VO | undefined)[][];
+    };
+    /**
+     * Enumerate simple cycles (may be expensive).
+     * @param isInclude2Cycle - If `true`, include 2-cycles when graph semantics allow.
+     * @returns Array of cycles (each as array of vertex keys).
+     * @remarks Time exponential in worst-case, Space O(V + E)
+     */
+    getCycles(isInclude2Cycle?: boolean): VertexKey[][];
+    /**
+     * Induced-subgraph filter: keep vertices where `predicate(key, value)` is true,
+     * and only keep edges whose endpoints both survive.
+     * @param predicate - `(key, value, index, self) => boolean`.
+     * @param thisArg - Optional `this` for callback.
+     * @returns A new graph of the same concrete class (`this` type).
+     * @remarks Time O(V + E), Space O(V + E)
+     */
+    filter(predicate: EntryCallback<VertexKey, V | undefined, boolean>, thisArg?: any): this;
+    /**
+     * Preserve the old behavior: return filtered entries as an array.
+     * @remarks Time O(V), Space O(V)
+     */
+    filterEntries(predicate: EntryCallback<VertexKey, V | undefined, boolean>, thisArg?: any): [VertexKey, V | undefined][];
+    map<T>(callback: EntryCallback<VertexKey, V | undefined, T>, thisArg?: any): T[];
+    /**
+     * Create a deep clone of the graph with the same species.
+     * @remarks Time O(V + E), Space O(V + E)
+     */
+    /**
+     * Create a deep clone of the graph with the same species.
+     * @returns A new graph of the same concrete class (`this` type).
+     * @remarks Time O(V + E), Space O(V + E)
+     */
+    clone(): this;
+    /**
+     * Internal iterator over `[key, value]` entries in insertion order.
+     * @returns Iterator of `[VertexKey, V | undefined]`.
+     * @remarks Time O(V), Space O(1)
+     */
+    protected _getIterator(): IterableIterator<[VertexKey, V | undefined]>;
+    /**
+     * Capture configuration needed to reproduce the current graph.
+     * Currently the graph has no runtime options, so we return an empty object.
+     */
+    /**
+     * Capture configuration needed to reproduce the current graph.
+     * @returns Options bag (opaque to callers).
+     * @remarks Time O(1), Space O(1)
+     */
+    protected _snapshotOptions(): Record<string, unknown>;
+    /**
+     * Create an empty graph instance of the same concrete species (Directed/Undirected/etc).
+     * @remarks Time O(1), Space O(1)
+     */
+    /**
+     * Create an empty graph instance of the same concrete species.
+     * @param _options - Snapshot options from `_snapshotOptions()`.
+     * @returns A new empty graph instance of `this` type.
+     * @remarks Time O(1), Space O(1)
+     */
+    protected _createInstance(_options?: Partial<Record<string, unknown>>): this;
+    /**
+     * Create a same-species graph populated with the given entries.
+     * Also preserves edges between kept vertices from the source graph.
+     * @remarks Time O(V + E), Space O(V + E)
+     */
+    /**
+     * Create a same-species graph populated with entries; preserves edges among kept vertices.
+     * @param iter - Optional entries to seed the new graph.
+     * @param options - Snapshot options.
+     * @returns A new graph of `this` type.
+     * @remarks Time O(V + E), Space O(V + E)
+     */
+    protected _createLike(iter?: Iterable<[VertexKey, V | undefined]>, options?: Partial<Record<string, unknown>>): this;
+    /**
+     * Internal hook to attach an edge into adjacency structures.
+     * @param edge - Edge instance.
+     * @returns `true` if inserted; otherwise `false`.
+     * @remarks Time O(1) avg, Space O(1)
+     */
+    protected abstract _addEdge(edge: EO): boolean;
+    /**
+     * Insert a pre-built vertex into the graph.
+     * @param newVertex - Concrete vertex instance.
+     * @returns `true` if inserted; `false` if key already exists.
+     * @remarks Time O(1) avg, Space O(1)
+     */
+    protected _addVertex(newVertex: VO): boolean;
+    /**
+     * Resolve a vertex key or instance to the concrete vertex instance.
+     * @param vertexOrKey - Vertex key or existing vertex.
+     * @returns Vertex instance or `undefined`.
+     * @remarks Time O(1), Space O(1)
+     */
+    protected _getVertex(vertexOrKey: VertexKey | VO): VO | undefined;
+    /**
+     * Resolve a vertex key from a key or vertex instance.
+     * @param vertexOrKey - Vertex key or existing vertex.
+     * @returns The vertex key.
+     * @remarks Time O(1), Space O(1)
+     */
+    protected _getVertexKey(vertexOrKey: VO | VertexKey): VertexKey;
+}

package/dist/types/data-structures/graph/directed-graph.d.ts

@@ -0,0 +1,207 @@
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+import type { GraphOptions, VertexKey } from '../../types';
+import { AbstractEdge, AbstractGraph, AbstractVertex } from './abstract-graph';
+import { IGraph } from '../../interfaces';
+export declare class DirectedVertex<V = any> extends AbstractVertex<V> {
+    constructor(key: VertexKey, value?: V);
+}
+export declare class DirectedEdge<E = any> extends AbstractEdge<E> {
+    src: VertexKey;
+    dest: VertexKey;
+    constructor(src: VertexKey, dest: VertexKey, weight?: number, value?: 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 declare class DirectedGraph<V = any, E = any, VO extends DirectedVertex<V> = DirectedVertex<V>, EO extends DirectedEdge<E> = DirectedEdge<E>> extends AbstractGraph<V, E, VO, EO> implements IGraph<V, E, VO, EO> {
+    /**
+     * Construct a directed graph with runtime defaults.
+     * @param options - `GraphOptions<V>` (e.g. `vertexValueInitializer`, `defaultEdgeWeight`).
+     * @remarks Time O(1), Space O(1)
+     */
+    constructor(options?: Partial<GraphOptions<V>>);
+    protected _outEdgeMap: Map<VO, EO[]>;
+    get outEdgeMap(): Map<VO, EO[]>;
+    set outEdgeMap(v: Map<VO, EO[]>);
+    protected _inEdgeMap: Map<VO, EO[]>;
+    get inEdgeMap(): Map<VO, EO[]>;
+    set inEdgeMap(v: Map<VO, EO[]>);
+    /**
+     * 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<K extends VertexKey>(keys: Iterable<K>): DirectedGraph<K, any, DirectedVertex<K>, DirectedEdge<any>>;
+    /**
+     * 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>>;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    deleteVertex(vertexOrKey: VO | VertexKey): boolean;
+    deleteEdgesBetween(v1: VertexKey | VO, v2: VertexKey | VO): 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[];
+    /**
+     * 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[];
+    /**
+     * 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;
+    inDegreeOf(vertexOrKey: VertexKey | VO): number;
+    outDegreeOf(vertexOrKey: VertexKey | VO): number;
+    /**
+     * 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[];
+    getEdgeSrc(e: EO): VO | undefined;
+    getEdgeDest(e: EO): VO | undefined;
+    /**
+     * 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[];
+    /**
+     * 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;
+    edgeSet(): EO[];
+    getNeighbors(vertexOrKey: VO | VertexKey): VO[];
+    /**
+     * 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;
+    /**
+     * Whether the graph has no vertices and no edges.
+     * @remarks Time O(1), Space O(1)
+     */
+    isEmpty(): boolean;
+    /**
+     * Remove all vertices and edges.
+     * @remarks Time O(V + E), Space O(1)
+     */
+    clear(): void;
+    /**
+     * 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(): this;
+    /**
+     * 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[]>;
+    };
+    /**
+     * DFN index map computed by `tarjan()`.
+     * @returns Map from vertex to DFN index.
+     * @remarks Time O(V), Space O(V)
+     */
+    getDFNMap(): Map<VO, 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>;
+    /**
+     * 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[]>;
+    /**
+     * 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;
+}

package/dist/types/data-structures/graph/map-graph.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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';
+export declare class MapVertex<V = any> extends DirectedVertex<V> {
+    lat: number;
+    long: number;
+    constructor(key: VertexKey, value: V, lat: number, long: number);
+}
+export declare class MapEdge<E = any> extends DirectedEdge<E> {
+    constructor(src: VertexKey, dest: VertexKey, weight?: number, value?: E);
+}
+/**
+ * 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 declare class MapGraph<V = any, E = any, VO extends MapVertex<V> = MapVertex<V>, EO extends MapEdge<E> = MapEdge<E>> extends DirectedGraph<V, E, VO, EO> {
+    /**
+     * 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);
+    protected _originCoord: MapGraphCoordinate;
+    get originCoord(): MapGraphCoordinate;
+    protected _bottomRight: MapGraphCoordinate | undefined;
+    get bottomRight(): MapGraphCoordinate | undefined;
+    /**
+     * 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)
+     */
+    createVertex(key: VertexKey, value?: V, lat?: number, long?: number): VO;
+    /**
+     * 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)
+     */
+    createEdge(src: VertexKey, dest: VertexKey, weight?: number, value?: E): EO;
+    /**
+     * 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(): this;
+    /**
+     * Include `originCoord` and `bottomRight` so `clone()/filter()` preserve geospatial settings.
+     * @returns Options bag extending super snapshot.
+     * @remarks Time O(1), Space O(1)
+     */
+    protected _snapshotOptions(): Record<string, unknown>;
+    /**
+     * 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)
+     */
+    protected _createInstance(options?: Partial<Record<string, unknown>>): this;
+}