@statelyai/graph 2.0.0 → 2.1.0

package/dist/{queries-BfXeTXRf.d.mts → queries-B6quF529.d.mts}

@@ -1,4 +1,4 @@
-import { d as Graph, m as GraphEdge, v as GraphNode, x as GraphPort } from "./types-DNYdIU21.mjs";
+import { S as GraphPort, f as Graph, h as GraphEdge, y as GraphNode } from "./types-BAEQTwK_.mjs";
 
 //#region src/queries.d.ts
 

package/dist/{queries-KirMDR7e.mjs → queries-BMM0XAv_.mjs}

@@ -1,4 +1,4 @@
-import { t as getEdgeMode } from "./mode-D8OnHFBk.mjs";
+import { t as getEdgeMode } from "./mode-gu_mhKKs.mjs";
 
 //#region src/indexing.ts
 const indexes = /* @__PURE__ */ new WeakMap();
@@ -14,7 +14,8 @@ const indexes = /* @__PURE__ */ new WeakMap();
 *
 * @example
 * ```ts
-* import { createGraph, getIndex } from '@statelyai/graph';
+* import { createGraph } from '@statelyai/graph';
+* import { getIndex } from './indexing';
 *
 * const graph = createGraph({
 *   nodes: [{ id: 'a' }, { id: 'b' }],
@@ -41,14 +42,15 @@ function getIndex(graph) {
 *
 * @example
 * ```ts
-* import { createGraph, invalidateIndex, getIndex } from '@statelyai/graph';
+* import { createGraph, getSuccessors, invalidateIndex } from '@statelyai/graph';
 *
 * const graph = createGraph({
 *   nodes: [{ id: 'a' }, { id: 'b' }],
 *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
 * });
 * graph.edges[0].targetId = 'a'; // in-place field mutation
