@statelyai/graph 0.7.0 → 0.9.0

package/dist/formats/edge-list/index.d.mts

@@ -1,4 +1,4 @@
-import { u as Graph } from "../../types-DkKjaQW3.mjs";
+import { u as Graph } from "../../types-BzckPChi.mjs";
 
 //#region src/formats/edge-list/index.d.ts
 

package/dist/formats/elk/index.d.mts

@@ -1,4 +1,4 @@
-import { D as VisualGraph, k as VisualGraphFormatConverter } from "../../types-DkKjaQW3.mjs";
+import { F as VisualGraphFormatConverter, M as VisualGraph } from "../../types-BzckPChi.mjs";
 import { ElkEdge, ElkEdgeSection, ElkExtendedEdge, ElkGraphElement, ElkLabel, ElkNode, ElkNode as ElkNode$1, ElkPoint, ElkPort, ElkPrimitiveEdge, ElkShape, LayoutOptions } from "elkjs/lib/elk-api";
 
 //#region src/formats/elk/index.d.ts

package/dist/formats/elk/index.mjs

@@ -16,12 +16,24 @@ const ELK_TO_DIRECTION = {
 function convertEdge(edge) {
 	const elkEdge = {
 		id: edge.id,
-		sources: [edge.sourceId],
-		targets: [edge.targetId]
+		sources: [edge.sourcePort ?? edge.sourceId],
+		targets: [edge.targetPort ?? edge.targetId]
 	};
 	if (edge.label) elkEdge.labels = [{ text: edge.label }];
 	return elkEdge;
 }
+function convertPort(port) {
+	const elkPort = {
+		id: port.name,
+		x: port.x,
+		y: port.y,
+		width: port.width,
+		height: port.height
+	};
+	if (port.label) elkPort.labels = [{ text: port.label }];
+	if (port.direction !== "inout") elkPort.layoutOptions = { "org.eclipse.elk.port.side": port.direction === "in" ? "WEST" : "EAST" };
+	return elkPort;
+}
 function convertNode(graph, node) {
 	const elkNode = {
 		id: node.id,
@@ -31,6 +43,7 @@ function convertNode(graph, node) {
 		height: node.height
 	};
 	if (node.label) elkNode.labels = [{ text: node.label }];
+	if (node.ports && node.ports.length > 0) elkNode.ports = node.ports.map(convertPort);
 	const children = getChildren(graph, node.id);
 	if (children.length > 0) {
 		elkNode.children = children.map((child) => convertNode(graph, child));
@@ -84,7 +97,7 @@ function toELK(graph) {
 	if (rootEdges.length > 0) root.edges = rootEdges.map(convertEdge);
 	return root;
 }
-function flattenElkNodes(elkNode, parentId, nodes, edges, edgeIdx) {
+function flattenElkNodes(elkNode, parentId, nodes, edges, edgeIdx, portOwner) {
 	if (elkNode.children) for (const child of elkNode.children) {
 		const label = child.labels?.[0]?.text ?? "";
 		const node = {
@@ -99,15 +112,34 @@ function flattenElkNodes(elkNode, parentId, nodes, edges, edgeIdx) {
 			width: child.width ?? 0,
 			height: child.height ?? 0
 		};
+		if (child.ports && child.ports.length > 0) node.ports = child.ports.map((elkPort) => {
+			portOwner.set(elkPort.id, child.id);
+			const sideOpt = elkPort.layoutOptions?.["org.eclipse.elk.port.side"];
+			let direction = "inout";
+			if (sideOpt === "WEST") direction = "in";
+			else if (sideOpt === "EAST") direction = "out";
+			return {
+				name: elkPort.id,
+				direction,
+				label: elkPort.labels?.[0]?.text,
+				data: void 0,
+				x: elkPort.x ?? 0,
+				y: elkPort.y ?? 0,
+				width: elkPort.width ?? 0,
+				height: elkPort.height ?? 0
+			};
+		});
 		nodes.push(node);
-		flattenElkNodes(child, child.id, nodes, edges, edgeIdx);
+		flattenElkNodes(child, child.id, nodes, edges, edgeIdx, portOwner);
 	}
 	if (elkNode.edges) for (const elkEdge of elkNode.edges) for (const source of elkEdge.sources) for (const target of elkEdge.targets) {
+		const sourceNodeId = portOwner.get(source);
+		const targetNodeId = portOwner.get(target);
 		const edge = {
 			type: "edge",
 			id: elkEdge.id ?? `e${edgeIdx.value++}`,
-			sourceId: source,
-			targetId: target,
+			sourceId: sourceNodeId ?? source,
+			targetId: targetNodeId ?? target,
 			label: elkEdge.labels?.[0]?.text ?? "",
 			data: void 0,
 			x: 0,
@@ -115,6 +147,8 @@ function flattenElkNodes(elkNode, parentId, nodes, edges, edgeIdx) {
 			width: 0,
 			height: 0
 		};
+		if (sourceNodeId) edge.sourcePort = source;
+		if (targetNodeId) edge.targetPort = target;
 		edges.push(edge);
 	}
 }
@@ -141,7 +175,7 @@ function flattenElkNodes(elkNode, parentId, nodes, edges, edgeIdx) {
 function fromELK(elkRoot) {
 	const nodes = [];
 	const edges = [];
-	flattenElkNodes(elkRoot, null, nodes, edges, { value: 0 });
+	flattenElkNodes(elkRoot, null, nodes, edges, { value: 0 }, /* @__PURE__ */ new Map());
 	const seenEdges = /* @__PURE__ */ new Map();
 	for (const edge of edges) if (!seenEdges.has(edge.id)) seenEdges.set(edge.id, edge);
 	const elkDir = elkRoot.layoutOptions?.["elk.direction"];

package/dist/formats/gexf/index.d.mts

@@ -1,4 +1,4 @@
-import { m as GraphFormatConverter, u as Graph } from "../../types-DkKjaQW3.mjs";
+import { g as GraphFormatConverter, u as Graph } from "../../types-BzckPChi.mjs";
 
 //#region src/formats/gexf/index.d.ts
 declare function toGEXF(graph: Graph): string;

package/dist/formats/gml/index.d.mts

@@ -1,4 +1,4 @@
-import { m as GraphFormatConverter, u as Graph } from "../../types-DkKjaQW3.mjs";
+import { g as GraphFormatConverter, u as Graph } from "../../types-BzckPChi.mjs";
 
 //#region src/formats/gml/index.d.ts
 

package/dist/formats/graphml/index.d.mts

@@ -1,4 +1,4 @@
-import { m as GraphFormatConverter, u as Graph } from "../../types-DkKjaQW3.mjs";
+import { g as GraphFormatConverter, u as Graph } from "../../types-BzckPChi.mjs";
 
 //#region src/formats/graphml/index.d.ts
 declare function toGraphML(graph: Graph): string;

package/dist/formats/jgf/index.d.mts

@@ -1,4 +1,4 @@
-import { m as GraphFormatConverter, u as Graph } from "../../types-DkKjaQW3.mjs";
+import { g as GraphFormatConverter, u as Graph } from "../../types-BzckPChi.mjs";
 
 //#region src/formats/jgf/index.d.ts
 interface JGFNode {

package/dist/formats/mermaid/index.d.mts

@@ -1,4 +1,4 @@
-import { m as GraphFormatConverter, u as Graph } from "../../types-DkKjaQW3.mjs";
+import { g as GraphFormatConverter, u as Graph } from "../../types-BzckPChi.mjs";
 
 //#region src/formats/mermaid/sequence.d.ts
 interface SequenceNodeData {

package/dist/formats/tgf/index.d.mts

@@ -1,4 +1,4 @@
-import { m as GraphFormatConverter, u as Graph } from "../../types-DkKjaQW3.mjs";
+import { g as GraphFormatConverter, u as Graph } from "../../types-BzckPChi.mjs";
 
 //#region src/formats/tgf/index.d.ts
 

package/dist/formats/xyflow/index.d.mts

@@ -1,4 +1,4 @@
-import { D as VisualGraph, k as VisualGraphFormatConverter } from "../../types-DkKjaQW3.mjs";
+import { F as VisualGraphFormatConverter, M as VisualGraph } from "../../types-BzckPChi.mjs";
 import { EdgeBase, NodeBase } from "@xyflow/system";
 
 //#region src/formats/xyflow/index.d.ts

package/dist/formats/xyflow/index.mjs

@@ -42,6 +42,8 @@ function toXYFlow(graph) {
 				source: e.sourceId,
 				target: e.targetId
 			};
+			if (e.sourcePort) edge.sourceHandle = e.sourcePort;
+			if (e.targetPort) edge.targetHandle = e.targetPort;
 			if (e.data !== void 0) edge.data = e.data;
 			if (e.label) edge.data = {
 				...edge.data,
@@ -96,6 +98,8 @@ function fromXYFlow(flow) {
 			sourceId: e.source,
 			targetId: e.target,
 			label: e.data?.label?.toString() ?? "",
+			...e.sourceHandle && { sourcePort: e.sourceHandle },
+			...e.targetHandle && { targetPort: e.targetHandle },
 			data: e.data,
 			x: 0,
 			y: 0,

package/dist/index.d.mts

@@ -1,10 +1,20 @@
-import { A as VisualNode, C as SinglePathOptions, D as VisualGraph, E as VisualEdge, M as WalkOptions, N as WeightedWalkOptions, O as VisualGraphConfig, S as PathOptions, T as TraversalOptions, _ as GraphPath, a as EdgeChange, b as NodeChange, c as EntitiesUpdate, d as GraphConfig, f as GraphDiff, g as GraphPatch, h as GraphNode, i as DeleteNodeOptions, j as WalkContext, l as EntityRect, m as GraphFormatConverter, n as AllPairsShortestPathsOptions, o as EdgeConfig, p as GraphEdge, r as CoverageStats, s as EntitiesConfig, t as AStarOptions, u as Graph, v as GraphStep, w as TransitionOptions, x as NodeConfig, y as MSTOptions } from "./types-DkKjaQW3.mjs";
-import { bfs, dfs, genCycles, genPostorders, genPreorders, genShortestPaths, genSimplePaths, getAStarPath, getAllPairsShortestPaths, getConnectedComponents, getCycles, getMinimumSpanningTree, getPostorder, getPostorders, getPreorder, getPreorders, getShortestPath, getShortestPaths, getSimplePath, getSimplePaths, getStronglyConnectedComponents, getTopologicalSort, hasPath, isAcyclic, isConnected, isTree, joinPaths } from "./algorithms.mjs";
+import { A as TraversalOptions, B as WeightedWalkOptions, C as NodeChange, D as PortDirection, E as PortConfig, I as VisualNode, L as VisualPort, M as VisualGraph, N as VisualGraphConfig, O as SinglePathOptions, P as VisualGraphEntity, R as WalkContext, S as MSTOptions, T as PathOptions, _ as GraphNode, a as EdgeChange, b as GraphPort, c as EntitiesUpdate, d as GraphConfig, f as GraphDiff, g as GraphFormatConverter, h as GraphEntityConfig, i as DeleteNodeOptions, j as VisualEdge, k as TransitionOptions, l as EntityRect, m as GraphEntity, n as AllPairsShortestPathsOptions, o as EdgeConfig, p as GraphEdge, r as CoverageStats, s as EntitiesConfig, t as AStarOptions, u as Graph, v as GraphPatch, w as NodeConfig, x as GraphStep, y as GraphPath, z as WalkOptions } from "./types-BzckPChi.mjs";
+import { A as getArticulationPoints, B as HITSResult, C as hasPath, D as joinPaths, E as isTree, F as genGirvanNewmanCommunities, G as getEigenvectorCentrality, H as getBetweennessCentrality, I as getGirvanNewmanCommunities, J as getOutDegreeCentrality, K as getHITS, L as getGreedyModularityCommunities, M as getBridges, N as GirvanNewmanOptions, O as IsomorphismOptions, P as LabelPropagationOptions, R as getLabelPropagationCommunities, S as getTopologicalSort, T as isConnected, U as getClosenessCentrality, V as IterativeCentralityOptions, W as getDegreeCentrality, Y as getPageRank, _ as getShortestPath, a as genPreorders, b as getSimplePaths, c as getAStarPath, d as getCycles, f as getMinimumSpanningTree, g as getPreorders, h as getPreorder, i as genPostorders, j as getBiconnectedComponents, k as isIsomorphic, l as getAllPairsShortestPaths, m as getPostorders, n as dfs, o as genShortestPaths, p as getPostorder, q as getInDegreeCentrality, r as genCycles, s as genSimplePaths, t as bfs, u as getConnectedComponents, v as getShortestPaths, w as isAcyclic, x as getStronglyConnectedComponents, y as getSimplePath, z as getModularity } from "./algorithms-g2uWmPrb.mjs";
 import { createFormatConverter } from "./formats/converter/index.mjs";
-import { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf } from "./queries.mjs";
+import { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesByPort, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPort, getPorts, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf } from "./queries.mjs";
 
 //#region src/graph.d.ts
 
+/**
+ * Create a resolved graph port from a config. Fills in defaults.
+ *
+ * @example
+ * ```ts
+ * const port = createGraphPort({ name: 'output', direction: 'out' });
+ * // { name: 'output', direction: 'out', data: undefined }
+ * ```
+ */
+declare function createGraphPort<P = any>(config: PortConfig<P>): GraphPort<P>;
 /**
  * Create a resolved graph node from a config. Fills in defaults.
  *
@@ -14,7 +24,7 @@ import { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdge
  * // { type: 'node', id: 'a', label: '', data: { label: 'hi' } }
  * ```
  */
-declare function createGraphNode<T = any>(config: NodeConfig<T>): GraphNode<T>;
+declare function createGraphNode<N = any, P = any>(config: NodeConfig<N, P>): GraphNode<N, P>;
 /**
  * Create a resolved graph edge from a config. Fills in defaults.
  *
@@ -36,7 +46,7 @@ declare function createGraphEdge<T = any>(config: EdgeConfig<T>): GraphEdge<T>;
  * });
  * ```
  */
-declare function createGraph<N = any, E = any, G = any>(config?: GraphConfig<N, E, G>): Graph<N, E, G>;
+declare function createGraph<N = any, E = any, G = any, P = any>(config?: GraphConfig<N, E, G, P>): Graph<N, E, G, P>;
 /**
  * Create a visual graph with required position/size on all nodes and edges.
  *
@@ -49,7 +59,7 @@ declare function createGraph<N = any, E = any, G = any>(config?: GraphConfig<N,
  * // graph.nodes[0].x === 0
  * ```
  */
-declare function createVisualGraph<N = any, E = any, G = any>(config?: VisualGraphConfig<N, E, G>): VisualGraph<N, E, G>;
+declare function createVisualGraph<N = any, E = any, G = any, P = any>(config?: VisualGraphConfig<N, E, G, P>): VisualGraph<N, E, G, P>;
 /**
  * Create a graph by BFS exploration of a transition function.
  * Each unique state becomes a node; each (state, event) -> nextState becomes an edge.
@@ -139,7 +149,7 @@ declare function hasEdge(graph: Graph, id: string): boolean;
  * // graph.nodes.length === 1
  * ```
  */
-declare function addNode<N>(graph: Graph<N>, config: NodeConfig<N>): GraphNode<N>;
+declare function addNode<N, P = any>(graph: Graph<N, any, any, P>, config: NodeConfig<N, P>): GraphNode<N, P>;
 /**
  * **Mutable.** Add an edge to the graph. Mutates `graph.edges` in place.
  * @returns The resolved edge that was added.
@@ -195,7 +205,7 @@ declare function deleteEdge(graph: Graph, id: string): void;
  * // updated.label === 'new'
  * ```
  */
-declare function updateNode<N>(graph: Graph<N>, id: string, update: Partial<Omit<NodeConfig<N>, 'id'>>): GraphNode<N>;
+declare function updateNode<N, P = any>(graph: Graph<N, any, any, P>, id: string, update: Partial<Omit<NodeConfig<N, P>, 'id'>>): GraphNode<N, P>;
 /**
  * **Mutable.** Update an edge in place.
  * @returns The updated edge.
@@ -273,9 +283,9 @@ declare function updateEntities<N, E>(graph: Graph<N, E>, updates: EntitiesUpdat
  * instance.toJSON(); // plain Graph object
  * ```
  */
-declare class GraphInstance<N = any, E = any, G = any> {
-  graph: Graph<N, E, G>;
-  constructor(config?: GraphConfig<N, E, G>);
+declare class GraphInstance<N = any, E = any, G = any, P = any> {
+  graph: Graph<N, E, G, P>;
+  constructor(config?: GraphConfig<N, E, G, P>);
   /**
    * Wrap an existing plain graph object.
    *
@@ -286,26 +296,26 @@ declare class GraphInstance<N = any, E = any, G = any> {
    * instance.hasNode('a'); // true
    * ```
    */
-  static from<N = any, E = any, G = any>(graph: Graph<N, E, G>): GraphInstance<N, E, G>;
+  static from<N = any, E = any, G = any, P = any>(graph: Graph<N, E, G, P>): GraphInstance<N, E, G, P>;
   get id(): string;
   get type(): "directed" | "undirected";
-  get nodes(): GraphNode<N>[];
+  get nodes(): GraphNode<N, P>[];
   get edges(): GraphEdge<E>[];
   get data(): G;
-  getNode(id: string): GraphNode<N> | undefined;
+  getNode(id: string): GraphNode<N, any> | undefined;
   getEdge(id: string): GraphEdge<E> | undefined;
   hasNode(id: string): boolean;
   hasEdge(id: string): boolean;
-  addNode(config: NodeConfig<N>): GraphNode<N>;
+  addNode(config: NodeConfig<N, P>): GraphNode<N, P>;
   addEdge(config: EdgeConfig<E>): GraphEdge<E>;
   deleteNode(id: string, opts?: DeleteNodeOptions): void;
   deleteEdge(id: string): void;
-  updateNode(id: string, update: Partial<Omit<NodeConfig<N>, 'id'>>): GraphNode<N>;
+  updateNode(id: string, update: Partial<Omit<NodeConfig<N, P>, 'id'>>): GraphNode<N, P>;
   updateEdge(id: string, update: Partial<Omit<EdgeConfig<E>, 'id'>>): GraphEdge<E>;
-  addEntities(entities: EntitiesConfig<N, E>): void;
+  addEntities(entities: EntitiesConfig<N, E, P>): void;
   deleteEntities(ids: string | string[], opts?: DeleteNodeOptions): void;
-  updateEntities(updates: EntitiesUpdate<N, E>): void;
-  toJSON(): Graph<N, E, G>;
+  updateEntities(updates: EntitiesUpdate<N, E, P>): void;
+  toJSON(): Graph<N, E, G, P>;
 }
 //#endregion
 //#region src/indexing.d.ts
@@ -324,6 +334,57 @@ declare class GraphInstance<N = any, E = any, G = any> {
  */
 declare function invalidateIndex(graph: Graph): void;
 //#endregion
+//#region src/equivalence.d.ts
+declare const LAYOUT_KEYS: {
+  node: readonly ["x", "y", "width", "height", "style", "color", "shape"];
+  edge: readonly ["x", "y", "width", "height", "style", "color"];
+};
+/**
+ * Compare two entities on a given set of keys.
+ * If `keys` is omitted or empty, compares all own keys of `a`.
+ *
+ * @example
+ * ```ts
+ * import { createGraphNode, areEntitiesEqual, LAYOUT_KEYS } from '@statelyai/graph';
+ *
+ * const a = createGraphNode({ id: 'n1', label: 'hello', x: 0 });
+ * const b = createGraphNode({ id: 'n1', label: 'hello', x: 100 });
+ *
+ * areEntitiesEqual(a, b, LAYOUT_KEYS.node); // false (x differs)
+ * areEntitiesEqual(a, b, NON_LAYOUT_KEYS.node); // true
+ * areEntitiesEqual(a, b); // false (compares all keys)
+ * ```
+ */
+declare function areEntitiesEqual<T extends GraphNode | GraphEdge>(a: T, b: T, keys?: readonly (keyof T)[]): boolean;
+/**
+ * Compare two entities on layout keys only (position, size, style, color, shape).
+ *
+ * @example
+ * ```ts
+ * import { createGraphNode, isLayoutEqual } from '@statelyai/graph';
+ *
+ * const a = createGraphNode({ id: 'n1', x: 0, y: 0 });
+ * const b = createGraphNode({ id: 'n1', x: 100, y: 200 });
+ *
+ * isLayoutEqual(a, b); // false
+ * ```
+ */
+declare function isLayoutEqual<T extends GraphNode | GraphEdge>(a: T, b: T): boolean;
+/**
+ * Compare two entities on non-layout keys only (id, data, connections, labels, etc.).
+ *
+ * @example
+ * ```ts
+ * import { createGraphNode, isNonLayoutEqual } from '@statelyai/graph';
+ *
+ * const a = createGraphNode({ id: 'n1', label: 'hello', x: 0 });
+ * const b = createGraphNode({ id: 'n1', label: 'hello', x: 100 });
+ *
+ * isNonLayoutEqual(a, b); // true (layout changed, but non-layout didn't)
+ * ```
+ */
+declare function isNonLayoutEqual<T extends GraphNode | GraphEdge>(a: T, b: T): boolean;
+//#endregion
 //#region src/diff.d.ts
 /**
  * Compute a structured diff from graph `a` to graph `b` by matching IDs.
@@ -567,4 +628,4 @@ declare function getCoverage<N, E>(graph: Graph<N, E>, steps: GraphStep<N, E>[],
   from?: string;
 }): CoverageStats;
 //#endregion
-export { type AStarOptions, type AllPairsShortestPathsOptions, type CoverageStats, type DeleteNodeOptions, type EdgeChange, type EdgeConfig, type EntitiesConfig, type EntitiesUpdate, type Graph, type GraphConfig, type GraphDiff, type GraphEdge, type GraphFormatConverter, GraphInstance, type GraphNode, type GraphPatch, type GraphPath, type GraphStep, type MSTOptions, type NodeChange, type NodeConfig, type PathOptions, type EntityRect as Positioned, type SinglePathOptions, type TransitionOptions, type TraversalOptions, type VisualEdge, type VisualGraph, type VisualGraphConfig, type VisualNode, type WalkContext, type WalkOptions, type WeightedWalkOptions, addEdge, addEntities, addNode, applyPatches, bfs, createFormatConverter, createGraph, createGraphEdge, createGraphFromTransition, createGraphNode, createVisualGraph, deleteEdge, deleteEntities, deleteNode, dfs, flatten, genCycles, genPostorders, genPredefinedWalk, genPreorders, genQuickRandomWalk, genRandomWalk, genShortestPaths, genSimplePaths, genWeightedRandomWalk, getAStarPath, getAllPairsShortestPaths, getAncestors, getChildren, getConnectedComponents, getCoverage, getCycles, getDegree, getDepth, getDescendants, getDiff, getEdge, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getMinimumSpanningTree, getNeighbors, getNode, getOutDegree, getOutEdges, getParent, getPatches, getPostorder, getPostorders, getPredecessors, getPreorder, getPreorders, getRelativeDistance, getRelativeDistanceMap, getRoots, getShortestPath, getShortestPaths, getSiblings, getSimplePath, getSimplePaths, getSinks, getSources, getStronglyConnectedComponents, getSubgraph, getSuccessors, getTopologicalSort, hasEdge, hasNode, hasPath, invalidateIndex, invertDiff, isAcyclic, isCompound, isConnected, isEmptyDiff, isLeaf, isTree, joinPaths, reverseGraph, takeSteps, takeUntilEdge, takeUntilEdgeCoverage, takeUntilNode, takeUntilNodeCoverage, toDiff, toPatches, updateEdge, updateEntities, updateNode };
+export { type AStarOptions, type AllPairsShortestPathsOptions, type CoverageStats, type DeleteNodeOptions, type EdgeChange, type EdgeConfig, type EntitiesConfig, type EntitiesUpdate, type GirvanNewmanOptions, type Graph, type GraphConfig, type GraphDiff, type GraphEdge, type GraphEntity, type GraphEntityConfig, type GraphFormatConverter, GraphInstance, type GraphNode, type GraphPatch, type GraphPath, type GraphPort, type GraphStep, type HITSResult, type IsomorphismOptions, type IterativeCentralityOptions, LAYOUT_KEYS, type LabelPropagationOptions, type MSTOptions, type NodeChange, type NodeConfig, type PathOptions, type PortConfig, type PortDirection, type EntityRect as Positioned, type SinglePathOptions, type TransitionOptions, type TraversalOptions, type VisualEdge, type VisualGraph, type VisualGraphConfig, type VisualGraphEntity, type VisualNode, type VisualPort, type WalkContext, type WalkOptions, type WeightedWalkOptions, addEdge, addEntities, addNode, applyPatches, areEntitiesEqual, bfs, createFormatConverter, createGraph, createGraphEdge, createGraphFromTransition, createGraphNode, createGraphPort, createVisualGraph, deleteEdge, deleteEntities, deleteNode, dfs, flatten, genCycles, genGirvanNewmanCommunities, genPostorders, genPredefinedWalk, genPreorders, genQuickRandomWalk, genRandomWalk, genShortestPaths, genSimplePaths, genWeightedRandomWalk, getAStarPath, getAllPairsShortestPaths, getAncestors, getArticulationPoints, getBetweennessCentrality, getBiconnectedComponents, getBridges, getChildren, getClosenessCentrality, getConnectedComponents, getCoverage, getCycles, getDegree, getDegreeCentrality, getDepth, getDescendants, getDiff, getEdge, getEdgeBetween, getEdgesByPort, getEdgesOf, getEigenvectorCentrality, getGirvanNewmanCommunities, getGreedyModularityCommunities, getHITS, getInDegree, getInDegreeCentrality, getInEdges, getLCA, getLabelPropagationCommunities, getMinimumSpanningTree, getModularity, getNeighbors, getNode, getOutDegree, getOutDegreeCentrality, getOutEdges, getPageRank, getParent, getPatches, getPort, getPorts, getPostorder, getPostorders, getPredecessors, getPreorder, getPreorders, getRelativeDistance, getRelativeDistanceMap, getRoots, getShortestPath, getShortestPaths, getSiblings, getSimplePath, getSimplePaths, getSinks, getSources, getStronglyConnectedComponents, getSubgraph, getSuccessors, getTopologicalSort, hasEdge, hasNode, hasPath, invalidateIndex, invertDiff, isAcyclic, isCompound, isConnected, isEmptyDiff, isIsomorphic, isLayoutEqual, isLeaf, isNonLayoutEqual, isTree, joinPaths, reverseGraph, takeSteps, takeUntilEdge, takeUntilEdgeCoverage, takeUntilNode, takeUntilNodeCoverage, toDiff, toPatches, updateEdge, updateEntities, updateNode };

package/dist/index.mjs

@@ -1,8 +1,100 @@
 import { o as invalidateIndex, t as getIndex } from "./indexing-DyfgLuzw.mjs";
-import { A as addEntities, B as getEdge, C as hasPath, D as joinPaths, E as isTree, F as createGraphNode, G as updateEntities, H as hasEdge, I as createVisualGraph, K as updateNode, L as deleteEdge, M as createGraph, N as createGraphEdge, O as GraphInstance, P as createGraphFromTransition, R as deleteEntities, S as getTopologicalSort, T as isConnected, U as hasNode, V as getNode, W as updateEdge, _ as getShortestPath, a as genPreorders, b as getSimplePaths, c as getAStarPath, d as getCycles, f as getMinimumSpanningTree, g as getPreorders, h as getPreorder, i as genPostorders, j as addNode, k as addEdge, l as getAllPairsShortestPaths, m as getPostorders, n as dfs, o as genShortestPaths, p as getPostorder, r as genCycles, s as genSimplePaths, t as bfs, u as getConnectedComponents, v as getShortestPaths, w as isAcyclic, x as getStronglyConnectedComponents, y as getSimplePath, z as deleteNode } from "./algorithms-Dw5jEwDK.mjs";
-import { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf } from "./queries.mjs";
+import { $ as createGraphPort, A as getBiconnectedComponents, B as getEigenvectorCentrality, C as hasPath, D as joinPaths, E as isTree, F as getLabelPropagationCommunities, G as GraphInstance, H as getInDegreeCentrality, I as getModularity, J as addNode, K as addEdge, L as getBetweennessCentrality, M as genGirvanNewmanCommunities, N as getGirvanNewmanCommunities, O as isIsomorphic, P as getGreedyModularityCommunities, Q as createGraphNode, R as getClosenessCentrality, S as getTopologicalSort, T as isConnected, U as getOutDegreeCentrality, V as getHITS, W as getPageRank, X as createGraphEdge, Y as createGraph, Z as createGraphFromTransition, _ as getShortestPath, a as genPreorders, at as getNode, b as getSimplePaths, c as getAStarPath, ct as updateEdge, d as getCycles, et as createVisualGraph, f as getMinimumSpanningTree, g as getPreorders, h as getPreorder, i as genPostorders, it as getEdge, j as getBridges, k as getArticulationPoints, l as getAllPairsShortestPaths, lt as updateEntities, m as getPostorders, n as dfs, nt as deleteEntities, o as genShortestPaths, ot as hasEdge, p as getPostorder, q as addEntities, r as genCycles, rt as deleteNode, s as genSimplePaths, st as hasNode, t as bfs, tt as deleteEdge, u as getConnectedComponents, ut as updateNode, v as getShortestPaths, w as isAcyclic, x as getStronglyConnectedComponents, y as getSimplePath, z as getDegreeCentrality } from "./algorithms-3xvCxHzo.mjs";
+import { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesByPort, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPort, getPorts, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf } from "./queries.mjs";
 import { n as createFormatConverter } from "./converter-B5CUD0r9.mjs";
 
+//#region src/equivalence.ts
+/** Shallow-compare two values, returning true if they differ. */
+function differs$1(a, b) {
+	if (a === b) return false;
+	if (a == null || b == null) return a !== b;
+	if (typeof a === "object" && typeof b === "object") return JSON.stringify(a) !== JSON.stringify(b);
+	return true;
+}
+const LAYOUT_KEYS = {
+	node: [
+		"x",
+		"y",
+		"width",
+		"height",
+		"style",
+		"color",
+		"shape"
+	],
+	edge: [
+		"x",
+		"y",
+		"width",
+		"height",
+		"style",
+		"color"
+	]
+};
+const LAYOUT_KEY_SET = {
+	node: new Set(LAYOUT_KEYS.node),
+	edge: new Set(LAYOUT_KEYS.edge)
+};
+/**
+* Compare two entities on a given set of keys.
+* If `keys` is omitted or empty, compares all own keys of `a`.
+*
+* @example
+* ```ts
+* import { createGraphNode, areEntitiesEqual, LAYOUT_KEYS } from '@statelyai/graph';
+*
+* const a = createGraphNode({ id: 'n1', label: 'hello', x: 0 });
+* const b = createGraphNode({ id: 'n1', label: 'hello', x: 100 });
+*
+* areEntitiesEqual(a, b, LAYOUT_KEYS.node); // false (x differs)
+* areEntitiesEqual(a, b, NON_LAYOUT_KEYS.node); // true
+* areEntitiesEqual(a, b); // false (compares all keys)
+* ```
+*/
+function areEntitiesEqual(a, b, keys) {
+	const compareKeys = keys && keys.length > 0 ? keys : Object.keys(a);
+	for (const key of compareKeys) if (differs$1(a[key], b[key])) return false;
+	return true;
+}
+/**
+* Compare two entities on layout keys only (position, size, style, color, shape).
+*
+* @example
+* ```ts
+* import { createGraphNode, isLayoutEqual } from '@statelyai/graph';
+*
+* const a = createGraphNode({ id: 'n1', x: 0, y: 0 });
+* const b = createGraphNode({ id: 'n1', x: 100, y: 200 });
+*
+* isLayoutEqual(a, b); // false
+* ```
+*/
+function isLayoutEqual(a, b) {
+	return areEntitiesEqual(a, b, LAYOUT_KEYS[a.type]);
+}
+/**
+* Compare two entities on non-layout keys only (id, data, connections, labels, etc.).
+*
+* @example
+* ```ts
+* import { createGraphNode, isNonLayoutEqual } from '@statelyai/graph';
+*
+* const a = createGraphNode({ id: 'n1', label: 'hello', x: 0 });
+* const b = createGraphNode({ id: 'n1', label: 'hello', x: 100 });
+*
+* isNonLayoutEqual(a, b); // true (layout changed, but non-layout didn't)
+* ```
+*/
+function isNonLayoutEqual(a, b) {
+	const skip = LAYOUT_KEY_SET[a.type];
+	const keys = Object.keys(a);
+	for (let i = 0; i < keys.length; i++) {
+		if (skip.has(keys[i])) continue;
+		if (differs$1(a[keys[i]], b[keys[i]])) return false;
+	}
+	return true;
+}
+
+//#endregion
 //#region src/diff.ts
 function nodeToConfig$1(node) {
 	const config = { id: node.id };
@@ -813,4 +905,4 @@ function getCoverage(graph, steps, options) {
 }
 
 //#endregion
-export { GraphInstance, addEdge, addEntities, addNode, applyPatches, bfs, createFormatConverter, createGraph, createGraphEdge, createGraphFromTransition, createGraphNode, createVisualGraph, deleteEdge, deleteEntities, deleteNode, dfs, flatten, genCycles, genPostorders, genPredefinedWalk, genPreorders, genQuickRandomWalk, genRandomWalk, genShortestPaths, genSimplePaths, genWeightedRandomWalk, getAStarPath, getAllPairsShortestPaths, getAncestors, getChildren, getConnectedComponents, getCoverage, getCycles, getDegree, getDepth, getDescendants, getDiff, getEdge, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getMinimumSpanningTree, getNeighbors, getNode, getOutDegree, getOutEdges, getParent, getPatches, getPostorder, getPostorders, getPredecessors, getPreorder, getPreorders, getRelativeDistance, getRelativeDistanceMap, getRoots, getShortestPath, getShortestPaths, getSiblings, getSimplePath, getSimplePaths, getSinks, getSources, getStronglyConnectedComponents, getSubgraph, getSuccessors, getTopologicalSort, hasEdge, hasNode, hasPath, invalidateIndex, invertDiff, isAcyclic, isCompound, isConnected, isEmptyDiff, isLeaf, isTree, joinPaths, reverseGraph, takeSteps, takeUntilEdge, takeUntilEdgeCoverage, takeUntilNode, takeUntilNodeCoverage, toDiff, toPatches, updateEdge, updateEntities, updateNode };
+export { GraphInstance, LAYOUT_KEYS, addEdge, addEntities, addNode, applyPatches, areEntitiesEqual, bfs, createFormatConverter, createGraph, createGraphEdge, createGraphFromTransition, createGraphNode, createGraphPort, createVisualGraph, deleteEdge, deleteEntities, deleteNode, dfs, flatten, genCycles, genGirvanNewmanCommunities, genPostorders, genPredefinedWalk, genPreorders, genQuickRandomWalk, genRandomWalk, genShortestPaths, genSimplePaths, genWeightedRandomWalk, getAStarPath, getAllPairsShortestPaths, getAncestors, getArticulationPoints, getBetweennessCentrality, getBiconnectedComponents, getBridges, getChildren, getClosenessCentrality, getConnectedComponents, getCoverage, getCycles, getDegree, getDegreeCentrality, getDepth, getDescendants, getDiff, getEdge, getEdgeBetween, getEdgesByPort, getEdgesOf, getEigenvectorCentrality, getGirvanNewmanCommunities, getGreedyModularityCommunities, getHITS, getInDegree, getInDegreeCentrality, getInEdges, getLCA, getLabelPropagationCommunities, getMinimumSpanningTree, getModularity, getNeighbors, getNode, getOutDegree, getOutDegreeCentrality, getOutEdges, getPageRank, getParent, getPatches, getPort, getPorts, getPostorder, getPostorders, getPredecessors, getPreorder, getPreorders, getRelativeDistance, getRelativeDistanceMap, getRoots, getShortestPath, getShortestPaths, getSiblings, getSimplePath, getSimplePaths, getSinks, getSources, getStronglyConnectedComponents, getSubgraph, getSuccessors, getTopologicalSort, hasEdge, hasNode, hasPath, invalidateIndex, invertDiff, isAcyclic, isCompound, isConnected, isEmptyDiff, isIsomorphic, isLayoutEqual, isLeaf, isNonLayoutEqual, isTree, joinPaths, reverseGraph, takeSteps, takeUntilEdge, takeUntilEdgeCoverage, takeUntilNode, takeUntilNodeCoverage, toDiff, toPatches, updateEdge, updateEntities, updateNode };

package/dist/queries.d.mts

@@ -1,4 +1,4 @@
-import { h as GraphNode, p as GraphEdge, u as Graph } from "./types-DkKjaQW3.mjs";
+import { _ as GraphNode, b as GraphPort, p as GraphEdge, u as Graph } from "./types-BzckPChi.mjs";
 
 //#region src/queries.d.ts
 
@@ -454,5 +454,62 @@ declare function getSources<N>(graph: Graph<N>): GraphNode<N>[];
  * ```
  */
 declare function getSinks<N>(graph: Graph<N>): GraphNode<N>[];
+/**
+ * Get a port by name on a node, or `undefined` if not found.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{
+ *     id: 'a',
+ *     ports: [{ name: 'out', direction: 'out' }],
+ *   }],
+ * });
+ * getPort(graph, 'a', 'out'); // => { name: 'out', direction: 'out', ... }
+ * getPort(graph, 'a', 'missing'); // => undefined
+ * ```
+ */
+declare function getPort<P = any>(graph: Graph<any, any, any, P>, nodeId: string, portName: string): GraphPort<P> | undefined;
+/**
+ * Get all ports on a node. Returns `[]` if the node has no ports or doesn't exist.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{
+ *     id: 'a',
+ *     ports: [
+ *       { name: 'in', direction: 'in' },
+ *       { name: 'out', direction: 'out' },
+ *     ],
+ *   }],
+ * });
+ * getPorts(graph, 'a'); // => [port in, port out]
+ * ```
+ */
+declare function getPorts<P = any>(graph: Graph<any, any, any, P>, nodeId: string): GraphPort<P>[];
+/**
+ * Get all edges connected to a specific port on a node.
+ *
+ * Returns edges where:
+ * - `sourceId === nodeId && sourcePort === portName`, or
+ * - `targetId === nodeId && targetPort === portName`
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [
+ *     { id: 'a', ports: [{ name: 'out', direction: 'out' }] },
+ *     { id: 'b', ports: [{ name: 'in', direction: 'in' }] },
+ *   ],
+ *   edges: [{
+ *     id: 'e1', sourceId: 'a', targetId: 'b',
+ *     sourcePort: 'out', targetPort: 'in',
+ *   }],
+ * });
+ * getEdgesByPort(graph, 'a', 'out'); // => [edge e1]
+ * ```
+ */
+declare function getEdgesByPort<E = any>(graph: Graph<any, E>, nodeId: string, portName: string): GraphEdge<E>[];
 //#endregion
-export { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf };
+export { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, 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

@@ -679,6 +679,83 @@ function getSinks(graph) {
 	const idx = getIndex(graph);
 	return graph.nodes.filter((n) => (idx.outEdges.get(n.id)?.length ?? 0) === 0);
 }
+/**
+* Get a port by name on a node, or `undefined` if not found.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{
+*     id: 'a',
+*     ports: [{ name: 'out', direction: 'out' }],
+*   }],
+* });
+* getPort(graph, 'a', 'out'); // => { name: 'out', direction: 'out', ... }
+* getPort(graph, 'a', 'missing'); // => undefined
+* ```
+*/
+function getPort(graph, nodeId, portName) {
+	const ni = getIndex(graph).nodeById.get(nodeId);
+	if (ni === void 0) return void 0;
+	return graph.nodes[ni].ports?.find((p) => p.name === portName);
+}
+/**
+* Get all ports on a node. Returns `[]` if the node has no ports or doesn't exist.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{
+*     id: 'a',
+*     ports: [
+*       { name: 'in', direction: 'in' },
+*       { name: 'out', direction: 'out' },
+*     ],
+*   }],
+* });
+* getPorts(graph, 'a'); // => [port in, port out]
+* ```
+*/
+function getPorts(graph, nodeId) {
+	const ni = getIndex(graph).nodeById.get(nodeId);
+	if (ni === void 0) return [];
+	return graph.nodes[ni].ports ?? [];
+}
+/**
+* Get all edges connected to a specific port on a node.
+*
+* Returns edges where:
+* - `sourceId === nodeId && sourcePort === portName`, or
+* - `targetId === nodeId && targetPort === portName`
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [
+*     { id: 'a', ports: [{ name: 'out', direction: 'out' }] },
+*     { id: 'b', ports: [{ name: 'in', direction: 'in' }] },
+*   ],
+*   edges: [{
+*     id: 'e1', sourceId: 'a', targetId: 'b',
+*     sourcePort: 'out', targetPort: 'in',
+*   }],
+* });
+* getEdgesByPort(graph, 'a', 'out'); // => [edge e1]
+* ```
+*/
+function getEdgesByPort(graph, nodeId, portName) {
+	const idx = getIndex(graph);
+	const result = [];
+	for (const eid of idx.outEdges.get(nodeId) ?? []) {
+		const ai = idx.edgeById.get(eid);
+		if (ai !== void 0 && graph.edges[ai].sourcePort === portName) result.push(graph.edges[ai]);
+	}
+	for (const eid of idx.inEdges.get(nodeId) ?? []) {
+		const ai = idx.edgeById.get(eid);
+		if (ai !== void 0 && graph.edges[ai].targetPort === portName) result.push(graph.edges[ai]);
+	}
+	return result;
+}
 
 //#endregion
-export { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf };
+export { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesByPort, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPort, getPorts, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf };