@statelyai/graph 2.0.0 → 2.1.0

package/README.md

@@ -14,14 +14,19 @@ Optional peers are only needed for specific adapters:
 
 <!-- optional peer dependencies derived from package.json#peerDependencies -->
 
-| Package           | Needed for                                          |
-| ----------------- | --------------------------------------------------- |
-| `fast-xml-parser` | `@statelyai/graph/gexf`, `@statelyai/graph/graphml` |
-| `dotparser`       | `@statelyai/graph/dot` parsing                      |
-| `cytoscape`       | Cytoscape integration tests and consumer typing     |
-| `d3-force`        | D3 force integration tests and consumer typing      |
-| `elkjs`           | `@statelyai/graph/elk`                              |
-| `zod`             | `@statelyai/graph/schemas`                          |
+| Package                                     | Needed for                                          |
+| ------------------------------------------- | --------------------------------------------------- |
+| `fast-xml-parser`                           | `@statelyai/graph/gexf`, `@statelyai/graph/graphml` |
+| `dotparser`                                 | `@statelyai/graph/dot` parsing                      |
+| `zod`                                       | `@statelyai/graph/schemas`                          |
+| `elkjs`                                     | `@statelyai/graph/elk`, `@statelyai/graph/layout/elk` |
+| `@dagrejs/dagre`                            | `@statelyai/graph/layout/dagre`                     |
+| `@hpcc-js/wasm-graphviz`                    | `@statelyai/graph/layout/graphviz`                  |
+| `d3-force`                                  | `@statelyai/graph/layout/d3-force`                  |
+| `graphology`, `graphology-layout-forceatlas2` | `@statelyai/graph/layout/forceatlas2`             |
+| `d3-hierarchy`                              | `@statelyai/graph/layout/d3-hierarchy`              |
+| `webcola`                                   | `@statelyai/graph/layout/webcola`                   |
+| `cytoscape`                                 | `@statelyai/graph/layout/cytoscape`, Cytoscape format typing |
 
 ## Highlights
 
@@ -29,7 +34,8 @@ Optional peers are only needed for specific adapters:
 - Standalone functions with a consistent `get*`/`gen*`/`is*`/`add*` naming model
 - Directed, undirected, hierarchical, and visual graph support
 - Ports for node-editor and dataflow-style graphs
-- Algorithms for traversal, paths, centrality, communities, connectivity, isomorphism, ordering, MST, and walks
+- Algorithms for traversal, paths, centrality, communities, connectivity, flow/cuts, matching, cores, isomorphism, ordering, MST, and walks
+- Pluggable layout over eight external engines (ELK, Graphviz, dagre, d3-force, ForceAtlas2, tidy tree, WebCola, cytoscape) — pure functions, optional peers
 - Diff/patch utilities for graph state changes
 - Multi-format conversion via package subpaths, with fidelity claims tested against fixtures
 - Small, fast test suite with broad format coverage
@@ -96,10 +102,10 @@ updateNode(graph, 'a', { color: null }); // unset
 
 ## Hierarchy
 
-Nodes support parent-child relationships for compound/nested graphs. Query children, ancestors, descendants, depth, and least common ancestor. Use `flatten()` to decompose into a flat leaf-node graph.
+Nodes support parent-child relationships for compound/nested graphs. Query children, ancestors, descendants, depth, and least common ancestor. Use `getFlattenedGraph()` to decompose into a flat leaf-node graph.
 
 ```ts
-import { createGraph, getChildren, getLCA, flatten } from '@statelyai/graph';
+import { createGraph, getChildren, getLCA, getFlattenedGraph } from '@statelyai/graph';
 
 const graph = createGraph({
   nodes: [
@@ -117,7 +123,7 @@ const graph = createGraph({
 });
 
 const children = getChildren(graph, 'b'); // [b1, b2]
-const flat = flatten(graph); // only leaf nodes, edges resolved
+const flat = getFlattenedGraph(graph); // only leaf nodes, edges resolved
 ```
 
 ## Ports
@@ -188,14 +194,14 @@ const parsed = GraphSchema.parse(unknownValue);
 
 <!-- algorithm functions exported from src/algorithms.ts -->
 