-* invalidateIndex(graph); // forces rebuild on next getIndex()
+* invalidateIndex(graph); // forces rebuild on next indexed read
+* getSuccessors(graph, 'a');
 * ```
 */
 function invalidateIndex(graph) {
@@ -148,6 +150,19 @@ function indexUpdateEdgeEndpoints(idx, edgeId, oldSourceId, oldTargetId, newSour
 
 //#endregion
 //#region src/queries.ts
+const nonDirectedSelfLoopCache = /* @__PURE__ */ new WeakMap();
+function getNonDirectedSelfLoopCounts(graph, idx) {
+	const cached = nonDirectedSelfLoopCache.get(idx);
+	if (cached && cached.version === idx.version && cached.mode === graph.mode) return cached.counts;
+	const counts = /* @__PURE__ */ new Map();
+	for (const edge of graph.edges) if (edge.sourceId === edge.targetId && getEdgeMode(graph, edge) !== "directed") counts.set(edge.sourceId, (counts.get(edge.sourceId) ?? 0) + 1);
+	nonDirectedSelfLoopCache.set(idx, {
+		version: idx.version,
+		mode: graph.mode,
+		counts
+	});
+	return counts;
+}
 /**
 * Returns all edges (incoming + outgoing) connected to a node.
 *
@@ -375,19 +390,10 @@ function getNeighbors(graph, nodeId) {
 */
 function getDegree(graph, nodeId) {
 	const idx = getIndex(graph);
-	const out = idx.outEdges.get(nodeId) ?? [];
-	const inE = idx.inEdges.get(nodeId) ?? [];
-	let degree = 0;
-	const countedNonDirected = /* @__PURE__ */ new Set();
-	for (const eid of [...out, ...inE]) {
-		const e = graph.edges[idx.edgeById.get(eid)];
-		if (getEdgeMode(graph, e) === "directed") degree++;
-		else if (!countedNonDirected.has(eid)) {
-			countedNonDirected.add(eid);
-			degree++;
-		}
-	}
-	return degree;
+	const out = idx.outEdges.get(nodeId);
+	const inE = idx.inEdges.get(nodeId);
+	const selfLoops = getNonDirectedSelfLoopCounts(graph, idx);
+	return (out?.length ?? 0) + (inE?.length ?? 0) - (selfLoops.get(nodeId) ?? 0);
 }
 /**
 * Returns the in-degree of a node — the number of edges traversable *into*

package/dist/queries.d.mts

@@ -1,2 +1,2 @@
-import { C as getSinks, D as isLeaf, E as isCompound, S as getSiblings, T as getSuccessors, _ as getPorts, a as getDescendants, b as getRelativeDistanceMap, c as getEdgesOf, d as getLCA, f as getNeighbors, g as getPort, h as getParent, i as getDepth, l as getInDegree, m as getOutEdges, n as getChildren, o as getEdgesBetween, p as getOutDegree, r as getDegree, s as getEdgesByPort, t as getAncestors, u as getInEdges, v as getPredecessors, w as getSources, x as getRoots, y as getRelativeDistance } from "./queries-BfXeTXRf.mjs";
+import { C as getSinks, D as isLeaf, E as isCompound, S as getSiblings, T as getSuccessors, _ as getPorts, a as getDescendants, b as getRelativeDistanceMap, c as getEdgesOf, d as getLCA, f as getNeighbors, g as getPort, h as getParent, i as getDepth, l as getInDegree, m as getOutEdges, n as getChildren, o as getEdgesBetween, p as getOutDegree, r as getDegree, s as getEdgesByPort, t as getAncestors, u as getInEdges, v as getPredecessors, w as getSources, x as getRoots, y as getRelativeDistance } from "./queries-B6quF529.mjs";
 export { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgesBetween, getEdgesByPort, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPort, getPorts, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf };

package/dist/queries.mjs

@@ -1,3 +1,3 @@
-import { C as getSinks, D as isLeaf, E as isCompound, S as getSiblings, T as getSuccessors, _ as getPorts, a as getDescendants, b as getRelativeDistanceMap, c as getEdgesOf, d as getLCA, f as getNeighbors, g as getPort, h as getParent, i as getDepth, l as getInDegree, m as getOutEdges, n as getChildren, o as getEdgesBetween, p as getOutDegree, r as getDegree, s as getEdgesByPort, t as getAncestors, u as getInEdges, v as getPredecessors, w as getSources, x as getRoots, y as getRelativeDistance } from "./queries-KirMDR7e.mjs";
+import { C as getSinks, D as isLeaf, E as isCompound, S as getSiblings, T as getSuccessors, _ as getPorts, a as getDescendants, b as getRelativeDistanceMap, c as getEdgesOf, d as getLCA, f as getNeighbors, g as getPort, h as getParent, i as getDepth, l as getInDegree, m as getOutEdges, n as getChildren, o as getEdgesBetween, p as getOutDegree, r as getDegree, s as getEdgesByPort, t as getAncestors, u as getInEdges, v as getPredecessors, w as getSources, x as getRoots, y as getRelativeDistance } from "./queries-BMM0XAv_.mjs";
 
 export { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgesBetween, getEdgesByPort, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPort, getPorts, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf };

package/dist/schemas.d.mts

@@ -1,4 +1,4 @@
-import { d as Graph, m as GraphEdge, v as GraphNode, x as GraphPort } from "./types-DNYdIU21.mjs";
+import { S as GraphPort, f as Graph, h as GraphEdge, y as GraphNode } from "./types-BAEQTwK_.mjs";
 import * as z from "zod";
 
 //#region src/schemas.d.ts
@@ -61,6 +61,15 @@ declare const EdgeSchema: z.ZodObject<{
     undirected: "undirected";
     bidirectional: "bidirectional";
   }>>;
+  points: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+  }, z.core.$strip>>>;
+  routing: z.ZodOptional<z.ZodEnum<{
+    polyline: "polyline";
+    orthogonal: "orthogonal";
+    splines: "splines";
+  }>>;
   data: z.ZodAny;
   x: z.ZodOptional<z.ZodNumber>;
   y: z.ZodOptional<z.ZodNumber>;
@@ -121,6 +130,15 @@ declare const GraphSchema: z.ZodObject<{
       undirected: "undirected";
       bidirectional: "bidirectional";
     }>>;
+    points: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      x: z.ZodNumber;
+      y: z.ZodNumber;
+    }, z.core.$strip>>>;
+    routing: z.ZodOptional<z.ZodEnum<{
+      polyline: "polyline";
+      orthogonal: "orthogonal";
+      splines: "splines";
+    }>>;
     data: z.ZodAny;
     x: z.ZodOptional<z.ZodNumber>;
     y: z.ZodOptional<z.ZodNumber>;

package/dist/schemas.mjs

@@ -1,4 +1,4 @@
-import { t as getGraphIssues$1 } from "./validate-TtH-x3JV.mjs";
+import { t as getGraphIssues$1 } from "./validate-BsfSOv0S.mjs";
 import * as z from "zod";
 
 //#region src/schemas.ts
@@ -54,6 +54,15 @@ const EdgeSchema = z.object({
 	sourcePort: z.string().optional(),
 	targetPort: z.string().optional(),
 	mode: ModeSchema.optional(),
+	points: z.array(z.object({
+		x: z.number(),
+		y: z.number()
+	})).optional(),
+	routing: z.enum([
+		"polyline",
+		"orthogonal",
+		"splines"
+	]).optional(),
 	data: z.any(),
 	x: z.number().optional(),
 	y: z.number().optional(),

package/dist/{types-DNYdIU21.d.mts → types-BAEQTwK_.d.mts}

@@ -16,6 +16,20 @@ interface EntityRect {
   width: number;
   height: number;
 }
+/** A 2D point, used for edge routing waypoints. */
+interface Point {
+  x: number;
+  y: number;
+}
+/**
+ * How an edge's {@link GraphEdge.points} should be interpreted by renderers:
+ *
+ * - `'polyline'` — straight segments through the points.
+ * - `'orthogonal'` — axis-aligned segments (ELK layered routing).
+ * - `'splines'` — bezier control points (Graphviz convention: 3n+1 chained
+ *   cubic curves, tail → head).
+ */
+type EdgeRouting = 'polyline' | 'orthogonal' | 'splines';
 /** Shared optional visual/style props for nodes, edges, ports. */
 interface GraphEntity {
   x?: number;
@@ -55,7 +69,7 @@ interface GraphConfig<TNodeData = any, TEdgeData = any, TGraphData = any, TPortD
   id?: string;
   /** Default directedness for all edges. Defaults to `'directed'`. */
   mode?: GraphMode;
-  initialNodeId?: string;
+  initialNodeId?: string | null;
   nodes?: NodeConfig<TNodeData, TPortData>[];
   edges?: EdgeConfig<TEdgeData>[];
   data?: TGraphData;
@@ -65,13 +79,20 @@ interface GraphConfig<TNodeData = any, TEdgeData = any, TGraphData = any, TPortD
 interface NodeConfig<TNodeData = any, TPortData = any> extends GraphEntity {
   id: string;
   parentId?: string | null;
-  initialNodeId?: string;
+  initialNodeId?: string | null;
   label?: string | null;
   data?: TNodeData;
   ports?: PortConfig<TPortData>[];
   shape?: string;
   color?: string;
 }
+/**
+ * Note on edge geometry: an edge's `x`/`y`/`width`/`height` are canonically
+ * the **label rect** (top-left + size). Layout adapters write computed edge
+ * label positions here, and engines that need label dimensions as input
+ * (dagre, ELK) read `width`/`height`. The edge's *route* lives in
+ * {@link EdgeConfig.points}.
+ */
 interface EdgeConfig<TEdgeData = any> extends GraphEntity {
   /**
    * The id of the edge.
@@ -104,6 +125,13 @@ interface EdgeConfig<TEdgeData = any> extends GraphEntity {
    * {@link GraphConfig.mode}.
    */
   mode?: GraphMode;
+  /**
+   * Edge route waypoints (including endpoints, tail → head), as computed by a
+   * layout engine. Interpretation is governed by {@link EdgeConfig.routing}.
+   */
+  points?: Point[];
+  /** How {@link EdgeConfig.points} should be interpreted. Default: polyline. */
+  routing?: EdgeRouting;
   data?: TEdgeData;
   color?: string;
 }
@@ -129,6 +157,11 @@ interface GraphNode<TNodeData = any, TPortData = any> extends GraphEntity {
   shape?: string;
   color?: string;
 }
+/**
+ * Note on edge geometry: an edge's `x`/`y`/`width`/`height` are canonically
+ * the **label rect** (top-left + size); the edge's *route* lives in
+ * {@link GraphEdge.points}. See {@link EdgeConfig} for details.
+ */
 interface GraphEdge<TEdgeData = any> extends GraphEntity {
   type: 'edge';
   id: string;
@@ -150,6 +183,13 @@ interface GraphEdge<TEdgeData = any> extends GraphEntity {
    * {@link Graph.mode}.
    */
   mode?: GraphMode;
+  /**
+   * Edge route waypoints (including endpoints, tail → head), as computed by a
+   * layout engine. Interpretation is governed by {@link GraphEdge.routing}.
+   */
+  points?: Point[];
+  /** How {@link GraphEdge.points} should be interpreted. Default: polyline. */
+  routing?: EdgeRouting;
   data: TEdgeData;
   color?: string;
 }
@@ -219,6 +259,9 @@ interface EdgeUpdate<TEdgeData = any> {
   sourcePort?: string | null;
   /** Port name on the target node, or `null` to clear the port reference. */
   targetPort?: string | null;
+  /** Edge route waypoints, or `null` to clear the route. */
+  points?: Point[] | null;
+  routing?: EdgeRouting | null;
   x?: number | null;
   y?: number | null;
   width?: number | null;
@@ -424,4 +467,4 @@ interface TransitionOptions<TState, TEvent> {
   id?: string;
 }
 //#endregion
-export { SinglePathOptions as A, WalkContext as B, MSTOptions as C, PathOptions as D, NodeUpdate as E, VisualGraphConfig as F, WeightedWalkOptions as H, VisualGraphEntity as I, VisualGraphFormatConverter as L, TraversalOptions as M, VisualEdge as N, PortConfig as O, VisualGraph as P, VisualNode as R, GraphStep as S, NodeConfig as T, WalkOptions as V, GraphMode as _, EdgeChange as a, GraphPath as b, EntitiesConfig as c, Graph as d, GraphConfig as f, GraphFormatConverter as g, GraphEntity as h, DeleteNodeOptions as i, TransitionOptions as j, PortDirection as k, EntitiesUpdate as l, GraphEdge as m, AllPairsShortestPathsOptions as n, EdgeConfig as o, GraphDiff as p, CoverageStats as r, EdgeUpdate as s, AStarOptions as t, EntityRect as u, GraphNode as v, NodeChange as w, GraphPort as x, GraphPatch as y, VisualPort as z };
+export { PortConfig as A, VisualNode as B, GraphStep as C, NodeUpdate as D, NodeConfig as E, VisualEdge as F, WalkContext as H, VisualGraph as I, VisualGraphConfig as L, SinglePathOptions as M, TransitionOptions as N, PathOptions as O, TraversalOptions as P, VisualGraphEntity as R, GraphPort as S, NodeChange as T, WalkOptions as U, VisualPort as V, WeightedWalkOptions as W, GraphFormatConverter as _, EdgeChange as a, GraphPatch as b, EdgeUpdate as c, EntityRect as d, Graph as f, GraphEntity as g, GraphEdge as h, DeleteNodeOptions as i, PortDirection as j, Point as k, EntitiesConfig as l, GraphDiff as m, AllPairsShortestPathsOptions as n, EdgeConfig as o, GraphConfig as p, CoverageStats as r, EdgeRouting as s, AStarOptions as t, EntitiesUpdate as u, GraphMode as v, MSTOptions as w, GraphPath as x, GraphNode as y, VisualGraphFormatConverter as z };

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@statelyai/graph",
   "type": "module",
-  "version": "2.0.0",
+  "sideEffects": false,
+  "version": "2.1.0",
   "description": "A TypeScript-first graph library with plain JSON-serializable objects",
   "author": "David Khourshid <david@stately.ai>",
   "license": "MIT",
@@ -40,6 +41,15 @@
     "./mermaid": "./dist/formats/mermaid/index.mjs",
     "./tgf": "./dist/formats/tgf/index.mjs",
     "./xyflow": "./dist/formats/xyflow/index.mjs",
+    "./layout": "./dist/layout/index.mjs",
+    "./layout/cytoscape": "./dist/layout/cytoscape.mjs",
+    "./layout/d3-force": "./dist/layout/d3-force.mjs",
+    "./layout/d3-hierarchy": "./dist/layout/d3-hierarchy.mjs",
+    "./layout/dagre": "./dist/layout/dagre.mjs",
+    "./layout/elk": "./dist/layout/elk.mjs",
+    "./layout/forceatlas2": "./dist/layout/forceatlas2.mjs",
+    "./layout/graphviz": "./dist/layout/graphviz.mjs",
+    "./layout/webcola": "./dist/layout/webcola.mjs",
     "./queries": "./dist/queries.mjs",
     "./schemas": "./dist/schemas.mjs",
     "./package.json": "./package.json"
@@ -53,22 +63,27 @@
   ],
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.2",
-    "@changesets/cli": "^2.29.8",
+    "@changesets/cli": "^2.31.0",
+    "@dagrejs/dagre": "^3.0.0",
     "@dagrejs/graphlib": "^4.0.1",
+    "@hpcc-js/wasm-graphviz": "^1.22.0",
     "@types/d3-array": "^3.2.2",
     "@types/d3-force": "^3.0.10",
+    "@types/d3-hierarchy": "^3.1.7",
     "@types/node": "^25.0.3",
     "@vitest/coverage-v8": "^4.0.18",
     "@xyflow/system": "^0.0.75",
     "bumpp": "^10.3.2",
-    "cytoscape": "^3.33.1",
+    "cytoscape": "^3.34.0",
     "d3-array": "^3.2.4",
     "d3-force": "^3.0.0",
+    "d3-hierarchy": "^3.1.2",
     "dotparser": "^1.1.1",
     "elkjs": "^0.11.1",
     "fast-xml-parser": "^5.3.4",
     "graphology": "^0.26.0",
     "graphology-components": "^1.5.4",
+    "graphology-layout-forceatlas2": "^0.10.1",
     "graphology-metrics": "^2.4.0",
     "graphology-shortest-path": "^2.1.0",
     "graphology-types": "^0.24.8",
@@ -76,27 +91,43 @@
     "ngraph.path": "^1.6.1",
     "publint": "^0.3.15",
     "tsdown": "^0.18.1",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.4",
     "typescript": "^5.9.3",
     "vitest": "^4.0.16",
+    "webcola": "^3.4.0",
     "xstate": "^5.28.0",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
+    "@dagrejs/dagre": "^3.0.0 || ^4.0.0",
+    "@hpcc-js/wasm-graphviz": "^1.0.0",
     "cytoscape": "^3.0.0",
     "d3-force": "^3.0.0",
+    "d3-hierarchy": "^3.0.0",
     "dotparser": "^1.0.0",
     "elkjs": "^0.9.0 || ^0.10.0 || ^0.11.0",
     "fast-xml-parser": "^5.0.0",
+    "graphology": "^0.26.0",
+    "graphology-layout-forceatlas2": "^0.10.0",
+    "webcola": "^3.4.0",
     "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {
+    "@dagrejs/dagre": {
+      "optional": true
+    },
+    "@hpcc-js/wasm-graphviz": {
+      "optional": true
+    },
     "cytoscape": {
       "optional": true
     },
     "d3-force": {
       "optional": true
     },
+    "d3-hierarchy": {
+      "optional": true
+    },
     "dotparser": {
       "optional": true
     },
@@ -106,6 +137,15 @@
     "fast-xml-parser": {
       "optional": true
     },
+    "graphology": {
+      "optional": true
+    },
+    "graphology-layout-forceatlas2": {
+      "optional": true
+    },
+    "webcola": {
+      "optional": true
+    },
     "zod": {
       "optional": true
     }
@@ -117,8 +157,10 @@
     "fix:generated": "pnpm generate-schema",
     "test": "vitest",
     "typecheck": "tsc --noEmit",
+    "typecheck:repo": "tsc --project tsconfig.repo.json",
     "check:generated": "tsx scripts/generate-json-schema.ts --check",
-    "verify": "pnpm typecheck && pnpm check:generated && pnpm test -- --run && pnpm build && pnpm validate:package",
+    "check:conventions": "tsx scripts/check-conventions.ts",
+    "verify": "pnpm typecheck && pnpm typecheck:repo && pnpm check:generated && pnpm check:conventions && pnpm test -- --run && pnpm build && pnpm validate:package",
     "validate:package": "publint && tsx scripts/smoke-package.ts",
     "generate-schema": "tsx scripts/generate-json-schema.ts",
     "changeset": "changeset",

package/schemas/edge.schema.json

@@ -42,6 +42,33 @@
         "bidirectional"
       ]
     },
+    "points": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "x": {
+            "type": "number"
+          },
+          "y": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "x",
+          "y"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "routing": {
+      "type": "string",
+      "enum": [
+        "polyline",
+        "orthogonal",
+        "splines"
+      ]
+    },
     "data": {},
     "x": {
       "type": "number"

package/schemas/graph.schema.json

@@ -217,6 +217,33 @@
               "bidirectional"
             ]
           },
+          "points": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "x": {
+                  "type": "number"
+                },
+                "y": {
+                  "type": "number"
+                }
+              },
+              "required": [
+                "x",
+                "y"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "routing": {
+            "type": "string",
+            "enum": [
+              "polyline",
+              "orthogonal",
+              "splines"
+            ]
+          },
           "data": {},
           "x": {
             "type": "number"