@statelyai/graph 0.4.0 → 0.6.0

package/dist/schemas.mjs

@@ -1,13 +1,21 @@
 import * as z from "zod";
 
 //#region src/schemas.ts
+const StyleSchema = z.record(z.string(), z.union([z.string(), z.number()]));
 const NodeSchema = z.object({
 	type: z.literal("node"),
 	id: z.string(),
-	parentId: z.string().nullable(),
-	initialNodeId: z.string().nullable(),
+	parentId: z.string().nullable().optional(),
+	initialNodeId: z.string().nullable().optional(),
 	label: z.string(),
-	data: z.any()
+	data: z.any(),
+	x: z.number().optional(),
+	y: z.number().optional(),
+	width: z.number().optional(),
+	height: z.number().optional(),
+	shape: z.string().optional(),
+	color: z.string().optional(),
+	style: StyleSchema.optional()
 });
 const EdgeSchema = z.object({
 	type: z.literal("edge"),
@@ -15,7 +23,14 @@ const EdgeSchema = z.object({
 	sourceId: z.string(),
 	targetId: z.string(),
 	label: z.string(),
-	data: z.any()
+	weight: z.number().optional(),
+	data: z.any(),
+	x: z.number().optional(),
+	y: z.number().optional(),
+	width: z.number().optional(),
+	height: z.number().optional(),
+	color: z.string().optional(),
+	style: StyleSchema.optional()
 });
 const GraphSchema = z.object({
 	id: z.string(),
@@ -23,7 +38,14 @@ const GraphSchema = z.object({
 	initialNodeId: z.string().nullable(),
 	nodes: z.array(NodeSchema),
 	edges: z.array(EdgeSchema),
-	data: z.any()
+	data: z.any(),
+	direction: z.enum([
+		"up",
+		"down",
+		"left",
+		"right"
+	]).optional(),
+	style: StyleSchema.optional()
 });
 
 //#endregion

package/dist/{types-Bq_fmLwW.d.mts → types-DF-HNw50.d.mts}

@@ -45,7 +45,13 @@ interface EdgeConfig<TEdgeData = any> {
   /**
    * The label of the edge.
    */
-  label?: string;
+  label?: string | null;
+  /**
+   * Optional numeric weight for the edge.
+   * Used by pathfinding, MST, and other weighted algorithms.
+   * When `getWeight` is not provided, algorithms default to `edge.weight ?? 1`.
+   */
+  weight?: number;
   data?: TEdgeData;
   x?: number;
   y?: number;
@@ -84,7 +90,13 @@ interface GraphEdge<TEdgeData = any> {
   id: string;
   sourceId: string;
   targetId: string;
-  label: string;
+  label: string | null;
+  /**
+   * Optional numeric weight for the edge.
+   * Used by pathfinding, MST, and other weighted algorithms.
+   * When `getWeight` is not provided, algorithms default to `edge.weight ?? 1`.
+   */
+  weight?: number;
   data: TEdgeData;
   x?: number;
   y?: number;
@@ -139,7 +151,7 @@ interface PathOptions<TEdgeData = any> {
   from?: string;
   /** Target node ID. If omitted → paths to all reachable nodes */
   to?: string;
-  /** Edge weight function. Default: every edge = 1. */
+  /** Edge weight function. Default: `(e) => e.weight ?? 1`. */
   getWeight?: (edge: GraphEdge<TEdgeData>) => number;
 }
 interface SinglePathOptions<TEdgeData = any> {
@@ -147,9 +159,22 @@ interface SinglePathOptions<TEdgeData = any> {
   from?: string;
   /** Target node ID. Required for single-path queries. */
   to: string;
-  /** Edge weight function. Default: every edge = 1. */
+  /** Edge weight function. Default: `(e) => e.weight ?? 1`. */
   getWeight?: (edge: GraphEdge<TEdgeData>) => number;
 }
+interface AStarOptions<TEdgeData = any> {
+  /** Source node ID. */
+  from: string;
+  /** Target node ID. */
+  to: string;
+  /** Edge weight function. Default: `(e) => e.weight ?? 1`. */
+  getWeight?: (edge: GraphEdge<TEdgeData>) => number;
+  /**
+   * Heuristic function estimating cost from a node to the target.
+   * Must be admissible (never overestimates the actual cost).
+   */
+  heuristic: (nodeId: string) => number;
+}
 interface TraversalOptions {
   /** Source node ID. Default: graph.initialNodeId, else sole inDegree-0 node */
   from?: string;
@@ -157,13 +182,13 @@ interface TraversalOptions {
 interface MSTOptions<TEdgeData = any> {
   /** Algorithm to use. Default: 'prim'. */
   algorithm?: 'prim' | 'kruskal';
-  /** Edge weight function. Default: every edge = 1. */
+  /** Edge weight function. Default: `(e) => e.weight ?? 1`. */
   getWeight?: (edge: GraphEdge<TEdgeData>) => number;
 }
 interface AllPairsShortestPathsOptions<TEdgeData = any> {
   /** Algorithm to use. Default: 'dijkstra'. */
   algorithm?: 'floyd-warshall' | 'dijkstra';
-  /** Edge weight function. Default: every edge = 1. */
+  /** Edge weight function. Default: `(e) => e.weight ?? 1`. */
   getWeight?: (edge: GraphEdge<TEdgeData>) => number;
 }
 interface NodeChange<TNodeData = any> {
@@ -228,22 +253,49 @@ type GraphPatch<TNodeData = any, TEdgeData = any> = {
  * };
  * ```
  */
-interface GraphFormatConverter<TSerial> {
+interface GraphFormatConverter<TSerial, N = any, E = any, G = any> {
   /** Convert a Graph to the serialized format. */
-  to(graph: Graph): TSerial;
+  to(graph: Graph<N, E, G>): TSerial;
   /** Convert from the serialized format to a Graph. */
-  from(input: TSerial): Graph;
+  from(input: TSerial): Graph<N, E, G>;
 }
 /**
  * A bidirectional converter between `VisualGraph` and a serialized format.
  *
  * Use this for formats that carry position/size data (e.g. xyflow, cytoscape).
  */
-interface VisualGraphFormatConverter<TSerial> {
+interface VisualGraphFormatConverter<TSerial, N = any, E = any, G = any> {
   /** Convert a VisualGraph to the serialized format. */
-  to(graph: VisualGraph): TSerial;
+  to(graph: VisualGraph<N, E, G>): TSerial;
   /** Convert from the serialized format to a VisualGraph. */
-  from(input: TSerial): VisualGraph;
+  from(input: TSerial): VisualGraph<N, E, G>;
+}
+interface WalkOptions<TEdgeData = any> {
+  /** Start node ID. Default: graph.initialNodeId, else sole inDegree-0 node */
+  from?: string;
+  /** Seed for deterministic RNG. Omit for Math.random. */
+  seed?: number;
+  /** Guard: only traverse edges where filter returns true. */
+  filter?: (edge: GraphEdge<TEdgeData>, context: WalkContext) => boolean;
+  /** Callback fired after each step. */
+  onStep?: (step: GraphStep<any, TEdgeData>, context: WalkContext) => void;
+}
+interface WeightedWalkOptions<TEdgeData = any> extends WalkOptions<TEdgeData> {
+  /** Edge weight function. Default: `(e) => e.weight ?? 1`. */
+  getWeight?: (edge: GraphEdge<TEdgeData>) => number;
+}
+interface WalkContext {
+  currentNodeId: string;
+  visitedNodes: Set<string>;
+  visitedEdges: Set<string>;
+  stepCount: number;
+}
+interface CoverageStats {
+  nodeCoverage: number;
+  edgeCoverage: number;
+  visitedNodes: string[];
+  visitedEdges: string[];
+  totalSteps: number;
 }
 interface TransitionOptions<TState, TEvent> {
   /** Initial state to begin BFS exploration from. */
@@ -262,4 +314,4 @@ interface TransitionOptions<TState, TEvent> {
   id?: string;
 }
 //#endregion
-export { TraversalOptions as C, VisualGraphFormatConverter as D, VisualGraphConfig as E, VisualNode as O, TransitionOptions as S, VisualGraph as T, MSTOptions as _, EntitiesConfig as a, PathOptions as b, Graph as c, GraphEdge as d, GraphFormatConverter as f, GraphStep as g, GraphPath as h, EdgeConfig as i, GraphConfig as l, GraphPatch as m, DeleteNodeOptions as n, EntitiesUpdate as o, GraphNode as p, EdgeChange as r, EntityRect as s, AllPairsShortestPathsOptions as t, GraphDiff as u, NodeChange as v, VisualEdge as w, SinglePathOptions as x, NodeConfig as y };
+export { VisualNode as A, SinglePathOptions as C, VisualGraph as D, VisualEdge as E, WalkOptions as M, WeightedWalkOptions as N, VisualGraphConfig as O, PathOptions as S, TraversalOptions as T, GraphPath as _, EdgeChange as a, NodeChange as b, EntitiesUpdate as c, GraphConfig as d, GraphDiff as f, GraphPatch as g, GraphNode as h, DeleteNodeOptions as i, WalkContext as j, VisualGraphFormatConverter as k, EntityRect as l, GraphFormatConverter as m, AllPairsShortestPathsOptions as n, EdgeConfig as o, GraphEdge as p, CoverageStats as r, EntitiesConfig as s, AStarOptions as t, Graph as u, GraphStep as v, TransitionOptions as w, NodeConfig as x, MSTOptions as y };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@statelyai/graph",
   "type": "module",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "A TypeScript-first graph library with plain JSON-serializable objects",
   "author": "David Khourshid <david@stately.ai>",
   "license": "MIT",
@@ -30,6 +30,7 @@
     "./d3": "./dist/formats/d3/index.mjs",
     "./dot": "./dist/formats/dot/index.mjs",
     "./edge-list": "./dist/formats/edge-list/index.mjs",
+    "./elk": "./dist/formats/elk/index.mjs",
     "./gexf": "./dist/formats/gexf/index.mjs",
     "./gml": "./dist/formats/gml/index.mjs",
     "./graphml": "./dist/formats/graphml/index.mjs",
@@ -60,6 +61,7 @@
     "d3-array": "^3.2.4",
     "d3-force": "^3.0.0",
     "dotparser": "^1.1.1",
+    "elkjs": "^0.11.1",
     "fast-xml-parser": "^5.3.4",
     "tsdown": "^0.18.1",
     "tsx": "^4.21.0",
@@ -72,6 +74,7 @@
     "cytoscape": "^3.0.0",
     "d3-force": "^3.0.0",
     "dotparser": "^1.0.0",
+    "elkjs": "^0.9.0 || ^0.10.0 || ^0.11.0",
     "fast-xml-parser": "^5.0.0",
     "zod": "^4.0.0"
   },
@@ -85,6 +88,9 @@
     "dotparser": {
       "optional": true
     },
+    "elkjs": {
+      "optional": true
+    },
     "fast-xml-parser": {
       "optional": true
     },

package/schemas/edge.schema.json

@@ -18,7 +18,38 @@
     "label": {
       "type": "string"
     },
-    "data": {}
+    "data": {},
+    "x": {
+      "type": "number"
+    },
+    "y": {
+      "type": "number"
+    },
+    "width": {
+      "type": "number"
+    },
+    "height": {
+      "type": "number"
+    },
+    "color": {
+      "type": "string"
+    },
+    "style": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "number"
+          }
+        ]
+      }
+    }
   },
   "required": [
     "type",

package/schemas/graph.schema.json

@@ -12,6 +12,16 @@
         "undirected"
       ]
     },
+    "initialNodeId": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
     "nodes": {
       "type": "array",
       "items": {
@@ -34,15 +44,58 @@
               }
             ]
           },
+          "initialNodeId": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
           "label": {
             "type": "string"
           },
-          "data": {}
+          "data": {},
+          "x": {
+            "type": "number"
+          },
+          "y": {
+            "type": "number"
+          },
+          "width": {
+            "type": "number"
+          },
+          "height": {
+            "type": "number"
+          },
+          "shape": {
+            "type": "string"
+          },
+          "color": {
+            "type": "string"
+          },
+          "style": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "number"
+                }
+              ]
+            }
+          }
         },
         "required": [
           "type",
           "id",
-          "parentId",
           "label",
           "data"
         ],
@@ -70,7 +123,38 @@
           "label": {
             "type": "string"
           },
-          "data": {}
+          "data": {},
+          "x": {
+            "type": "number"
+          },
+          "y": {
+            "type": "number"
+          },
+          "width": {
+            "type": "number"
+          },
+          "height": {
+            "type": "number"
+          },
+          "color": {
+            "type": "string"
+          },
+          "style": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "number"
+                }
+              ]
+            }
+          }
         },
         "required": [
           "type",
@@ -83,11 +167,37 @@
         "additionalProperties": false
       }
     },
-    "data": {}
+    "data": {},
+    "direction": {
+      "type": "string",
+      "enum": [
+        "up",
+        "down",
+        "left",
+        "right"
+      ]
+    },
+    "style": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "number"
+          }
+        ]
+      }
+    }
   },
   "required": [
     "id",
     "type",
+    "initialNodeId",
     "nodes",
     "edges",
     "data"

package/schemas/node.schema.json

@@ -19,15 +19,58 @@
         }
       ]
     },
+    "initialNodeId": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
     "label": {
       "type": "string"
     },
-    "data": {}
+    "data": {},
+    "x": {
+      "type": "number"
+    },
+    "y": {
+      "type": "number"
+    },
+    "width": {
+      "type": "number"
+    },
+    "height": {
+      "type": "number"
+    },
+    "shape": {
+      "type": "string"
+    },
+    "color": {
+      "type": "string"
+    },
+    "style": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "number"
+          }
+        ]
+      }
+    }
   },
   "required": [
     "type",
     "id",
-    "parentId",
     "label",
     "data"
   ],