@statelyai/graph 0.3.0 → 0.4.0

package/dist/queries.mjs

@@ -1,6 +1,22 @@
-import { t as getIndex } from "./indexing-BFFVMnjF.mjs";
+import { t as getIndex } from "./indexing-DitHphT7.mjs";
 
 //#region src/queries.ts
+/**
+* Returns all edges (incoming + outgoing) connected to a node.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'e1', sourceId: 'a', targetId: 'b' },
+*     { id: 'e2', sourceId: 'c', targetId: 'b' },
+*   ],
+* });
+* getEdgesOf(graph, 'b');
+* // => [edge e1, edge e2]
+* ```
+*/
 function getEdgesOf(graph, nodeId) {
 	const idx = getIndex(graph);
 	const outIds = idx.outEdges.get(nodeId) ?? [];
@@ -18,14 +34,60 @@ function getEdgesOf(graph, nodeId) {
 	}
 	return result;
 }
+/**
+* Returns incoming edges to a node.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+* });
+* getInEdges(graph, 'b');
+* // => [edge e1]
+* getInEdges(graph, 'a');
+* // => []
+* ```
+*/
 function getInEdges(graph, nodeId) {
 	const idx = getIndex(graph);
 	return (idx.inEdges.get(nodeId) ?? []).map((eid) => graph.edges[idx.edgeById.get(eid)]);
 }
+/**
+* Returns outgoing edges from a node.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+* });
+* getOutEdges(graph, 'a');
+* // => [edge e1]
+* getOutEdges(graph, 'b');
+* // => []
+* ```
+*/
 function getOutEdges(graph, nodeId) {
 	const idx = getIndex(graph);
 	return (idx.outEdges.get(nodeId) ?? []).map((eid) => graph.edges[idx.edgeById.get(eid)]);
 }
+/**
+* Returns the edge from `sourceId` to `targetId`, or `undefined` if none exists.
+* For undirected graphs, checks both directions.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+* });
+* getEdgeBetween(graph, 'a', 'b');
+* // => edge e1
+* getEdgeBetween(graph, 'b', 'a');
+* // => undefined (directed graph)
+* ```
+*/
 function getEdgeBetween(graph, sourceId, targetId) {
 	const idx = getIndex(graph);
 	const outIds = idx.outEdges.get(sourceId) ?? [];
@@ -43,6 +105,22 @@ function getEdgeBetween(graph, sourceId, targetId) {
 		}
 	}
 }
+/**
+* Returns direct successor nodes (targets of outgoing edges).
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'e1', sourceId: 'a', targetId: 'b' },
+*     { id: 'e2', sourceId: 'a', targetId: 'c' },
+*   ],
+* });
+* getSuccessors(graph, 'a');
+* // => [node b, node c]
+* ```
+*/
 function getSuccessors(graph, nodeId) {
 	const idx = getIndex(graph);
 	const edgeIds = idx.outEdges.get(nodeId) ?? [];
@@ -58,6 +136,22 @@ function getSuccessors(graph, nodeId) {
 	}
 	return result;
 }
+/**
+* Returns direct predecessor nodes (sources of incoming edges).
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'e1', sourceId: 'a', targetId: 'c' },
+*     { id: 'e2', sourceId: 'b', targetId: 'c' },
+*   ],
+* });
+* getPredecessors(graph, 'c');
+* // => [node a, node b]
+* ```
+*/
 function getPredecessors(graph, nodeId) {
 	const idx = getIndex(graph);
 	const edgeIds = idx.inEdges.get(nodeId) ?? [];
@@ -73,6 +167,22 @@ function getPredecessors(graph, nodeId) {
 	}
 	return result;
 }
