@statelyai/graph 0.13.0 → 2.0.0

package/README.md

@@ -86,6 +86,14 @@ 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.
@@ -149,7 +157,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,7 +188,9 @@ 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*), 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.
+
+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 {
@@ -183,9 +204,13 @@ import {
   getConnectedComponents,
   getMinimumSpanningTree,
   getPageRank,
+  getLouvainCommunities,
   getLabelPropagationCommunities,
   genGirvanNewmanCommunities,
   getBridges,
+  getMaxFlow,
+  getDominatorTree,
+  getTransitiveReduction,
   isIsomorphic,
 } from '@statelyai/graph';
 
@@ -201,11 +226,15 @@ 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
 ```
 
@@ -252,7 +281,7 @@ const imported = fromGEXF(gexfXmlString); // GEXF (Gephi)
 
 <!-- supported format adapters derived from src/formats/* subdirectories -->
 
-**Supported formats:** Cytoscape.js JSON, D3.js JSON, JSON Graph Format, GEXF, GraphML, GML, TGF, DOT, Mermaid (flowchart, state, sequence, class, ER, mindmap, block, Ishikawa), ELK, xyflow, adjacency list, and edge list.
+**Supported formats:** Cytoscape.js JSON, D3.js JSON, D2, JSON Graph Format, GEXF, GraphML, GML, TGF, DOT, Mermaid (flowchart, state, sequence, class, ER, mindmap, block, Ishikawa), ELK, xyflow, adjacency list, and edge list.
 
 Each bidirectional format also has a converter object:
 
@@ -272,28 +301,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.    |
-| `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.
 
@@ -304,6 +334,7 @@ Format-specific docs live alongside the source:
 - [Adjacency list](./src/formats/adjacency-list/README.md)
 - [Cytoscape](./src/formats/cytoscape/README.md)
 - [D3](./src/formats/d3/README.md)
+- [D2](./src/formats/d2/README.md)
 - [DOT](./src/formats/dot/README.md)
 - [Edge list](./src/formats/edge-list/README.md)
 - [ELK](./src/formats/elk/README.md)

package/dist/{adjacency-list-Ca0VjKIf.mjs → adjacency-list-GeL1Cu-L.mjs}

@@ -20,7 +20,7 @@ function toAdjacencyList(graph) {
 	for (const node of graph.nodes) adj[node.id] = [];
 	for (const edge of graph.edges) {
 		adj[edge.sourceId]?.push(edge.targetId);
-		if (graph.type === "undirected") adj[edge.targetId]?.push(edge.sourceId);
+		if (graph.mode !== "directed") adj[edge.targetId]?.push(edge.sourceId);
 	}
 	return adj;
 }
@@ -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,
@@ -70,7 +72,7 @@ function fromAdjacencyList(adj, options) {
 	}
 	return {
 		id: options?.id ?? "",
-		type: directed ? "directed" : "undirected",
+		mode: directed ? "directed" : "undirected",
 		initialNodeId: null,
 		nodes,
 		edges,

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

@@ -1,13 +1,26 @@
-import { D as SinglePathOptions, g as GraphNode, k as TraversalOptions, n as AllPairsShortestPathsOptions, p as GraphEdge, t as AStarOptions, u as Graph, v as GraphPath, w as PathOptions, x as MSTOptions } from "./types-CnZ01raw.mjs";
+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";
 
 //#region src/algorithms/traversal.d.ts
 declare function bfs<N>(graph: Graph<N>, startId: string): Generator<GraphNode<N>>;
 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
@@ -175,4 +188,126 @@ interface IsomorphismOptions<N = any, E = any> {
  */
 declare function isIsomorphic<N, E>(graphA: Graph<N, E>, graphB: Graph<N, E>, options?: IsomorphismOptions<N, E>): boolean;
 //#endregion
-export { genCycles as A, getStronglyConnectedComponents as B, getMinimumSpanningTree as C, getPostorders as D, getPostorder as E, getCycles as F, getTopologicalSort as G, bfs as H, getShortestPath as I, isConnected as J, hasPath as K, getShortestPaths as L, genSimplePaths as M, getAStarPath as N, getPreorder as O, getAllPairsShortestPaths as P, getSimplePath as R, getPageRank as S, genPreorders as T, dfs as U, joinPaths as V, getConnectedComponents as W, isTree as Y, getDegreeCentrality as _, getBridges as a, getInDegreeCentrality as b, genGirvanNewmanCommunities as c, getLabelPropagationCommunities as d, getModularity as f, getClosenessCentrality as g, getBetweennessCentrality as h, getBiconnectedComponents as i, genShortestPaths as j, getPreorders as k, getGirvanNewmanCommunities as l, IterativeCentralityOptions as m, isIsomorphic as n, GirvanNewmanOptions as o, HITSResult as p, isAcyclic as q, getArticulationPoints as r, LabelPropagationOptions as s, IsomorphismOptions as t, getGreedyModularityCommunities as u, getEigenvectorCentrality as v, genPostorders as w, getOutDegreeCentrality as x, getHITS as y, getSimplePaths as z };
+//#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>[];
+}
+/**
+ * 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>;
+//#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 { 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 };