@statelyai/graph 0.5.0 → 0.7.0

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

@@ -1,4 +1,4 @@
-import { c as Graph, f as GraphFormatConverter } from "../../types-FBZCrmnG.mjs";
+import { m as GraphFormatConverter, u as Graph } from "../../types-DkKjaQW3.mjs";
 
 //#region src/formats/mermaid/sequence.d.ts
 interface SequenceNodeData {
@@ -23,6 +23,11 @@ interface SequenceEdgeData {
   bidirectional?: boolean;
   sequenceNumber?: number;
 }
+/**
+ * Control-flow blocks (loop/alt/par/opt/critical/break/rect).
+ * Not graph topology — they describe ordering constraints.
+ * Stored in `graphData.blocks` for round-trip fidelity.
+ */
 type SequenceBlock = {
   type: 'loop';
   label: string;

package/dist/formats/mermaid/index.mjs

@@ -1836,7 +1836,10 @@ function fromMermaidClass(input) {
 		if (classBlockMatch) {
 			currentClass = classBlockMatch[1];
 			const node = ensureNode(currentClass);
-			if (classBlockMatch[2]) node.data.genericType = classBlockMatch[2];
+			if (classBlockMatch[2]) {
+				node.data ??= {};
+				node.data.genericType = classBlockMatch[2];
+			}
 			inClassBlock = true;
 			braceDepth = 1;
 			continue;
@@ -1852,10 +1855,13 @@ function fromMermaidClass(input) {
 			}
 			const annotMatch = line.match(/^<<(.+)>>$/);
 			if (annotMatch) {
-				nodeMap.get(currentClass).data.annotation = annotMatch[1];
+				const node$1 = nodeMap.get(currentClass);
+				node$1.data ??= {};
+				node$1.data.annotation = annotMatch[1];
 				continue;
 			}
 			const node = nodeMap.get(currentClass);
+			node.data ??= {};
 			if (!node.data.members) node.data.members = [];
 			node.data.members.push(parseMember(line));
 			continue;
@@ -1863,12 +1869,16 @@ function fromMermaidClass(input) {
 		const classInlineMatch = line.match(/^class\s+(\S+?)(?:~(.+?)~)?\s*$/);
 		if (classInlineMatch) {
 			const node = ensureNode(classInlineMatch[1]);
-			if (classInlineMatch[2]) node.data.genericType = classInlineMatch[2];
+			if (classInlineMatch[2]) {
+				node.data ??= {};
+				node.data.genericType = classInlineMatch[2];
+			}
 			continue;
 		}
 		const annotLineMatch = line.match(/^<<(.+)>>\s+(\S+)\s*$/);
 		if (annotLineMatch) {
 			const node = ensureNode(annotLineMatch[2]);
+			node.data ??= {};
 			node.data.annotation = annotLineMatch[1];
 			continue;
 		}
@@ -1876,6 +1886,7 @@ function fromMermaidClass(input) {
 		if (inlineMemberMatch) {
 			if (!parseRelationship(line)) {
 				const node = ensureNode(inlineMemberMatch[1]);
+				node.data ??= {};
 				if (!node.data.members) node.data.members = [];
 				node.data.members.push(parseMember(inlineMemberMatch[2]));
 				continue;
@@ -2067,7 +2078,10 @@ function fromMermaidER(input) {
 			const attrMatch = line.match(/^(\S+)\s+(\S+)(?:\s+(PK|FK|UK))?(?:\s+"([^"]*)")?$/);
 			if (attrMatch) {
 				const node = nodeMap.get(currentEntity);
-				if (!node.data.attributes) node.data.attributes = [];
+				if (!node.data?.attributes) {
+					if (!node.data) node.data = {};
+					node.data.attributes = [];
+				}
 				node.data.attributes.push({
 					type: attrMatch[1],
 					name: attrMatch[2],
@@ -2289,7 +2303,7 @@ function toMermaidMindmap(graph) {
 			const indent = "  ".repeat(depth + 1);
 			const shape = child.shape;
 			const brackets = shape ? SHAPE_TO_BRACKETS[shape] : void 0;
-			const label = escapeMermaidLabel(child.label);
+			const label = escapeMermaidLabel(child.label ?? child.id);
 			const text = brackets ? `${brackets[0]}${label}${brackets[1]}` : label;
 			let extra = "";
 			if (child.data?.icon) extra = `\n${"  ".repeat(depth + 2)}::icon(${child.data.icon})`;
@@ -2442,7 +2456,7 @@ function fromMermaidBlock(input) {
 			const label = spanMatch[2] ?? id;
 			const span = parseInt(spanMatch[3], 10);
 			const node = ensureNode(id, label);
-			node.data.span = span;
+			if (node.data) node.data.span = span;
 			continue;
 		}
 		const parts = line.split(/\s+/);

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

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

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

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

package/dist/index.d.mts

@@ -1,10 +1,30 @@
-import { C as TraversalOptions, E as VisualGraphConfig, O as VisualNode, S as TransitionOptions, T as VisualGraph, _ as MSTOptions, a as EntitiesConfig, b as PathOptions, c as Graph, d as GraphEdge, f as GraphFormatConverter, g as GraphStep, h as GraphPath, i as EdgeConfig, l as GraphConfig, m as GraphPatch, n as DeleteNodeOptions, o as EntitiesUpdate, p as GraphNode, r as EdgeChange, s as EntityRect, t as AllPairsShortestPathsOptions, u as GraphDiff, v as NodeChange, w as VisualEdge, x as SinglePathOptions, y as NodeConfig } from "./types-FBZCrmnG.mjs";
-import { bfs, dfs, genCycles, genPostorders, genPreorders, genShortestPaths, genSimplePaths, 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 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 { 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";
 
 //#region src/graph.d.ts
 
+/**
+ * Create a resolved graph node from a config. Fills in defaults.
+ *
+ * @example
+ * ```ts
+ * const node = createGraphNode({ id: 'a', data: { label: 'hi' } });
+ * // { type: 'node', id: 'a', label: '', data: { label: 'hi' } }
+ * ```
+ */
+declare function createGraphNode<T = any>(config: NodeConfig<T>): GraphNode<T>;
+/**
+ * Create a resolved graph edge from a config. Fills in defaults.
+ *
+ * @example
+ * ```ts
+ * const edge = createGraphEdge({ id: 'e1', sourceId: 'a', targetId: 'b' });
+ * // { type: 'edge', id: 'e1', sourceId: 'a', targetId: 'b', label: null, data: undefined }
+ * ```
+ */
+declare function createGraphEdge<T = any>(config: EdgeConfig<T>): GraphEdge<T>;
 /**
  * Create a graph from a config. Resolves defaults for all fields.
  *
@@ -449,5 +469,102 @@ declare function toDiff<N, E>(patches: GraphPatch<N, E>[]): GraphDiff<N, E>;
  * ```
  */
 declare function flatten<N, E, G>(graph: Graph<N, E, G>): Graph<N, E, G>;
+/**
+ * Returns the induced subgraph containing only the given node IDs
+ * and edges whose endpoints are both in the set.
+ *
+ * Parent references to nodes outside the set are removed.
+ *
+ * @example
+ * ```ts
+ * import { createGraph, getSubgraph } from '@statelyai/graph';
+ *
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+ *   edges: [
+ *     { id: 'ab', sourceId: 'a', targetId: 'b' },
+ *     { id: 'bc', sourceId: 'b', targetId: 'c' },
+ *   ],
+ * });
+ *
+ * const sub = getSubgraph(graph, ['a', 'b']);
+ * // sub.nodes: [a, b], sub.edges: [ab]
+ * ```
+ */
+declare function getSubgraph<N, E, G>(graph: Graph<N, E, G>, nodeIds: string[]): Graph<N, E, G>;
+/**
+ * Returns a new graph with all edge directions flipped (source ↔ target).
+ * Optionally filters which edges to include.
+ *
+ * @example
+ * ```ts
+ * import { createGraph, reverseGraph } from '@statelyai/graph';
+ *
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+ *   edges: [
+ *     { id: 'ab', sourceId: 'a', targetId: 'b' },
+ *     { id: 'bc', sourceId: 'b', targetId: 'c' },
+ *   ],
+ * });
+ *
+ * const rev = reverseGraph(graph);
+ * // rev edges: b→a, c→b
+ *
+ * const filtered = reverseGraph(graph, (e) => e.id !== 'bc');
+ * // filtered edges: b→a (only ab reversed, bc excluded)
+ * ```
+ */
+declare function reverseGraph<N, E, G>(graph: Graph<N, E, G>, filterEdge?: (edge: GraphEdge<E>) => boolean): Graph<N, E, G>;
+//#endregion
+//#region src/walks.d.ts
+/**
+ * Random walk. At each node, picks a uniformly random outgoing edge.
+ * Yields steps indefinitely (may revisit nodes) until a sink node is reached.
+ */
+declare function genRandomWalk<N, E>(graph: Graph<N, E>, options?: WalkOptions<E>): Generator<GraphStep<N, E>>;
+/**
+ * Weighted random walk. Edge selection probability proportional to weight.
+ */
+declare function genWeightedRandomWalk<N, E>(graph: Graph<N, E>, options?: WeightedWalkOptions<E>): Generator<GraphStep<N, E>>;
+/**
+ * Quick random walk targeting unvisited edges.
+ * If unvisited outgoing edges exist, picks one randomly.
+ * Otherwise, finds shortest path to a node with unvisited outgoing edges.
+ */
+declare function genQuickRandomWalk<N, E>(graph: Graph<N, E>, options?: WalkOptions<E>): Generator<GraphStep<N, E>>;
+/**
+ * Walk a predefined sequence of edge IDs.
+ * Validates each edge exists and connects from the current position.
+ */
+declare function genPredefinedWalk<N, E>(graph: Graph<N, E>, edgeIds: string[], options?: Pick<WalkOptions<E>, 'from'>): Generator<GraphStep<N, E>>;
+/**
+ * Yield at most `n` steps from the source generator.
+ */
+declare function takeSteps<N, E>(gen: Generator<GraphStep<N, E>>, n: number): Generator<GraphStep<N, E>>;
+/**
+ * Yield steps until a specific node is reached.
+ */
+declare function takeUntilNode<N, E>(gen: Generator<GraphStep<N, E>>, nodeId: string): Generator<GraphStep<N, E>>;
+/**
+ * Yield steps until a specific edge is traversed.
+ */
+declare function takeUntilEdge<N, E>(gen: Generator<GraphStep<N, E>>, edgeId: string): Generator<GraphStep<N, E>>;
+/**
+ * Yield steps until node coverage reaches the target (0–1).
+ */
+declare function takeUntilNodeCoverage<N, E>(gen: Generator<GraphStep<N, E>>, graph: Graph<N, E>, coverage: number, options?: {
+  from?: string;
+}): Generator<GraphStep<N, E>>;
+/**
+ * Yield steps until edge coverage reaches the target (0–1).
+ */
+declare function takeUntilEdgeCoverage<N, E>(gen: Generator<GraphStep<N, E>>, graph: Graph<N, E>, coverage: number): Generator<GraphStep<N, E>>;
+/**
+ * Compute coverage statistics for a completed walk.
+ */
+declare function getCoverage<N, E>(graph: Graph<N, E>, steps: GraphStep<N, E>[], options?: {
+  from?: string;
+}): CoverageStats;
 //#endregion
-export { type AllPairsShortestPathsOptions, 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, addEdge, addEntities, addNode, applyPatches, bfs, createFormatConverter, createGraph, createGraphFromTransition, createVisualGraph, deleteEdge, deleteEntities, deleteNode, dfs, flatten, genCycles, genPostorders, genPreorders, genShortestPaths, genSimplePaths, getAllPairsShortestPaths, getAncestors, getChildren, getConnectedComponents, 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, getSuccessors, getTopologicalSort, hasEdge, hasNode, hasPath, invalidateIndex, invertDiff, isAcyclic, isCompound, isConnected, isEmptyDiff, isLeaf, isTree, joinPaths, toDiff, toPatches, updateEdge, updateEntities, updateNode };
+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 };

package/dist/index.mjs

@@ -1,10 +1,10 @@
 import { o as invalidateIndex, t as getIndex } from "./indexing-DyfgLuzw.mjs";
-import { A as addNode, B as hasNode, C as isAcyclic, D as GraphInstance, E as joinPaths, F as deleteEntities, H as updateEntities, I as deleteNode, L as getEdge, M as createGraphFromTransition, N as createVisualGraph, O as addEdge, P as deleteEdge, R as getNode, S as hasPath, T as isTree, U as updateNode, V as updateEdge, _ as getShortestPaths, a as genPreorders, b as getStronglyConnectedComponents, c as getAllPairsShortestPaths, d as getMinimumSpanningTree, f as getPostorder, g as getShortestPath, h as getPreorders, i as genPostorders, j as createGraph, k as addEntities, l as getConnectedComponents, m as getPreorder, n as dfs, o as genShortestPaths, p as getPostorders, r as genCycles, s as genSimplePaths, t as bfs, u as getCycles, v as getSimplePath, w as isConnected, x as getTopologicalSort, y as getSimplePaths, z as hasEdge } from "./algorithms-DldwenLt.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 { n as createFormatConverter } from "./converter-B5CUD0r9.mjs";
 
 //#region src/diff.ts
-function nodeToConfig(node) {
+function nodeToConfig$1(node) {
 	const config = { id: node.id };
 	if (node.parentId) config.parentId = node.parentId;
 	if (node.initialNodeId) config.initialNodeId = node.initialNodeId;
@@ -19,7 +19,7 @@ function nodeToConfig(node) {
 	if (node.style !== void 0) config.style = node.style;
 	return config;
 }
-function edgeToConfig(edge) {
+function edgeToConfig$1(edge) {
 	const config = {
 		id: edge.id,
 		sourceId: edge.sourceId,
@@ -101,7 +101,7 @@ function getDiff(a, b) {
 	};
 	for (const [id, nodeB] of bNodeMap) {
 		const nodeA = aNodeMap.get(id);
-		if (!nodeA) diff.nodes.added.push(nodeToConfig(nodeB));
+		if (!nodeA) diff.nodes.added.push(nodeToConfig$1(nodeB));
 		else {
 			const oldPartial = {};
 			const newPartial = {};
@@ -116,10 +116,10 @@ function getDiff(a, b) {
 			});
 		}
 	}
-	for (const [id, nodeA] of aNodeMap) if (!bNodeMap.has(id)) diff.nodes.removed.push(nodeToConfig(nodeA));
+	for (const [id, nodeA] of aNodeMap) if (!bNodeMap.has(id)) diff.nodes.removed.push(nodeToConfig$1(nodeA));
 	for (const [id, edgeB] of bEdgeMap) {
 		const edgeA = aEdgeMap.get(id);
-		if (!edgeA) diff.edges.added.push(edgeToConfig(edgeB));
+		if (!edgeA) diff.edges.added.push(edgeToConfig$1(edgeB));
 		else {
 			const oldPartial = {};
 			const newPartial = {};
@@ -134,7 +134,7 @@ function getDiff(a, b) {
 			});
 		}
 	}
-	for (const [id, edgeA] of aEdgeMap) if (!bEdgeMap.has(id)) diff.edges.removed.push(edgeToConfig(edgeA));
+	for (const [id, edgeA] of aEdgeMap) if (!bEdgeMap.has(id)) diff.edges.removed.push(edgeToConfig$1(edgeA));
 	return diff;
 }
 /**
@@ -455,6 +455,362 @@ function flatten(graph) {
 		data: graph.data
 	});
 }
+function nodeToConfig(node, nodeIdSet) {
+	const config = {
+		id: node.id,
+		label: node.label,
+		data: node.data
+	};
+	if (node.parentId !== void 0 && node.parentId !== null) config.parentId = nodeIdSet && !nodeIdSet.has(node.parentId) ? void 0 : node.parentId;
+	if (node.initialNodeId !== void 0) config.initialNodeId = node.initialNodeId ?? void 0;
+	if (node.x !== void 0) config.x = node.x;
+	if (node.y !== void 0) config.y = node.y;
+	if (node.width !== void 0) config.width = node.width;
+	if (node.height !== void 0) config.height = node.height;
+	if (node.shape !== void 0) config.shape = node.shape;
+	if (node.color !== void 0) config.color = node.color;
+	if (node.style !== void 0) config.style = node.style;
+	return config;
+}
+function edgeToConfig(edge) {
+	const config = {
+		id: edge.id,
+		sourceId: edge.sourceId,
+		targetId: edge.targetId,
+		label: edge.label,
+		data: edge.data
+	};
+	if (edge.weight !== void 0) config.weight = edge.weight;
+	if (edge.x !== void 0) config.x = edge.x;
+	if (edge.y !== void 0) config.y = edge.y;
+	if (edge.width !== void 0) config.width = edge.width;
+	if (edge.height !== void 0) config.height = edge.height;
+	if (edge.color !== void 0) config.color = edge.color;
+	if (edge.style !== void 0) config.style = edge.style;
+	return config;
+}
+/**
+* Returns the induced subgraph containing only the given node IDs
+* and edges whose endpoints are both in the set.
+*
+* Parent references to nodes outside the set are removed.
+*
+* @example
+* ```ts
+* import { createGraph, getSubgraph } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'bc', sourceId: 'b', targetId: 'c' },
+*   ],
+* });
+*
+* const sub = getSubgraph(graph, ['a', 'b']);
+* // sub.nodes: [a, b], sub.edges: [ab]
+* ```
+*/
+function getSubgraph(graph, nodeIds) {
+	const nodeIdSet = new Set(nodeIds);
+	return createGraph({
+		id: graph.id,
+		type: graph.type,
+		initialNodeId: graph.initialNodeId && nodeIdSet.has(graph.initialNodeId) ? graph.initialNodeId : void 0,
+		nodes: graph.nodes.filter((n) => nodeIdSet.has(n.id)).map((n) => nodeToConfig(n, nodeIdSet)),
+		edges: graph.edges.filter((e) => nodeIdSet.has(e.sourceId) && nodeIdSet.has(e.targetId)).map(edgeToConfig),
+		data: graph.data
+	});
+}
+/**
+* Returns a new graph with all edge directions flipped (source ↔ target).
+* Optionally filters which edges to include.
+*
+* @example
+* ```ts
+* import { createGraph, reverseGraph } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'bc', sourceId: 'b', targetId: 'c' },
+*   ],
+* });
+*
+* const rev = reverseGraph(graph);
+* // rev edges: b→a, c→b
+*
+* const filtered = reverseGraph(graph, (e) => e.id !== 'bc');
+* // filtered edges: b→a (only ab reversed, bc excluded)
+* ```
+*/
+function reverseGraph(graph, filterEdge) {
+	const edges = filterEdge ? graph.edges.filter(filterEdge) : graph.edges;
+	return createGraph({
+		id: graph.id,
+		type: graph.type,
+		initialNodeId: graph.initialNodeId ?? void 0,
+		nodes: graph.nodes.map((n) => nodeToConfig(n)),
+		edges: edges.map((e) => {
+			const config = edgeToConfig(e);
+			config.sourceId = e.targetId;
+			config.targetId = e.sourceId;
+			return config;
+		}),
+		data: graph.data
+	});
+}
+
+//#endregion
+//#region src/walks.ts
+function mulberry32(seed) {
+	let s = seed | 0;
+	return () => {
+		s = s + 1831565813 | 0;
+		let t = Math.imul(s ^ s >>> 15, 1 | s);
+		t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	};
+}
+function makeRng(seed) {
+	return seed !== void 0 ? mulberry32(seed) : Math.random;
+}
+function resolveFrom(graph, from) {
+	if (from) return from;
+	if (graph.initialNodeId) return graph.initialNodeId;
+	const inDeg = /* @__PURE__ */ new Map();
+	for (const n of graph.nodes) inDeg.set(n.id, 0);
+	for (const e of graph.edges) inDeg.set(e.targetId, (inDeg.get(e.targetId) ?? 0) + 1);
+	const roots = [...inDeg.entries()].filter(([, d]) => d === 0);
+	if (roots.length === 1) return roots[0][0];
+	throw new Error("Cannot determine start node: provide `from`, set graph.initialNodeId, or have exactly one source node.");
+}
+/**
+* Random walk. At each node, picks a uniformly random outgoing edge.
+* Yields steps indefinitely (may revisit nodes) until a sink node is reached.
+*/
+function* genRandomWalk(graph, options) {
+	const rng = makeRng(options?.seed);
+	let currentId = resolveFrom(graph, options?.from);
+	const ctx = {
+		currentNodeId: currentId,
+		visitedNodes: new Set([currentId]),
+		visitedEdges: /* @__PURE__ */ new Set(),
+		stepCount: 0
+	};
+	while (true) {
+		let edges = getOutEdges(graph, currentId);
+		if (options?.filter) edges = edges.filter((e) => options.filter(e, ctx));
+		if (edges.length === 0) return;
+		const edge = edges[Math.floor(rng() * edges.length)];
+		const node = getNode(graph, edge.targetId);
+		const step = {
+			edge,
+			node
+		};
+		currentId = node.id;
+		ctx.currentNodeId = currentId;
+		ctx.visitedNodes.add(currentId);
+		ctx.visitedEdges.add(edge.id);
+		ctx.stepCount++;
+		options?.onStep?.(step, ctx);
+		yield step;
+	}
+}
+/**
+* Weighted random walk. Edge selection probability proportional to weight.
+*/
+function* genWeightedRandomWalk(graph, options) {
+	const rng = makeRng(options?.seed);
+	const getWeight = options?.getWeight ?? ((e) => e.weight ?? 1);
+	let currentId = resolveFrom(graph, options?.from);
+	const ctx = {
+		currentNodeId: currentId,
+		visitedNodes: new Set([currentId]),
+		visitedEdges: /* @__PURE__ */ new Set(),
+		stepCount: 0
+	};
+	while (true) {
+		let edges = getOutEdges(graph, currentId);
+		if (options?.filter) edges = edges.filter((e) => options.filter(e, ctx));
+		if (edges.length === 0) return;
+		const weights = edges.map((e) => Math.max(0, getWeight(e)));
+		const total = weights.reduce((a, b) => a + b, 0);
+		if (total === 0) return;
+		let r = rng() * total;
+		let chosen = edges[0];
+		for (let i = 0; i < edges.length; i++) {
+			r -= weights[i];
+			if (r <= 0) {
+				chosen = edges[i];
+				break;
+			}
+		}
+		const node = getNode(graph, chosen.targetId);
+		const step = {
+			edge: chosen,
+			node
+		};
+		currentId = node.id;
+		ctx.currentNodeId = currentId;
+		ctx.visitedNodes.add(currentId);
+		ctx.visitedEdges.add(chosen.id);
+		ctx.stepCount++;
+		options?.onStep?.(step, ctx);
+		yield step;
+	}
+}
+/**
+* Quick random walk targeting unvisited edges.
+* If unvisited outgoing edges exist, picks one randomly.
+* Otherwise, finds shortest path to a node with unvisited outgoing edges.
+*/
+function* genQuickRandomWalk(graph, options) {
+	const rng = makeRng(options?.seed);
+	let currentId = resolveFrom(graph, options?.from);
+	const visitedEdges = /* @__PURE__ */ new Set();
+	const allEdgeIds = new Set(graph.edges.map((e) => e.id));
+	const ctx = {
+		currentNodeId: currentId,
+		visitedNodes: new Set([currentId]),
+		visitedEdges,
+		stepCount: 0
+	};
+	while (visitedEdges.size < allEdgeIds.size) {
+		let edges = getOutEdges(graph, currentId);
+		if (options?.filter) edges = edges.filter((e) => options.filter(e, ctx));
+		const unvisited = edges.filter((e) => !visitedEdges.has(e.id));
+		if (unvisited.length > 0) {
+			const edge = unvisited[Math.floor(rng() * unvisited.length)];
+			const node = getNode(graph, edge.targetId);
+			const step = {
+				edge,
+				node
+			};
+			currentId = node.id;
+			ctx.currentNodeId = currentId;
+			ctx.visitedNodes.add(currentId);
+			visitedEdges.add(edge.id);
+			ctx.stepCount++;
+			options?.onStep?.(step, ctx);
+			yield step;
+		} else {
+			let targetNodeId;
+			for (const n of graph.nodes) if (getOutEdges(graph, n.id).some((e) => !visitedEdges.has(e.id))) {
+				targetNodeId = n.id;
+				break;
+			}
+			if (!targetNodeId) return;
+			const path = getShortestPath(graph, {
+				from: currentId,
+				to: targetNodeId
+			});
+			if (!path || path.steps.length === 0) return;
+			for (const step of path.steps) {
+				currentId = step.node.id;
+				ctx.currentNodeId = currentId;
+				ctx.visitedNodes.add(currentId);
+				visitedEdges.add(step.edge.id);
+				ctx.stepCount++;
+				options?.onStep?.(step, ctx);
+				yield step;
+			}
+		}
+	}
+}
+/**
+* Walk a predefined sequence of edge IDs.
+* Validates each edge exists and connects from the current position.
+*/
+function* genPredefinedWalk(graph, edgeIds, options) {
+	let currentId = resolveFrom(graph, options?.from);
+	for (const edgeId of edgeIds) {
+		const edge = graph.edges.find((e) => e.id === edgeId);
+		if (!edge) throw new Error(`Edge "${edgeId}" not found in graph.`);
+		if (edge.sourceId !== currentId) throw new Error(`Edge "${edgeId}" starts at "${edge.sourceId}" but current position is "${currentId}".`);
+		const node = getNode(graph, edge.targetId);
+		currentId = node.id;
+		yield {
+			edge,
+			node
+		};
+	}
+}
+/**
+* Yield at most `n` steps from the source generator.
+*/
+function* takeSteps(gen, n) {
+	let count = 0;
+	for (const step of gen) {
+		yield step;
+		if (++count >= n) return;
+	}
+}
+/**
+* Yield steps until a specific node is reached.
+*/
+function* takeUntilNode(gen, nodeId) {
+	for (const step of gen) {
+		yield step;
+		if (step.node.id === nodeId) return;
+	}
+}
+/**
+* Yield steps until a specific edge is traversed.
+*/
+function* takeUntilEdge(gen, edgeId) {
+	for (const step of gen) {
+		yield step;
+		if (step.edge.id === edgeId) return;
+	}
+}
+/**
+* Yield steps until node coverage reaches the target (0–1).
+*/
+function* takeUntilNodeCoverage(gen, graph, coverage, options) {
+	const totalNodes = graph.nodes.length;
+	const target = Math.ceil(coverage * totalNodes);
+	const startId = options?.from ?? graph.initialNodeId ?? graph.nodes[0]?.id;
+	const visited = new Set(startId ? [startId] : []);
+	for (const step of gen) {
+		visited.add(step.node.id);
+		yield step;
+		if (visited.size >= target) return;
+	}
+}
+/**
+* Yield steps until edge coverage reaches the target (0–1).
+*/
+function* takeUntilEdgeCoverage(gen, graph, coverage) {
+	const totalEdges = graph.edges.length;
+	const target = Math.ceil(coverage * totalEdges);
+	const visited = /* @__PURE__ */ new Set();
+	for (const step of gen) {
+		visited.add(step.edge.id);
+		yield step;
+		if (visited.size >= target) return;
+	}
+}
+/**
+* Compute coverage statistics for a completed walk.
+*/
+function getCoverage(graph, steps, options) {
+	const startId = options?.from ?? graph.initialNodeId ?? graph.nodes[0]?.id;
+	const visitedNodes = new Set(startId ? [startId] : []);
+	const visitedEdges = /* @__PURE__ */ new Set();
+	for (const step of steps) {
+		visitedNodes.add(step.node.id);
+		visitedEdges.add(step.edge.id);
+	}
+	return {
+		nodeCoverage: graph.nodes.length > 0 ? visitedNodes.size / graph.nodes.length : 1,
+		edgeCoverage: graph.edges.length > 0 ? visitedEdges.size / graph.edges.length : 1,
+		visitedNodes: [...visitedNodes],
+		visitedEdges: [...visitedEdges],
+		totalSteps: steps.length
+	};
+}
 
 //#endregion
-export { GraphInstance, addEdge, addEntities, addNode, applyPatches, bfs, createFormatConverter, createGraph, createGraphFromTransition, createVisualGraph, deleteEdge, deleteEntities, deleteNode, dfs, flatten, genCycles, genPostorders, genPreorders, genShortestPaths, genSimplePaths, getAllPairsShortestPaths, getAncestors, getChildren, getConnectedComponents, 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, getSuccessors, getTopologicalSort, hasEdge, hasNode, hasPath, invalidateIndex, invertDiff, isAcyclic, isCompound, isConnected, isEmptyDiff, isLeaf, isTree, joinPaths, toDiff, toPatches, updateEdge, updateEntities, updateNode };
+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 };