@statelyai/graph 0.11.1 → 0.12.0

package/README.md

@@ -1,7 +1,3 @@
----
-title: '@statelyai/graph'
----
-
 # @statelyai/graph
 
 A TypeScript graph library built on plain JSON objects. Supports directed/undirected graphs, hierarchical nodes, graph algorithms, visual properties, and serialization to DOT, GraphML, Mermaid, and more.
@@ -18,14 +14,14 @@ Optional peers are only needed for specific adapters:
 
 <!-- optional peer dependencies derived from package.json#peerDependencies -->
 
-| Package | Needed for |
-| --- | --- |
+| 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` |
+| `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`                          |
 
 ## Highlights
 
@@ -43,7 +39,12 @@ Optional peers are only needed for specific adapters:
 Graphs are plain JSON-serializable objects. All operations are standalone functions — no classes, no DOM, no rendering engine.
 
 ```ts
-import { createGraph, addNode, addEdge, getShortestPath } from '@statelyai/graph';
+import {
+  createGraph,
+  addNode,
+  addEdge,
+  getShortestPath,
+} from '@statelyai/graph';
 
 const graph = createGraph({
   nodes: [
@@ -70,12 +71,17 @@ const path = getShortestPath(graph, { from: 'a', to: 'c' });
 Look up, add, delete, and update nodes and edges. Query neighbors, predecessors, successors, degree, and more.
 
 ```ts
-import { getNode, deleteNode, getNeighbors, getSources } from '@statelyai/graph';
+import {
+  getNode,
+  deleteNode,
+  getNeighbors,
+  getSources,
+} from '@statelyai/graph';
 
-const node = getNode(graph, 'a');       // lookup by id
-deleteNode(graph, 'd');                 // removes node + connected edges
+const node = getNode(graph, 'a'); // lookup by id
+deleteNode(graph, 'd'); // removes node + connected edges
 const neighbors = getNeighbors(graph, 'a'); // adjacent nodes
-const roots = getSources(graph);        // nodes with no incoming edges
+const roots = getSources(graph); // nodes with no incoming edges
 ```
 
 Batch operations (`addEntities`, `deleteEntities`, `updateEntities`) let you apply multiple changes at once.
@@ -96,14 +102,14 @@ const graph = createGraph({
     { id: 'c' },
   ],
   edges: [
-    { id: 'e1', sourceId: 'a', targetId: 'b' },   // resolves to a -> b1
+    { id: 'e1', sourceId: 'a', targetId: 'b' }, // resolves to a -> b1
     { id: 'e2', sourceId: 'b1', targetId: 'b2' },
-    { id: 'e3', sourceId: 'b', targetId: 'c' },    // expands from all leaves of b
+    { id: 'e3', sourceId: 'b', targetId: 'c' }, // expands from all leaves of b
   ],
 });
 
 const children = getChildren(graph, 'b'); // [b1, b2]
-const flat = flatten(graph);              // only leaf nodes, edges resolved
+const flat = flatten(graph); // only leaf nodes, edges resolved
 ```
 
 ## Ports
@@ -139,6 +145,26 @@ getPorts(graph, 'fetch'); // [{ name: 'result', ... }]
 getEdgesByPort(graph, 'render', 'input'); // [e1]
 ```
 
+## Schema Validation
+
+<!-- validation helpers exported from src/schemas.ts -->
+
+Use the `@statelyai/graph/schemas` subpath when you want runtime validation or JSON Schema generation.
+
+```ts
+import { GraphSchema, getGraphIssues, isGraph } from '@statelyai/graph/schemas';
+
+const unknownValue: unknown = JSON.parse(input);
+
+if (isGraph(unknownValue)) {
+  // fully typed Graph
+} else {
+  console.error(getGraphIssues(unknownValue));
+}
+
+const parsed = GraphSchema.parse(unknownValue);
+```
+
 ## Algorithms
 
 <!-- algorithm functions exported from src/algorithms.ts -->
@@ -147,27 +173,40 @@ Includes traversal (BFS, DFS, preorder/postorder), pathfinding (shortest path, s
 
 ```ts
 import {
-  bfs, dfs, hasPath, isAcyclic,
-  getShortestPath, getCycles, getTopologicalSort,
-  getConnectedComponents, getMinimumSpanningTree,
-  getPageRank, getLabelPropagationCommunities,
-  genGirvanNewmanCommunities, getBridges, isIsomorphic,
+  bfs,
+  dfs,
+  hasPath,
+  isAcyclic,
+  getShortestPath,
+  getCycles,
+  getTopologicalSort,
+  getConnectedComponents,
+  getMinimumSpanningTree,
+  getPageRank,
+  getLabelPropagationCommunities,
+  genGirvanNewmanCommunities,
+  getBridges,
+  isIsomorphic,
 } from '@statelyai/graph';
 
-for (const node of bfs(graph, 'a')) { /* breadth-first */ }
-for (const node of dfs(graph, 'a')) { /* depth-first */ }
-
-hasPath(graph, 'a', 'c');                          // reachability
-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
-getPageRank(graph);                                // link analysis scores
-getLabelPropagationCommunities(graph);             // community detection
-[...genGirvanNewmanCommunities(graph)];            // lazy community splits
-getBridges(graph);                                 // bridge edges
-isIsomorphic(graph, otherGraph);                   // structural equivalence
+for (const node of bfs(graph, 'a')) {
+  /* breadth-first */
+}
+for (const node of dfs(graph, 'a')) {
+  /* depth-first */
+}
+
+hasPath(graph, 'a', 'c'); // reachability
+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
+getPageRank(graph); // link analysis scores
+getLabelPropagationCommunities(graph); // community detection
+[...genGirvanNewmanCommunities(graph)]; // lazy community splits
+getBridges(graph); // bridge edges
+isIsomorphic(graph, otherGraph); // structural equivalence
 ```
 
 ## Diff & Walks
@@ -205,10 +244,10 @@ import { fromGEXF } from '@statelyai/graph/gexf';
 import { toCytoscapeJSON } from '@statelyai/graph/cytoscape';
 import { toD3Graph } from '@statelyai/graph/d3';
 
-const dot = toDOT(graph);                   // Graphviz DOT
-const cytoData = toCytoscapeJSON(graph);     // Cytoscape.js JSON
-const d3Data = toD3Graph(graph);             // D3.js { nodes, links }
-const imported = fromGEXF(gexfXmlString);    // GEXF (Gephi)
+const dot = toDOT(graph); // Graphviz DOT
+const cytoData = toCytoscapeJSON(graph); // Cytoscape.js JSON
+const d3Data = toD3Graph(graph); // D3.js { nodes, links }
+const imported = fromGEXF(gexfXmlString); // GEXF (Gephi)
 ```
 
 <!-- supported format adapters derived from src/formats/* subdirectories -->
@@ -224,6 +263,33 @@ const cyto = cytoscapeConverter.to(graph);
 const back = cytoscapeConverter.from(cyto);
 ```
 
+## Format Support
+
+<!-- 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    | partial | partial    | Ports round-trip through element data.                                     |
+| `d3`                | none      | full    | partial | partial    | Ports round-trip through node/link objects.                                |
+| `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    | partial    | Best for layout exchange.                                                  |
+| `gexf`              | full      | full    | partial | partial    | Ports round-trip via custom attributes.                                    |
+| `gml`               | full      | full    | partial | partial    | Ports round-trip through JSON-stringified metadata.                        |
+| `graphml`           | full      | full    | partial | partial    | Ports round-trip through `<data>` fields.                                  |
+| `jgf`               | full      | full    | none    | partial    | Ports round-trip through metadata.                                         |
+| `tgf`               | none      | none    | none    | partial    | Minimal ids and labels only.                                               |
+| `xyflow`            | none      | full    | full    | partial    | Ports map directly to handles.                                             |
+| `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    | State notes are still lossy.                                               |
+
 Some formats have optional peer dependencies: `fast-xml-parser` (GEXF, GraphML) and `dotparser` (DOT). All other formats are dependency-free.
 
 Format-specific docs live alongside the source:

package/dist/format-support.mjs

@@ -21,14 +21,14 @@ const FORMAT_SUPPORT_MATRIX = [
 		features: {
 			directed: "full",
 			undirected: "full",
-			hierarchy: "partial",
-			ports: "none",
+			hierarchy: "full",
+			ports: "full",
 			visual: "partial",
 			style: "partial",
 			weight: "full",
 			roundTrip: "partial"
 		},
-		notes: ["Uses Cytoscape JSON element data with partial layout/style fidelity."]
+		notes: ["Uses Cytoscape JSON element data with partial layout/style fidelity.", "Ports round-trip through element data as `ports`, `sourcePort`, and `targetPort`."]
 	},
 	{
 		id: "d3",
@@ -37,13 +37,13 @@ const FORMAT_SUPPORT_MATRIX = [
 			directed: "full",
 			undirected: "full",
 			hierarchy: "none",
-			ports: "none",
+			ports: "full",
 			visual: "partial",
 			style: "none",
 			weight: "full",
 			roundTrip: "partial"
 		},
-		notes: ["Targets force-graph structures, not compound graph metadata."]
+		notes: ["Targets force-graph structures, not compound graph metadata.", "Ports round-trip through node/link objects."]
 	},
 	{
 		id: "dot",
@@ -58,7 +58,7 @@ const FORMAT_SUPPORT_MATRIX = [
 			weight: "none",
 			roundTrip: "partial"
 		},
-		notes: ["Port syntax (`:port:compass`) is not fully mapped.", "HTML labels and layout hints beyond `rankdir` are lossy."]
+		notes: ["Edge port ids round-trip, but compass points and node port definitions are not mapped.", "HTML labels and layout hints beyond `rankdir` are lossy."]
 	},
 	{
 		id: "edge-list",
@@ -96,14 +96,14 @@ const FORMAT_SUPPORT_MATRIX = [
 		features: {
 			directed: "full",
 			undirected: "full",
-			hierarchy: "none",
-			ports: "none",
+			hierarchy: "full",
+			ports: "full",
 			visual: "partial",
 			style: "partial",
 			weight: "full",
 			roundTrip: "partial"
 		},
-		notes: ["Attribute and viz extensions round-trip partially."]
+		notes: ["Attribute and viz extensions round-trip partially.", "Ports round-trip via custom node/edge attributes."]
 	},
 	{
 		id: "gml",
@@ -111,14 +111,14 @@ const FORMAT_SUPPORT_MATRIX = [
 		features: {
 			directed: "full",
 			undirected: "full",
-			hierarchy: "none",
-			ports: "none",
+			hierarchy: "full",
+			ports: "full",
 			visual: "partial",
 			style: "partial",
 			weight: "full",
 			roundTrip: "partial"
 		},
-		notes: ["GML support focuses on common graph/node/edge attributes."]
+		notes: ["GML support focuses on common graph/node/edge attributes.", "Ports round-trip through JSON-stringified node metadata and edge fields."]
 	},
 	{
 		id: "graphml",
@@ -126,14 +126,14 @@ const FORMAT_SUPPORT_MATRIX = [
 		features: {
 			directed: "full",
 			undirected: "full",
-			hierarchy: "none",
-			ports: "none",
+			hierarchy: "full",
+			ports: "full",
 			visual: "partial",
 			style: "partial",
 			weight: "full",
 			roundTrip: "partial"
 		},
-		notes: ["GraphML attribute fidelity is good, but not every extension is represented."]
+		notes: ["GraphML attribute fidelity is good, but not every extension is represented.", "Ports round-trip through node and edge `<data>` fields."]
 	},
 	{
 		id: "jgf",
@@ -141,14 +141,14 @@ const FORMAT_SUPPORT_MATRIX = [
 		features: {
 			directed: "full",
 			undirected: "full",
-			hierarchy: "none",
-			ports: "none",
+			hierarchy: "full",
+			ports: "full",
 			visual: "none",
 			style: "none",
 			weight: "full",
 			roundTrip: "partial"
 		},
-		notes: ["JGF preserves core graph structure and data, but not layout primitives."]
+		notes: ["JGF preserves core graph structure and data, but not layout primitives.", "Ports round-trip through node and edge metadata."]
 	},
 	{
 		id: "tgf",

package/dist/formats/cytoscape/index.mjs

@@ -38,6 +38,7 @@ function toCytoscapeJSON(graph) {
 				if (n.height !== void 0) data.height = n.height;
 				if (n.shape) data.shape = n.shape;
 				if (n.color) data.color = n.color;
+				if (n.ports !== void 0) data.ports = n.ports;
 				const node = { data };
 				if (n.x !== void 0 && n.y !== void 0) node.position = {
 					x: n.x,
@@ -54,6 +55,8 @@ function toCytoscapeJSON(graph) {
 				if (e.label) data.label = e.label;
 				if (e.data !== void 0) data.edgeData = e.data;
 				if (e.color) data.color = e.color;
+				if (e.sourcePort !== void 0) data.sourcePort = e.sourcePort;
+				if (e.targetPort !== void 0) data.targetPort = e.targetPort;
 				return { data };
 			})
 		}
@@ -99,7 +102,8 @@ function fromCytoscapeJSON(cyto) {
 			...n.data.width !== void 0 && { width: n.data.width },
 			...n.data.height !== void 0 && { height: n.data.height },
 			...n.data.shape && { shape: n.data.shape },
-			...n.data.color && { color: n.data.color }
+			...n.data.color && { color: n.data.color },
+			...n.data.ports !== void 0 && { ports: n.data.ports }
 		})),
 		edges: cyto.elements.edges.map((e, i) => ({
 			type: "edge",
@@ -108,7 +112,9 @@ function fromCytoscapeJSON(cyto) {
 			targetId: e.data.target,
 			label: e.data.label ?? "",
 			data: e.data.edgeData,
-			...e.data.color && { color: e.data.color }
+			...e.data.color && { color: e.data.color },
+			...e.data.sourcePort !== void 0 && { sourcePort: e.data.sourcePort },
+			...e.data.targetPort !== void 0 && { targetPort: e.data.targetPort }
 		}))
 	};
 }

package/dist/formats/d3/index.mjs

@@ -28,6 +28,7 @@ function toD3Graph(graph) {
 			if (n.y !== void 0) node.y = n.y;
 			if (n.color) node.color = n.color;
 			if (n.shape) node.shape = n.shape;
+			if (n.ports !== void 0) node.ports = n.ports;
 			return node;
 		}),
 		links: graph.edges.map((e) => {
@@ -39,6 +40,8 @@ function toD3Graph(graph) {
 			if (e.label) link.label = e.label;
 			if (e.data !== void 0) link.data = e.data;
 			if (e.color) link.color = e.color;
+			if (e.sourcePort !== void 0) link.sourcePort = e.sourcePort;
+			if (e.targetPort !== void 0) link.targetPort = e.targetPort;
 			return link;
 		})
 	};
@@ -75,7 +78,8 @@ function fromD3Graph(d3) {
 			...n.x !== void 0 && { x: n.x },
 			...n.y !== void 0 && { y: n.y },
 			...n.color && { color: n.color },
-			...n.shape && { shape: n.shape }
+			...n.shape && { shape: n.shape },
+			...n.ports !== void 0 && { ports: n.ports }
 		})),
 		edges: d3.links.map((l, i) => ({
 			type: "edge",
@@ -84,7 +88,9 @@ function fromD3Graph(d3) {
 			targetId: typeof l.target === "string" ? l.target : l.target.id,
 			label: l.label ?? "",
 			data: l.data,
-			...l.color && { color: l.color }
+			...l.color && { color: l.color },
+			...l.sourcePort !== void 0 && { sourcePort: l.sourcePort },
+			...l.targetPort !== void 0 && { targetPort: l.targetPort }
 		}))
 	};
 }

package/dist/formats/dot/index.mjs

@@ -11,6 +11,9 @@ function escapeId(id) {
 function escapeLabel(label) {
 	return label.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
 }
+function formatEndpoint(id, port) {
+	return `${escapeId(id)}${port ? `:${escapeId(port)}` : ""}`;
+}
 const DIRECTION_TO_RANKDIR = {
 	down: "TB",
 	up: "BT",
@@ -72,7 +75,7 @@ function toDOT(graph) {
 		if (edge.label) attrs.push(`label="${escapeLabel(edge.label)}"`);
 		if (edge.color) attrs.push(`color="${escapeLabel(edge.color)}"`);
 		const attrStr = attrs.length > 0 ? ` [${attrs.join(", ")}]` : "";
-		lines.push(`  ${escapeId(edge.sourceId)} ${edgeOp} ${escapeId(edge.targetId)}${attrStr};`);
+		lines.push(`  ${formatEndpoint(edge.sourceId, edge.sourcePort)} ${edgeOp} ${formatEndpoint(edge.targetId, edge.targetPort)}${attrStr};`);
 	}
 	lines.push("}");
 	return lines.join("\n");
@@ -95,6 +98,10 @@ const DOT_TO_SHAPE = {
 	cylinder: "cylinder",
 	parallelogram: "parallelogram"
 };
+function getPortId(nodeId) {
+	const port = nodeId.port;
+	return typeof port?.id === "string" ? port.id : void 0;
+}
 function attrsToMap(attrList) {
 	const map = {};
 	for (const a of attrList) map[a.id] = String(a.eq);
@@ -209,24 +216,29 @@ function fromDOT(dot) {
 				const endpointGroups = [];
 				for (const item of stmt.edge_list) if (item.type === "node_id") {
 					ensureNode(item.id, parentId, nd);
-					endpointGroups.push([item.id]);
+					endpointGroups.push([{
+						id: item.id,
+						...getPortId(item) && { port: getPortId(item) }
+					}]);
 				} else if (item.type === "subgraph") {
 					walkChildren(item.children, parentId, nd, ed);
 					const subNodeIds = getNodeIdsFromSubgraph(item.children);
 					for (const subNodeId of subNodeIds) ensureNode(subNodeId, parentId, nd);
-					if (subNodeIds.length > 0) endpointGroups.push(subNodeIds);
+					if (subNodeIds.length > 0) endpointGroups.push(subNodeIds.map((id) => ({ id })));
 				}
 				for (let i = 0; i < endpointGroups.length - 1; i++) {
 					const left = endpointGroups[i];
 					const right = endpointGroups[i + 1];
-					for (const sourceId of left) for (const targetId of right) {
+					for (const source of left) for (const target of right) {
 						const edge = {
 							type: "edge",
 							id: `e${edgeIdx++}`,
-							sourceId,
-							targetId,
+							sourceId: source.id,
+							targetId: target.id,
 							label: mergedEdgeAttrs["label"] ?? "",
 							data: void 0,
+							...source.port && { sourcePort: source.port },
+							...target.port && { targetPort: target.port },
 							...mergedEdgeAttrs["color"] && { color: mergedEdgeAttrs["color"] }
 						};
 						edges.push(edge);

package/dist/formats/gexf/index.mjs

@@ -23,13 +23,30 @@ function toGEXF(graph) {
 			"@_id": "a_shape",
 			"@_title": "shape",
 			"@_type": "string"
+		},
+		{
+			"@_id": "a_ports",
+			"@_title": "ports",
+			"@_type": "string"
+		}
+	];
+	const edgeAttrs = [
+		{
+			"@_id": "a_edgeData",
+			"@_title": "data",
+			"@_type": "string"
+		},
+		{
+			"@_id": "a_sourcePort",
+			"@_title": "sourcePort",
+			"@_type": "string"
+		},
+		{
+			"@_id": "a_targetPort",
+			"@_title": "targetPort",
+			"@_type": "string"
 		}
 	];
-	const edgeAttrs = [{
-		"@_id": "a_edgeData",
-		"@_title": "data",
-		"@_type": "string"
-	}];
 	const nodes = graph.nodes.map((n) => {
 		const attvalues = [];
 		if (n.parentId) attvalues.push({
@@ -48,6 +65,10 @@ function toGEXF(graph) {
 			"@_for": "a_shape",
 			"@_value": n.shape
 		});
+		if (n.ports !== void 0) attvalues.push({
+			"@_for": "a_ports",
+			"@_value": JSON.stringify(n.ports)
+		});
 		const node = {
 			"@_id": n.id,
 			"@_label": n.label || n.id
@@ -80,6 +101,16 @@ function toGEXF(graph) {
 			"@_for": "a_edgeData",
 			"@_value": JSON.stringify(e.data)
 		}] };
+		const edgeAttvalues = edge.attvalues?.attvalue ?? [];
+		if (e.sourcePort !== void 0) edgeAttvalues.push({
+			"@_for": "a_sourcePort",
+			"@_value": e.sourcePort
+		});
+		if (e.targetPort !== void 0) edgeAttvalues.push({
+			"@_for": "a_targetPort",
+			"@_value": e.targetPort
+		});
+		if (edgeAttvalues.length > 0) edge.attvalues = { attvalue: edgeAttvalues };
 		if (e.color) {
 			const hex$1 = e.color.replace("#", "");
 			if (hex$1.length === 6) edge["viz:color"] = {
@@ -90,15 +121,6 @@ function toGEXF(graph) {
 		}
 		return edge;
 	});
-	const graphData = [];
-	if (graph.initialNodeId) graphData.push({
-		"@_for": "a_initialNodeId",
-		"@_value": graph.initialNodeId
-	});
-	if (graph.data !== void 0) graphData.push({
-		"@_for": "a_data",
-		"@_value": JSON.stringify(graph.data)
-	});
 	const obj = {
 		"?xml": {
 			"@_version": "1.0",
@@ -111,6 +133,9 @@ function toGEXF(graph) {
 			graph: {
 				"@_defaultedgetype": graph.type === "directed" ? "directed" : "undirected",
 				...graph.id && { "@_id": graph.id },
+				...graph.initialNodeId && { "@_initialNodeId": graph.initialNodeId },
+				...graph.direction && { "@_direction": graph.direction },
+				...graph.data !== void 0 && { "@_data": JSON.stringify(graph.data) },
 				attributes: [{
 					"@_class": "node",
 					attribute: nodeAttrs
@@ -168,6 +193,7 @@ function fromGEXF(xml) {
 				data: attvals["data"] !== void 0 ? tryParseJSON(attvals["data"]) : void 0
 			};
 			if (attvals["shape"]) node.shape = attvals["shape"];
+			if (attvals["ports"] !== void 0) node.ports = tryParseJSON(attvals["ports"]);
 			const pos = n["viz:position"];
 			if (pos) {
 				node.x = Number(pos["@_x"] ?? 0);
@@ -199,7 +225,9 @@ function fromGEXF(xml) {
 			sourceId: String(e["@_source"]),
 			targetId: String(e["@_target"]),
 			label: e["@_label"] ?? "",
-			data: attvals["data"] !== void 0 ? tryParseJSON(attvals["data"]) : void 0
+			data: attvals["data"] !== void 0 ? tryParseJSON(attvals["data"]) : void 0,
+			...attvals["sourcePort"] !== void 0 && { sourcePort: attvals["sourcePort"] },
+			...attvals["targetPort"] !== void 0 && { targetPort: attvals["targetPort"] }
 		};
 		const color = e["viz:color"];
 		if (color) {
@@ -213,10 +241,11 @@ function fromGEXF(xml) {
 	return {
 		id: String(graphEl["@_id"] ?? ""),
 		type: graphType,
-		initialNodeId: null,
+		initialNodeId: graphEl["@_initialNodeId"] ?? null,
 		nodes,
 		edges,
-		data: void 0
+		data: graphEl["@_data"] !== void 0 ? tryParseJSON(String(graphEl["@_data"])) : void 0,
+		...graphEl["@_direction"] && { direction: graphEl["@_direction"] }
 	};
 }
 function asArray(val) {

package/dist/formats/gml/index.mjs

@@ -40,6 +40,7 @@ function toGML(graph) {
 		if (node.label) lines.push(`${indent}  label ${gmlString(node.label)}`);
 		if (node.initialNodeId) lines.push(`${indent}  initialNodeId ${gmlString(node.initialNodeId)}`);
 		if (node.data !== void 0) lines.push(`${indent}  data ${gmlString(JSON.stringify(node.data))}`);
+		if (node.ports !== void 0) lines.push(`${indent}  ports ${gmlString(JSON.stringify(node.ports))}`);
 		if (node.shape) lines.push(`${indent}  shape ${gmlString(node.shape)}`);
 		if (node.color) lines.push(`${indent}  color ${gmlString(node.color)}`);
 		if (node.x !== void 0 || node.y !== void 0 || node.width !== void 0 || node.height !== void 0) {
@@ -63,6 +64,8 @@ function toGML(graph) {
 		lines.push(`    target ${gmlString(edge.targetId)}`);
 		if (edge.label) lines.push(`    label ${gmlString(edge.label)}`);
 		if (edge.data !== void 0) lines.push(`    data ${gmlString(JSON.stringify(edge.data))}`);
+		if (edge.sourcePort !== void 0) lines.push(`    sourcePort ${gmlString(edge.sourcePort)}`);
+		if (edge.targetPort !== void 0) lines.push(`    targetPort ${gmlString(edge.targetPort)}`);
 		if (edge.color) lines.push(`    color ${gmlString(edge.color)}`);
 		lines.push("  ]");
 	}
@@ -112,6 +115,7 @@ function fromGML(gml) {
 				initialNodeId: n["initialNodeId"] ?? null,
 				label: n["label"] ?? "",
 				data: n["data"] !== void 0 ? tryParseJSON(n["data"]) : void 0,
+				...n["ports"] !== void 0 && { ports: tryParseJSON(n["ports"]) },
 				...n["shape"] && { shape: n["shape"] },
 				...n["color"] && { color: n["color"] },
 				...gfx?.x !== void 0 && { x: gfx.x },
@@ -131,6 +135,8 @@ function fromGML(gml) {
 		targetId: String(e["target"] ?? ""),
 		label: e["label"] ?? "",
 		data: e["data"] !== void 0 ? tryParseJSON(e["data"]) : void 0,
+		...e["sourcePort"] !== void 0 && { sourcePort: String(e["sourcePort"]) },
+		...e["targetPort"] !== void 0 && { targetPort: String(e["targetPort"]) },
 		...e["color"] && { color: e["color"] }
 	});
 	return {

package/dist/formats/jgf/index.mjs

@@ -38,6 +38,7 @@ function toJGF(graph) {
 			if (n.height !== void 0) meta.height = n.height;
 			if (n.shape) meta.shape = n.shape;
 			if (n.color) meta.color = n.color;
+			if (n.ports !== void 0) meta.ports = n.ports;
 			return {
 				id: n.id,
 				...n.label && { label: n.label },
@@ -48,6 +49,8 @@ function toJGF(graph) {
 			const meta = {};
 			if (e.data !== void 0) meta.data = e.data;
 			if (e.color) meta.color = e.color;
+			if (e.sourcePort !== void 0) meta.sourcePort = e.sourcePort;
+			if (e.targetPort !== void 0) meta.targetPort = e.targetPort;
 			return {
 				id: e.id,
 				source: e.sourceId,
@@ -98,7 +101,8 @@ function fromJGF(jgf) {
 			...n.metadata?.width !== void 0 && { width: n.metadata.width },
 			...n.metadata?.height !== void 0 && { height: n.metadata.height },
 			...n.metadata?.shape && { shape: n.metadata.shape },
-			...n.metadata?.color && { color: n.metadata.color }
+			...n.metadata?.color && { color: n.metadata.color },
+			...n.metadata?.ports !== void 0 && { ports: n.metadata.ports }
 		})),
 		edges: g.edges.map((e, i) => ({
 			type: "edge",
@@ -107,7 +111,9 @@ function fromJGF(jgf) {
 			targetId: e.target,
 			label: e.label ?? "",
 			data: e.metadata?.data,
-			...e.metadata?.color && { color: e.metadata.color }
+			...e.metadata?.color && { color: e.metadata.color },
+			...e.metadata?.sourcePort !== void 0 && { sourcePort: e.metadata.sourcePort },
+			...e.metadata?.targetPort !== void 0 && { targetPort: e.metadata.targetPort }
 		}))
 	};
 }

package/dist/schemas.d.mts

@@ -1,3 +1,4 @@
+import { g as GraphNode, p as GraphEdge, u as Graph, y as GraphPort } from "./types-CnZ01raw.mjs";
 import * as z from "zod";
 
 //#region src/schemas.d.ts
@@ -126,5 +127,18 @@ declare const GraphSchema: z.ZodObject<{
   }>>;
   style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
 }, z.core.$strip>;
+interface GraphValidationIssue {
+  code: string;
+  message: string;
+  path: Array<string | number>;
+}
+declare function isGraphPort(value: unknown): value is GraphPort;
+declare function isGraphNode(value: unknown): value is GraphNode;
+declare function isGraphEdge(value: unknown): value is GraphEdge;
+declare function isGraph(value: unknown): value is Graph;
+declare function getGraphPortIssues(value: unknown): GraphValidationIssue[];
+declare function getGraphNodeIssues(value: unknown): GraphValidationIssue[];
+declare function getGraphEdgeIssues(value: unknown): GraphValidationIssue[];
+declare function getGraphIssues(value: unknown): GraphValidationIssue[];
 //#endregion
-export { EdgeSchema, GraphSchema, NodeSchema, PortSchema };
+export { EdgeSchema, GraphSchema, GraphValidationIssue, NodeSchema, PortSchema, getGraphEdgeIssues, getGraphIssues, getGraphNodeIssues, getGraphPortIssues, isGraph, isGraphEdge, isGraphNode, isGraphPort };

package/dist/schemas.mjs

@@ -66,6 +66,39 @@ const GraphSchema = z.object({
 	]).optional(),
 	style: StyleSchema.optional()
 });
+function getValidationIssues(schema, value) {
+	const result = schema.safeParse(value);
+	if (result.success) return [];
+	return result.error.issues.map((issue) => ({
+		code: issue.code,
+		message: issue.message,
+		path: issue.path.map((segment) => typeof segment === "symbol" ? String(segment) : segment)
+	}));
+}
+function isGraphPort(value) {
+	return PortSchema.safeParse(value).success;
+}
+function isGraphNode(value) {
+	return NodeSchema.safeParse(value).success;
+}
+function isGraphEdge(value) {
+	return EdgeSchema.safeParse(value).success;
+}
+function isGraph(value) {
+	return GraphSchema.safeParse(value).success;
+}
+function getGraphPortIssues(value) {
+	return getValidationIssues(PortSchema, value);
+}
+function getGraphNodeIssues(value) {
+	return getValidationIssues(NodeSchema, value);
+}
+function getGraphEdgeIssues(value) {
+	return getValidationIssues(EdgeSchema, value);
+}
+function getGraphIssues(value) {
+	return getValidationIssues(GraphSchema, value);
+}
 
 //#endregion
-export { EdgeSchema, GraphSchema, NodeSchema, PortSchema };
+export { EdgeSchema, GraphSchema, NodeSchema, PortSchema, getGraphEdgeIssues, getGraphIssues, getGraphNodeIssues, getGraphPortIssues, isGraph, isGraphEdge, isGraphNode, isGraphPort };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@statelyai/graph",
   "type": "module",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "A TypeScript-first graph library with plain JSON-serializable objects",
   "author": "David Khourshid <david@stately.ai>",
   "license": "MIT",