@statelyai/graph 1.0.0 → 2.1.0

package/dist/index.mjs

@@ -1,9 +1,98 @@
-import { o as invalidateIndex, t as getIndex } from "./indexing-DR8M1vBy.mjs";
-import { $ as createGraphPort, A as isAcyclic, B as getShortestPaths, C as getPreorder, D as getConnectedComponents, E as dfs, F as genSimplePaths, G as GraphInstance, H as getSimplePaths, I as getAStarPath, J as addNode, K as addEdge, L as getAllPairsShortestPaths, M as isTree, N as genCycles, O as getTopologicalSort, P as genShortestPaths, Q as createGraphNode, R as getCycles, S as getPostorders, T as bfs, U as getStronglyConnectedComponents, V as getSimplePath, W as joinPaths, X as createGraphEdge, Y as createGraph, Z as createGraphFromTransition, _ as getPageRank, a as genGirvanNewmanCommunities, at as getNode, b as genPreorders, c as getLabelPropagationCommunities, ct as updateEdge, d as getClosenessCentrality, et as createVisualGraph, f as getDegreeCentrality, g as getOutDegreeCentrality, h as getInDegreeCentrality, i as getBridges, it as getEdge, j as isConnected, k as hasPath, l as getModularity, lt as updateEntities, m as getHITS, n as getArticulationPoints, nt as deleteEntities, o as getGirvanNewmanCommunities, ot as hasEdge, p as getEigenvectorCentrality, q as addEntities, r as getBiconnectedComponents, rt as deleteNode, s as getGreedyModularityCommunities, st as hasNode, t as isIsomorphic, tt as deleteEdge, u as getBetweennessCentrality, ut as updateNode, v as getMinimumSpanningTree, w as getPreorders, x as getPostorder, y as genPostorders, z as getShortestPath } from "./algorithms-Ba7o7niK.mjs";
-import { n as isEdgeDirected, t as getEdgeMode } from "./mode-D8OnHFBk.mjs";
-import { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgesBetween, 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-udLITX36.mjs";
+import { C as getSinks, D as isLeaf, E as isCompound, N as invalidateIndex, S as getSiblings, T as getSuccessors, _ as getPorts, a as getDescendants, b as getRelativeDistanceMap, c as getEdgesOf, d as getLCA, f as getNeighbors, g as getPort, h as getParent, i as getDepth, l as getInDegree, m as getOutEdges, n as getChildren, o as getEdgesBetween, p as getOutDegree, r as getDegree, s as getEdgesByPort, t as getAncestors, u as getInEdges, v as getPredecessors, w as getSources, x as getRoots, y as getRelativeDistance } from "./queries-BMM0XAv_.mjs";
+import { S as updateNode, _ as getNode, a as addEntities, b as updateEdge, c as createGraphEdge, d as createGraphPort, f as createVisualGraph, g as getEdge, h as deleteNode, i as addEdge, l as createGraphFromTransition, m as deleteEntities, n as toNodeConfig, o as addNode, p as deleteEdge, r as GraphInstance, s as createGraph, t as toEdgeConfig, u as createGraphNode, v as hasEdge, x as updateEntities, y as hasNode } from "./config-Dt5u1gSf.mjs";
+import { n as isEdgeDirected, t as getEdgeMode } from "./mode-gu_mhKKs.mjs";
+import { t as getGraphIssues } from "./validate-BsfSOv0S.mjs";
+import { $ as getAStarPath, A as genPreorders, B as getTopologicalSort, C as getHITS, D as getPageRank, E as getOutDegreeCentrality, F as bfs, G as flatten, H as isAcyclic, I as dfs, J as getSubgraph, K as getFlattenedGraph, L as genBFS, M as getPostorders, N as getPreorder, O as getMinimumSpanningTree, P as getPreorders, Q as genSimplePaths, R as genDFS, S as getEigenvectorCentrality, T as getKatzCentrality, U as isConnected, V as hasPath, W as isTree, X as genCycles, Y as reverseGraph, Z as genShortestPaths, _ as getCoreNumbers, a as getLouvainCommunities, at as getSimplePath, b as getClosenessCentrality, c as getBiconnectedComponents, ct as joinPaths, d as getGirvanNewmanCommunities, et as getAllPairsShortestPaths, f as getGreedyModularityCommunities, g as isBipartite, h as getMaximumBipartiteMatching, i as getMinCut, it as getShortestPaths, j as getPostorder, k as genPostorders, l as getBridges, lt as mulberry32$1, m as getModularity, n as getDominatorTree, nt as getJoinedPath, o as isIsomorphic, ot as getSimplePaths, p as getLabelPropagationCommunities, q as getReversedGraph, r as getMaxFlow, rt as getShortestPath, s as getArticulationPoints, st as getStronglyConnectedComponents, t as getTransitiveReduction, tt as getCycles, u as genGirvanNewmanCommunities, v as getKCore, w as getInDegreeCentrality, x as getDegreeCentrality, y as getBetweennessCentrality, z as getConnectedComponents } from "./algorithms-DBpH74hR.mjs";
+import { n as createFormatConverter } from "./converter-DB6Rg6Vd.mjs";
 
+//#region src/generators.ts
+function assertNonNegativeInteger(caller, name, value) {
+	if (!Number.isInteger(value) || value < 0) throw new Error(`${caller}: ${name} ${value} is invalid — pass a non-negative integer`);
+}
+/**
+* Create the complete graph K_n: every pair of distinct nodes connected by
+* one undirected edge. Nodes are `n0..n{n-1}` (`options.idPrefix` overrides
+* the `n` prefix); edges are `e0..`.
+*/
+function createCompleteGraph(n, options) {
+	assertNonNegativeInteger("createCompleteGraph", "node count", n);
+	const prefix = options?.idPrefix ?? "n";
+	const nodes = [];
+	for (let i = 0; i < n; i++) nodes.push({ id: `${prefix}${i}` });
+	const edges = [];
+	let edgeId = 0;
+	for (let i = 0; i < n; i++) for (let j = i + 1; j < n; j++) edges.push({
+		id: `e${edgeId++}`,
+		sourceId: `${prefix}${i}`,
+		targetId: `${prefix}${j}`
+	});
+	return createGraph({
+		mode: "undirected",
+		nodes,
+		edges
+	});
+}
+/**
+* Create a `rows × cols` grid graph: node `(r, c)` is connected to its right
+* and down neighbors by undirected edges. Nodes are `n{r}_{c}`
+* (`options.idPrefix` overrides the `n` prefix); edges are `e0..`.
+*/
+function createGridGraph(rows, cols, options) {
+	assertNonNegativeInteger("createGridGraph", "row count", rows);
+	assertNonNegativeInteger("createGridGraph", "column count", cols);
+	const prefix = options?.idPrefix ?? "n";
+	const nodeId = (r, c) => `${prefix}${r}_${c}`;
+	const nodes = [];
+	const edges = [];
+	let edgeId = 0;
+	for (let r = 0; r < rows; r++) for (let c = 0; c < cols; c++) {
+		nodes.push({ id: nodeId(r, c) });
+		if (c + 1 < cols) edges.push({
+			id: `e${edgeId++}`,
+			sourceId: nodeId(r, c),
+			targetId: nodeId(r, c + 1)
+		});
+		if (r + 1 < rows) edges.push({
+			id: `e${edgeId++}`,
+			sourceId: nodeId(r, c),
+			targetId: nodeId(r + 1, c)
+		});
+	}
+	return createGraph({
+		mode: "undirected",
+		nodes,
+		edges
+	});
+}
+/**
+* Create an Erdős–Rényi G(n, p) random graph: each of the n·(n-1)/2 node
+* pairs gets an undirected edge with probability `probability`. With
+* `options.seed` the result is deterministic per seed (mulberry32);
+* otherwise `Math.random` is used. Nodes are `n0..n{n-1}`
+* (`options.idPrefix` overrides the `n` prefix); edges are `e0..`.
+*/
+function createRandomGraph(n, probability, options) {
+	assertNonNegativeInteger("createRandomGraph", "node count", n);
+	if (!(probability >= 0 && probability <= 1)) throw new Error(`createRandomGraph: probability ${probability} is invalid — pass a number between 0 and 1`);
+	const prefix = options?.idPrefix ?? "n";
+	const rng = options?.seed !== void 0 ? mulberry32$1(options.seed) : Math.random;
+	const nodes = [];
+	for (let i = 0; i < n; i++) nodes.push({ id: `${prefix}${i}` });
+	const edges = [];
+	let edgeId = 0;
+	for (let i = 0; i < n; i++) for (let j = i + 1; j < n; j++) if (rng() < probability) edges.push({
+		id: `e${edgeId++}`,
+		sourceId: `${prefix}${i}`,
+		targetId: `${prefix}${j}`
+	});
+	return createGraph({
+		mode: "undirected",
+		nodes,
+		edges
+	});
+}
+
+//#endregion
 //#region src/equivalence.ts
 /** Shallow-compare two values, returning true if they differ. */
 function differs$1(a, b) {
@@ -27,6 +116,8 @@ const LAYOUT_KEYS = {
 		"y",
 		"width",
 		"height",
+		"points",
+		"routing",
 		"style",
 		"color"
 	]
@@ -52,7 +143,7 @@ const LAYOUT_KEY_SET = {
 * ```
 */
 function areEntitiesEqual(a, b, keys) {
-	const compareKeys = keys && keys.length > 0 ? keys : Object.keys(a);
+	const compareKeys = keys && keys.length > 0 ? keys : [...new Set([...Object.keys(a), ...Object.keys(b)])];
 	for (const key of compareKeys) if (differs$1(a[key], b[key])) return false;
 	return true;
 }
@@ -87,47 +178,16 @@ function isLayoutEqual(a, b) {
 */
 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;
+	const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+	for (const key of keys) {
+		if (skip.has(key)) continue;
+		if (differs$1(a[key], b[key])) return false;
 	}
 	return true;
 }
 
 //#endregion
 //#region src/diff.ts
-function nodeToConfig$1(node) {
-	const config = { id: node.id };
-	if (node.parentId) config.parentId = node.parentId;
-	if (node.initialNodeId) config.initialNodeId = node.initialNodeId;
-	if (node.label !== "") config.label = node.label;
-	if (node.data !== void 0) config.data = node.data;
-	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$1(edge) {
-	const config = {
-		id: edge.id,
-		sourceId: edge.sourceId,
-		targetId: edge.targetId
-	};
-	if (edge.label !== "") config.label = edge.label;
-	if (edge.data !== void 0) config.data = edge.data;
-	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;
-}
 /** Shallow-compare two values, returning true if they differ. */
 function differs(a, b) {
 	if (a === b) return false;
@@ -140,6 +200,7 @@ const NODE_COMPARE_KEYS = [
 	"initialNodeId",
 	"label",
 	"data",
+	"ports",
 	"x",
 	"y",
 	"width",
@@ -153,6 +214,12 @@ const EDGE_COMPARE_KEYS = [
 	"targetId",
 	"label",
 	"data",
+	"weight",
+	"mode",
+	"sourcePort",
+	"targetPort",
+	"points",
+	"routing",
 	"x",
 	"y",
 	"width",
@@ -194,13 +261,17 @@ function getDiff(a, b) {
 	};
 	for (const [id, nodeB] of bNodeMap) {
 		const nodeA = aNodeMap.get(id);
-		if (!nodeA) diff.nodes.added.push(nodeToConfig$1(nodeB));
+		if (!nodeA) diff.nodes.added.push(toNodeConfig(nodeB));
 		else {
 			const oldPartial = {};
 			const newPartial = {};
-			for (const key of NODE_COMPARE_KEYS) if (differs(nodeA[key], nodeB[key])) {
-				oldPartial[key] = nodeA[key];
-				newPartial[key] = nodeB[key];
+			for (const key of NODE_COMPARE_KEYS) {
+				const oldValue = nodeA[key] ?? null;
+				const newValue = nodeB[key] ?? null;
+				if (differs(oldValue, newValue)) {
+					oldPartial[key] = oldValue;
+					newPartial[key] = newValue;
+				}
 			}
 			if (Object.keys(oldPartial).length > 0) diff.nodes.updated.push({
 				id,
@@ -209,16 +280,20 @@ function getDiff(a, b) {
 			});
 		}
 	}
-	for (const [id, nodeA] of aNodeMap) if (!bNodeMap.has(id)) diff.nodes.removed.push(nodeToConfig$1(nodeA));
+	for (const [id, nodeA] of aNodeMap) if (!bNodeMap.has(id)) diff.nodes.removed.push(toNodeConfig(nodeA));
 	for (const [id, edgeB] of bEdgeMap) {
 		const edgeA = aEdgeMap.get(id);
-		if (!edgeA) diff.edges.added.push(edgeToConfig$1(edgeB));
+		if (!edgeA) diff.edges.added.push(toEdgeConfig(edgeB));
 		else {
 			const oldPartial = {};
 			const newPartial = {};
-			for (const key of EDGE_COMPARE_KEYS) if (differs(edgeA[key], edgeB[key])) {
-				oldPartial[key] = edgeA[key];
-				newPartial[key] = edgeB[key];
+			for (const key of EDGE_COMPARE_KEYS) {
+				const oldValue = edgeA[key] ?? null;
+				const newValue = edgeB[key] ?? null;
+				if (differs(oldValue, newValue)) {
+					oldPartial[key] = oldValue;
+					newPartial[key] = newValue;
+				}
 			}
 			if (Object.keys(oldPartial).length > 0) diff.edges.updated.push({
 				id,
@@ -227,7 +302,7 @@ function getDiff(a, b) {
 			});
 		}
 	}
-	for (const [id, edgeA] of aEdgeMap) if (!bEdgeMap.has(id)) diff.edges.removed.push(edgeToConfig$1(edgeA));
+	for (const [id, edgeA] of aEdgeMap) if (!bEdgeMap.has(id)) diff.edges.removed.push(toEdgeConfig(edgeA));
 	return diff;
 }
 /**
@@ -250,42 +325,49 @@ function isEmptyDiff(diff) {
 *
 * @example
 * ```ts
-* import { createGraph, getDiff, invertDiff } from '@statelyai/graph';
+* import { createGraph, getDiff, getInvertedDiff } from '@statelyai/graph';
 *
 * const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
 * const b = createGraph({ nodes: [{ id: 'n2' }], edges: [] });
 *
 * const diff = getDiff(a, b);
-* const inv = invertDiff(diff);
+* const inv = getInvertedDiff(diff);
 * // inv.nodes.added contains n1 (was removed)
 * // inv.nodes.removed contains n2 (was added)
 * ```
 */
-function invertDiff(diff) {
+function getInvertedDiff(diff) {
 	return {
 		nodes: {
-			added: diff.nodes.removed,
-			removed: diff.nodes.added,
+			added: diff.nodes.removed.map((c) => structuredClone(c)),
+			removed: diff.nodes.added.map((c) => structuredClone(c)),
 			updated: diff.nodes.updated.map((c) => ({
 				id: c.id,
-				old: c.new,
-				new: c.old
+				old: structuredClone(c.new),
+				new: structuredClone(c.old)
 			}))
 		},
 		edges: {
-			added: diff.edges.removed,
-			removed: diff.edges.added,
+			added: diff.edges.removed.map((c) => structuredClone(c)),
+			removed: diff.edges.added.map((c) => structuredClone(c)),
 			updated: diff.edges.updated.map((c) => ({
 				id: c.id,
-				old: c.new,
-				new: c.old
+				old: structuredClone(c.new),
+				new: structuredClone(c.old)
 			}))
 		}
 	};
 }
 /**
+* @deprecated Use {@link getInvertedDiff}.
+*/
+function invertDiff(diff) {
+	return getInvertedDiff(diff);
+}
+/**
 * Compute an ordered patch list from graph `a` to graph `b`.
-* Order: delete edges → delete nodes → add nodes → add edges → update nodes → update edges.
+* Order (see {@link toPatches}): add nodes → update edges → delete edges →
+* delete nodes → add edges → update nodes.
 *
 * @example
 * ```ts
@@ -307,17 +389,17 @@ function getPatches(a, b) {
 *
 * @example
 * ```ts
-* import { createGraph, getPatches, applyPatches } from '@statelyai/graph';
+* import { createGraph, getPatches, updateGraphWithPatches } from '@statelyai/graph';
 *
 * const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
 * const b = createGraph({ nodes: [{ id: 'n1' }, { id: 'n2' }], edges: [] });
 *
 * const patches = getPatches(a, b);
-* applyPatches(a, patches);
+* updateGraphWithPatches(a, patches);
 * // a now contains both n1 and n2
 * ```
 */
-function applyPatches(graph, patches) {
+function updateGraphWithPatches(graph, patches) {
 	for (const patch of patches) switch (patch.op) {
 		case "addNode":
 			addNode(graph, patch.node);
@@ -340,6 +422,12 @@ function applyPatches(graph, patches) {
 	}
 }
 /**
+* @deprecated Use {@link updateGraphWithPatches}.
+*/
+function applyPatches(graph, patches) {
+	updateGraphWithPatches(graph, patches);
+}
+/**
 * Flatten a structured diff into an ordered patch list.
 * Order: add nodes → update edges → delete edges → delete nodes → add edges → update nodes.
 * This avoids cascading deletes removing edges that are being updated,
@@ -365,7 +453,7 @@ function toPatches(diff) {
 	});
 	for (const change of diff.edges.updated) {
 		const data = {};
-		for (const [key, value] of Object.entries(change.new)) data[key] = value;
+		for (const [key, value] of Object.entries(change.new)) data[key] = value ?? null;
 		patches.push({
 			op: "updateEdge",
 			id: change.id,
@@ -386,7 +474,7 @@ function toPatches(diff) {
 	});
 	for (const change of diff.nodes.updated) {
 		const data = {};
-		for (const [key, value] of Object.entries(change.new)) data[key] = value;
+		for (const [key, value] of Object.entries(change.new)) data[key] = value ?? null;
 		patches.push({
 			op: "updateNode",
 			id: change.id,
@@ -460,201 +548,6 @@ function toDiff(patches) {
 	return diff;
 }
 
-//#endregion
-//#region src/transforms.ts
-/**
-* Flattens a hierarchical graph into a flat graph with only leaf nodes.
-*
-* - Edges targeting a compound node resolve to its initial child (recursively).
-* - Edges originating from a compound node expand to all leaf descendants.
-* - Only leaf nodes (nodes with no children) appear in the result.
-* - Duplicate edges (same source + target) are deduplicated.
-*
-* @example
-* ```ts
-* import { createGraph, flatten } from '@statelyai/graph';
-*
-* const graph = createGraph({
-*   nodes: [
-*     { id: 'parent', initialNodeId: 'child1' },
-*     { id: 'child1', parentId: 'parent' },
-*     { id: 'child2', parentId: 'parent' },
-*     { id: 'other' },
-*   ],
-*   edges: [{ id: 'e1', sourceId: 'other', targetId: 'parent' }],
-* });
-*
-* const flat = flatten(graph);
-* // flat.nodes → [child1, child2, other] (leaf nodes only)
-* // flat.edges → edge from 'other' → 'child1' (resolved via initialNodeId)
-* ```
-*/
-function flatten(graph) {
-	const idx = getIndex(graph);
-	const leaves = /* @__PURE__ */ new Set();
-	for (const node of graph.nodes) if ((idx.childNodes.get(node.id) ?? []).length === 0) leaves.add(node.id);
-	function resolveInitial(nodeId) {
-		if (leaves.has(nodeId)) return nodeId;
-		const ni = idx.nodeById.get(nodeId);
-		if (ni === void 0) return null;
-		const node = graph.nodes[ni];
-		if (node.initialNodeId) return resolveInitial(node.initialNodeId);
-		const childIds = idx.childNodes.get(nodeId) ?? [];
-		if (childIds.length > 0) return resolveInitial(childIds[0]);
-		return nodeId;
-	}
-	function getLeafDescendants(nodeId) {
-		if (leaves.has(nodeId)) return [nodeId];
-		const result = [];
-		const collect = (id) => {
-			const childIds = idx.childNodes.get(id) ?? [];
-			for (const childId of childIds) if (leaves.has(childId)) result.push(childId);
-			else collect(childId);
-		};
-		collect(nodeId);
-		return result;
-	}
-	const edgeSeen = /* @__PURE__ */ new Set();
-	const flatEdges = [];
-	for (const edge of graph.edges) {
-		const sources = leaves.has(edge.sourceId) ? [edge.sourceId] : getLeafDescendants(edge.sourceId);
-		const target = leaves.has(edge.targetId) ? edge.targetId : resolveInitial(edge.targetId);
-		if (target === null) continue;
-		for (const source of sources) {
-			if (source === target) continue;
-			const key = `${source}->${target}`;
-			if (edgeSeen.has(key)) continue;
-			edgeSeen.add(key);
-			flatEdges.push({
-				type: "edge",
-				id: `${edge.id}:${source}->${target}`,
-				sourceId: source,
-				targetId: target,
-				label: edge.label,
-				data: edge.data
-			});
-		}
-	}
-	const leafNodes = graph.nodes.filter((n) => leaves.has(n.id)).map((n) => ({
-		id: n.id,
-		label: n.label,
-		data: n.data
-	}));
-	return createGraph({
-		id: graph.id,
-		mode: graph.mode,
-		nodes: leafNodes,
-		edges: flatEdges,
-		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,
-		mode: graph.mode,
-		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,
-		mode: graph.mode,
-		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) {
@@ -680,7 +573,24 @@ function resolveFrom(graph, from) {
 	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.
+* Edges traversable from a node, with the node reached by taking each one.
+* Out-edges always; in-edges too when their effective mode is not 'directed'.
+*/
+function getTraversableEdges(graph, nodeId) {
+	const result = [];
+	for (const edge of getOutEdges(graph, nodeId)) result.push({
+		edge,
+		nextId: edge.targetId
+	});
+	for (const edge of getInEdges(graph, nodeId)) if (edge.sourceId !== edge.targetId && getEdgeMode(graph, edge) !== "directed") result.push({
+		edge,
+		nextId: edge.sourceId
+	});
+	return result;
+}
+/**
+* Random walk. At each node, picks a uniformly random traversable edge
+* (outgoing edges, plus non-directed edges both ways).
 * Yields steps indefinitely (may revisit nodes) until a sink node is reached.
 */
 function* genRandomWalk(graph, options) {
@@ -693,11 +603,11 @@ function* genRandomWalk(graph, options) {
 		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);
+		let traversable = getTraversableEdges(graph, currentId);
+		if (options?.filter) traversable = traversable.filter(({ edge: edge$1 }) => options.filter(edge$1, ctx));
+		if (traversable.length === 0) return;
+		const { edge, nextId } = traversable[Math.floor(rng() * traversable.length)];
+		const node = getNode(graph, nextId);
 		const step = {
 			edge,
 			node
@@ -725,30 +635,30 @@ function* genWeightedRandomWalk(graph, options) {
 		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)));
+		let traversable = getTraversableEdges(graph, currentId);
+		if (options?.filter) traversable = traversable.filter(({ edge }) => options.filter(edge, ctx));
+		if (traversable.length === 0) return;
+		const weights = traversable.map(({ edge }) => Math.max(0, getWeight(edge)));
 		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++) {
+		let chosen = traversable[0];
+		for (let i = 0; i < traversable.length; i++) {
 			r -= weights[i];
 			if (r <= 0) {
-				chosen = edges[i];
+				chosen = traversable[i];
 				break;
 			}
 		}
-		const node = getNode(graph, chosen.targetId);
+		const node = getNode(graph, chosen.nextId);
 		const step = {
-			edge: chosen,
+			edge: chosen.edge,
 			node
 		};
 		currentId = node.id;
 		ctx.currentNodeId = currentId;
 		ctx.visitedNodes.add(currentId);
-		ctx.visitedEdges.add(chosen.id);
+		ctx.visitedEdges.add(chosen.edge.id);
 		ctx.stepCount++;
 		options?.onStep?.(step, ctx);
 		yield step;
@@ -756,8 +666,9 @@ function* genWeightedRandomWalk(graph, options) {
 }
 /**
 * 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.
+* If unvisited traversable edges exist at the current node, picks one randomly.
+* Otherwise, walks the fewest-hop path (BFS, honoring `filter` and edge modes)
+* to the nearest unvisited edge. Ends when no unvisited edge is reachable.
 */
 function* genQuickRandomWalk(graph, options) {
 	const rng = makeRng(options?.seed);
@@ -770,13 +681,16 @@ function* genQuickRandomWalk(graph, options) {
 		visitedEdges,
 		stepCount: 0
 	};
+	const allowedEdges = (nodeId) => {
+		let traversable = getTraversableEdges(graph, nodeId);
+		if (options?.filter) traversable = traversable.filter(({ edge }) => options.filter(edge, ctx));
+		return traversable;
+	};
 	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));
+		const unvisited = allowedEdges(currentId).filter(({ edge }) => !visitedEdges.has(edge.id));
 		if (unvisited.length > 0) {
-			const edge = unvisited[Math.floor(rng() * unvisited.length)];
-			const node = getNode(graph, edge.targetId);
+			const { edge, nextId } = unvisited[Math.floor(rng() * unvisited.length)];
+			const node = getNode(graph, nextId);
 			const step = {
 				edge,
 				node
@@ -789,22 +703,54 @@ function* genQuickRandomWalk(graph, options) {
 			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;
+			const prevStep = /* @__PURE__ */ new Map();
+			const seen = new Set([currentId]);
+			const queue = [currentId];
+			let found;
+			while (queue.length > 0 && !found) {
+				const id = queue.shift();
+				for (const t of allowedEdges(id)) {
+					if (!visitedEdges.has(t.edge.id)) {
+						found = {
+							atId: id,
+							edge: t.edge,
+							nextId: t.nextId
+						};
+						break;
+					}
+					if (!seen.has(t.nextId)) {
+						seen.add(t.nextId);
+						prevStep.set(t.nextId, {
+							edge: t.edge,
+							fromId: id
+						});
+						queue.push(t.nextId);
+					}
+				}
 			}
-			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;
+			if (!found) return;
+			const pathSteps = [{
+				edge: found.edge,
+				nextId: found.nextId
+			}];
+			let cursor = found.atId;
+			while (cursor !== currentId) {
+				const p = prevStep.get(cursor);
+				pathSteps.unshift({
+					edge: p.edge,
+					nextId: cursor
+				});
+				cursor = p.fromId;
+			}
+			for (const { edge, nextId } of pathSteps) {
+				const step = {
+					edge,
+					node: getNode(graph, nextId)
+				};
+				currentId = nextId;
 				ctx.currentNodeId = currentId;
 				ctx.visitedNodes.add(currentId);
-				visitedEdges.add(step.edge.id);
+				visitedEdges.add(edge.id);
 				ctx.stepCount++;
 				options?.onStep?.(step, ctx);
 				yield step;
@@ -815,14 +761,19 @@ function* genQuickRandomWalk(graph, options) {
 /**
 * Walk a predefined sequence of edge IDs.
 * Validates each edge exists and connects from the current position.
+* Edges whose effective mode is not `'directed'` may be traversed
+* target → source as well.
 */
 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);
+		let nextId;
+		if (edge.sourceId === currentId) nextId = edge.targetId;
+		else if (edge.targetId === currentId && getEdgeMode(graph, edge) !== "directed") nextId = edge.sourceId;
+		else throw new Error(`Edge "${edgeId}" connects "${edge.sourceId}" → "${edge.targetId}" but current position is "${currentId}".`);
+		const node = getNode(graph, nextId);
 		currentId = node.id;
 		yield {
 			edge,
@@ -833,7 +784,7 @@ function* genPredefinedWalk(graph, edgeIds, options) {
 /**
 * Yield at most `n` steps from the source generator.
 */
-function* takeSteps(gen, n) {
+function* genWalkSteps(gen, n) {
 	let count = 0;
 	for (const step of gen) {
 		yield step;
@@ -841,31 +792,50 @@ function* takeSteps(gen, n) {
 	}
 }
 /**
+* @deprecated Use {@link genWalkSteps}.
+*/
+function* takeSteps(gen, n) {
+	yield* genWalkSteps(gen, n);
+}
+/**
 * Yield steps until a specific node is reached.
 */
-function* takeUntilNode(gen, nodeId) {
+function* genWalkUntilNode(gen, nodeId) {
 	for (const step of gen) {
 		yield step;
 		if (step.node.id === nodeId) return;
 	}
 }
 /**
+* @deprecated Use {@link genWalkUntilNode}.
+*/
+function* takeUntilNode(gen, nodeId) {
+	yield* genWalkUntilNode(gen, nodeId);
+}
+/**
 * Yield steps until a specific edge is traversed.
 */
-function* takeUntilEdge(gen, edgeId) {
+function* genWalkUntilEdge(gen, edgeId) {
 	for (const step of gen) {
 		yield step;
 		if (step.edge.id === edgeId) return;
 	}
 }
 /**
+* @deprecated Use {@link genWalkUntilEdge}.
+*/
+function* takeUntilEdge(gen, edgeId) {
+	yield* genWalkUntilEdge(gen, edgeId);
+}
+/**
 * Yield steps until node coverage reaches the target (0–1).
 */
-function* takeUntilNodeCoverage(gen, graph, coverage, options) {
+function* genWalkUntilNodeCoverage(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] : []);
+	if (visited.size >= target) return;
 	for (const step of gen) {
 		visited.add(step.node.id);
 		yield step;
@@ -873,12 +843,19 @@ function* takeUntilNodeCoverage(gen, graph, coverage, options) {
 	}
 }
 /**
+* @deprecated Use {@link genWalkUntilNodeCoverage}.
+*/
+function* takeUntilNodeCoverage(gen, graph, coverage, options) {
+	yield* genWalkUntilNodeCoverage(gen, graph, coverage, options);
+}
+/**
 * Yield steps until edge coverage reaches the target (0–1).
 */
-function* takeUntilEdgeCoverage(gen, graph, coverage) {
+function* genWalkUntilEdgeCoverage(gen, graph, coverage) {
 	const totalEdges = graph.edges.length;
 	const target = Math.ceil(coverage * totalEdges);
 	const visited = /* @__PURE__ */ new Set();
+	if (target <= 0) return;
 	for (const step of gen) {
 		visited.add(step.edge.id);
 		yield step;
@@ -886,6 +863,12 @@ function* takeUntilEdgeCoverage(gen, graph, coverage) {
 	}
 }
 /**
+* @deprecated Use {@link genWalkUntilEdgeCoverage}.
+*/
+function* takeUntilEdgeCoverage(gen, graph, coverage) {
+	yield* genWalkUntilEdgeCoverage(gen, graph, coverage);
+}
+/**
 * Compute coverage statistics for a completed walk.
 */
 function getCoverage(graph, steps, options) {
@@ -906,4 +889,4 @@ function getCoverage(graph, steps, options) {
 }
 
 //#endregion
-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, getEdgeMode, getEdgesBetween, 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, isEdgeDirected, isEmptyDiff, isIsomorphic, isLayoutEqual, isLeaf, isNonLayoutEqual, isTree, joinPaths, reverseGraph, takeSteps, takeUntilEdge, takeUntilEdgeCoverage, takeUntilNode, takeUntilNodeCoverage, toDiff, toPatches, updateEdge, updateEntities, updateNode };
+export { GraphInstance, LAYOUT_KEYS, addEdge, addEntities, addNode, applyPatches, areEntitiesEqual, bfs, createCompleteGraph, createFormatConverter, createGraph, createGraphEdge, createGraphFromTransition, createGraphNode, createGraphPort, createGridGraph, createRandomGraph, createVisualGraph, deleteEdge, deleteEntities, deleteNode, dfs, flatten, genBFS, genCycles, genDFS, genGirvanNewmanCommunities, genPostorders, genPredefinedWalk, genPreorders, genQuickRandomWalk, genRandomWalk, genShortestPaths, genSimplePaths, genWalkSteps, genWalkUntilEdge, genWalkUntilEdgeCoverage, genWalkUntilNode, genWalkUntilNodeCoverage, genWeightedRandomWalk, getAStarPath, getAllPairsShortestPaths, getAncestors, getArticulationPoints, getBetweennessCentrality, getBiconnectedComponents, getBridges, getChildren, getClosenessCentrality, getConnectedComponents, getCoreNumbers, getCoverage, getCycles, getDegree, getDegreeCentrality, getDepth, getDescendants, getDiff, getDominatorTree, getEdge, getEdgeMode, getEdgesBetween, getEdgesByPort, getEdgesOf, getEigenvectorCentrality, getFlattenedGraph, getGirvanNewmanCommunities, getGraphIssues, getGreedyModularityCommunities, getHITS, getInDegree, getInDegreeCentrality, getInEdges, getInvertedDiff, getJoinedPath, getKCore, getKatzCentrality, getLCA, getLabelPropagationCommunities, getLouvainCommunities, getMaxFlow, getMaximumBipartiteMatching, getMinCut, getMinimumSpanningTree, getModularity, getNeighbors, getNode, getOutDegree, getOutDegreeCentrality, getOutEdges, getPageRank, getParent, getPatches, getPort, getPorts, getPostorder, getPostorders, getPredecessors, getPreorder, getPreorders, getRelativeDistance, getRelativeDistanceMap, getReversedGraph, getRoots, getShortestPath, getShortestPaths, getSiblings, getSimplePath, getSimplePaths, getSinks, getSources, getStronglyConnectedComponents, getSubgraph, getSuccessors, getTopologicalSort, getTransitiveReduction, hasEdge, hasNode, hasPath, invalidateIndex, invertDiff, isAcyclic, isBipartite, isCompound, isConnected, isEdgeDirected, isEmptyDiff, isIsomorphic, isLayoutEqual, isLeaf, isNonLayoutEqual, isTree, joinPaths, reverseGraph, takeSteps, takeUntilEdge, takeUntilEdgeCoverage, takeUntilNode, takeUntilNodeCoverage, toDiff, toPatches, updateEdge, updateEntities, updateGraphWithPatches, updateNode };