+/**
+* Returns all neighbor nodes (successors + predecessors).
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'e1', sourceId: 'a', targetId: 'b' },
+*     { id: 'e2', sourceId: 'c', targetId: 'b' },
+*   ],
+* });
+* getNeighbors(graph, 'b');
+* // => [node a, node c]
+* ```
+*/
 function getNeighbors(graph, nodeId) {
 	const idx = getIndex(graph);
 	const ids = /* @__PURE__ */ new Set();
@@ -80,6 +190,23 @@ function getNeighbors(graph, nodeId) {
 	for (const eid of idx.inEdges.get(nodeId) ?? []) ids.add(graph.edges[idx.edgeById.get(eid)].sourceId);
 	return [...ids].map((id) => graph.nodes[idx.nodeById.get(id)]).filter(Boolean);
 }
+/**
+* Returns the total degree of a node (inDegree + outDegree).
+* For undirected graphs, each edge is counted once.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'e1', sourceId: 'a', targetId: 'b' },
+*     { id: 'e2', sourceId: 'c', targetId: 'b' },
+*   ],
+* });
+* getDegree(graph, 'b'); // => 2
+* getDegree(graph, 'a'); // => 1
+* ```
+*/
 function getDegree(graph, nodeId) {
 	const idx = getIndex(graph);
 	if (graph.type === "undirected") {
@@ -89,32 +216,110 @@ function getDegree(graph, nodeId) {
 	}
 	return (idx.inEdges.get(nodeId)?.length ?? 0) + (idx.outEdges.get(nodeId)?.length ?? 0);
 }
+/**
+* Returns the in-degree of a node (number of incoming edges).
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+* });
+* getInDegree(graph, 'b'); // => 1
+* getInDegree(graph, 'a'); // => 0
+* ```
+*/
 function getInDegree(graph, nodeId) {
 	return getIndex(graph).inEdges.get(nodeId)?.length ?? 0;
 }
+/**
+* Returns the out-degree of a node (number of outgoing edges).
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+* });
+* getOutDegree(graph, 'a'); // => 1
+* getOutDegree(graph, 'b'); // => 0
+* ```
+*/
 function getOutDegree(graph, nodeId) {
 	return getIndex(graph).outEdges.get(nodeId)?.length ?? 0;
 }
+/**
+* Returns direct children of a node in the hierarchy.
+* Pass `null` to get root-level nodes.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [
+*     { id: 'parent' },
+*     { id: 'child1', parentId: 'parent' },
+*     { id: 'child2', parentId: 'parent' },
+*   ],
+* });
+* getChildren(graph, 'parent');
+* // => [node child1, node child2]
+* getChildren(graph, null);
+* // => [node parent]
+* ```
+*/
 function getChildren(graph, nodeId) {
 	const idx = getIndex(graph);
 	return (idx.childNodes.get(nodeId) ?? []).map((id) => graph.nodes[idx.nodeById.get(id)]).filter(Boolean);
 }
+/**
+* Returns the parent node in the hierarchy, or `undefined` if root-level.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [
+*     { id: 'parent' },
+*     { id: 'child', parentId: 'parent' },
+*   ],
+* });
+* getParent(graph, 'child');
+* // => node parent
+* getParent(graph, 'parent');
+* // => undefined
+* ```
+*/
 function getParent(graph, nodeId) {
 	const idx = getIndex(graph);
 	const ni = idx.nodeById.get(nodeId);
 	if (ni === void 0) return void 0;
 	const node = graph.nodes[ni];
-	if (node.parentId === null) return void 0;
+	if (!node.parentId) return void 0;
 	const pi = idx.nodeById.get(node.parentId);
 	return pi !== void 0 ? graph.nodes[pi] : void 0;
 }
+/**
+* Returns all ancestors from the node up to the root (nearest parent first).
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [
+*     { id: 'root' },
+*     { id: 'mid', parentId: 'root' },
+*     { id: 'leaf', parentId: 'mid' },
+*   ],
+* });
+* getAncestors(graph, 'leaf');
+* // => [node mid, node root]
+* ```
+*/
 function getAncestors(graph, nodeId) {
 	const idx = getIndex(graph);
 	const result = [];
 	let ni = idx.nodeById.get(nodeId);
 	if (ni === void 0) return result;
 	let current = graph.nodes[ni];
-	while (current && current.parentId !== null) {
+	while (current && current.parentId) {
 		const pi = idx.nodeById.get(current.parentId);
 		if (pi === void 0) break;
 		const p = graph.nodes[pi];
@@ -123,6 +328,22 @@ function getAncestors(graph, nodeId) {
 	}
 	return result;
 }
+/**
+* Returns all descendants recursively (depth-first).
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [
+*     { id: 'root' },
+*     { id: 'child', parentId: 'root' },
+*     { id: 'grandchild', parentId: 'child' },
+*   ],
+* });
+* getDescendants(graph, 'root');
+* // => [node child, node grandchild]
+* ```
+*/
 function getDescendants(graph, nodeId) {
 	const idx = getIndex(graph);
 	const result = [];
@@ -139,26 +360,87 @@ function getDescendants(graph, nodeId) {
 	collect(nodeId);
 	return result;
 }
+/**
+* Returns all root nodes (nodes with no parent).
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [
+*     { id: 'root1' },
+*     { id: 'root2' },
+*     { id: 'child', parentId: 'root1' },
+*   ],
+* });
+* getRoots(graph);
+* // => [node root1, node root2]
+* ```
+*/
 function getRoots(graph) {
 	const idx = getIndex(graph);
 	return idx.childNodes.get(null)?.map((id) => graph.nodes[idx.nodeById.get(id)]).filter(Boolean) ?? [];
 }
-/** Whether a node has children (is a compound/group node). */
+/**
+* Whether a node has children (is a compound/group node).
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [
+*     { id: 'parent' },
+*     { id: 'child', parentId: 'parent' },
+*   ],
+* });
+* isCompound(graph, 'parent'); // => true
+* isCompound(graph, 'child');  // => false
+* ```
+*/
 function isCompound(graph, nodeId) {
 	return (getIndex(graph).childNodes.get(nodeId) ?? []).length > 0;
 }
-/** Whether a node has no children (is a leaf/atomic node). */
+/**
+* Whether a node has no children (is a leaf/atomic node).
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [
+*     { id: 'parent' },
+*     { id: 'child', parentId: 'parent' },
+*   ],
+* });
+* isLeaf(graph, 'child');  // => true
+* isLeaf(graph, 'parent'); // => false
+* ```
+*/
 function isLeaf(graph, nodeId) {
 	return !isCompound(graph, nodeId);
 }
-/** Depth of a node in the hierarchy (root = 0). */
+/**
+* Depth of a node in the hierarchy (root = 0).
+* Returns -1 if the node is not found.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [
+*     { id: 'root' },
+*     { id: 'child', parentId: 'root' },
+*     { id: 'grandchild', parentId: 'child' },
+*   ],
+* });
+* getDepth(graph, 'root');       // => 0
+* getDepth(graph, 'child');      // => 1
+* getDepth(graph, 'grandchild'); // => 2
+* ```
+*/
 function getDepth(graph, nodeId) {
 	const idx = getIndex(graph);
 	let d = 0;
 	let ni = idx.nodeById.get(nodeId);
 	if (ni === void 0) return -1;
 	let current = graph.nodes[ni];
-	while (current.parentId !== null) {
+	while (current.parentId) {
 		d++;
 		const pi = idx.nodeById.get(current.parentId);
 		if (pi === void 0) break;
@@ -166,17 +448,49 @@ function getDepth(graph, nodeId) {
 	}
 	return d;
 }
-/** Sibling nodes (same parentId, excluding the node itself). */
+/**
+* Sibling nodes (same parentId, excluding the node itself).
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [
+*     { id: 'parent' },
+*     { id: 'a', parentId: 'parent' },
+*     { id: 'b', parentId: 'parent' },
+*     { id: 'c', parentId: 'parent' },
+*   ],
+* });
+* getSiblings(graph, 'a');
+* // => [node b, node c]
+* ```
+*/
 function getSiblings(graph, nodeId) {
 	const idx = getIndex(graph);
 	const ni = idx.nodeById.get(nodeId);
 	if (ni === void 0) return [];
 	const node = graph.nodes[ni];
-	return (idx.childNodes.get(node.parentId) ?? []).filter((id) => id !== nodeId).map((id) => graph.nodes[idx.nodeById.get(id)]).filter(Boolean);
+	return (idx.childNodes.get(node.parentId ?? null) ?? []).filter((id) => id !== nodeId).map((id) => graph.nodes[idx.nodeById.get(id)]).filter(Boolean);
 }
 /**
-* Least Common Ancestor — deepest proper ancestor of all given nodes.
+* Least Common Ancestor -- deepest proper ancestor of all given nodes.
 * A proper ancestor excludes the input nodes themselves.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [
+*     { id: 'root' },
+*     { id: 'a', parentId: 'root' },
+*     { id: 'b', parentId: 'root' },
+*     { id: 'a1', parentId: 'a' },
+*   ],
+* });
+* getLCA(graph, 'a1', 'b');
+* // => node root
+* getLCA(graph, 'a', 'b');
+* // => node root
+* ```
 */
 function getLCA(graph, ...nodeIds) {
 	if (nodeIds.length === 0) return void 0;
@@ -186,7 +500,7 @@ function getLCA(graph, ...nodeIds) {
 		let ni$1 = idx.nodeById.get(id);
 		if (ni$1 === void 0) return result;
 		let current = graph.nodes[ni$1];
-		while (current.parentId !== null) {
+		while (current.parentId) {
 			result.push(current.parentId);
 			const pi = idx.nodeById.get(current.parentId);
 			if (pi === void 0) break;
@@ -250,7 +564,7 @@ function getRelativeDistanceMap(graph, parentId) {
 	let sourceId = null;
 	if (parentId !== null) {
 		const pi = idx.nodeById.get(parentId);
-		if (pi !== void 0) sourceId = graph.nodes[pi].initialNodeId;
+		if (pi !== void 0) sourceId = graph.nodes[pi].initialNodeId ?? null;
 	} else sourceId = graph.initialNodeId;
 	if (!sourceId) return {};
 	const siblingSet = new Set(idx.childNodes.get(parentId) ?? []);
@@ -323,14 +637,44 @@ function getRelativeDistance(graph, nodeId) {
 	const ni = getIndex(graph).nodeById.get(nodeId);
 	if (ni === void 0) return void 0;
 	const node = graph.nodes[ni];
-	return getRelativeDistanceMap(graph, node.parentId)[nodeId];
+	return getRelativeDistanceMap(graph, node.parentId ?? null)[nodeId];
 }
-/** Nodes with no incoming edges (inDegree 0). */
+/**
+* Nodes with no incoming edges (inDegree 0).
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'e1', sourceId: 'a', targetId: 'b' },
+*     { id: 'e2', sourceId: 'b', targetId: 'c' },
+*   ],
+* });
+* getSources(graph);
+* // => [node a]
+* ```
+*/
 function getSources(graph) {
 	const idx = getIndex(graph);
 	return graph.nodes.filter((n) => (idx.inEdges.get(n.id)?.length ?? 0) === 0);
 }
-/** Nodes with no outgoing edges (outDegree 0). */
+/**
+* Nodes with no outgoing edges (outDegree 0).
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'e1', sourceId: 'a', targetId: 'b' },
+*     { id: 'e2', sourceId: 'b', targetId: 'c' },
+*   ],
+* });
+* getSinks(graph);
+* // => [node c]
+* ```
+*/
 function getSinks(graph) {
 	const idx = getIndex(graph);
 	return graph.nodes.filter((n) => (idx.outEdges.get(n.id)?.length ?? 0) === 0);

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

@@ -67,8 +67,8 @@ interface Graph<TNodeData = any, TEdgeData = any, TGraphData = any> {
 interface GraphNode<TNodeData = any> {
   type: 'node';
   id: string;
-  parentId: string | null;
-  initialNodeId: string | null;
+  parentId?: string | null;
+  initialNodeId?: string | null;
   label: string;
   data: TNodeData;
   x?: number;
@@ -94,7 +94,7 @@ interface GraphEdge<TEdgeData = any> {
   style?: Record<string, string | number>;
 }
 interface VisualNode<TNodeData = any> extends Omit<GraphNode<TNodeData>, keyof EntityRect>, EntityRect {
-  shape: string;
+  shape?: string;
 }
 interface VisualEdge<TEdgeData = any> extends Omit<GraphEdge<TEdgeData>, keyof EntityRect>, EntityRect {}
 interface VisualGraph<TNodeData = any, TEdgeData = any, TGraphData = any> extends Omit<Graph<TNodeData, TEdgeData, TGraphData>, 'nodes' | 'edges'> {
@@ -234,6 +234,17 @@ interface GraphFormatConverter<TSerial> {
   /** Convert from the serialized format to a Graph. */
   from(input: TSerial): Graph;
 }
+/**
+ * A bidirectional converter between `VisualGraph` and a serialized format.
+ *
+ * Use this for formats that carry position/size data (e.g. xyflow, cytoscape).
+ */
+interface VisualGraphFormatConverter<TSerial> {
+  /** Convert a VisualGraph to the serialized format. */
+  to(graph: VisualGraph): TSerial;
+  /** Convert from the serialized format to a VisualGraph. */
+  from(input: TSerial): VisualGraph;
+}
 interface TransitionOptions<TState, TEvent> {
   /** Initial state to begin BFS exploration from. */
   initialState: TState;
@@ -251,4 +262,4 @@ interface TransitionOptions<TState, TEvent> {
   id?: string;
 }
 //#endregion
-export { TraversalOptions as C, VisualNode as D, VisualGraphConfig as E, TransitionOptions as S, VisualGraph as T, MSTOptions as _, EntitiesConfig as a, PathOptions as b, Graph as c, GraphEdge as d, GraphFormatConverter as f, GraphStep as g, GraphPath as h, EdgeConfig as i, GraphConfig as l, GraphPatch as m, DeleteNodeOptions as n, EntitiesUpdate as o, GraphNode as p, EdgeChange as r, EntityRect as s, AllPairsShortestPathsOptions as t, GraphDiff as u, NodeChange as v, VisualEdge as w, SinglePathOptions as x, NodeConfig as y };
+export { TraversalOptions as C, VisualGraphFormatConverter as D, VisualGraphConfig as E, VisualNode as O, TransitionOptions as S, VisualGraph as T, MSTOptions as _, EntitiesConfig as a, PathOptions as b, Graph as c, GraphEdge as d, GraphFormatConverter as f, GraphStep as g, GraphPath as h, EdgeConfig as i, GraphConfig as l, GraphPatch as m, DeleteNodeOptions as n, EntitiesUpdate as o, GraphNode as p, EdgeChange as r, EntityRect as s, AllPairsShortestPathsOptions as t, GraphDiff as u, NodeChange as v, VisualEdge as w, SinglePathOptions as x, NodeConfig as y };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@statelyai/graph",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A TypeScript-first graph library with plain JSON-serializable objects",
   "author": "David Khourshid <david@stately.ai>",
   "license": "MIT",
@@ -36,6 +36,7 @@
     "./jgf": "./dist/formats/jgf/index.mjs",
     "./mermaid": "./dist/formats/mermaid/index.mjs",
     "./tgf": "./dist/formats/tgf/index.mjs",
+    "./xyflow": "./dist/formats/xyflow/index.mjs",
     "./queries": "./dist/queries.mjs",
     "./schemas": "./dist/schemas.mjs",
     "./package.json": "./package.json"
@@ -53,6 +54,7 @@
     "@types/d3-array": "^3.2.2",
     "@types/d3-force": "^3.0.10",
     "@types/node": "^25.0.3",
+    "@xyflow/system": "^0.0.75",
     "bumpp": "^10.3.2",
     "cytoscape": "^3.33.1",
     "d3-array": "^3.2.4",

package/dist/converter-DnbeyE_p.mjs

@@ -1,33 +0,0 @@
-import { n as toAdjacencyList, t as fromAdjacencyList } from "./adjacency-list-A4_Eiwj3.mjs";
-import { n as toEdgeList, t as fromEdgeList } from "./edge-list-DuHMz8hf.mjs";
-
-//#region src/formats/converter/index.ts
-/**
-* Create a `GraphFormatConverter` from a pair of `to`/`from` functions.
-*
-* @example
-* ```ts
-* import { createFormatConverter } from '@statelyai/graph';
-*
-* const yamlConverter = createFormatConverter(
-*   (graph) => toYAML(graph),
-*   (yaml) => fromYAML(yaml),
-* );
-*
-* const yaml = yamlConverter.to(graph);
-* const graph = yamlConverter.from(yaml);
-* ```
-*/
-function createFormatConverter(to, from) {
-	return {
-		to,
-		from
-	};
-}
-/** Bidirectional converter for adjacency-list format (`Record<string, string[]>`). */
-const adjacencyListConverter = createFormatConverter(toAdjacencyList, fromAdjacencyList);
-/** Bidirectional converter for edge-list format (`[source, target][]`). */
-const edgeListConverter = createFormatConverter(toEdgeList, fromEdgeList);
-
-//#endregion
-export { createFormatConverter as n, edgeListConverter as r, adjacencyListConverter as t };