@statelyai/graph 1.0.0 → 2.1.0

package/dist/algorithms-D1cgly0g.d.mts

@@ -0,0 +1,452 @@
+import { M as SinglePathOptions, O as PathOptions, P as TraversalOptions, f as Graph, h as GraphEdge, n as AllPairsShortestPathsOptions, t as AStarOptions, w as MSTOptions, x as GraphPath, y as GraphNode } from "./types-BAEQTwK_.mjs";
+
+//#region src/algorithms/traversal.d.ts
+declare function genBFS<N>(graph: Graph<N>, startId: string): Generator<GraphNode<N>>;
+/**
+ * @deprecated Use {@link genBFS}.
+ */
+declare function bfs<N>(graph: Graph<N>, startId: string): Generator<GraphNode<N>>;
+declare function genDFS<N>(graph: Graph<N>, startId: string): Generator<GraphNode<N>>;
+/**
+ * @deprecated Use {@link genDFS}.
+ */
+declare function dfs<N>(graph: Graph<N>, startId: string): Generator<GraphNode<N>>;
+declare function isAcyclic(graph: Graph): boolean;
+declare function getConnectedComponents<N>(graph: Graph<N>): GraphNode<N>[][];
+/**
+ * Returns a topological ordering of the graph's nodes, or `null` if no such
+ * ordering exists.
+ *
+ * Any edge whose effective mode (per {@link getEdgeMode}) is not `'directed'`
+ * makes ordering impossible — an undirected/bidirectional edge is mutual
+ * precedence, i.e. a 2-cycle — so the function returns `null`.
+ */
+declare function getTopologicalSort<N>(graph: Graph<N>): GraphNode<N>[] | null;
+declare function hasPath(graph: Graph, sourceId: string, targetId: string): boolean;
+declare function isConnected(graph: Graph): boolean;
+/**
+ * Returns whether the graph is a tree: connected, acyclic, and with exactly
+ * `nodes.length - 1` edges (so directed diamonds and parallel edges are not
+ * trees). Empty and single-node graphs are considered trees.
+ */
+declare function isTree(graph: Graph): boolean;
+//#endregion
+//#region src/algorithms/paths.d.ts
+declare function genShortestPaths<N, E>(graph: Graph<N, E>, opts?: PathOptions<E>): Generator<GraphPath<N, E>>;
+declare function getShortestPaths<N, E>(graph: Graph<N, E>, opts?: PathOptions<E>): GraphPath<N, E>[];
+declare function getShortestPath<N, E>(graph: Graph<N, E>, opts: SinglePathOptions<E>): GraphPath<N, E> | undefined;
+declare function getSimplePaths<N, E>(graph: Graph<N, E>, opts?: PathOptions<E>): GraphPath<N, E>[];
+declare function genSimplePaths<N, E>(graph: Graph<N, E>, opts?: PathOptions<E>): Generator<GraphPath<N, E>>;
+declare function getSimplePath<N, E>(graph: Graph<N, E>, opts: SinglePathOptions<E>): GraphPath<N, E> | undefined;
+declare function getStronglyConnectedComponents<N>(graph: Graph<N>): GraphNode<N>[][];
+declare function getCycles<N, E>(graph: Graph<N, E>): GraphPath<N, E>[];
+declare function genCycles<N, E>(graph: Graph<N, E>): Generator<GraphPath<N, E>>;
+declare function getAllPairsShortestPaths<N, E>(graph: Graph<N, E>, opts?: AllPairsShortestPathsOptions<E>): GraphPath<N, E>[];
+declare function getAStarPath<N, E>(graph: Graph<N, E>, opts: AStarOptions<E>): GraphPath<N, E> | undefined;
+declare function getJoinedPath<N, E>(headPath: GraphPath<N, E>, tailPath: GraphPath<N, E>): GraphPath<N, E>;
+/**
+ * @deprecated Use {@link getJoinedPath}.
+ */
+declare function joinPaths<N, E>(headPath: GraphPath<N, E>, tailPath: GraphPath<N, E>): GraphPath<N, E>;
+//#endregion
+//#region src/algorithms/ordering.d.ts
+declare function getPreorder<N>(graph: Graph<N>, opts?: TraversalOptions): GraphNode<N>[];
+declare function getPostorder<N>(graph: Graph<N>, opts?: TraversalOptions): GraphNode<N>[];
+declare function getPreorders<N>(graph: Graph<N>, opts?: TraversalOptions): GraphNode<N>[][];
+declare function getPostorders<N>(graph: Graph<N>, opts?: TraversalOptions): GraphNode<N>[][];
+declare function genPreorders<N>(graph: Graph<N>, opts?: TraversalOptions): Generator<GraphNode<N>[]>;
+declare function genPostorders<N>(graph: Graph<N>, opts?: TraversalOptions): Generator<GraphNode<N>[]>;
+//#endregion
+//#region src/algorithms/spanning-tree.d.ts
+declare function getMinimumSpanningTree<N, E>(graph: Graph<N, E>, opts?: MSTOptions<E>): Graph<N, E>;
+//#endregion
+//#region src/algorithms/centrality.d.ts
+interface IterativeCentralityOptions {
+  alpha?: number;
+  maxIterations?: number;
+  tolerance?: number;
+}
+interface EigenvectorCentralityOptions<E = any> extends IterativeCentralityOptions {
+  /** Edge weight accessor. Defaults to unweighted (every edge counts 1). */
+  getWeight?: (edge: GraphEdge<E>) => number;
+}
+interface KatzCentralityOptions<E = any> extends IterativeCentralityOptions {
+  /** Constant added to every node each iteration. Defaults to `1`. */
+  beta?: number;
+  /** Edge weight accessor. Defaults to unweighted (every edge counts 1). */
+  getWeight?: (edge: GraphEdge<E>) => number;
+}
+interface HITSResult {
+  hubs: Record<string, number>;
+  authorities: Record<string, number>;
+}
+/**
+ * Returns degree centrality scores for all nodes.
+ *
+ * Degree centrality is the node degree normalized by `n - 1`.
+ *
+ * @example
+ * ```ts
+ * const scores = getDegreeCentrality(graph);
+ * console.log(scores.a); // 0.5
+ * ```
+ */
+declare function getDegreeCentrality(graph: Graph): Record<string, number>;
+/**
+ * Returns in-degree centrality scores for all nodes.
+ *
+ * In-degree centrality is the incoming degree normalized by `n - 1`.
+ */
+declare function getInDegreeCentrality(graph: Graph): Record<string, number>;
+/**
+ * Returns out-degree centrality scores for all nodes.
+ *
+ * Out-degree centrality is the outgoing degree normalized by `n - 1`.
+ */
+declare function getOutDegreeCentrality(graph: Graph): Record<string, number>;
+/**
+ * Returns closeness centrality scores for all nodes.
+ *
+ * Distances are computed over unweighted shortest paths using the graph's
+ * existing directed or undirected edge semantics.
+ */
+declare function getClosenessCentrality(graph: Graph): Record<string, number>;
+/**
+ * Returns betweenness centrality scores for all nodes.
+ *
+ * Uses Brandes' algorithm over unweighted shortest paths and returns
+ * normalized scores.
+ */
+declare function getBetweennessCentrality(graph: Graph): Record<string, number>;
+/**
+ * Returns PageRank scores for all nodes.
+ *
+ * Uses power iteration with damping factor `alpha`.
+ */
+declare function getPageRank(graph: Graph, options?: IterativeCentralityOptions): Record<string, number>;
+/**
+ * Returns HITS hub and authority scores for all nodes.
+ *
+ * Uses power iteration and L2 normalization per iteration.
+ */
+declare function getHITS(graph: Graph, options?: IterativeCentralityOptions): HITSResult;
+/**
+ * Returns eigenvector centrality scores for all nodes.
+ *
+ * Power iteration with the `A + I` shift (same scheme as graphology and
+ * networkx, so bipartite structures converge instead of oscillating).
+ * Scores flow along edge direction: a node's score is fed by its incoming
+ * neighbors; undirected edges feed both endpoints. The result vector is
+ * Euclidean (L2) normalized.
+ *
+ * Throws when the iteration has not converged (L1 error < `n × tolerance`)
+ * within `maxIterations`.
+ */
+declare function getEigenvectorCentrality<N, E>(graph: Graph<N, E>, options?: EigenvectorCentralityOptions<E>): Record<string, number>;
+/**
+ * Returns Katz centrality scores for all nodes.
+ *
+ * Iterates `x' = alpha · Aᵀx + beta` to its fixed point (networkx-style),
+ * then Euclidean (L2) normalizes the result. Scores flow along edge
+ * direction: a node's score is fed by its incoming neighbors; undirected
+ * edges feed both endpoints.
+ *
+ * Converges only when `alpha` is below the reciprocal of the largest
+ * eigenvalue of the adjacency matrix; throws when the iteration has not
+ * converged (L1 error < `n × tolerance`) within `maxIterations`.
+ */
+declare function getKatzCentrality<N, E>(graph: Graph<N, E>, options?: KatzCentralityOptions<E>): Record<string, number>;
+//#endregion
+//#region src/algorithms/cores.d.ts
+/**
+ * Returns the core number of every node (largest `k` such that the node
+ * belongs to the k-core).
+ *
+ * Uses Batagelj–Zaveršnik bucket peeling — O(m). Edges are treated as
+ * undirected (the standard k-core definition); self-loops are ignored.
+ *
+ * @example
+ * ```ts
+ * const cores = getCoreNumbers(graph);
+ * console.log(cores.a); // 3
+ * ```
+ */
+declare function getCoreNumbers(graph: Graph): Record<string, number>;
+/**
+ * Returns the ids of all nodes in the k-core: the maximal subgraph in which
+ * every node has at least `k` neighbors (edges treated as undirected).
+ *
+ * Node order follows `graph.nodes`. `k <= 0` returns every node id.
+ */
+declare function getKCore(graph: Graph, k: number): string[];
+//#endregion
+//#region src/algorithms/bipartite.d.ts
+interface BipartiteMatch {
+  /** Source node id of the matched edge (as stored on the edge). */
+  sourceId: string;
+  /** Target node id of the matched edge (as stored on the edge). */
+  targetId: string;
+  /** Id of the edge realizing the match. */
+  edgeId: string;
+}
+/**
+ * Returns whether the graph is bipartite (2-colorable).
+ *
+ * Edges are treated as undirected; self-loops make a graph non-bipartite.
+ * Runs a BFS 2-coloring per connected component — O(n + m).
+ */
+declare function isBipartite(graph: Graph): boolean;
+/**
+ * Returns a maximum-cardinality matching of a bipartite graph using
+ * Hopcroft–Karp — O(m·√n).
+ *
+ * The bipartition is derived by 2-coloring (edges treated as undirected).
+ * Each match reports the realizing edge with its stored `sourceId`/
+ * `targetId` orientation; for parallel edges between a matched pair, the
+ * first edge used by the algorithm is reported.
+ *
+ * Throws if the graph is not bipartite, naming the offending edge.
+ */
+declare function getMaximumBipartiteMatching(graph: Graph): BipartiteMatch[];
+//#endregion
+//#region src/algorithms/community.d.ts
+interface GirvanNewmanOptions {
+  level?: number;
+  maxLevels?: number;
+}
+interface LabelPropagationOptions {
+  maxIterations?: number;
+  /**
+   * When provided, runs *asynchronous* label propagation with a shuffled
+   * node order per round and random tie-breaking, seeded with mulberry32 —
+   * deterministic per seed. Without a seed, ties break lexicographically.
+   */
+  seed?: number;
+}
+type Community<N = any> = GraphNode<N>[];
+/**
+ * Returns label-propagation communities for the graph.
+ *
+ * The implementation is deterministic: ties are broken by lexicographic label
+ * order so test results remain stable. Pass `options.seed` for the classic
+ * asynchronous variant (shuffled node order per round, random tie-breaking)
+ * — still deterministic per seed.
+ */
+declare function getLabelPropagationCommunities<N>(graph: Graph<N>, options?: LabelPropagationOptions): Community<N>[];
+/**
+ * Lazily yields Girvan-Newman community splits as edge betweenness removes
+ * bridge-like edges from the graph.
+ */
+declare function genGirvanNewmanCommunities<N>(graph: Graph<N>, options?: GirvanNewmanOptions): Generator<Community<N>[]>;
+/**
+ * Returns the requested Girvan-Newman split level eagerly.
+ *
+ * `level: 1` returns the first split yielded by `genGirvanNewmanCommunities`.
+ */
+declare function getGirvanNewmanCommunities<N>(graph: Graph<N>, options?: GirvanNewmanOptions): Community<N>[];
+/**
+ * Returns the modularity score for a partition of communities.
+ *
+ * Community algorithms in this module treat the graph as undirected.
+ */
+declare function getModularity<N>(graph: Graph<N>, communities: Community<N>[]): number;
+/**
+ * Returns communities found by greedily merging partitions that improve
+ * modularity the most at each step.
+ */
+declare function getGreedyModularityCommunities<N>(graph: Graph<N>): Community<N>[];
+//#endregion
+//#region src/algorithms/connectivity.d.ts
+/**
+ * Returns bridge edges whose removal disconnects the graph.
+ *
+ * Connectivity algorithms in this module treat the graph as undirected.
+ */
+declare function getBridges<N, E>(graph: Graph<N, E>): GraphEdge<E>[];
+/**
+ * Returns articulation points (cut vertices) for the graph.
+ *
+ * Connectivity algorithms in this module treat the graph as undirected.
+ */
+declare function getArticulationPoints<N, E>(graph: Graph<N, E>): GraphNode<N>[];
+/**
+ * Returns biconnected components as arrays of nodes.
+ *
+ * Articulation points may appear in multiple returned components.
+ */
+declare function getBiconnectedComponents<N, E>(graph: Graph<N, E>): GraphNode<N>[][];
+//#endregion
+//#region src/algorithms/isomorphism.d.ts
+interface IsomorphismOptions<N = any, E = any> {
+  nodeMatch?: (a: GraphNode<N>, b: GraphNode<N>) => boolean;
+  edgeMatch?: (a: GraphEdge<E>, b: GraphEdge<E>) => boolean;
+}
+/**
+ * Returns whether two graphs are structurally isomorphic.
+ *
+ * Optional `nodeMatch` and `edgeMatch` predicates can refine the match using
+ * node and edge payloads.
+ */
+declare function isIsomorphic<N, E>(graphA: Graph<N, E>, graphB: Graph<N, E>, options?: IsomorphismOptions<N, E>): boolean;
+//#endregion
+//#region src/algorithms/louvain.d.ts
+interface LouvainOptions<E = any> {
+  /** Edge weight accessor. Defaults to `edge.weight ?? 1`. */
+  getWeight?: (edge: GraphEdge<E>) => number;
+  /** Resolution parameter γ. Values > 1 favor smaller communities. Default 1. */
+  resolution?: number;
+  /** Maximum number of two-phase (local move + aggregation) passes. Default 10. */
+  maxPasses?: number;
+}
+/**
+ * Returns communities found by the classic two-phase Louvain modularity
+ * optimization (local moving + community aggregation).
+ *
+ * Like the other community algorithms in this library, the graph is treated
+ * as undirected regardless of `graph.mode` or per-edge modes. Parallel edges
+ * have their weights summed; self-loops contribute to a community's internal
+ * weight.
+ *
+ * The implementation is deterministic: nodes are visited in `graph.nodes`
+ * array order and there is no random shuffling, so tie-breaking is
+ * order-dependent but stable across runs.
+ *
+ * Returns communities of node ids, each community sorted lexicographically
+ * and communities sorted by their first id.
+ *
+ * @example
+ * ```ts
+ * const communities = getLouvainCommunities(graph);
+ * // [['a', 'b', 'c'], ['d', 'e', 'f']]
+ * ```
+ */
+declare function getLouvainCommunities<N, E>(graph: Graph<N, E>, options?: LouvainOptions<E>): string[][];
+//#endregion
+//#region src/algorithms/flow.d.ts
+interface MaxFlowOptions<E = any> {
+  /** Source node id. */
+  from: string;
+  /** Sink node id. */
+  to: string;
+  /** Edge capacity accessor. Defaults to `edge.weight ?? 1`. */
+  getCapacity?: (edge: GraphEdge<E>) => number;
+}
+interface MaxFlowResult<E = any> {
+  /** Maximum flow value from source to sink. */
+  value: number;
+  /** Net flow per edge id (positive means source→target direction). */
+  flows: Record<string, number>;
+  /** Edges in the minimum cut (max-flow-min-cut theorem). */
+  cutEdges: GraphEdge<E>[];
+}
+interface MinCutOptions<E = any> {
+  /** Source node id. */
+  source: string;
+  /** Sink node id. */
+  sink: string;
+  /** Edge capacity accessor. Defaults to `edge.weight ?? 1`. */
+  getCapacity?: (edge: GraphEdge<E>) => number;
+}
+interface MinCutResult {
+  /** Total capacity of the cut (equals the max-flow value). */
+  value: number;
+  /** Ids of the edges crossing the cut. */
+  cutEdges: string[];
+  /** Node ids on each side of the cut, in `graph.nodes` order. */
+  partition: {
+    source: string[];
+    sink: string[];
+  };
+}
+/**
+ * Returns the maximum flow from `from` to `to` using the Edmonds-Karp
+ * algorithm (BFS augmenting paths).
+ *
+ * Directed edges carry capacity from source to target only. Edges whose
+ * effective mode is not `'directed'` (undirected/bidirectional) are modeled
+ * as two independent opposite arcs, each with the edge's full capacity.
+ *
+ * The returned `flows` record maps every edge id to its net flow (positive
+ * in the source→target direction). `cutEdges` is a minimum s-t cut: the
+ * edges crossing from the source side to the sink side of the final
+ * residual graph; the sum of their capacities equals `value`.
+ *
+ * @example
+ * ```ts
+ * const { value, cutEdges } = getMaxFlow(graph, { from: 's', to: 't' });
+ * ```
+ */
+declare function getMaxFlow<N, E>(graph: Graph<N, E>, options: MaxFlowOptions<E>): MaxFlowResult<E>;
+/**
+ * Returns a minimum s-t cut between `source` and `sink` via the max-flow
+ * min-cut theorem: runs the same Edmonds-Karp solver as {@link getMaxFlow},
+ * then splits the nodes by residual reachability from the source.
+ *
+ * `partition.source` holds every node reachable from `source` in the final
+ * residual graph; `partition.sink` holds the rest (both in `graph.nodes`
+ * order). `cutEdges` are the ids of the edges crossing the cut, and their
+ * total capacity equals `value` (the max-flow value).
+ *
+ * @example
+ * ```ts
+ * const { value, cutEdges, partition } = getMinCut(graph, {
+ *   source: 's',
+ *   sink: 't',
+ * });
+ * ```
+ */
+declare function getMinCut<N, E>(graph: Graph<N, E>, options: MinCutOptions<E>): MinCutResult;
+//#endregion
+//#region src/algorithms/dominators.d.ts
+interface DominatorTreeOptions {
+  /**
+   * Root node id. Defaults to `graph.initialNodeId`, then to the unique
+   * zero-in-degree node.
+   */
+  from?: string;
+}
+/**
+ * Returns the dominator tree of the graph rooted at `from`, computed with
+ * the Cooper–Harvey–Kennedy iterative algorithm.
+ *
+ * Each reachable node maps to its immediate dominator's id; the root maps
+ * to `null`. Unreachable nodes are omitted. Traversal is mode-aware:
+ * undirected/bidirectional edges are traversable both ways.
+ *
+ * For statecharts this answers "which states must every path from the
+ * initial state pass through to reach this state?" — node `d` dominates
+ * node `n` when every path from the initial state to `n` goes through `d`.
+ *
+ * @example
+ * ```ts
+ * // a→b, a→c, b→d, c→d (diamond)
+ * getDominatorTree(graph, { from: 'a' });
+ * // { a: null, b: 'a', c: 'a', d: 'a' }
+ * ```
+ */
+declare function getDominatorTree(graph: Graph, options?: DominatorTreeOptions): Record<string, string | null>;
+//#endregion
+//#region src/algorithms/reduction.d.ts
+/**
+ * Returns a new graph with all transitively-redundant edges removed (the
+ * transitive reduction). The input graph is not mutated; nodes and surviving
+ * edges keep all of their fields.
+ *
+ * An edge u→v is removed when v is also reachable from u via a path of
+ * length ≥ 2. Exact-duplicate parallel edges u→v collapse to the first one
+ * in `graph.edges` order (a duplicate adds no reachability, so at most one
+ * edge per (u, v) pair survives).
+ *
+ * DAG-only: throws when the graph contains a cycle or any edge whose
+ * effective mode is not `'directed'`.
+ *
+ * @example
+ * ```ts
+ * // a→b, b→c, a→c
+ * const reduced = getTransitiveReduction(graph);
+ * // a→c removed; edges: a→b, b→c
+ * ```
+ */
+declare function getTransitiveReduction<N, E, G, P>(graph: Graph<N, E, G, P>): Graph<N, E, G, P>;
+//#endregion
+export { getAllPairsShortestPaths as $, HITSResult as A, getOutDegreeCentrality as B, getModularity as C, getCoreNumbers as D, isBipartite as E, getDegreeCentrality as F, getPostorder as G, getMinimumSpanningTree as H, getEigenvectorCentrality as I, getPreorders as J, getPostorders as K, getHITS as L, KatzCentralityOptions as M, getBetweennessCentrality as N, getKCore as O, getClosenessCentrality as P, getAStarPath as Q, getInDegreeCentrality as R, getLabelPropagationCommunities as S, getMaximumBipartiteMatching as T, genPostorders as U, getPageRank as V, genPreorders as W, genShortestPaths as X, genCycles as Y, genSimplePaths as Z, GirvanNewmanOptions as _, isTree as _t, MaxFlowResult as a, getSimplePaths as at, getGirvanNewmanCommunities as b, getMaxFlow as c, bfs as ct, getLouvainCommunities as d, genDFS as dt, getCycles as et, IsomorphismOptions as f, getConnectedComponents as ft, getBridges as g, isConnected as gt, getBiconnectedComponents as h, isAcyclic as ht, MaxFlowOptions as i, getSimplePath as it, IterativeCentralityOptions as j, EigenvectorCentralityOptions as k, getMinCut as l, dfs as lt, getArticulationPoints as m, hasPath as mt, DominatorTreeOptions as n, getShortestPath as nt, MinCutOptions as o, getStronglyConnectedComponents as ot, isIsomorphic as p, getTopologicalSort as pt, getPreorder as q, getDominatorTree as r, getShortestPaths as rt, MinCutResult as s, joinPaths as st, getTransitiveReduction as t, getJoinedPath as tt, LouvainOptions as u, genBFS as ut, LabelPropagationOptions as v, BipartiteMatch as w, getGreedyModularityCommunities as x, genGirvanNewmanCommunities as y, getKatzCentrality as z };