-Includes traversal (BFS, DFS, preorder/postorder), pathfinding (shortest path, simple paths, all-pairs shortest paths, A*), centrality/link analysis (degree, closeness, betweenness, PageRank, HITS, eigenvector), community detection (Louvain, label propagation, Girvan-Newman, greedy modularity, modularity scoring), flow (max-flow/min-cut), cycle detection, connected/strongly-connected components, bridges, articulation points, biconnected components, dominator trees, transitive reduction, isomorphism, topological sort, minimum spanning tree, and more. Many algorithms have lazy generator variants (`gen*`) for early exit.
+Includes traversal (BFS, DFS, preorder/postorder), pathfinding (shortest path, simple paths, all-pairs shortest paths, A*, bidirectional Dijkstra), centrality/link analysis (degree, closeness, betweenness, PageRank, HITS, eigenvector, Katz), community detection (Louvain, label propagation, Girvan-Newman, greedy modularity, modularity scoring), flow & cuts (`getMaxFlow`, `getMinCut`), bipartite analysis (`isBipartite`, Hopcroft–Karp `getMaximumBipartiteMatching`), k-cores (`getCoreNumbers`, `getKCore`), cycle detection, connected/strongly-connected components, bridges, articulation points, biconnected components, dominator trees, transitive reduction, isomorphism, topological sort, minimum spanning tree, and seeded graph generators (`createCompleteGraph`, `createGridGraph`, `createRandomGraph`). Many algorithms have lazy generator variants (`gen*`) for early exit. See [docs/algorithms.md](./docs/algorithms.md) for the full reference.
 
 Hot algorithm loops (centrality, components) run on an internal compressed-sparse-row snapshot — cached and invalidated transparently like the rest of the index — so they stay fast on large graphs without changing the plain-JSON model. Algorithm results are differential-tested against graphology on seeded random graphs.
 
 ```ts
 import {
-  bfs,
-  dfs,
+  genBFS,
+  genDFS,
   hasPath,
   isAcyclic,
   getShortestPath,
@@ -214,10 +220,10 @@ import {
   isIsomorphic,
 } from '@statelyai/graph';
 
-for (const node of bfs(graph, 'a')) {
+for (const node of genBFS(graph, 'a')) {
   /* breadth-first */
 }
-for (const node of dfs(graph, 'a')) {
+for (const node of genDFS(graph, 'a')) {
   /* depth-first */
 }
 
@@ -238,13 +244,44 @@ getTransitiveReduction(graph); // minimal equivalent DAG
 isIsomorphic(graph, otherGraph); // structural equivalence
 ```
 
