@statelyai/graph 0.13.0 → 2.0.0

package/dist/index.mjs

@@ -1,7 +1,8 @@
-import { o as invalidateIndex, t as getIndex } from "./indexing-DUl3kTqm.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-BNDQcHU3.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-Dspillnn.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-KirMDR7e.mjs";
+import { $ as joinPaths, A as dfs, B as toEdgeConfig, C as genPostorders, D as getPreorder, E as getPostorders, F as isConnected, G as getAStarPath, H as genCycles, I as isTree, J as getShortestPath, K as getAllPairsShortestPaths, L as flatten, M as getTopologicalSort, N as hasPath, O as getPreorders, P as isAcyclic, Q as getStronglyConnectedComponents, R as getSubgraph, S as getMinimumSpanningTree, T as getPostorder, U as genShortestPaths, V as toNodeConfig, W as genSimplePaths, X as getSimplePath, Y as getShortestPaths, Z as getSimplePaths, _ as getEigenvectorCentrality, _t as updateEdge, a as isIsomorphic, at as createGraphEdge, b as getOutDegreeCentrality, c as getBridges, ct as createGraphPort, d as getGreedyModularityCommunities, dt as deleteEntities, et as GraphInstance, f as getLabelPropagationCommunities, ft as deleteNode, g as getDegreeCentrality, gt as hasNode, h as getClosenessCentrality, ht as hasEdge, i as getLouvainCommunities, it as createGraph, j as getConnectedComponents, k as bfs, l as genGirvanNewmanCommunities, lt as createVisualGraph, m as getBetweennessCentrality, mt as getNode, n as getDominatorTree, nt as addEntities, o as getArticulationPoints, ot as createGraphFromTransition, p as getModularity, pt as getEdge, q as getCycles, r as getMaxFlow, rt as addNode, s as getBiconnectedComponents, st as createGraphNode, t as getTransitiveReduction, tt as addEdge, u as getGirvanNewmanCommunities, ut as deleteEdge, v as getHITS, vt as updateEntities, w as genPreorders, x as getPageRank, y as getInDegreeCentrality, yt as updateNode, z as reverseGraph } from "./algorithms-DF1pSQGv.mjs";
+import { n as isEdgeDirected, t as getEdgeMode } from "./mode-D8OnHFBk.mjs";
+import { t as getGraphIssues } from "./validate-TtH-x3JV.mjs";
+import { n as createFormatConverter } from "./converter-DyCJJfTe.mjs";
 
 //#region src/equivalence.ts
 /** Shallow-compare two values, returning true if they differ. */
@@ -51,7 +52,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;
 }
@@ -86,47 +87,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;
@@ -139,6 +109,7 @@ const NODE_COMPARE_KEYS = [
 	"initialNodeId",
 	"label",
 	"data",
+	"ports",
 	"x",
 	"y",
 	"width",
@@ -152,6 +123,10 @@ const EDGE_COMPARE_KEYS = [
 	"targetId",
 	"label",
 	"data",
+	"weight",
+	"mode",
+	"sourcePort",
+	"targetPort",
 	"x",
 	"y",
 	"width",
@@ -193,13 +168,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,
@@ -208,16 +187,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,
@@ -226,7 +209,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;
 }
 /**
@@ -263,28 +246,29 @@ function isEmptyDiff(diff) {
 function invertDiff(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)
 			}))
 		}
 	};
 }
 /**
 * 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
@@ -364,7 +348,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,
@@ -385,7 +369,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,
@@ -459,201 +443,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,
-		type: graph.type,
-		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,
-		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) {
@@ -679,7 +468,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) {
@@ -692,11 +498,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
@@ -724,30 +530,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;
@@ -755,8 +561,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);
@@ -769,13 +576,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
@@ -788,22 +598,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;
@@ -814,14 +656,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,
@@ -865,6 +712,7 @@ function* takeUntilNodeCoverage(gen, graph, coverage, options) {
 	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;
@@ -878,6 +726,7 @@ function* takeUntilEdgeCoverage(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;
@@ -905,4 +754,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, 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, 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, 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, getDominatorTree, getEdge, getEdgeMode, getEdgesBetween, getEdgesByPort, getEdgesOf, getEigenvectorCentrality, getGirvanNewmanCommunities, getGraphIssues, getGreedyModularityCommunities, getHITS, getInDegree, getInDegreeCentrality, getInEdges, getLCA, getLabelPropagationCommunities, getLouvainCommunities, getMaxFlow, 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, getTransitiveReduction, 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 };

package/dist/mode-D8OnHFBk.mjs

@@ -0,0 +1,15 @@
+//#region src/mode.ts
+/**
+* Resolve an edge's effective directedness. Falls back to the graph's
+* {@link Graph.mode} when the edge has no per-edge override.
+*/
+function getEdgeMode(graph, edge) {
+	return edge.mode ?? graph.mode;
+}
+/** Whether an edge points only from source to target. */
+function isEdgeDirected(graph, edge) {
+	return getEdgeMode(graph, edge) === "directed";
+}
+
+//#endregion
+export { isEdgeDirected as n, getEdgeMode as t };