@statelyai/graph 0.11.0 → 0.12.0

package/README.md

@@ -12,14 +12,16 @@ npm install @statelyai/graph
 
 Optional peers are only needed for specific adapters:
 
-| Package | Needed for |
-| --- | --- |
+<!-- 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` |
+| `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
 
@@ -37,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: [
@@ -64,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.
@@ -90,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
@@ -133,33 +145,68 @@ 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
 
-Includes traversal (BFS, DFS), pathfinding (shortest path, simple paths, all-pairs shortest paths), 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.
+<!-- 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.
 
 ```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
@@ -197,13 +244,15 @@ 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 formats:** Cytoscape.js JSON, D3.js JSON, JSON Graph Format, GEXF, GraphML, GML, TGF, DOT, Mermaid (flowchart, state, sequence, class, ER, mindmap, block), adjacency list, and edge list.
+<!-- 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.
 
 Each bidirectional format also has a converter object:
 
@@ -214,23 +263,58 @@ 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:
 
+<!-- format README files under src/formats/*/README.md -->
+
+- [Adjacency list](./src/formats/adjacency-list/README.md)
+- [Cytoscape](./src/formats/cytoscape/README.md)
+- [D3](./src/formats/d3/README.md)
 - [DOT](./src/formats/dot/README.md)
-- [GraphML](./src/formats/graphml/README.md)
+- [Edge list](./src/formats/edge-list/README.md)
+- [ELK](./src/formats/elk/README.md)
 - [GEXF](./src/formats/gexf/README.md)
 - [GML](./src/formats/gml/README.md)
+- [GraphML](./src/formats/graphml/README.md)
 - [JGF](./src/formats/jgf/README.md)
-- [TGF](./src/formats/tgf/README.md)
-- [Cytoscape](./src/formats/cytoscape/README.md)
-- [D3](./src/formats/d3/README.md)
 - [Mermaid](./src/formats/mermaid/README.md)
+- [TGF](./src/formats/tgf/README.md)
+- [xyflow](./src/formats/xyflow/README.md)
 - [Converter helpers](./src/formats/converter/README.md)
 
 ## Examples
 
+<!-- runnable example files under examples/ -->
+
 The repo includes runnable examples under [`examples/`](./examples):
 
 - [Flow-based math](./examples/flow-based-math.ts) shows ports, topological ordering, and value propagation.
@@ -238,6 +322,8 @@ The repo includes runnable examples under [`examples/`](./examples):
 
 ## Development
 
+<!-- dev commands from package.json#scripts -->
+
 ```bash
 pnpm install
 pnpm verify

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",
@@ -240,6 +240,21 @@ const FORMAT_SUPPORT_MATRIX = [
 		},
 		notes: ["Index-based `linkStyle` metadata is fragile after graph mutation.", "Mermaid init directives are not fully preserved."]
 	},
+	{
+		id: "mermaid/ishikawa",
+		importPath: "@statelyai/graph/mermaid",
+		features: {
+			directed: "full",
+			undirected: "none",
+			hierarchy: "full",
+			ports: "none",
+			visual: "none",
+			style: "none",
+			weight: "none",
+			roundTrip: "partial"
+		},
+		notes: ["Indentation is preserved as hierarchy; renderer-specific fishbone layout is not represented."]
+	},
 	{
 		id: "mermaid/mindmap",
 		importPath: "@statelyai/graph/mermaid",

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) {