@statelyai/graph 0.1.0

package/dist/algorithms-R35X6ro4.mjs

@@ -0,0 +1,1197 @@
+import { a as indexUpdateEdgeEndpoints, i as indexReparentNode, n as indexAddEdge, o as invalidateIndex, r as indexAddNode, t as getIndex } from "./indexing-BHg1VhqN.mjs";
+
+//#region src/graph.ts
+function resolveNode(config) {
+	const node = {
+		type: "node",
+		id: config.id,
+		parentId: config.parentId ?? null,
+		initialNodeId: config.initialNodeId ?? null,
+		label: config.label ?? "",
+		data: config.data
+	};
+	if (config.x !== void 0) node.x = config.x;
+	if (config.y !== void 0) node.y = config.y;
+	if (config.width !== void 0) node.width = config.width;
+	if (config.height !== void 0) node.height = config.height;
+	if (config.shape !== void 0) node.shape = config.shape;
+	if (config.color !== void 0) node.color = config.color;
+	if (config.style !== void 0) node.style = config.style;
+	return node;
+}
+function resolveEdge(config) {
+	const edge = {
+		type: "edge",
+		id: config.id,
+		sourceId: config.sourceId,
+		targetId: config.targetId,
+		label: config.label ?? "",
+		data: config.data
+	};
+	if (config.x !== void 0) edge.x = config.x;
+	if (config.y !== void 0) edge.y = config.y;
+	if (config.width !== void 0) edge.width = config.width;
+	if (config.height !== void 0) edge.height = config.height;
+	if (config.color !== void 0) edge.color = config.color;
+	if (config.style !== void 0) edge.style = config.style;
+	return edge;
+}
+/** Create a graph from a config. Resolves defaults for all fields. */
+function createGraph(config) {
+	const graph = {
+		id: config?.id ?? "",
+		type: config?.type ?? "directed",
+		initialNodeId: config?.initialNodeId ?? null,
+		nodes: (config?.nodes ?? []).map(resolveNode),
+		edges: (config?.edges ?? []).map(resolveEdge),
+		data: config?.data ?? void 0
+	};
+	if (config?.direction !== void 0) graph.direction = config.direction;
+	if (config?.style !== void 0) graph.style = config.style;
+	return graph;
+}
+/** Create a visual graph with required position/size on all nodes and edges. */
+function createVisualGraph(config) {
+	const base = createGraph(config);
+	return {
+		...base,
+		direction: config?.direction ?? "down",
+		nodes: base.nodes.map((n) => ({
+			...n,
+			x: n.x ?? 0,
+			y: n.y ?? 0,
+			width: n.width ?? 0,
+			height: n.height ?? 0,
+			shape: n.shape ?? "rectangle"
+		})),
+		edges: base.edges.map((e) => ({
+			...e,
+			x: e.x ?? 0,
+			y: e.y ?? 0,
+			width: e.width ?? 0,
+			height: e.height ?? 0
+		}))
+	};
+}
+/** Get a node by id, or `undefined` if not found. */
+function getNode(graph, id) {
+	const arrayIdx = getIndex(graph).nodeById.get(id);
+	return arrayIdx !== void 0 ? graph.nodes[arrayIdx] : void 0;
+}
+/** Get an edge by id, or `undefined` if not found. */
+function getEdge(graph, id) {
+	const arrayIdx = getIndex(graph).edgeById.get(id);
+	return arrayIdx !== void 0 ? graph.edges[arrayIdx] : void 0;
+}
+/** Check if a node exists in the graph. */
+function hasNode(graph, id) {
+	return getIndex(graph).nodeById.has(id);
+}
+/** Check if an edge exists in the graph. */
+function hasEdge(graph, id) {
+	return getIndex(graph).edgeById.has(id);
+}
+/**
+* **Mutable.** Add a node to the graph. Mutates `graph.nodes` in place.
+* @returns The resolved node that was added.
+*/
+function addNode(graph, config) {
+	const idx = getIndex(graph);
+	if (idx.nodeById.has(config.id)) throw new Error(`Node "${config.id}" already exists`);
+	if (config.parentId != null && !idx.nodeById.has(config.parentId)) throw new Error(`Parent node "${config.parentId}" does not exist`);
+	const node = resolveNode(config);
+	indexAddNode(idx, node, graph.nodes.push(node) - 1);
+	return node;
+}
+/**
+* **Mutable.** Add an edge to the graph. Mutates `graph.edges` in place.
+* @returns The resolved edge that was added.
+*/
+function addEdge(graph, config) {
+	const idx = getIndex(graph);
+	if (idx.edgeById.has(config.id)) throw new Error(`Edge "${config.id}" already exists`);
+	if (!idx.nodeById.has(config.sourceId)) throw new Error(`Source node "${config.sourceId}" does not exist`);
+	if (!idx.nodeById.has(config.targetId)) throw new Error(`Target node "${config.targetId}" does not exist`);
+	const edge = resolveEdge(config);
+	indexAddEdge(idx, edge, graph.edges.push(edge) - 1);
+	return edge;
+}
+/**
+* **Mutable.** Delete a node and its connected edges. Mutates `graph.nodes`
+* and `graph.edges` in place.
+*
+* By default, children are deleted recursively.
+* With `{ reparent: true }`, children are re-parented to the deleted node's parent.
+*/
+function deleteNode(graph, id, opts) {
+	const node = getNode(graph, id);
+	if (!node) throw new Error(`Node "${id}" does not exist`);
+	if (opts?.reparent) {
+		for (const n of graph.nodes) if (n.parentId === id) n.parentId = node.parentId;
+		graph.nodes = graph.nodes.filter((n) => n.id !== id);
+		graph.edges = graph.edges.filter((e) => e.sourceId !== id && e.targetId !== id);
+	} else {
+		const toDelete = collectDescendants(graph, id);
+		graph.nodes = graph.nodes.filter((n) => !toDelete.has(n.id));
+		graph.edges = graph.edges.filter((e) => !toDelete.has(e.sourceId) && !toDelete.has(e.targetId));
+	}
+	invalidateIndex(graph);
+}
+/**
+* **Mutable.** Delete an edge. Mutates `graph.edges` in place.
+*/
+function deleteEdge(graph, id) {
+	if (!hasEdge(graph, id)) throw new Error(`Edge "${id}" does not exist`);
+	graph.edges = graph.edges.filter((e) => e.id !== id);
+	invalidateIndex(graph);
+}
+/**
+* **Mutable.** Update a node in place.
+* @returns The updated node.
+*/
+function updateNode(graph, id, update) {
+	const idx = getIndex(graph);
+	const arrayIdx = idx.nodeById.get(id);
+	if (arrayIdx === void 0) throw new Error(`Node "${id}" does not exist`);
+	if (update.parentId !== void 0 && update.parentId !== null) {
+		if (!idx.nodeById.has(update.parentId)) throw new Error(`Parent node "${update.parentId}" does not exist`);
+	}
+	const node = graph.nodes[arrayIdx];
+	const oldParentId = node.parentId;
+	const updated = {
+		...node,
+		...update.parentId !== void 0 && { parentId: update.parentId ?? null },
+		...update.initialNodeId !== void 0 && { initialNodeId: update.initialNodeId ?? null },
+		...update.label !== void 0 && { label: update.label },
+		...update.data !== void 0 && { data: update.data }
+	};
+	graph.nodes[arrayIdx] = updated;
+	if (update.parentId !== void 0 && updated.parentId !== oldParentId) indexReparentNode(idx, id, oldParentId, updated.parentId);
+	return updated;
+}
+/**
+* **Mutable.** Update an edge in place.
+* @returns The updated edge.
+*/
+function updateEdge(graph, id, update) {
+	const idx = getIndex(graph);
+	const arrayIdx = idx.edgeById.get(id);
+	if (arrayIdx === void 0) throw new Error(`Edge "${id}" does not exist`);
+	if (update.sourceId !== void 0 && !idx.nodeById.has(update.sourceId)) throw new Error(`Source node "${update.sourceId}" does not exist`);
+	if (update.targetId !== void 0 && !idx.nodeById.has(update.targetId)) throw new Error(`Target node "${update.targetId}" does not exist`);
+	const edge = graph.edges[arrayIdx];
+	const oldSourceId = edge.sourceId;
+	const oldTargetId = edge.targetId;
+	const updated = {
+		...edge,
+		...update.sourceId !== void 0 && { sourceId: update.sourceId },
+		...update.targetId !== void 0 && { targetId: update.targetId },
+		...update.label !== void 0 && { label: update.label },
+		...update.data !== void 0 && { data: update.data }
+	};
+	graph.edges[arrayIdx] = updated;
+	if (updated.sourceId !== oldSourceId || updated.targetId !== oldTargetId) indexUpdateEdgeEndpoints(idx, id, oldSourceId, oldTargetId, updated.sourceId, updated.targetId);
+	return updated;
+}
+/**
+* **Mutable.** Add multiple nodes and edges to the graph.
+* Nodes are added first, then edges (so edges can reference new nodes).
+*/
+function addEntities(graph, entities) {
+	for (const nodeConfig of entities.nodes ?? []) addNode(graph, nodeConfig);
+	for (const edgeConfig of entities.edges ?? []) addEdge(graph, edgeConfig);
+}
+/**
+* **Mutable.** Delete entities by id(s). Automatically detects whether each id
+* is a node or edge. Node deletions cascade to children and connected edges.
+*/
+function deleteEntities(graph, ids, opts) {
+	const idArray = Array.isArray(ids) ? ids : [ids];
+	for (const id of idArray) if (hasNode(graph, id)) deleteNode(graph, id, opts);
+	else if (hasEdge(graph, id)) deleteEdge(graph, id);
+}
+/**
+* **Mutable.** Update multiple nodes and edges in place.
+* Each entry must include an `id` to identify which entity to update.
+*/
+function updateEntities(graph, updates) {
+	for (const nodeUpdate of updates.nodes ?? []) {
+		const { id, ...patch } = nodeUpdate;
+		updateNode(graph, id, patch);
+	}
+	for (const edgeUpdate of updates.edges ?? []) {
+		const { id, ...patch } = edgeUpdate;
+		updateEdge(graph, id, patch);
+	}
+}
+/**
+* OOP wrapper around a plain `Graph` object.
+* Delegates to the standalone mutable functions.
+*/
+var GraphInstance = class GraphInstance {
+	graph;
+	constructor(config) {
+		this.graph = createGraph(config);
+	}
+	/** Wrap an existing plain graph object. */
+	static from(graph) {
+		const instance = Object.create(GraphInstance.prototype);
+		instance.graph = graph;
+		return instance;
+	}
+	get id() {
+		return this.graph.id;
+	}
+	get type() {
+		return this.graph.type;
+	}
+	get nodes() {
+		return this.graph.nodes;
+	}
+	get edges() {
+		return this.graph.edges;
+	}
+	get data() {
+		return this.graph.data;
+	}
+	getNode(id) {
+		return getNode(this.graph, id);
+	}
+	getEdge(id) {
+		return getEdge(this.graph, id);
+	}
+	hasNode(id) {
+		return hasNode(this.graph, id);
+	}
+	hasEdge(id) {
+		return hasEdge(this.graph, id);
+	}
+	addNode(config) {
+		return addNode(this.graph, config);
+	}
+	addEdge(config) {
+		return addEdge(this.graph, config);
+	}
+	deleteNode(id, opts) {
+		return deleteNode(this.graph, id, opts);
+	}
+	deleteEdge(id) {
+		return deleteEdge(this.graph, id);
+	}
+	updateNode(id, update) {
+		return updateNode(this.graph, id, update);
+	}
+	updateEdge(id, update) {
+		return updateEdge(this.graph, id, update);
+	}
+	addEntities(entities) {
+		return addEntities(this.graph, entities);
+	}
+	deleteEntities(ids, opts) {
+		return deleteEntities(this.graph, ids, opts);
+	}
+	updateEntities(updates) {
+		return updateEntities(this.graph, updates);
+	}
+	toJSON() {
+		return this.graph;
+	}
+};
+function collectDescendants(graph, id) {
+	const idx = getIndex(graph);
+	const toDelete = /* @__PURE__ */ new Set();
+	const walk = (nodeId) => {
+		toDelete.add(nodeId);
+		const childIds = idx.childNodes.get(nodeId) ?? [];
+		for (const childId of childIds) if (!toDelete.has(childId)) walk(childId);
+	};
+	walk(id);
+	return toDelete;
+}
+
+//#endregion
+//#region src/algorithms.ts
+function* bfs(graph, startId) {
+	const idx = getIndex(graph);
+	const visited = /* @__PURE__ */ new Set();
+	const queue = [startId];
+	visited.add(startId);
+	while (queue.length > 0) {
+		const id = queue.shift();
+		const ni = idx.nodeById.get(id);
+		if (ni === void 0) continue;
+		yield graph.nodes[ni];
+		for (const nId of getNeighborIds(graph, id)) if (!visited.has(nId)) {
+			visited.add(nId);
+			queue.push(nId);
+		}
+	}
+}
+function* dfs(graph, startId) {
+	const idx = getIndex(graph);
+	const visited = /* @__PURE__ */ new Set();
+	const stack = [startId];
+	while (stack.length > 0) {
+		const id = stack.pop();
+		if (visited.has(id)) continue;
+		visited.add(id);
+		const ni = idx.nodeById.get(id);
+		if (ni === void 0) continue;
+		yield graph.nodes[ni];
+		for (const nId of getNeighborIds(graph, id)) if (!visited.has(nId)) stack.push(nId);
+	}
+}
+function getNeighborIds(graph, nodeId) {
+	const idx = getIndex(graph);
+	const ids = [];
+	for (const eid of idx.outEdges.get(nodeId) ?? []) {
+		const ai = idx.edgeById.get(eid);
+		if (ai !== void 0) ids.push(graph.edges[ai].targetId);
+	}
+	if (graph.type === "undirected") for (const eid of idx.inEdges.get(nodeId) ?? []) {
+		const ai = idx.edgeById.get(eid);
+		if (ai !== void 0) ids.push(graph.edges[ai].sourceId);
+	}
+	return ids;
+}
+function getSuccessorIds(graph, nodeId) {
+	const idx = getIndex(graph);
+	return (idx.outEdges.get(nodeId) ?? []).map((eid) => graph.edges[idx.edgeById.get(eid)].targetId);
+}
+function isAcyclic(graph) {
+	if (graph.type === "undirected") return isAcyclicUndirected(graph);
+	const WHITE = 0, GRAY = 1, BLACK = 2;
+	const color = /* @__PURE__ */ new Map();
+	for (const n of graph.nodes) color.set(n.id, WHITE);
+	const hasCycle = (id) => {
+		color.set(id, GRAY);
+		for (const nId of getSuccessorIds(graph, id)) {
+			const c = color.get(nId);
+			if (c === GRAY) return true;
+			if (c === WHITE && hasCycle(nId)) return true;
+		}
+		color.set(id, BLACK);
+		return false;
+	};
+	for (const n of graph.nodes) if (color.get(n.id) === WHITE && hasCycle(n.id)) return false;
+	return true;
+}
+function isAcyclicUndirected(graph) {
+	const idx = getIndex(graph);
+	const visited = /* @__PURE__ */ new Set();
+	const hasCycle = (id, parentId) => {
+		visited.add(id);
+		for (const eid of idx.outEdges.get(id) ?? []) {
+			const ai = idx.edgeById.get(eid);
+			if (ai === void 0) continue;
+			const neighborId = graph.edges[ai].targetId;
+			if (!visited.has(neighborId)) {
+				if (hasCycle(neighborId, id)) return true;
+			} else if (neighborId !== parentId) return true;
+		}
+		for (const eid of idx.inEdges.get(id) ?? []) {
+			const ai = idx.edgeById.get(eid);
+			if (ai === void 0) continue;
+			const neighborId = graph.edges[ai].sourceId;
+			if (!visited.has(neighborId)) {
+				if (hasCycle(neighborId, id)) return true;
+			} else if (neighborId !== parentId) return true;
+		}
+		return false;
+	};
+	for (const n of graph.nodes) if (!visited.has(n.id) && hasCycle(n.id, null)) return false;
+	return true;
+}
+function getConnectedComponents(graph) {
+	const idx = getIndex(graph);
+	const visited = /* @__PURE__ */ new Set();
+	const components = [];
+	for (const n of graph.nodes) {
+		if (visited.has(n.id)) continue;
+		const component = [];
+		const queue = [n.id];
+		visited.add(n.id);
+		while (queue.length > 0) {
+			const id = queue.shift();
+			const ni = idx.nodeById.get(id);
+			if (ni !== void 0) component.push(graph.nodes[ni]);
+			for (const eid of idx.outEdges.get(id) ?? []) {
+				const ai = idx.edgeById.get(eid);
+				if (ai === void 0) continue;
+				const neighborId = graph.edges[ai].targetId;
+				if (!visited.has(neighborId)) {
+					visited.add(neighborId);
+					queue.push(neighborId);
+				}
+			}
+			for (const eid of idx.inEdges.get(id) ?? []) {
+				const ai = idx.edgeById.get(eid);
+				if (ai === void 0) continue;
+				const neighborId = graph.edges[ai].sourceId;
+				if (!visited.has(neighborId)) {
+					visited.add(neighborId);
+					queue.push(neighborId);
+				}
+			}
+		}
+		components.push(component);
+	}
+	return components;
+}
+function getTopologicalSort(graph) {
+	const idx = getIndex(graph);
+	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 queue = [];
+	for (const [id, deg] of inDeg) if (deg === 0) queue.push(id);
+	const result = [];
+	while (queue.length > 0) {
+		const id = queue.shift();
+		const ni = idx.nodeById.get(id);
+		if (ni !== void 0) result.push(graph.nodes[ni]);
+		for (const eid of idx.outEdges.get(id) ?? []) {
+			const ai = idx.edgeById.get(eid);
+			if (ai === void 0) continue;
+			const targetId = graph.edges[ai].targetId;
+			const newDeg = (inDeg.get(targetId) ?? 1) - 1;
+			inDeg.set(targetId, newDeg);
+			if (newDeg === 0) queue.push(targetId);
+		}
+	}
+	if (result.length !== graph.nodes.length) return null;
+	return result;
+}
+function hasPath(graph, sourceId, targetId) {
+	return getShortestPaths(graph, {
+		from: sourceId,
+		to: targetId
+	}).length > 0;
+}
+function isConnected(graph) {
+	if (graph.nodes.length === 0) return true;
+	return getConnectedComponents(graph).length <= 1;
+}
+function isTree(graph) {
+	return isConnected(graph) && isAcyclic(graph);
+}
+/** Resolve the `from` node ID from opts or graph defaults. */
+function resolveFrom(graph, opts) {
+	if (opts?.from) return opts.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).map(([id]) => id);
+	if (roots.length === 1) return roots[0];
+	throw new Error("Cannot determine start node — provide opts.from or set graph.initialNodeId");
+}
+/** Get neighbor IDs with their connecting edges. */
+function getNeighborEdges(graph, nodeId) {
+	const idx = getIndex(graph);
+	const result = [];
+	for (const eid of idx.outEdges.get(nodeId) ?? []) {
+		const ai = idx.edgeById.get(eid);
+		if (ai !== void 0) {
+			const e = graph.edges[ai];
+			result.push({
+				neighborId: e.targetId,
+				edge: e
+			});
+		}
+	}
+	if (graph.type === "undirected") for (const eid of idx.inEdges.get(nodeId) ?? []) {
+		const ai = idx.edgeById.get(eid);
+		if (ai !== void 0) {
+			const e = graph.edges[ai];
+			result.push({
+				neighborId: e.sourceId,
+				edge: e
+			});
+		}
+	}
+	return result;
+}
+/**
+* Returns all shortest paths from a source node.
+* Returns all paths of equal minimum length per target (not just one).
+* Uses BFS by default; Dijkstra when `opts.getWeight` is provided.
+*/
+/** Compute distance + prev maps via BFS or Dijkstra. */
+function computeShortestDistances(graph, sourceId, getWeight) {
+	const dist = /* @__PURE__ */ new Map();
+	const prev = /* @__PURE__ */ new Map();
+	dist.set(sourceId, 0);
+	prev.set(sourceId, []);
+	if (!getWeight) {
+		const queue = [sourceId];
+		while (queue.length > 0) {
+			const id = queue.shift();
+			const d = dist.get(id);
+			for (const { neighborId, edge } of getNeighborEdges(graph, id)) {
+				const newDist = d + 1;
+				const existing = dist.get(neighborId);
+				if (existing === void 0) {
+					dist.set(neighborId, newDist);
+					prev.set(neighborId, [{
+						from: id,
+						edge
+					}]);
+					queue.push(neighborId);
+				} else if (existing === newDist) prev.get(neighborId).push({
+					from: id,
+					edge
+				});
+			}
+		}
+	} else {
+		const visited = /* @__PURE__ */ new Set();
+		const pq = [{
+			id: sourceId,
+			dist: 0
+		}];
+		while (pq.length > 0) {
+			let minIdx = 0;
+			for (let i = 1; i < pq.length; i++) if (pq[i].dist < pq[minIdx].dist) minIdx = i;
+			const { id, dist: d } = pq.splice(minIdx, 1)[0];
+			if (visited.has(id)) continue;
+			visited.add(id);
+			for (const { neighborId, edge } of getNeighborEdges(graph, id)) {
+				const newDist = d + getWeight(edge);
+				const existing = dist.get(neighborId);
+				if (existing === void 0 || newDist < existing) {
+					dist.set(neighborId, newDist);
+					prev.set(neighborId, [{
+						from: id,
+						edge
+					}]);
+					pq.push({
+						id: neighborId,
+						dist: newDist
+					});
+				} else if (existing === newDist) prev.get(neighborId).push({
+					from: id,
+					edge
+				});
+			}
+		}
+	}
+	return {
+		dist,
+		prev
+	};
+}
+/** Reconstruct all shortest paths to a target by backtracking through prev map. */
+function* reconstructPaths(graph, prev, sourceNode, targetId) {
+	if (targetId === sourceNode.id) {
+		yield {
+			source: sourceNode,
+			steps: []
+		};
+		return;
+	}
+	const preds = prev.get(targetId);
+	if (!preds || preds.length === 0) return;
+	const targetNi = getIndex(graph).nodeById.get(targetId);
+	const targetNode = targetNi !== void 0 ? graph.nodes[targetNi] : graph.nodes.find((n) => n.id === targetId);
+	for (const { from, edge } of preds) for (const prefix of reconstructPaths(graph, prev, sourceNode, from)) yield {
+		source: sourceNode,
+		steps: [...prefix.steps, {
+			edge,
+			node: targetNode
+		}]
+	};
+}
+/**
+* Lazily yields all shortest paths from a source node.
+* Use `getShortestPaths` for the full array.
+*/
+function* genShortestPaths(graph, opts) {
+	const idx = getIndex(graph);
+	const sourceId = resolveFrom(graph, opts);
+	const { dist, prev } = computeShortestDistances(graph, sourceId, opts?.getWeight);
+	const targets = opts?.to ? [opts.to].filter((id) => dist.has(id)) : [...dist.keys()].filter((id) => id !== sourceId);
+	const sourceNi = idx.nodeById.get(sourceId);
+	const sourceNode = sourceNi !== void 0 ? graph.nodes[sourceNi] : graph.nodes.find((n) => n.id === sourceId);
+	for (const targetId of targets) yield* reconstructPaths(graph, prev, sourceNode, targetId);
+}
+function getShortestPaths(graph, opts) {
+	return [...genShortestPaths(graph, opts)];
+}
+/**
+* Returns a single shortest path from source to target, or undefined if unreachable.
+*/
+function getShortestPath(graph, opts) {
+	for (const path of genShortestPaths(graph, opts)) return path;
+}
+/**
+* Returns all simple (acyclic) paths from a source node.
+* Uses DFS with backtracking.
+*/
+function getSimplePaths(graph, opts) {
+	return [...genSimplePaths(graph, opts)];
+}
+/**
+* Lazily yields all simple (acyclic) paths from a source node.
+* Use `getSimplePaths` for the full array.
+*/
+function* genSimplePaths(graph, opts) {
+	const idx = getIndex(graph);
+	const sourceId = resolveFrom(graph, opts);
+	const sourceNi = idx.nodeById.get(sourceId);
+	const sourceNode = sourceNi !== void 0 ? graph.nodes[sourceNi] : graph.nodes.find((n) => n.id === sourceId);
+	const targetId = opts?.to;
+	const visited = /* @__PURE__ */ new Set();
+	const currentSteps = [];
+	const found = [];
+	function dfsCollect(nodeId) {
+		visited.add(nodeId);
+		if (targetId !== void 0) {
+			if (nodeId === targetId) {
+				found.push({
+					source: sourceNode,
+					steps: [...currentSteps]
+				});
+				visited.delete(nodeId);
+				return;
+			}
+		} else if (currentSteps.length > 0) found.push({
+			source: sourceNode,
+			steps: [...currentSteps]
+		});
+		for (const { neighborId, edge } of getNeighborEdges(graph, nodeId)) if (!visited.has(neighborId)) {
+			const neighborNi = idx.nodeById.get(neighborId);
+			const neighborNode = neighborNi !== void 0 ? graph.nodes[neighborNi] : graph.nodes.find((n) => n.id === neighborId);
+			currentSteps.push({
+				edge,
+				node: neighborNode
+			});
+			dfsCollect(neighborId);
+			currentSteps.pop();
+		}
+		visited.delete(nodeId);
+	}
+	dfsCollect(sourceId);
+	yield* found;
+}
+/**
+* Returns a single simple (acyclic) path from source to target, or undefined if unreachable.
+*/
+function getSimplePath(graph, opts) {
+	for (const path of genSimplePaths(graph, opts)) return path;
+}
+function getStronglyConnectedComponents(graph) {
+	const idx = getIndex(graph);
+	let indexCounter = 0;
+	const nodeIndex = /* @__PURE__ */ new Map();
+	const lowlink = /* @__PURE__ */ new Map();
+	const onStack = /* @__PURE__ */ new Set();
+	const stack = [];
+	const result = [];
+	function strongconnect(id) {
+		nodeIndex.set(id, indexCounter);
+		lowlink.set(id, indexCounter);
+		indexCounter++;
+		stack.push(id);
+		onStack.add(id);
+		for (const eid of idx.outEdges.get(id) ?? []) {
+			const ai = idx.edgeById.get(eid);
+			if (ai === void 0) continue;
+			const wId = graph.edges[ai].targetId;
+			if (!nodeIndex.has(wId)) {
+				strongconnect(wId);
+				lowlink.set(id, Math.min(lowlink.get(id), lowlink.get(wId)));
+			} else if (onStack.has(wId)) lowlink.set(id, Math.min(lowlink.get(id), nodeIndex.get(wId)));
+		}
+		if (lowlink.get(id) === nodeIndex.get(id)) {
+			const component = [];
+			let wId;
+			do {
+				wId = stack.pop();
+				onStack.delete(wId);
+				const ni = idx.nodeById.get(wId);
+				if (ni !== void 0) component.push(graph.nodes[ni]);
+			} while (wId !== id);
+			result.push(component);
+		}
+	}
+	for (const n of graph.nodes) if (!nodeIndex.has(n.id)) strongconnect(n.id);
+	return result;
+}
+function getCycles(graph) {
+	return [...genCycles(graph)];
+}
+/**
+* Lazily yields cycles one at a time.
+* Use `getCycles` for the full array.
+*/
+function* genCycles(graph) {
+	if (graph.type === "undirected") yield* genCyclesUndirected(graph);
+	else yield* genCyclesDirected(graph);
+}
+function* genCyclesDirected(graph) {
+	const idx = getIndex(graph);
+	const sortedIds = graph.nodes.map((n) => n.id).sort();
+	for (let si = 0; si < sortedIds.length; si++) {
+		const startId = sortedIds[si];
+		const allowed = new Set(sortedIds.slice(si));
+		const visited = /* @__PURE__ */ new Set();
+		const steps = [];
+		const startNi = idx.nodeById.get(startId);
+		const startNode = graph.nodes[startNi];
+		const found = [];
+		function dfsFind(currentId) {
+			visited.add(currentId);
+			for (const eid of idx.outEdges.get(currentId) ?? []) {
+				const ai = idx.edgeById.get(eid);
+				if (ai === void 0) continue;
+				const e = graph.edges[ai];
+				const neighborId = e.targetId;
+				if (neighborId === startId && (steps.length > 0 || currentId === startId)) found.push({
+					source: startNode,
+					steps: [...steps, {
+						edge: e,
+						node: startNode
+					}]
+				});
+				else if (allowed.has(neighborId) && !visited.has(neighborId)) {
+					const ni = idx.nodeById.get(neighborId);
+					steps.push({
+						edge: e,
+						node: graph.nodes[ni]
+					});
+					dfsFind(neighborId);
+					steps.pop();
+				}
+			}
+			visited.delete(currentId);
+		}
+		dfsFind(startId);
+		yield* found;
+	}
+}
+function* genCyclesUndirected(graph) {
+	const idx = getIndex(graph);
+	const sortedIds = graph.nodes.map((n) => n.id).sort();
+	const seen = /* @__PURE__ */ new Set();
+	for (let si = 0; si < sortedIds.length; si++) {
+		const startId = sortedIds[si];
+		const allowed = new Set(sortedIds.slice(si));
+		const visited = /* @__PURE__ */ new Set();
+		const steps = [];
+		const startNi = idx.nodeById.get(startId);
+		const startNode = graph.nodes[startNi];
+		const found = [];
+		function dfsFind(currentId, parentId) {
+			visited.add(currentId);
+			for (const { neighborId, edge } of getNeighborEdgesAll(graph, currentId)) {
+				if (neighborId === parentId) {
+					parentId = null;
+					continue;
+				}
+				if (neighborId === startId && steps.length >= 2) {
+					const innerIds = steps.map((s) => s.node.id).sort().join(",");
+					if (!seen.has(innerIds)) {
+						seen.add(innerIds);
+						found.push({
+							source: startNode,
+							steps: [...steps, {
+								edge,
+								node: startNode
+							}]
+						});
+					}
+				} else if (allowed.has(neighborId) && !visited.has(neighborId)) {
+					const ni = idx.nodeById.get(neighborId);
+					steps.push({
+						edge,
+						node: graph.nodes[ni]
+					});
+					dfsFind(neighborId, currentId);
+					steps.pop();
+				}
+			}
+			visited.delete(currentId);
+		}
+		dfsFind(startId, null);
+		yield* found;
+	}
+}
+/** Like getNeighborEdges but always includes both directions (for undirected cycle finding). */
+function getNeighborEdgesAll(graph, nodeId) {
+	const idx = getIndex(graph);
+	const result = [];
+	for (const eid of idx.outEdges.get(nodeId) ?? []) {
+		const ai = idx.edgeById.get(eid);
+		if (ai !== void 0) {
+			const e = graph.edges[ai];
+			result.push({
+				neighborId: e.targetId,
+				edge: e
+			});
+		}
+	}
+	for (const eid of idx.inEdges.get(nodeId) ?? []) {
+		const ai = idx.edgeById.get(eid);
+		if (ai !== void 0) {
+			const e = graph.edges[ai];
+			result.push({
+				neighborId: e.sourceId,
+				edge: e
+			});
+		}
+	}
+	return result;
+}
+/**
+* Returns a single canonical preorder (DFS visit-order) sequence.
+* Visits neighbors in the order they appear in the adjacency list.
+*/
+function getPreorder(graph, opts) {
+	const idx = getIndex(graph);
+	const startId = resolveFrom(graph, opts);
+	const startNi = idx.nodeById.get(startId);
+	if (startNi === void 0) return [];
+	const visited = new Set([startId]);
+	const result = [graph.nodes[startNi]];
+	const stack = [startId];
+	while (stack.length > 0) {
+		const top = stack[stack.length - 1];
+		const next = getNeighborIds(graph, top).find((id) => !visited.has(id));
+		if (next === void 0) {
+			stack.pop();
+			continue;
+		}
+		visited.add(next);
+		stack.push(next);
+		const ni = idx.nodeById.get(next);
+		if (ni !== void 0) result.push(graph.nodes[ni]);
+	}
+	return result;
+}
+/**
+* Returns a single canonical postorder (DFS finish-order) sequence.
+* Visits neighbors in the order they appear in the adjacency list.
+*/
+function getPostorder(graph, opts) {
+	const idx = getIndex(graph);
+	const startId = resolveFrom(graph, opts);
+	if (idx.nodeById.get(startId) === void 0) return [];
+	const visited = new Set([startId]);
+	const result = [];
+	const stack = [startId];
+	while (stack.length > 0) {
+		const top = stack[stack.length - 1];
+		const next = getNeighborIds(graph, top).find((id) => !visited.has(id));
+		if (next === void 0) {
+			stack.pop();
+			const ni = idx.nodeById.get(top);
+			if (ni !== void 0) result.push(graph.nodes[ni]);
+			continue;
+		}
+		visited.add(next);
+		stack.push(next);
+	}
+	return result;
+}
+/** Returns all possible preorder sequences as an array. Can be exponential — prefer `genPreorders`. */
+function getPreorders(graph, opts) {
+	return [...genPreorders(graph, opts)];
+}
+/** Returns all possible postorder sequences as an array. Can be exponential — prefer `genPostorders`. */
+function getPostorders(graph, opts) {
+	return [...genPostorders(graph, opts)];
+}
+/**
+* Lazily yields all possible preorder (DFS visit-order) sequences.
+* Different neighbor exploration orders yield different sequences.
+* Use `getPreorder()` for a single canonical ordering.
+*/
+function* genPreorders(graph, opts) {
+	const idx = getIndex(graph);
+	const startId = resolveFrom(graph, opts);
+	const startNi = idx.nodeById.get(startId);
+	const startNode = startNi !== void 0 ? graph.nodes[startNi] : void 0;
+	if (!startNode) return;
+	const queue = [{
+		visited: new Set([startId]),
+		preorder: [startNode],
+		dfsStack: [startId]
+	}];
+	while (queue.length > 0) {
+		const frame = queue.pop();
+		const { visited, dfsStack } = frame;
+		let { preorder } = frame;
+		let branched = false;
+		while (dfsStack.length > 0) {
+			const top = dfsStack[dfsStack.length - 1];
+			const unvisited = getNeighborIds(graph, top).filter((id) => !visited.has(id));
+			if (unvisited.length === 0) {
+				dfsStack.pop();
+				continue;
+			}
+			for (const nextId of unvisited) {
+				const ni = idx.nodeById.get(nextId);
+				if (ni === void 0) continue;
+				const newVisited = new Set(visited);
+				newVisited.add(nextId);
+				queue.push({
+					visited: newVisited,
+					preorder: [...preorder, graph.nodes[ni]],
+					dfsStack: [...dfsStack, nextId]
+				});
+			}
+			branched = true;
+			break;
+		}
+		if (!branched) yield preorder;
+	}
+}
+/**
+* Lazily yields all possible postorder (DFS finish-order) sequences.
+* Different neighbor exploration orders yield different sequences.
+* Use `getPostorder()` for a single canonical ordering.
+*/
+function* genPostorders(graph, opts) {
+	const idx = getIndex(graph);
+	const startId = resolveFrom(graph, opts);
+	if (idx.nodeById.get(startId) === void 0) return;
+	const queue = [{
+		visited: new Set([startId]),
+		postorder: [],
+		dfsStack: [startId]
+	}];
+	while (queue.length > 0) {
+		const frame = queue.pop();
+		const { visited, dfsStack } = frame;
+		let { postorder } = frame;
+		let branched = false;
+		while (dfsStack.length > 0) {
+			const top = dfsStack[dfsStack.length - 1];
+			const unvisited = getNeighborIds(graph, top).filter((id) => !visited.has(id));
+			if (unvisited.length === 0) {
+				dfsStack.pop();
+				const ni = idx.nodeById.get(top);
+				if (ni !== void 0) postorder = [...postorder, graph.nodes[ni]];
+				continue;
+			}
+			for (const nextId of unvisited) {
+				if (idx.nodeById.get(nextId) === void 0) continue;
+				const newVisited = new Set(visited);
+				newVisited.add(nextId);
+				queue.push({
+					visited: newVisited,
+					postorder: [...postorder],
+					dfsStack: [...dfsStack, nextId]
+				});
+			}
+			branched = true;
+			break;
+		}
+		if (!branched) yield postorder;
+	}
+}
+/**
+* Returns a minimum spanning tree of the graph.
+* Only meaningful for connected undirected graphs (or the component reachable
+* from an arbitrary start node in directed graphs).
+*/
+function getMinimumSpanningTree(graph, opts) {
+	const algorithm = opts?.algorithm ?? "prim";
+	const getWeight = opts?.getWeight ?? (() => 1);
+	const mstEdges = algorithm === "kruskal" ? kruskalMST(graph, getWeight) : primMST(graph, getWeight);
+	return createGraph({
+		id: graph.id,
+		type: graph.type,
+		initialNodeId: graph.initialNodeId ?? void 0,
+		nodes: graph.nodes.map((n) => ({
+			id: n.id,
+			parentId: n.parentId ?? void 0,
+			initialNodeId: n.initialNodeId ?? void 0,
+			label: n.label,
+			data: n.data
+		})),
+		edges: mstEdges.map((e) => ({
+			id: e.id,
+			sourceId: e.sourceId,
+			targetId: e.targetId,
+			label: e.label,
+			data: e.data
+		}))
+	});
+}
+function primMST(graph, getWeight) {
+	if (graph.nodes.length === 0) return [];
+	const idx = getIndex(graph);
+	const inMST = /* @__PURE__ */ new Set();
+	const mstEdges = [];
+	const candidates = [];
+	function addEdgesOf(nodeId) {
+		for (const eid of idx.outEdges.get(nodeId) ?? []) {
+			const ai = idx.edgeById.get(eid);
+			if (ai === void 0) continue;
+			const e = graph.edges[ai];
+			if (!inMST.has(e.targetId)) candidates.push({
+				weight: getWeight(e),
+				edge: e
+			});
+		}
+		if (graph.type === "undirected") for (const eid of idx.inEdges.get(nodeId) ?? []) {
+			const ai = idx.edgeById.get(eid);
+			if (ai === void 0) continue;
+			const e = graph.edges[ai];
+			if (!inMST.has(e.sourceId)) candidates.push({
+				weight: getWeight(e),
+				edge: e
+			});
+		}
+	}
+	const startId = graph.nodes[0].id;
+	inMST.add(startId);
+	addEdgesOf(startId);
+	while (candidates.length > 0 && inMST.size < graph.nodes.length) {
+		let minIdx = 0;
+		for (let i = 1; i < candidates.length; i++) if (candidates[i].weight < candidates[minIdx].weight) minIdx = i;
+		const { edge } = candidates.splice(minIdx, 1)[0];
+		const targetId = graph.type === "undirected" && inMST.has(edge.targetId) ? edge.sourceId : edge.targetId;
+		if (inMST.has(targetId)) continue;
+		inMST.add(targetId);
+		mstEdges.push(edge);
+		addEdgesOf(targetId);
+	}
+	return mstEdges;
+}
+function kruskalMST(graph, getWeight) {
+	const sorted = [...graph.edges].sort((a, b) => getWeight(a) - getWeight(b));
+	const parent = /* @__PURE__ */ new Map();
+	const rank = /* @__PURE__ */ new Map();
+	for (const n of graph.nodes) {
+		parent.set(n.id, n.id);
+		rank.set(n.id, 0);
+	}
+	function find(x) {
+		if (parent.get(x) !== x) parent.set(x, find(parent.get(x)));
+		return parent.get(x);
+	}
+	function union(x, y) {
+		const rx = find(x), ry = find(y);
+		if (rx === ry) return false;
+		if (rank.get(rx) < rank.get(ry)) parent.set(rx, ry);
+		else if (rank.get(rx) > rank.get(ry)) parent.set(ry, rx);
+		else {
+			parent.set(ry, rx);
+			rank.set(rx, rank.get(rx) + 1);
+		}
+		return true;
+	}
+	const mstEdges = [];
+	for (const e of sorted) if (union(e.sourceId, e.targetId)) mstEdges.push(e);
+	return mstEdges;
+}
+/**
+* Returns shortest paths between all pairs of nodes.
+* Algorithm 'dijkstra' (default): runs getShortestPaths per source node.
+* Algorithm 'floyd-warshall': classic O(V³) dynamic programming.
+*/
+function getAllPairsShortestPaths(graph, opts) {
+	if ((opts?.algorithm ?? "dijkstra") === "floyd-warshall") return floydWarshallAllPaths(graph, opts?.getWeight);
+	return dijkstraAllPaths(graph, opts?.getWeight);
+}
+function dijkstraAllPaths(graph, getWeight) {
+	const results = [];
+	for (const node of graph.nodes) {
+		const paths = getShortestPaths(graph, {
+			from: node.id,
+			getWeight
+		});
+		results.push(...paths);
+	}
+	return results;
+}
+function floydWarshallAllPaths(graph, getWeight) {
+	const idx = getIndex(graph);
+	const w = getWeight ?? (() => 1);
+	const nodeIds = graph.nodes.map((n$1) => n$1.id);
+	const n = nodeIds.length;
+	const idxOf = /* @__PURE__ */ new Map();
+	for (let i = 0; i < n; i++) idxOf.set(nodeIds[i], i);
+	const INF = Infinity;
+	const dist = Array.from({ length: n }, () => Array(n).fill(INF));
+	const prev = Array.from({ length: n }, () => Array.from({ length: n }, () => []));
+	for (let i = 0; i < n; i++) dist[i][i] = 0;
+	for (const e of graph.edges) {
+		const u = idxOf.get(e.sourceId);
+		const v = idxOf.get(e.targetId);
+		const weight = w(e);
+		if (weight < dist[u][v]) {
+			dist[u][v] = weight;
+			prev[u][v] = [{
+				from: u,
+				edge: e
+			}];
+		} else if (weight === dist[u][v] && weight < INF) prev[u][v].push({
+			from: u,
+			edge: e
+		});
+		if (graph.type === "undirected") {
+			if (weight < dist[v][u]) {
+				dist[v][u] = weight;
+				prev[v][u] = [{
+					from: v,
+					edge: e
+				}];
+			} else if (weight === dist[v][u] && weight < INF) prev[v][u].push({
+				from: v,
+				edge: e
+			});
+		}
+	}
+	for (let k = 0; k < n; k++) for (let i = 0; i < n; i++) for (let j = 0; j < n; j++) {
+		if (dist[i][k] === INF || dist[k][j] === INF) continue;
+		const newDist = dist[i][k] + dist[k][j];
+		if (newDist < dist[i][j]) {
+			dist[i][j] = newDist;
+			prev[i][j] = prev[k][j].map((p) => ({ ...p }));
+		} else if (newDist === dist[i][j] && newDist < INF) {
+			for (const p of prev[k][j]) if (!prev[i][j].some((x) => x.edge.id === p.edge.id)) prev[i][j].push({ ...p });
+		}
+	}
+	const results = [];
+	for (let i = 0; i < n; i++) {
+		const sourceNi = idx.nodeById.get(nodeIds[i]);
+		if (sourceNi === void 0) continue;
+		const sourceNode = graph.nodes[sourceNi];
+		for (let j = 0; j < n; j++) {
+			if (i === j || dist[i][j] === INF) continue;
+			const paths = fwReconstruct(graph, prev, idxOf, nodeIds, sourceNode, i, j);
+			results.push(...paths);
+		}
+	}
+	return results;
+}
+function fwReconstruct(graph, prev, idxOf, nodeIds, sourceNode, sourceIdx, targetIdx) {
+	if (sourceIdx === targetIdx) return [{
+		source: sourceNode,
+		steps: []
+	}];
+	const preds = prev[sourceIdx][targetIdx];
+	if (preds.length === 0) return [];
+	const targetNi = getIndex(graph).nodeById.get(nodeIds[targetIdx]);
+	if (targetNi === void 0) return [];
+	const targetNode = graph.nodes[targetNi];
+	const results = [];
+	for (const { from, edge } of preds) {
+		const prefixPaths = fwReconstruct(graph, prev, idxOf, nodeIds, sourceNode, sourceIdx, from);
+		for (const prefix of prefixPaths) results.push({
+			source: sourceNode,
+			steps: [...prefix.steps, {
+				edge,
+				node: targetNode
+			}]
+		});
+	}
+	return results;
+}
+
+//#endregion
+export { createGraph as A, updateEntities as B, isAcyclic as C, addEdge as D, GraphInstance as E, getEdge as F, getNode as I, hasEdge as L, deleteEdge as M, deleteEntities as N, addEntities as O, deleteNode as P, hasNode as R, hasPath as S, isTree as T, updateNode as V, getShortestPaths as _, genPreorders as a, getStronglyConnectedComponents as b, getAllPairsShortestPaths as c, getMinimumSpanningTree as d, getPostorder as f, getShortestPath as g, getPreorders as h, genPostorders as i, createVisualGraph as j, addNode as k, getConnectedComponents as l, getPreorder as m, dfs as n, genShortestPaths as o, getPostorders as p, genCycles as r, genSimplePaths as s, bfs as t, getCycles as u, getSimplePath as v, isConnected as w, getTopologicalSort as x, getSimplePaths as y, updateEdge as z };