stack-typed 2.1.0 → 2.1.2

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

@@ -1,340 +0,0 @@
-/**
- * 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;
-}