@statelyai/graph 0.5.0 → 0.6.0

package/dist/{algorithms-DldwenLt.mjs → algorithms-oVD9PYil.mjs}

@@ -30,9 +30,10 @@ function resolveEdge(config) {
 		id: config.id,
 		sourceId: config.sourceId,
 		targetId: config.targetId,
-		label: config.label ?? "",
+		label: config.label ?? null,
 		data: config.data
 	};
+	if (config.weight !== void 0) edge.weight = config.weight;
 	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;
@@ -570,6 +571,8 @@ function collectDescendants(graph, id) {
 /**
 * Breadth-first traversal generator yielding nodes level by level.
 *
+* **O(V + E)** time, **O(V)** space.
+*
 * @example
 * ```ts
 * import { createGraph, bfs } from '@statelyai/graph';
@@ -603,6 +606,8 @@ function* bfs(graph, startId) {
 /**
 * Depth-first traversal generator yielding nodes as visited.
 *
+* **O(V + E)** time, **O(V)** space.
+*
 * @example
 * ```ts
 * import { createGraph, dfs } from '@statelyai/graph';
@@ -648,9 +653,56 @@ function getSuccessorIds(graph, nodeId) {
 	const idx = getIndex(graph);
 	return (idx.outEdges.get(nodeId) ?? []).map((eid) => graph.edges[idx.edgeById.get(eid)].targetId);
 }
+var MinPriorityQueue = class {
+	items = [];
+	constructor(compare) {
+		this.compare = compare;
+	}
+	get size() {
+		return this.items.length;
+	}
+	push(item) {
+		this.items.push(item);
+		this.bubbleUp(this.items.length - 1);
+	}
+	pop() {
+		if (this.items.length === 0) return void 0;
+		const first = this.items[0];
+		const last = this.items.pop();
+		if (this.items.length > 0) {
+			this.items[0] = last;
+			this.bubbleDown(0);
+		}
+		return first;
+	}
+	bubbleUp(index) {
+		let current = index;
+		while (current > 0) {
+			const parent = Math.floor((current - 1) / 2);
+			if (this.compare(this.items[current], this.items[parent]) >= 0) break;
+			[this.items[current], this.items[parent]] = [this.items[parent], this.items[current]];
+			current = parent;
+		}
+	}
+	bubbleDown(index) {
+		let current = index;
+		while (true) {
+			const left = current * 2 + 1;
+			const right = left + 1;
+			let smallest = current;
+			if (left < this.items.length && this.compare(this.items[left], this.items[smallest]) < 0) smallest = left;
+			if (right < this.items.length && this.compare(this.items[right], this.items[smallest]) < 0) smallest = right;
+			if (smallest === current) break;
+			[this.items[current], this.items[smallest]] = [this.items[smallest], this.items[current]];
+			current = smallest;
+		}
+	}
+};
 /**
 * Checks whether the graph contains no cycles.
 *
+* **O(V + E)** time.
+*
 * @example
 * ```ts
 * import { createGraph, isAcyclic } from '@statelyai/graph';
@@ -711,6 +763,8 @@ function isAcyclicUndirected(graph) {
 * Returns connected components as arrays of nodes.
 * Treats all edges as undirected for connectivity.
 *
+* **O(V + E)** time.
+*
 * @example
 * ```ts
 * import { createGraph, getConnectedComponents } from '@statelyai/graph';
@@ -763,6 +817,8 @@ function getConnectedComponents(graph) {
 /**
 * Returns a topological ordering of nodes, or `null` if the graph is cyclic.
 *
+* **O(V + E)** time (Kahn's algorithm).
+*
 * @example
 * ```ts
 * import { createGraph, getTopologicalSort } from '@statelyai/graph';
@@ -806,6 +862,8 @@ function getTopologicalSort(graph) {
 /**
 * Checks whether a path exists between two nodes.
 *
+* **O(V + E)** time (BFS) or **O((V + E) log V)** (Dijkstra when weighted).
+*
 * @example
 * ```ts
 * import { createGraph, hasPath } from '@statelyai/graph';
@@ -828,6 +886,8 @@ function hasPath(graph, sourceId, targetId) {
 /**
 * Checks whether the graph is connected (all nodes reachable from any node).
 *
+* **O(V + E)** time.
+*
 * @example
 * ```ts
 * import { createGraph, isConnected } from '@statelyai/graph';
@@ -847,6 +907,8 @@ function isConnected(graph) {
 /**
 * Checks whether the graph is a tree (connected and acyclic).
 *
+* **O(V + E)** time.
+*
 * @example
 * ```ts
 * import { createGraph, isTree } from '@statelyai/graph';
@@ -905,7 +967,7 @@ function getNeighborEdges(graph, nodeId) {
 /**
 * 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.
+* Uses BFS when all edges are unweighted; Dijkstra otherwise.
 */
 /** Compute distance + prev maps via BFS or Dijkstra. */
 function computeShortestDistances(graph, sourceId, getWeight) {
@@ -913,7 +975,7 @@ function computeShortestDistances(graph, sourceId, getWeight) {
 	const prev = /* @__PURE__ */ new Map();
 	dist.set(sourceId, 0);
 	prev.set(sourceId, []);
-	if (!getWeight) {
+	if (!getWeight && !graph.edges.some((e) => e.weight !== void 0)) {
 		const queue = [sourceId];
 		while (queue.length > 0) {
 			const id = queue.shift();
@@ -935,19 +997,19 @@ function computeShortestDistances(graph, sourceId, getWeight) {
 			}
 		}
 	} else {
+		const effectiveWeight = getWeight ?? ((e) => e.weight ?? 1);
 		const visited = /* @__PURE__ */ new Set();
-		const pq = [{
+		const pq = new MinPriorityQueue((a, b) => a.dist - b.dist);
+		pq.push({
 			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;
+		});
+		while (pq.size > 0) {
+			const { id, dist: d } = pq.pop();
+			if (visited.has(id) || d !== dist.get(id)) continue;
 			visited.add(id);
 			for (const { neighborId, edge } of getNeighborEdges(graph, id)) {
-				const newDist = d + getWeight(edge);
+				const newDist = d + effectiveWeight(edge);
 				const existing = dist.get(neighborId);
 				if (existing === void 0 || newDist < existing) {
 					dist.set(neighborId, newDist);
@@ -996,6 +1058,9 @@ function* reconstructPaths(graph, prev, sourceNode, targetId) {
 * Lazily yields all shortest paths from a source node.
 * Use `getShortestPaths` for the full array.
 *
+* **O(V + E)** time (BFS) or **O((V + E) log V)** (Dijkstra when weighted),
+* plus **O(P)** per path yielded where P is the path length.
+*
 * @example
 * ```ts
 * import { createGraph, genShortestPaths } from '@statelyai/graph';
@@ -1027,6 +1092,8 @@ function* genShortestPaths(graph, opts) {
 * Returns all shortest paths from a source node as an array.
 * Delegates to `genShortestPaths` internally.
 *
+* **O(V + E)** time (BFS) or **O((V + E) log V)** (Dijkstra when weighted).
+*
 * @example
 * ```ts
 * import { createGraph, getShortestPaths } from '@statelyai/graph';
@@ -1050,6 +1117,8 @@ function getShortestPaths(graph, opts) {
 /**
 * Returns a single shortest path from source to target, or `undefined` if unreachable.
 *
+* **O(V + E)** time (BFS) or **O((V + E) log V)** (Dijkstra when weighted).
+*
 * @example
 * ```ts
 * import { createGraph, getShortestPath } from '@statelyai/graph';
@@ -1074,6 +1143,8 @@ function getShortestPath(graph, opts) {
 * Returns all simple (acyclic) paths from a source node as an array.
 * Delegates to `genSimplePaths` internally.
 *
+* **O(V!)** worst-case (exponential in dense graphs).
+*
 * @example
 * ```ts
 * import { createGraph, getSimplePaths } from '@statelyai/graph';
@@ -1099,6 +1170,8 @@ function getSimplePaths(graph, opts) {
 * Lazily yields all simple (acyclic) paths from a source node via DFS backtracking.
 * Use `getSimplePaths` for the full array.
 *
+* **O(V!)** worst-case (exponential in dense graphs).
+*
 * @example
 * ```ts
 * import { createGraph, genSimplePaths } from '@statelyai/graph';
@@ -1127,22 +1200,21 @@ function* genSimplePaths(graph, opts) {
 	const targetId = opts?.to;
 	const visited = /* @__PURE__ */ new Set();
 	const currentSteps = [];
-	const found = [];
-	function dfsCollect(nodeId) {
+	function* dfsCollect(nodeId) {
 		visited.add(nodeId);
 		if (targetId !== void 0) {
 			if (nodeId === targetId) {
-				found.push({
+				yield {
 					source: sourceNode,
 					steps: [...currentSteps]
-				});
+				};
 				visited.delete(nodeId);
 				return;
 			}
-		} else if (currentSteps.length > 0) found.push({
+		} else if (currentSteps.length > 0) yield {
 			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);
@@ -1150,17 +1222,18 @@ function* genSimplePaths(graph, opts) {
 				edge,
 				node: neighborNode
 			});
-			dfsCollect(neighborId);
+			yield* dfsCollect(neighborId);
 			currentSteps.pop();
 		}
 		visited.delete(nodeId);
 	}
-	dfsCollect(sourceId);
-	yield* found;
+	yield* dfsCollect(sourceId);
 }
 /**
 * Returns a single simple (acyclic) path from source to target, or `undefined` if unreachable.
 *
+* **O(V + E)** typical, **O(V!)** worst-case.
+*
 * @example
 * ```ts
 * import { createGraph, getSimplePath } from '@statelyai/graph';
@@ -1185,6 +1258,8 @@ function getSimplePath(graph, opts) {
 * Returns strongly connected components using Tarjan's algorithm.
 * Only meaningful for directed graphs.
 *
+* **O(V + E)** time.
+*
 * @example
 * ```ts
 * import { createGraph, getStronglyConnectedComponents } from '@statelyai/graph';
@@ -1244,6 +1319,8 @@ function getStronglyConnectedComponents(graph) {
 * Returns all elementary cycles as an array of paths.
 * Delegates to `genCycles` internally.
 *
+* **O((V + E) · C)** where C is the number of elementary cycles (can be exponential).
+*
 * @example
 * ```ts
 * import { createGraph, getCycles } from '@statelyai/graph';
@@ -1267,6 +1344,8 @@ function getCycles(graph) {
 * Lazily yields elementary cycles one at a time.
 * Use `getCycles` for the full array.
 *
+* **O((V + E) · C)** where C is the number of elementary cycles (can be exponential).
+*
 * @example
 * ```ts
 * import { createGraph, genCycles } from '@statelyai/graph';
@@ -1406,6 +1485,8 @@ function getNeighborEdgesAll(graph, nodeId) {
 * Returns a single canonical preorder (DFS visit-order) sequence.
 * Visits neighbors in the order they appear in the adjacency list.
 *
+* **O(V + E)** time.
+*
 * @example
 * ```ts
 * import { createGraph, getPreorder } from '@statelyai/graph';
@@ -1449,6 +1530,8 @@ function getPreorder(graph, opts) {
 * Returns a single canonical postorder (DFS finish-order) sequence.
 * Visits neighbors in the order they appear in the adjacency list.
 *
+* **O(V + E)** time.
+*
 * @example
 * ```ts
 * import { createGraph, getPostorder } from '@statelyai/graph';
@@ -1490,6 +1573,8 @@ function getPostorder(graph, opts) {
 /**
 * Returns all possible preorder sequences as an array. Can be exponential -- prefer `genPreorders`.
 *
+* **O(V! · V)** worst-case (exponential).
+*
 * @example
 * ```ts
 * import { createGraph, getPreorders } from '@statelyai/graph';
@@ -1513,6 +1598,8 @@ function getPreorders(graph, opts) {
 /**
 * Returns all possible postorder sequences as an array. Can be exponential -- prefer `genPostorders`.
 *
+* **O(V! · V)** worst-case (exponential).
+*
 * @example
 * ```ts
 * import { createGraph, getPostorders } from '@statelyai/graph';
@@ -1538,6 +1625,8 @@ function getPostorders(graph, opts) {
 * Different neighbor exploration orders yield different sequences.
 * Use `getPreorder()` for a single canonical ordering.
 *
+* **O(V! · V)** worst-case (exponential).
+*
 * @example
 * ```ts
 * import { createGraph, genPreorders } from '@statelyai/graph';
@@ -1602,6 +1691,8 @@ function* genPreorders(graph, opts) {
 * Different neighbor exploration orders yield different sequences.
 * Use `getPostorder()` for a single canonical ordering.
 *
+* **O(V! · V)** worst-case (exponential).
+*
 * @example
 * ```ts
 * import { createGraph, genPostorders } from '@statelyai/graph';
@@ -1665,6 +1756,8 @@ function* genPostorders(graph, opts) {
 * Only meaningful for connected undirected graphs (or the component reachable
 * from an arbitrary start node in directed graphs).
 *
+* **O(E log E)** using either edge sorting (Kruskal) or a min-heap (Prim).
+*
 * @example
 * ```ts
 * import { createGraph, getMinimumSpanningTree } from '@statelyai/graph';
@@ -1687,7 +1780,7 @@ function* genPostorders(graph, opts) {
 */
 function getMinimumSpanningTree(graph, opts) {
 	const algorithm = opts?.algorithm ?? "prim";
-	const getWeight = opts?.getWeight ?? (() => 1);
+	const getWeight = opts?.getWeight ?? ((e) => e.weight ?? 1);
 	const mstEdges = algorithm === "kruskal" ? kruskalMST(graph, getWeight) : primMST(graph, getWeight);
 	return createGraph({
 		id: graph.id,
@@ -1705,7 +1798,8 @@ function getMinimumSpanningTree(graph, opts) {
 			sourceId: e.sourceId,
 			targetId: e.targetId,
 			label: e.label,
-			data: e.data
+			data: e.data,
+			...e.weight !== void 0 && { weight: e.weight }
 		}))
 	});
 }
@@ -1714,7 +1808,7 @@ function primMST(graph, getWeight) {
 	const idx = getIndex(graph);
 	const inMST = /* @__PURE__ */ new Set();
 	const mstEdges = [];
-	const candidates = [];
+	const candidates = new MinPriorityQueue((a, b) => a.weight - b.weight);
 	function addEdgesOf(nodeId) {
 		for (const eid of idx.outEdges.get(nodeId) ?? []) {
 			const ai = idx.edgeById.get(eid);
@@ -1738,10 +1832,8 @@ function primMST(graph, getWeight) {
 	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];
+	while (candidates.size > 0 && inMST.size < graph.nodes.length) {
+		const { edge } = candidates.pop();
 		const targetId = graph.type === "undirected" && inMST.has(edge.targetId) ? edge.sourceId : edge.targetId;
 		if (inMST.has(targetId)) continue;
 		inMST.add(targetId);
@@ -1780,7 +1872,9 @@ function kruskalMST(graph, getWeight) {
 /**
 * Returns shortest paths between all pairs of nodes.
 * Algorithm 'dijkstra' (default): runs getShortestPaths per source node.
-* Algorithm 'floyd-warshall': classic O(V^3) dynamic programming.
+* Algorithm 'floyd-warshall': classic dynamic programming.
+*
+* **O(V · (V + E) log V)** (Dijkstra) or **O(V³)** (Floyd-Warshall).
 *
 * @example
 * ```ts
@@ -1815,7 +1909,7 @@ function dijkstraAllPaths(graph, getWeight) {
 }
 function floydWarshallAllPaths(graph, getWeight) {
 	const idx = getIndex(graph);
-	const w = getWeight ?? (() => 1);
+	const w = getWeight ?? ((e) => e.weight ?? 1);
 	const nodeIds = graph.nodes.map((n$1) => n$1.id);
 	const n = nodeIds.length;
 	const idxOf = /* @__PURE__ */ new Map();
@@ -1898,6 +1992,100 @@ function fwReconstruct(graph, prev, idxOf, nodeIds, sourceNode, sourceIdx, targe
 	return results;
 }
 /**
+* Returns a shortest path using A* search with an admissible heuristic.
+* More efficient than Dijkstra when a good heuristic is available.
+*
+* **O((V + E) log V)** time with a good heuristic; degrades to Dijkstra
+* with `heuristic: () => 0`.
+*
+* @example
+* ```ts
+* import { createGraph, getAStarPath } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [
+*     { id: 'a', x: 0, y: 0 },
+*     { id: 'b', x: 1, y: 0 },
+*     { id: 'c', x: 1, y: 1 },
+*   ],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b', weight: 1 },
+*     { id: 'bc', sourceId: 'b', targetId: 'c', weight: 1 },
+*     { id: 'ac', sourceId: 'a', targetId: 'c', weight: 3 },
+*   ],
+* });
+*
+* const path = getAStarPath(graph, {
+*   from: 'a',
+*   to: 'c',
+*   heuristic: (nodeId) => {
+*     const node = graph.nodes.find(n => n.id === nodeId)!;
+*     const target = graph.nodes.find(n => n.id === 'c')!;
+*     return Math.abs(node.x! - target.x!) + Math.abs(node.y! - target.y!);
+*   },
+* });
+* // path: a -> b -> c (weight 2, cheaper than direct a -> c)
+* ```
+*/
+function getAStarPath(graph, opts) {
+	const idx = getIndex(graph);
+	const { from: sourceId, to: targetId, heuristic } = opts;
+	const getWeight = opts.getWeight ?? ((e) => e.weight ?? 1);
+	const sourceNi = idx.nodeById.get(sourceId);
+	if (sourceNi === void 0) return void 0;
+	if (!idx.nodeById.has(targetId)) return void 0;
+	if (sourceId === targetId) return {
+		source: graph.nodes[sourceNi],
+		steps: []
+	};
+	const gScore = /* @__PURE__ */ new Map();
+	const cameFrom = /* @__PURE__ */ new Map();
+	const closedSet = /* @__PURE__ */ new Set();
+	const openSet = new MinPriorityQueue((a, b) => a.f - b.f);
+	gScore.set(sourceId, 0);
+	openSet.push({
+		id: sourceId,
+		f: heuristic(sourceId)
+	});
+	while (openSet.size > 0) {
+		const { id: currentId } = openSet.pop();
+		if (closedSet.has(currentId)) continue;
+		if (currentId === targetId) {
+			const steps = [];
+			let cur = targetId;
+			while (cur !== sourceId) {
+				const prev = cameFrom.get(cur);
+				const ni = idx.nodeById.get(cur);
+				steps.unshift({
+					edge: prev.edge,
+					node: graph.nodes[ni]
+				});
+				cur = prev.from;
+			}
+			return {
+				source: graph.nodes[sourceNi],
+				steps
+			};
+		}
+		closedSet.add(currentId);
+		for (const { neighborId, edge } of getNeighborEdges(graph, currentId)) {
+			if (closedSet.has(neighborId)) continue;
+			const tentativeG = (gScore.get(currentId) ?? Infinity) + getWeight(edge);
+			if (tentativeG < (gScore.get(neighborId) ?? Infinity)) {
+				cameFrom.set(neighborId, {
+					from: currentId,
+					edge
+				});
+				gScore.set(neighborId, tentativeG);
+				openSet.push({
+					id: neighborId,
+					f: tentativeG + heuristic(neighborId)
+				});
+			}
+		}
+	}
+}
+/**
 * Joins two paths end-to-end. The last node of the head path must equal
 * the source of the tail path (the overlap node).
 *
@@ -1933,4 +2121,4 @@ function joinPaths(headPath, tailPath) {
 }
 
 //#endregion
-export { addNode as A, hasNode as B, isAcyclic as C, GraphInstance as D, joinPaths as E, deleteEntities as F, updateEntities as H, deleteNode as I, getEdge as L, createGraphFromTransition as M, createVisualGraph as N, addEdge as O, deleteEdge as P, getNode as R, hasPath as S, isTree as T, updateNode as U, updateEdge 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, createGraph as j, addEntities 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, hasEdge as z };
+export { addEntities as A, hasEdge as B, hasPath as C, joinPaths as D, isTree as E, deleteEdge as F, updateEdge as H, deleteEntities as I, deleteNode as L, createGraph as M, createGraphFromTransition as N, GraphInstance as O, createVisualGraph as P, getEdge as R, getTopologicalSort as S, isConnected as T, updateEntities as U, hasNode as V, updateNode as W, getShortestPath as _, genPreorders as a, getSimplePaths as b, getAStarPath as c, getCycles as d, getMinimumSpanningTree as f, getPreorders as g, getPreorder as h, genPostorders as i, addNode as j, addEdge as k, getAllPairsShortestPaths as l, getPostorders as m, dfs as n, genShortestPaths as o, getPostorder as p, genCycles as r, genSimplePaths as s, bfs as t, getConnectedComponents as u, getShortestPaths as v, isAcyclic as w, getStronglyConnectedComponents as x, getSimplePath as y, getNode as z };