@statelyai/graph 1.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
@@ -86,12 +92,20 @@ const roots = getSources(graph); // nodes with no incoming edges
 
 Batch operations (`addEntities`, `deleteEntities`, `updateEntities`) let you apply multiple changes at once.
 
+`updateNode`/`updateEdge` accept any config field. Optional fields (position, size, `shape`, `color`, `style`, edge `weight`/`mode`/ports) can be **unset** by passing `null`; `undefined` leaves them unchanged:
+
+```ts
+updateNode(graph, 'a', { x: 100, color: 'red' }); // set
+updateEdge(graph, 'e1', { weight: 2, mode: 'undirected' });
+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: [
@@ -109,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
@@ -149,7 +163,18 @@ getEdgesByPort(graph, 'render', 'input'); // [e1]
 
 <!-- validation helpers exported from src/schemas.ts -->
 
-Use the `@statelyai/graph/schemas` subpath when you want runtime validation or JSON Schema generation. `validateGraph()` combines shape checks with graph invariants such as duplicate ids, dangling edges, missing parents, missing initial nodes, duplicate ports, invalid port references, and parent cycles.
+For structural invariant checking without zod, the core export `getGraphIssues(graph)` returns machine-readable issues (duplicate ids, dangling edge endpoints, missing parents, parent cycles, missing initial nodes, duplicate or invalid port references) — the recommended gate for untrusted or imported graphs:
+
+```ts
+import { getGraphIssues } from '@statelyai/graph';
+
+const issues = getGraphIssues(importedGraph);
+if (issues.length > 0) {
+  console.error(issues.map((issue) => issue.message));
+}
+```
+
+Use the `@statelyai/graph/schemas` subpath when you want full runtime shape validation or JSON Schema generation. `validateGraph()` combines zod shape checks with the same graph invariants.
 
 ```ts
 import { GraphSchema, isGraph, validateGraph } from '@statelyai/graph/schemas';
@@ -169,12 +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 (label propagation, Girvan-Newman, greedy modularity, modularity scoring), cycle detection, connected/strongly-connected components, bridges, articulation points, biconnected components, 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,
@@ -183,16 +210,20 @@ import {
   getConnectedComponents,
   getMinimumSpanningTree,
   getPageRank,
+  getLouvainCommunities,
   getLabelPropagationCommunities,
   genGirvanNewmanCommunities,
   getBridges,
+  getMaxFlow,
+  getDominatorTree,
+  getTransitiveReduction,
   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 */
 }
 
@@ -201,21 +232,56 @@ isAcyclic(graph); // cycle check
 getShortestPath(graph, { from: 'a', to: 'c' }); // single shortest path
 getTopologicalSort(graph); // topological order (or null)
 getConnectedComponents(graph); // connected components
-getMinimumSpanningTree(graph, { weight: (e) => e.data?.weight ?? 1 }); // MST
+getMinimumSpanningTree(graph, { getWeight: (e) => e.weight ?? 1 }); // MST
 getPageRank(graph); // link analysis scores
+getLouvainCommunities(graph); // community detection (Louvain)
 getLabelPropagationCommunities(graph); // community detection
 [...genGirvanNewmanCommunities(graph)]; // lazy community splits
 getBridges(graph); // bridge edges
+getMaxFlow(graph, { from: 'a', to: 'c' }); // max flow + min cut
+getDominatorTree(graph, { from: 'a' }); // immediate dominators
+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
 
@@ -272,29 +338,29 @@ source information instead of preserving it as metadata.
 
 <!-- format support matrix derived from src/formats/support.ts -->
 