+## Layout
+
+<!-- layout adapters under src/layout/*.ts and helpers exported from src/layout/index.ts -->
+
+Plug-and-play layout over external engines — pure functions in, positioned `VisualGraph` out. No layout algorithms of our own; each adapter is a subpath with an optional peer dependency. The hierarchical engines (ELK, dagre, Graphviz) also produce routed edge `points` and computed edge-label rects; the physics/tree/cytoscape engines position nodes only.
+
+```ts
+import { getElkLayout } from '@statelyai/graph/layout/elk'; // elkjs
+import { getDagreLayout } from '@statelyai/graph/layout/dagre'; // @dagrejs/dagre
+import { getGraphvizLayout } from '@statelyai/graph/layout/graphviz'; // @hpcc-js/wasm-graphviz (8 engines)
+import { genForceLayout } from '@statelyai/graph/layout/d3-force'; // d3-force
+import { getForceAtlas2Layout } from '@statelyai/graph/layout/forceatlas2'; // graphology FA2
+import { getTidyTreeLayout } from '@statelyai/graph/layout/d3-hierarchy'; // d3-hierarchy
+import { getColaLayout } from '@statelyai/graph/layout/webcola'; // webcola (constraints)
+import { getCytoscapeLayout } from '@statelyai/graph/layout/cytoscape'; // cytoscape ecosystem
+import { applyLayoutFrame, getLayoutBounds, centerGraph } from '@statelyai/graph/layout';
+
+const laidOut = await getElkLayout(graph, {
+  measure: (node) => measureText(node.label), // text measurement stays yours
+  constraints: { layer: (node) => node.data?.tier }, // portable layer constraint
+});
+
+// Physics layouts are generators — one tick per frame, cancel by stopping
+for (const frame of genForceLayout(graph, { seed: 42 })) {
+  applyLayoutFrame(graph, frame);
+  render(graph);
+}
+```
+
+Edge `x`/`y`/`width`/`height` are canonically the edge-label rect; routes live in `edge.points` (`routing` says how to interpret them). Layouts are plain JSON — tween between engines with `genLayoutTransition`, or diff them with `getPatches`. See [docs/layout.md](./docs/layout.md) and [docs/layout-transitions.md](./docs/layout-transitions.md).
+
 ## Diff & Walks
 
 Beyond classic graph algorithms, the library also includes utilities for evolving and exploring graph state:
 
-- `getDiff()`, `getPatches()`, `applyPatches()` for graph change tracking
+- `getDiff()`, `getPatches()`, `updateGraphWithPatches()` for graph change tracking
 - `genRandomWalk()`, `genWeightedRandomWalk()`, and coverage helpers for model-based testing and simulation
-- `getSubgraph()` and `reverseGraph()` for structural transforms
+- `getSubgraph()` and `getReversedGraph()` for structural transforms
 
 ## Visual Graphs
 
@@ -347,6 +384,17 @@ Format-specific docs live alongside the source:
 - [xyflow](./src/formats/xyflow/README.md)
 - [Converter helpers](./src/formats/converter/README.md)
 
+## Guides
+
+<!-- guide documents under docs/*.md -->
+
+- [Layout guide](./docs/layout.md) — the adapter contract, all eight engines, constraints, sizing, web workers
+- [Layout transitions](./docs/layout-transitions.md) — tween between engines; layouts are just data
+- [Algorithms reference](./docs/algorithms.md) — every algorithm with complexity and semantics notes
+- [Benchmarks](./docs/benchmarks.md) — measured against graphology, ngraph, graphlib, and cytoscape
+- [Migrating from graphlib](./docs/migrating-from-graphlib.md)
+- [React Flow + ELK pipeline](./docs/react-flow-elk-pipeline.md) — measured nodes, worker layout, live re-layout
+
 ## Examples
 
 <!-- runnable example files under examples/ -->

package/dist/{algorithms-CsGNehct.d.mts → algorithms-D1cgly0g.d.mts}

@@ -1,7 +1,15 @@
-import { A as SinglePathOptions, C as MSTOptions, D as PathOptions, M as TraversalOptions, b as GraphPath, d as Graph, m as GraphEdge, n as AllPairsShortestPathsOptions, t as AStarOptions, v as GraphNode } from "./types-DNYdIU21.mjs";
+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>[][];
@@ -35,6 +43,10 @@ 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
@@ -54,6 +66,16 @@ interface IterativeCentralityOptions {
   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>;
@@ -111,10 +133,81 @@ declare function getHITS(graph: Graph, options?: IterativeCentralityOptions): HI
 /**
  * Returns eigenvector centrality scores for all nodes.
  *
- * Uses power iteration over incoming neighbors for directed graphs and
- * undirected adjacency for undirected graphs.
+ * 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 getEigenvectorCentrality(graph: Graph, options?: IterativeCentralityOptions): Record<string, number>;
+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 {
@@ -123,13 +216,21 @@ interface GirvanNewmanOptions {
 }
 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.
+ * 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>[];
 /**
@@ -238,6 +339,25 @@ interface MaxFlowResult<E = any> {
   /** 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).
@@ -257,6 +377,25 @@ interface MaxFlowResult<E = any> {
  * ```
  */
 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 {
@@ -310,4 +449,4 @@ declare function getDominatorTree(graph: Graph, options?: DominatorTreeOptions):
  */
 declare function getTransitiveReduction<N, E, G, P>(graph: Graph<N, E, G, P>): Graph<N, E, G, P>;
 //#endregion
-export { getTopologicalSort as $, getPageRank as A, genSimplePaths as B, getBetweennessCentrality as C, getHITS as D, getEigenvectorCentrality as E, getPostorders as F, getShortestPaths as G, getAllPairsShortestPaths as H, getPreorder as I, getStronglyConnectedComponents as J, getSimplePath as K, getPreorders as L, genPostorders as M, genPreorders as N, getInDegreeCentrality as O, getPostorder as P, getConnectedComponents as Q, genCycles as R, IterativeCentralityOptions as S, getDegreeCentrality as T, getCycles as U, getAStarPath as V, getShortestPath as W, bfs as X, joinPaths as Y, dfs as Z, getGirvanNewmanCommunities as _, MaxFlowResult as a, getModularity as b, getLouvainCommunities as c, getArticulationPoints as d, hasPath as et, getBiconnectedComponents as f, genGirvanNewmanCommunities as g, LabelPropagationOptions as h, MaxFlowOptions as i, getMinimumSpanningTree as j, getOutDegreeCentrality as k, IsomorphismOptions as l, GirvanNewmanOptions as m, DominatorTreeOptions as n, isConnected as nt, getMaxFlow as o, getBridges as p, getSimplePaths as q, getDominatorTree as r, isTree as rt, LouvainOptions as s, getTransitiveReduction as t, isAcyclic as tt, isIsomorphic as u, getGreedyModularityCommunities as v, getClosenessCentrality as w, HITSResult as x, getLabelPropagationCommunities as y, genShortestPaths as z };
+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 };