-| Format              | Hierarchy | Ports   | Visual  | Round-trip | Notes                                                                      |
-| ------------------- | --------- | ------- | ------- | ---------- | -------------------------------------------------------------------------- |
-| `adjacency-list`    | none      | none    | none    | partial    | Connectivity only; edge metadata is lost.                                  |
-| `cytoscape`         | full      | full    | full    | full       | Graph, node, and edge metadata round-trip through element data.            |
-| `d3`                | full      | full    | full    | full       | Graph, node, and edge metadata round-trip through the loose JSON shape.    |
-| `d2`                | full      | full    | full    | full       | D2 syntax, hierarchy, ports, styles, and connector modes round-trip.       |
-| `dot`               | partial   | partial | partial | partial    | Edge port ids round-trip, but `:port:compass` mapping is still incomplete. |
-| `edge-list`         | none      | none    | none    | partial    | Endpoints only.                                                            |
-| `elk`               | full      | full    | full    | full       | Metadata round-trips through reserved layout options.                      |
-| `gexf`              | full      | full    | full    | full       | Custom attributes preserve metadata beyond the standard viz module.        |
-| `gml`               | full      | full    | full    | full       | Graph, node, and edge metadata round-trip through direct and JSON fields.  |
-| `graphml`           | full      | full    | partial | partial    | Ports round-trip through `<data>` fields.                                  |
-| `jgf`               | full      | full    | full    | full       | Graph, node, and edge metadata round-trip through `metadata` objects.      |
-| `tgf`               | none      | none    | none    | partial    | Minimal ids and labels only.                                               |
-| `xyflow`            | full      | full    | full    | full       | Metadata round-trips through reserved data fields.                         |
-| `mermaid/block`     | partial   | none    | partial | partial    | Syntax-driven, not port-aware.                                             |
-| `mermaid/class`     | none      | none    | none    | partial    | Class syntax is stored conservatively.                                     |
-| `mermaid/er`        | none      | none    | none    | partial    | Focuses on entities and cardinality.                                       |
-| `mermaid/flowchart` | partial   | none    | partial | partial    | `linkStyle` indices are fragile.                                           |
-| `mermaid/ishikawa`  | full      | none    | none    | partial    | Preserves hierarchy, not fishbone layout.                                  |
-| `mermaid/mindmap`   | full      | none    | partial | partial    | Icon syntax is not fully re-emitted.                                       |
-| `mermaid/sequence`  | partial   | none    | none    | partial    | Actor links and menu syntax are incomplete.                                |
-| `mermaid/state`     | full      | none    | partial | full       | State syntax round-trips through graph and node data.                      |
+| Format              | Hierarchy | Ports   | Visual  | Round-trip | Notes                                                                                                                                        |
+| ------------------- | --------- | ------- | ------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `adjacency-list`    | none      | none    | none    | partial    | Connectivity only; edge metadata is lost.                                                                                                    |
+| `cytoscape`         | full      | full    | full    | full       | Graph/node/edge metadata (incl. per-edge `mode`) round-trips through element data.                                                           |
+| `d3`                | full      | full    | full    | full       | Graph/node/edge metadata (incl. per-edge `mode`) round-trips through the loose JSON shape.                                                   |
+| `d2`                | full      | full    | full    | full       | Hierarchy, ports, styles, and connector modes round-trip; nested `vars` sub-blocks are dropped.                                              |
+| `dot`               | partial   | partial | partial | partial    | Edge port ids round-trip, but `:port:compass` mapping is still incomplete.                                                                   |
+| `edge-list`         | none      | none    | none    | partial    | Endpoints only.                                                                                                                              |
+| `elk`               | full      | full    | full    | full       | Metadata round-trips through reserved layout options; port ids are emitted as `nodeId__portName` (document-unique, as ELK requires).         |
+| `gexf`              | full      | full    | full    | full       | Custom attributes preserve metadata; `bidirectional` maps to directed.                                                                       |
+| `gml`               | full      | full    | full    | full       | Metadata round-trips through direct and JSON fields; per-edge/graph `mode` via a dialect key.                                                |
+| `graphml`           | full      | full    | partial | full       | Emit is own-dialect (`<data>` fields, flat); import handles both dialects incl. standard nested `<graph>`, native `<port>` elements, and `sourceport`/`targetport` attributes. Multi-graph files import the first graph. |
+| `jgf`               | full      | full    | full    | full       | Metadata (incl. per-edge/graph `mode`) round-trips through `metadata` objects.                                                               |
+| `tgf`               | none      | none    | none    | partial    | Minimal ids and labels only.                                                                                                                 |
+| `xyflow`            | full      | full    | full    | full       | Metadata (incl. weight, ports, per-edge `mode`) round-trips through reserved data fields; parents are ordered before children for React Flow. |
+| `mermaid/block`     | partial   | none    | partial | partial    | Syntax-driven, not port-aware.                                                                                                               |
+| `mermaid/class`     | none      | none    | none    | partial    | Class syntax is stored conservatively.                                                                                                       |
+| `mermaid/er`        | none      | none    | none    | partial    | Focuses on entities and cardinality.                                                                                                         |
+| `mermaid/flowchart` | partial   | none    | partial | partial    | `linkStyle` indices are fragile.                                                                                                             |
+| `mermaid/ishikawa`  | full      | none    | none    | partial    | Preserves hierarchy, not fishbone layout.                                                                                                    |
+| `mermaid/mindmap`   | full      | none    | partial | partial    | Icon syntax is not fully re-emitted.                                                                                                         |
+| `mermaid/sequence`  | partial   | none    | none    | partial    | Actor links and menu syntax are incomplete.                                                                                                  |
+| `mermaid/state`     | full      | none    | partial | partial    | Isolated states and labels now emit (labels via the description form); `initialNodeId` round-trips as `[*] -->`.                             |
 
 Some formats have optional peer dependencies: `fast-xml-parser` (GEXF, GraphML) and `dotparser` (DOT). All other formats are dependency-free.
 
@@ -318,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/{adjacency-list-VsUaH9SJ.mjs → adjacency-list-DQ32Mmhx.mjs}

@@ -44,7 +44,9 @@ function toAdjacencyList(graph) {
 function fromAdjacencyList(adj, options) {
 	const directed = options?.directed ?? true;
 	const seen = /* @__PURE__ */ new Set();
-	const nodes = Object.keys(adj).map((id) => ({
+	const nodeIds = new Set(Object.keys(adj));
+	for (const targets of Object.values(adj)) for (const targetId of targets) nodeIds.add(targetId);
+	const nodes = [...nodeIds].map((id) => ({
 		type: "node",
 		id,
 		parentId: null,