@statelyai/graph 0.8.0 → 0.10.0

package/dist/{algorithms-Pbj9dJB1.mjs → algorithms-C-S7u40k.mjs}

@@ -49,7 +49,7 @@ function createGraphNode(config) {
 		id: config.id,
 		...config.parentId !== void 0 && { parentId: config.parentId ?? null },
 		...config.initialNodeId !== void 0 && { initialNodeId: config.initialNodeId ?? null },
-		label: config.label ?? "",
+		label: config.label ?? null,
 		data: config.data
 	};
 	if (config.ports !== void 0 && config.ports.length > 0) {
@@ -649,6 +649,729 @@ function collectDescendants(graph, id) {
 	return toDelete;
 }
 
+//#endregion
+//#region src/algorithms/centrality.ts
+function getNodeIds(graph) {
+	return graph.nodes.map((node) => node.id);
+}
+function getNeighborIds$1(graph, nodeId) {
+	const idx = getIndex(graph);
+	const neighbors = [];
+	for (const edgeId of idx.outEdges.get(nodeId) ?? []) {
+		const edgeIndex = idx.edgeById.get(edgeId);
+		if (edgeIndex !== void 0) neighbors.push(graph.edges[edgeIndex].targetId);
+	}
+	if (graph.type === "undirected") for (const edgeId of idx.inEdges.get(nodeId) ?? []) {
+		const edgeIndex = idx.edgeById.get(edgeId);
+		if (edgeIndex !== void 0) neighbors.push(graph.edges[edgeIndex].sourceId);
+	}
+	return neighbors;
+}
+function getIncomingIds(graph, nodeId) {
+	const idx = getIndex(graph);
+	const incoming = [];
+	for (const edgeId of idx.inEdges.get(nodeId) ?? []) {
+		const edgeIndex = idx.edgeById.get(edgeId);
+		if (edgeIndex !== void 0) incoming.push(graph.edges[edgeIndex].sourceId);
+	}
+	if (graph.type === "undirected") for (const edgeId of idx.outEdges.get(nodeId) ?? []) {
+		const edgeIndex = idx.edgeById.get(edgeId);
+		if (edgeIndex !== void 0) incoming.push(graph.edges[edgeIndex].targetId);
+	}
+	return incoming;
+}
+function createEmptyScoreMap(graph) {
+	return Object.fromEntries(graph.nodes.map((node) => [node.id, 0]));
+}
+function normalizeVector(scores) {
+	const magnitude = Math.sqrt(Object.values(scores).reduce((sum, value) => sum + value * value, 0));
+	if (magnitude === 0) return scores;
+	for (const key of Object.keys(scores)) scores[key] /= magnitude;
+	return scores;
+}
+function maxDiff(previous, next) {
+	let diff = 0;
+	for (const key of Object.keys(next)) diff = Math.max(diff, Math.abs((previous[key] ?? 0) - next[key]));
+	return diff;
+}
+function getReachableDistances(graph, startId) {
+	const distances = /* @__PURE__ */ new Map();
+	const queue = [startId];
+	distances.set(startId, 0);
+	while (queue.length > 0) {
+		const currentId = queue.shift();
+		const currentDistance = distances.get(currentId);
+		for (const neighborId of getNeighborIds$1(graph, currentId)) {
+			if (distances.has(neighborId)) continue;
+			distances.set(neighborId, currentDistance + 1);
+			queue.push(neighborId);
+		}
+	}
+	return distances;
+}
+/**
+* Returns degree centrality scores for all nodes.
+*
+* Degree centrality is the node degree normalized by `n - 1`.
+*
+* @example
+* ```ts
+* const scores = getDegreeCentrality(graph);
+* console.log(scores.a); // 0.5
+* ```
+*/
+function getDegreeCentrality(graph) {
+	const scale = graph.nodes.length > 1 ? 1 / (graph.nodes.length - 1) : 0;
+	const idx = getIndex(graph);
+	const scores = createEmptyScoreMap(graph);
+	for (const node of graph.nodes) {
+		const outDegree = idx.outEdges.get(node.id)?.length ?? 0;
+		const inDegree = idx.inEdges.get(node.id)?.length ?? 0;
+		const degree = graph.type === "undirected" ? new Set([...idx.outEdges.get(node.id) ?? [], ...idx.inEdges.get(node.id) ?? []]).size : outDegree + inDegree;
+		scores[node.id] = degree * scale;
+	}
+	return scores;
+}
+/**
+* Returns in-degree centrality scores for all nodes.
+*
+* In-degree centrality is the incoming degree normalized by `n - 1`.
+*/
+function getInDegreeCentrality(graph) {
+	const scale = graph.nodes.length > 1 ? 1 / (graph.nodes.length - 1) : 0;
+	const idx = getIndex(graph);
+	const scores = createEmptyScoreMap(graph);
+	for (const node of graph.nodes) scores[node.id] = (idx.inEdges.get(node.id)?.length ?? 0) * scale;
+	return scores;
+}
+/**
+* Returns out-degree centrality scores for all nodes.
+*
+* Out-degree centrality is the outgoing degree normalized by `n - 1`.
+*/
+function getOutDegreeCentrality(graph) {
+	const scale = graph.nodes.length > 1 ? 1 / (graph.nodes.length - 1) : 0;
+	const idx = getIndex(graph);
+	const scores = createEmptyScoreMap(graph);
+	for (const node of graph.nodes) scores[node.id] = (idx.outEdges.get(node.id)?.length ?? 0) * scale;
+	return scores;
+}
+/**
+* Returns closeness centrality scores for all nodes.
+*
+* Distances are computed over unweighted shortest paths using the graph's
+* existing directed or undirected edge semantics.
+*/
+function getClosenessCentrality(graph) {
+	const scores = createEmptyScoreMap(graph);
+	const order = graph.nodes.length;
+	for (const node of graph.nodes) {
+		const distances = getReachableDistances(graph, node.id);
+		distances.delete(node.id);
+		if (distances.size === 0) continue;
+		const totalDistance = [...distances.values()].reduce((sum, distance) => sum + distance, 0);
+		if (totalDistance === 0) continue;
+		const reachable = distances.size;
+		const closeness = reachable / totalDistance;
+		scores[node.id] = order > 1 ? closeness * (reachable / (order - 1)) : closeness;
+	}
+	return scores;
+}
+/**
+* Returns betweenness centrality scores for all nodes.
+*
+* Uses Brandes' algorithm over unweighted shortest paths and returns
+* normalized scores.
+*/
+function getBetweennessCentrality(graph) {
+	const scores = createEmptyScoreMap(graph);
+	for (const source of graph.nodes) {
+		const stack = [];
+		const predecessors = /* @__PURE__ */ new Map();
+		const sigma = /* @__PURE__ */ new Map();
+		const distance = /* @__PURE__ */ new Map();
+		const queue = [source.id];
+		for (const node of graph.nodes) {
+			predecessors.set(node.id, []);
+			sigma.set(node.id, 0);
+			distance.set(node.id, -1);
+		}
+		sigma.set(source.id, 1);
+		distance.set(source.id, 0);
+		while (queue.length > 0) {
+			const currentId = queue.shift();
+			stack.push(currentId);
+			for (const neighborId of getNeighborIds$1(graph, currentId)) {
+				if (distance.get(neighborId) === -1) {
+					queue.push(neighborId);
+					distance.set(neighborId, distance.get(currentId) + 1);
+				}
+				if (distance.get(neighborId) === distance.get(currentId) + 1) {
+					sigma.set(neighborId, sigma.get(neighborId) + sigma.get(currentId));
+					predecessors.get(neighborId).push(currentId);
+				}
+			}
+		}
+		const delta = /* @__PURE__ */ new Map();
+		for (const node of graph.nodes) delta.set(node.id, 0);
+		while (stack.length > 0) {
+			const nodeId = stack.pop();
+			const sigmaNode = sigma.get(nodeId);
+			if (sigmaNode === 0) continue;
+			for (const predecessorId of predecessors.get(nodeId)) {
+				const contribution = sigma.get(predecessorId) / sigmaNode * (1 + delta.get(nodeId));
+				delta.set(predecessorId, delta.get(predecessorId) + contribution);
+			}
+			if (nodeId !== source.id) scores[nodeId] += delta.get(nodeId);
+		}
+	}
+	const order = graph.nodes.length;
+	if (order <= 2) return scores;
+	const scale = graph.type === "undirected" ? 1 / ((order - 1) * (order - 2) / 2) : 1 / ((order - 1) * (order - 2));
+	for (const nodeId of Object.keys(scores)) {
+		if (graph.type === "undirected") scores[nodeId] /= 2;
+		scores[nodeId] *= scale;
+	}
+	return scores;
+}
+/**
+* Returns PageRank scores for all nodes.
+*
+* Uses power iteration with damping factor `alpha`.
+*/
+function getPageRank(graph, options) {
+	const nodeIds = getNodeIds(graph);
+	if (nodeIds.length === 0) return {};
+	const alpha = options?.alpha ?? .85;
+	const maxIterations = options?.maxIterations ?? 100;
+	const tolerance = options?.tolerance ?? 1e-6;
+	let scores = Object.fromEntries(nodeIds.map((nodeId) => [nodeId, 1 / nodeIds.length]));
+	for (let iteration = 0; iteration < maxIterations; iteration++) {
+		const nextScores = Object.fromEntries(nodeIds.map((nodeId) => [nodeId, (1 - alpha) / nodeIds.length]));
+		let danglingMass = 0;
+		for (const nodeId of nodeIds) {
+			const neighbors = getNeighborIds$1(graph, nodeId);
+			if (neighbors.length === 0) {
+				danglingMass += scores[nodeId];
+				continue;
+			}
+			const share = scores[nodeId] / neighbors.length;
+			for (const neighborId of neighbors) nextScores[neighborId] += alpha * share;
+		}
+		if (danglingMass > 0) {
+			const share = alpha * danglingMass / nodeIds.length;
+			for (const nodeId of nodeIds) nextScores[nodeId] += share;
+		}
+		if (maxDiff(scores, nextScores) <= tolerance) {
+			scores = nextScores;
+			break;
+		}
+		scores = nextScores;
+	}
+	const total = Object.values(scores).reduce((sum, value) => sum + value, 0);
+	if (total !== 0) for (const nodeId of nodeIds) scores[nodeId] /= total;
+	return scores;
+}
+/**
+* Returns HITS hub and authority scores for all nodes.
+*
+* Uses power iteration and L2 normalization per iteration.
+*/
+function getHITS(graph, options) {
+	const nodeIds = getNodeIds(graph);
+	if (nodeIds.length === 0) return {
+		hubs: {},
+		authorities: {}
+	};
+	const maxIterations = options?.maxIterations ?? 100;
+	const tolerance = options?.tolerance ?? 1e-6;
+	let hubs = Object.fromEntries(nodeIds.map((nodeId) => [nodeId, 1]));
+	let authorities = createEmptyScoreMap(graph);
+	for (let iteration = 0; iteration < maxIterations; iteration++) {
+		const nextAuthorities = createEmptyScoreMap(graph);
+		for (const nodeId of nodeIds) for (const predecessorId of getIncomingIds(graph, nodeId)) nextAuthorities[nodeId] += hubs[predecessorId];
+		normalizeVector(nextAuthorities);
+		const nextHubs = createEmptyScoreMap(graph);
+		for (const nodeId of nodeIds) for (const neighborId of getNeighborIds$1(graph, nodeId)) nextHubs[nodeId] += nextAuthorities[neighborId];
+		normalizeVector(nextHubs);
+		const hubDiff = maxDiff(hubs, nextHubs);
+		const authorityDiff = maxDiff(authorities, nextAuthorities);
+		hubs = nextHubs;
+		authorities = nextAuthorities;
+		if (Math.max(hubDiff, authorityDiff) <= tolerance) break;
+	}
+	return {
+		hubs,
+		authorities
+	};
+}
+/**
+* Returns eigenvector centrality scores for all nodes.
+*
+* Uses power iteration over incoming neighbors for directed graphs and
+* undirected adjacency for undirected graphs.
+*/
+function getEigenvectorCentrality(graph, options) {
+	const nodeIds = getNodeIds(graph);
+	if (nodeIds.length === 0) return {};
+	const maxIterations = options?.maxIterations ?? 100;
+	const tolerance = options?.tolerance ?? 1e-6;
+	let scores = Object.fromEntries(nodeIds.map((nodeId) => [nodeId, 1]));
+	normalizeVector(scores);
+	for (let iteration = 0; iteration < maxIterations; iteration++) {
+		const nextScores = createEmptyScoreMap(graph);
+		for (const nodeId of nodeIds) for (const predecessorId of getIncomingIds(graph, nodeId)) nextScores[nodeId] += scores[predecessorId];
+		normalizeVector(nextScores);
+		const diff = maxDiff(scores, nextScores);
+		scores = nextScores;
+		if (diff <= tolerance) break;
+	}
+	return scores;
+}
+
+//#endregion
+//#region src/algorithms/community.ts
+function getUndirectedNeighbors$1(graph, nodeId) {
+	const idx = getIndex(graph);
+	const neighbors = [];
+	for (const edgeId of idx.outEdges.get(nodeId) ?? []) {
+		const edgeIndex = idx.edgeById.get(edgeId);
+		if (edgeIndex !== void 0) neighbors.push({
+			nodeId: graph.edges[edgeIndex].targetId,
+			edgeId
+		});
+	}
+	for (const edgeId of idx.inEdges.get(nodeId) ?? []) {
+		const edgeIndex = idx.edgeById.get(edgeId);
+		if (edgeIndex !== void 0) neighbors.push({
+			nodeId: graph.edges[edgeIndex].sourceId,
+			edgeId
+		});
+	}
+	return neighbors;
+}
+function getUndirectedConnectedComponents(graph) {
+	const idx = getIndex(graph);
+	const visited = /* @__PURE__ */ new Set();
+	const communities = [];
+	for (const node of graph.nodes) {
+		if (visited.has(node.id)) continue;
+		const community = [];
+		const queue = [node.id];
+		visited.add(node.id);
+		while (queue.length > 0) {
+			const currentId = queue.shift();
+			const nodeIndex = idx.nodeById.get(currentId);
+			if (nodeIndex !== void 0) community.push(graph.nodes[nodeIndex]);
+			for (const neighbor of getUndirectedNeighbors$1(graph, currentId)) {
+				if (visited.has(neighbor.nodeId)) continue;
+				visited.add(neighbor.nodeId);
+				queue.push(neighbor.nodeId);
+			}
+		}
+		communities.push(community.sort((a, b) => a.id.localeCompare(b.id)));
+	}
+	return communities.sort((a, b) => a[0].id.localeCompare(b[0].id));
+}
+function getNodeMap(graph) {
+	return new Map(graph.nodes.map((node) => [node.id, node]));
+}
+function normalizeCommunities(graph, labels) {
+	const nodeMap = getNodeMap(graph);
+	const grouped = /* @__PURE__ */ new Map();
+	for (const [nodeId, label] of Object.entries(labels)) {
+		if (!grouped.has(label)) grouped.set(label, []);
+		const node = nodeMap.get(nodeId);
+		if (node) grouped.get(label).push(node);
+	}
+	return [...grouped.values()].map((community) => community.sort((a, b) => a.id.localeCompare(b.id))).sort((a, b) => a[0].id.localeCompare(b[0].id));
+}
+function getEdgeBetweenness(graph) {
+	const scores = Object.fromEntries(graph.edges.map((edge) => [edge.id, 0]));
+	for (const source of graph.nodes) {
+		const stack = [];
+		const predecessors = /* @__PURE__ */ new Map();
+		const sigma = /* @__PURE__ */ new Map();
+		const distance = /* @__PURE__ */ new Map();
+		const queue = [source.id];
+		for (const node of graph.nodes) {
+			predecessors.set(node.id, []);
+			sigma.set(node.id, 0);
+			distance.set(node.id, -1);
+		}
+		sigma.set(source.id, 1);
+		distance.set(source.id, 0);
+		while (queue.length > 0) {
+			const currentId = queue.shift();
+			stack.push(currentId);
+			for (const neighbor of getUndirectedNeighbors$1(graph, currentId)) {
+				if (distance.get(neighbor.nodeId) === -1) {
+					queue.push(neighbor.nodeId);
+					distance.set(neighbor.nodeId, distance.get(currentId) + 1);
+				}
+				if (distance.get(neighbor.nodeId) === distance.get(currentId) + 1) {
+					sigma.set(neighbor.nodeId, sigma.get(neighbor.nodeId) + sigma.get(currentId));
+					predecessors.get(neighbor.nodeId).push({
+						nodeId: currentId,
+						edgeId: neighbor.edgeId
+					});
+				}
+			}
+		}
+		const delta = /* @__PURE__ */ new Map();
+		for (const node of graph.nodes) delta.set(node.id, 0);
+		while (stack.length > 0) {
+			const nodeId = stack.pop();
+			const sigmaNode = sigma.get(nodeId);
+			if (sigmaNode === 0) continue;
+			for (const predecessor of predecessors.get(nodeId)) {
+				const contribution = sigma.get(predecessor.nodeId) / sigmaNode * (1 + delta.get(nodeId));
+				scores[predecessor.edgeId] += contribution;
+				delta.set(predecessor.nodeId, delta.get(predecessor.nodeId) + contribution);
+			}
+		}
+	}
+	for (const edgeId of Object.keys(scores)) scores[edgeId] /= 2;
+	return scores;
+}
+function cloneWithEdges(graph, edges) {
+	return {
+		...graph,
+		nodes: [...graph.nodes],
+		edges
+	};
+}
+function toCommunityIds(communities) {
+	return communities.map((community) => new Set(community.map((node) => node.id)));
+}
+/**
+* Returns label-propagation communities for the graph.
+*
+* The implementation is deterministic: ties are broken by lexicographic label
+* order so test results remain stable.
+*/
+function getLabelPropagationCommunities(graph, options) {
+	if (graph.nodes.length === 0) return [];
+	const maxIterations = options?.maxIterations ?? 50;
+	let labels = Object.fromEntries(graph.nodes.map((node) => [node.id, node.id]));
+	const nodeIds = graph.nodes.map((node) => node.id).sort();
+	for (let iteration = 0; iteration < maxIterations; iteration++) {
+		const nextLabels = { ...labels };
+		let changed = false;
+		for (const nodeId of nodeIds) {
+			const counts = /* @__PURE__ */ new Map();
+			for (const neighbor of getUndirectedNeighbors$1(graph, nodeId)) {
+				const label = labels[neighbor.nodeId];
+				counts.set(label, (counts.get(label) ?? 0) + 1);
+			}
+			if (counts.size === 0) continue;
+			const bestLabel = [...counts.entries()].sort((a, b) => {
+				if (b[1] !== a[1]) return b[1] - a[1];
+				return a[0].localeCompare(b[0]);
+			})[0][0];
+			if (bestLabel !== labels[nodeId]) {
+				nextLabels[nodeId] = bestLabel;
+				changed = true;
+			}
+		}
+		labels = nextLabels;
+		if (!changed) break;
+	}
+	return normalizeCommunities(graph, labels);
+}
+/**
+* Lazily yields Girvan-Newman community splits as edge betweenness removes
+* bridge-like edges from the graph.
+*/
+function* genGirvanNewmanCommunities(graph, options) {
+	if (graph.nodes.length === 0 || graph.edges.length === 0) return;
+	const maxLevels = options?.maxLevels ?? Number.POSITIVE_INFINITY;
+	let yielded = 0;
+	let edges = [...graph.edges];
+	let previousCount = getUndirectedConnectedComponents(graph).length;
+	while (edges.length > 0 && yielded < maxLevels) {
+		const betweenness = getEdgeBetweenness(cloneWithEdges(graph, edges));
+		const maxScore = Math.max(...Object.values(betweenness));
+		edges = edges.filter((edge) => betweenness[edge.id] < maxScore - 1e-12);
+		const components = getUndirectedConnectedComponents(cloneWithEdges(graph, edges));
+		if (components.length > previousCount) {
+			yield components;
+			yielded++;
+			previousCount = components.length;
+		}
+	}
+}
+/**
+* Returns the requested Girvan-Newman split level eagerly.
+*
+* `level: 1` returns the first split yielded by `genGirvanNewmanCommunities`.
+*/
+function getGirvanNewmanCommunities(graph, options) {
+	if (graph.nodes.length === 0) return [];
+	const targetLevel = options?.level ?? 1;
+	if (targetLevel <= 0) return getUndirectedConnectedComponents(graph);
+	let last = getUndirectedConnectedComponents(graph);
+	let level = 0;
+	for (const partition of genGirvanNewmanCommunities(graph, { maxLevels: targetLevel })) {
+		last = partition;
+		level++;
+		if (level >= targetLevel) break;
+	}
+	return last;
+}
+/**
+* Returns the modularity score for a partition of communities.
+*
+* Community algorithms in this module treat the graph as undirected.
+*/
+function getModularity(graph, communities) {
+	if (graph.edges.length === 0 || communities.length === 0) return 0;
+	const nodeIds = graph.nodes.map((node) => node.id);
+	const adjacency = /* @__PURE__ */ new Map();
+	const degree = Object.fromEntries(nodeIds.map((nodeId) => [nodeId, 0]));
+	for (const nodeId of nodeIds) adjacency.set(nodeId, /* @__PURE__ */ new Map());
+	for (const edge of graph.edges) {
+		adjacency.get(edge.sourceId).set(edge.targetId, (adjacency.get(edge.sourceId).get(edge.targetId) ?? 0) + 1);
+		adjacency.get(edge.targetId).set(edge.sourceId, (adjacency.get(edge.targetId).get(edge.sourceId) ?? 0) + 1);
+		degree[edge.sourceId]++;
+		degree[edge.targetId]++;
+	}
+	const m2 = graph.edges.length * 2;
+	let modularity = 0;
+	for (const community of toCommunityIds(communities)) {
+		const ids = [...community];
+		for (const i of ids) for (const j of ids) {
+			const aij = adjacency.get(i).get(j) ?? 0;
+			modularity += aij - degree[i] * degree[j] / m2;
+		}
+	}
+	return modularity / m2;
+}
+/**
+* Returns communities found by greedily merging partitions that improve
+* modularity the most at each step.
+*/
+function getGreedyModularityCommunities(graph) {
+	if (graph.nodes.length === 0) return [];
+	let communities = graph.nodes.map((node) => [node]);
+	let currentScore = getModularity(graph, communities);
+	while (communities.length > 1) {
+		let bestScore = currentScore;
+		let bestMerge;
+		for (let i = 0; i < communities.length; i++) for (let j = i + 1; j < communities.length; j++) {
+			const merged = communities.filter((_, index) => index !== i && index !== j);
+			merged.push([...communities[i], ...communities[j]].sort((a, b) => a.id.localeCompare(b.id)));
+			const score = getModularity(graph, merged);
+			if (score > bestScore + 1e-12) {
+				bestScore = score;
+				bestMerge = merged;
+			}
+		}
+		if (!bestMerge) break;
+		communities = bestMerge.sort((a, b) => a[0].id.localeCompare(b[0].id));
+		currentScore = bestScore;
+	}
+	return communities;
+}
+
+//#endregion
+//#region src/algorithms/connectivity.ts
+function getUndirectedNeighbors(graph, nodeId) {
+	const idx = getIndex(graph);
+	const neighbors = [];
+	for (const edgeId of idx.outEdges.get(nodeId) ?? []) {
+		const edgeIndex = idx.edgeById.get(edgeId);
+		if (edgeIndex !== void 0) neighbors.push({
+			nodeId: graph.edges[edgeIndex].targetId,
+			edgeId
+		});
+	}
+	for (const edgeId of idx.inEdges.get(nodeId) ?? []) {
+		const edgeIndex = idx.edgeById.get(edgeId);
+		if (edgeIndex !== void 0) neighbors.push({
+			nodeId: graph.edges[edgeIndex].sourceId,
+			edgeId
+		});
+	}
+	return neighbors;
+}
+function popComponentUntil(state, stopEdgeId) {
+	const nodeIds = /* @__PURE__ */ new Set();
+	while (state.edgeStack.length > 0) {
+		const edgeId = state.edgeStack.pop();
+		const edge = state.edgeById.get(edgeId);
+		if (edge) {
+			nodeIds.add(edge.sourceId);
+			nodeIds.add(edge.targetId);
+		}
+		if (edgeId === stopEdgeId) break;
+	}
+	if (nodeIds.size > 0) state.components.push(nodeIds);
+}
+function finalizeRemainingComponent(state) {
+	if (state.edgeStack.length === 0) return;
+	const nodeIds = /* @__PURE__ */ new Set();
+	while (state.edgeStack.length > 0) {
+		const edge = state.edgeById.get(state.edgeStack.pop());
+		if (edge) {
+			nodeIds.add(edge.sourceId);
+			nodeIds.add(edge.targetId);
+		}
+	}
+	if (nodeIds.size > 0) state.components.push(nodeIds);
+}
+function traverseConnectivity(graph, nodeId, parentEdgeId, state) {
+	state.time += 1;
+	state.disc.set(nodeId, state.time);
+	state.low.set(nodeId, state.time);
+	let childCount = 0;
+	for (const neighbor of getUndirectedNeighbors(graph, nodeId)) {
+		if (neighbor.edgeId === parentEdgeId) continue;
+		if (!state.disc.has(neighbor.nodeId)) {
+			childCount += 1;
+			state.edgeStack.push(neighbor.edgeId);
+			traverseConnectivity(graph, neighbor.nodeId, neighbor.edgeId, state);
+			state.low.set(nodeId, Math.min(state.low.get(nodeId), state.low.get(neighbor.nodeId)));
+			if (state.low.get(neighbor.nodeId) > state.disc.get(nodeId)) state.bridges.add(neighbor.edgeId);
+			if (parentEdgeId !== null && state.low.get(neighbor.nodeId) >= state.disc.get(nodeId)) {
+				state.articulationPoints.add(nodeId);
+				popComponentUntil(state, neighbor.edgeId);
+			}
+		} else if (state.disc.get(neighbor.nodeId) < state.disc.get(nodeId)) {
+			state.edgeStack.push(neighbor.edgeId);
+			state.low.set(nodeId, Math.min(state.low.get(nodeId), state.disc.get(neighbor.nodeId)));
+		}
+	}
+	if (parentEdgeId === null && childCount > 1) state.articulationPoints.add(nodeId);
+}
+function analyzeConnectivity(graph) {
+	const state = {
+		time: 0,
+		disc: /* @__PURE__ */ new Map(),
+		low: /* @__PURE__ */ new Map(),
+		edgeStack: [],
+		bridges: /* @__PURE__ */ new Set(),
+		articulationPoints: /* @__PURE__ */ new Set(),
+		components: [],
+		nodeById: new Map(graph.nodes.map((node) => [node.id, node])),
+		edgeById: new Map(graph.edges.map((edge) => [edge.id, edge]))
+	};
+	for (const node of graph.nodes) {
+		if (state.disc.has(node.id)) continue;
+		traverseConnectivity(graph, node.id, null, state);
+		finalizeRemainingComponent(state);
+	}
+	return state;
+}
+/**
+* Returns bridge edges whose removal disconnects the graph.
+*
+* Connectivity algorithms in this module treat the graph as undirected.
+*/
+function getBridges(graph) {
+	if (graph.edges.length === 0) return [];
+	const state = analyzeConnectivity(graph);
+	return [...state.bridges].map((edgeId) => state.edgeById.get(edgeId)).sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+* Returns articulation points (cut vertices) for the graph.
+*
+* Connectivity algorithms in this module treat the graph as undirected.
+*/
+function getArticulationPoints(graph) {
+	if (graph.nodes.length === 0) return [];
+	const state = analyzeConnectivity(graph);
+	return [...state.articulationPoints].map((nodeId) => state.nodeById.get(nodeId)).sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+* Returns biconnected components as arrays of nodes.
+*
+* Articulation points may appear in multiple returned components.
+*/
+function getBiconnectedComponents(graph) {
+	if (graph.edges.length === 0) return [];
+	const state = analyzeConnectivity(graph);
+	return state.components.map((component) => [...component].map((nodeId) => state.nodeById.get(nodeId)).sort((a, b) => a.id.localeCompare(b.id))).sort((a, b) => a[0].id.localeCompare(b[0].id));
+}
+
+//#endregion
+//#region src/algorithms/isomorphism.ts
+function getDegreeSignature(graph, nodeId) {
+	const idx = getIndex(graph);
+	const outDegree = idx.outEdges.get(nodeId)?.length ?? 0;
+	const inDegree = idx.inEdges.get(nodeId)?.length ?? 0;
+	if (graph.type === "undirected") return `u:${new Set([...idx.outEdges.get(nodeId) ?? [], ...idx.inEdges.get(nodeId) ?? []]).size}`;
+	return `d:${inDegree}:${outDegree}`;
+}
+function getEdgesBetween(graph, sourceId, targetId) {
+	if (graph.type === "undirected") return graph.edges.filter((edge) => edge.sourceId === sourceId && edge.targetId === targetId || edge.sourceId === targetId && edge.targetId === sourceId);
+	return graph.edges.filter((edge) => edge.sourceId === sourceId && edge.targetId === targetId);
+}
+function edgesAreCompatible(edgesA, edgesB, edgeMatch) {
+	if (edgesA.length !== edgesB.length) return false;
+	if (!edgeMatch || edgesA.length === 0) return true;
+	const remaining = [...edgesB];
+	for (const edgeA of edgesA) {
+		const matchIndex = remaining.findIndex((edgeB) => edgeMatch(edgeA, edgeB));
+		if (matchIndex === -1) return false;
+		remaining.splice(matchIndex, 1);
+	}
+	return true;
+}
+/**
+* Returns whether two graphs are structurally isomorphic.
+*
+* Optional `nodeMatch` and `edgeMatch` predicates can refine the match using
+* node and edge payloads.
+*/
+function isIsomorphic(graphA, graphB, options) {
+	if (graphA.type !== graphB.type) return false;
+	if (graphA.nodes.length !== graphB.nodes.length) return false;
+	if (graphA.edges.length !== graphB.edges.length) return false;
+	const nodeMatch = options?.nodeMatch;
+	const edgeMatch = options?.edgeMatch;
+	const nodesA = [...graphA.nodes].sort((a, b) => {
+		const sigDiff = getDegreeSignature(graphA, b.id).localeCompare(getDegreeSignature(graphA, a.id));
+		if (sigDiff !== 0) return sigDiff;
+		return a.id.localeCompare(b.id);
+	});
+	const nodesB = [...graphB.nodes];
+	const signaturesA = nodesA.map((node) => getDegreeSignature(graphA, node.id)).sort();
+	const signaturesB = nodesB.map((node) => getDegreeSignature(graphB, node.id)).sort();
+	if (signaturesA.join("|") !== signaturesB.join("|")) return false;
+	const mapping = /* @__PURE__ */ new Map();
+	const usedB = /* @__PURE__ */ new Set();
+	const backtrack = (index) => {
+		if (index >= nodesA.length) return true;
+		const nodeA = nodesA[index];
+		const signatureA = getDegreeSignature(graphA, nodeA.id);
+		for (const nodeB of nodesB) {
+			if (usedB.has(nodeB.id)) continue;
+			if (getDegreeSignature(graphB, nodeB.id) !== signatureA) continue;
+			if (nodeMatch && !nodeMatch(nodeA, nodeB)) continue;
+			let compatible = true;
+			for (const [mappedAId, mappedBId] of mapping.entries()) {
+				if (!edgesAreCompatible(getEdgesBetween(graphA, nodeA.id, mappedAId), getEdgesBetween(graphB, nodeB.id, mappedBId), edgeMatch)) {
+					compatible = false;
+					break;
+				}
+				if (!edgesAreCompatible(getEdgesBetween(graphA, mappedAId, nodeA.id), getEdgesBetween(graphB, mappedBId, nodeB.id), edgeMatch)) {
+					compatible = false;
+					break;
+				}
+			}
+			if (!compatible) continue;
+			mapping.set(nodeA.id, nodeB.id);
+			usedB.add(nodeB.id);
+			if (backtrack(index + 1)) return true;
+			mapping.delete(nodeA.id);
+			usedB.delete(nodeB.id);
+		}
+		return false;
+	};
+	return backtrack(0);
+}
+
 //#endregion
 //#region src/algorithms.ts
 /**
@@ -1052,8 +1775,9 @@ function getNeighborEdges(graph, nodeId) {
 * Returns all paths of equal minimum length per target (not just one).
 * Uses BFS when all edges are unweighted; Dijkstra otherwise.
 */
-/** Compute distance + prev maps via BFS or Dijkstra. */
-function computeShortestDistances(graph, sourceId, getWeight) {
+/** Compute distance + prev maps via BFS, Dijkstra, or Bellman-Ford. */
+function computeShortestDistances(graph, sourceId, getWeight, algorithm) {
+	if (algorithm === "bellman-ford") return bellmanFord(graph, sourceId, getWeight);
 	const dist = /* @__PURE__ */ new Map();
 	const prev = /* @__PURE__ */ new Map();
 	dist.set(sourceId, 0);
@@ -1116,6 +1840,73 @@ function computeShortestDistances(graph, sourceId, getWeight) {
 		prev
 	};
 }
+/**
+* Bellman-Ford single-source shortest paths.
+* **O(VE)** time. Handles negative edge weights.
+* Throws if a negative-weight cycle is reachable from the source.
+*/
+function bellmanFord(graph, sourceId, getWeight) {
+	const dist = /* @__PURE__ */ new Map();
+	const prev = /* @__PURE__ */ new Map();
+	const effectiveWeight = getWeight ?? ((e) => e.weight ?? 1);
+	const isUndirected = graph.type === "undirected";
+	for (const node of graph.nodes) {
+		dist.set(node.id, Infinity);
+		prev.set(node.id, []);
+	}
+	dist.set(sourceId, 0);
+	const V = graph.nodes.length;
+	const directedEdges = [];
+	for (const edge of graph.edges) {
+		directedEdges.push({
+			fromId: edge.sourceId,
+			toId: edge.targetId,
+			edge
+		});
+		if (isUndirected) directedEdges.push({
+			fromId: edge.targetId,
+			toId: edge.sourceId,
+			edge
+		});
+	}
+	for (let i = 0; i < V - 1; i++) {
+		let changed = false;
+		for (const { fromId, toId, edge } of directedEdges) {
+			const d = dist.get(fromId);
+			if (d === Infinity) continue;
+			const newDist = d + effectiveWeight(edge);
+			const existing = dist.get(toId);
+			if (newDist < existing) {
+				dist.set(toId, newDist);
+				prev.set(toId, [{
+					from: fromId,
+					edge
+				}]);
+				changed = true;
+			} else if (newDist === existing && existing !== Infinity) {
+				const preds = prev.get(toId);
+				if (!preds.some((p) => p.from === fromId && p.edge === edge)) preds.push({
+					from: fromId,
+					edge
+				});
+			}
+		}
+		if (!changed) break;
+	}
+	for (const { fromId, toId, edge } of directedEdges) {
+		const d = dist.get(fromId);
+		if (d === Infinity) continue;
+		if (d + effectiveWeight(edge) < dist.get(toId)) throw new Error("Graph contains a negative-weight cycle reachable from the source node");
+	}
+	for (const [id, d] of dist) if (d === Infinity) {
+		dist.delete(id);
+		prev.delete(id);
+	}
+	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) {
@@ -1165,7 +1956,7 @@ function* reconstructPaths(graph, prev, sourceNode, targetId) {
 function* genShortestPaths(graph, opts) {
 	const idx = getIndex(graph);
 	const sourceId = resolveFrom(graph, opts);
-	const { dist, prev } = computeShortestDistances(graph, sourceId, opts?.getWeight);
+	const { dist, prev } = computeShortestDistances(graph, sourceId, opts?.getWeight, opts?.algorithm);
 	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);
@@ -1955,9 +2746,10 @@ function kruskalMST(graph, getWeight) {
 /**
 * Returns shortest paths between all pairs of nodes.
 * Algorithm 'dijkstra' (default): runs getShortestPaths per source node.
+* Algorithm 'bellman-ford': handles negative weights, throws on negative cycles.
 * Algorithm 'floyd-warshall': classic dynamic programming.
 *
-* **O(V · (V + E) log V)** (Dijkstra) or **O(V³)** (Floyd-Warshall).
+* **O(V · (V + E) log V)** (Dijkstra), **O(V²E)** (Bellman-Ford), or **O(V³)** (Floyd-Warshall).
 *
 * @example
 * ```ts
@@ -1976,9 +2768,23 @@ function kruskalMST(graph, getWeight) {
 * ```
 */
 function getAllPairsShortestPaths(graph, opts) {
-	if ((opts?.algorithm ?? "dijkstra") === "floyd-warshall") return floydWarshallAllPaths(graph, opts?.getWeight);
+	const algorithm = opts?.algorithm ?? "dijkstra";
+	if (algorithm === "floyd-warshall") return floydWarshallAllPaths(graph, opts?.getWeight);
+	if (algorithm === "bellman-ford") return bellmanFordAllPaths(graph, opts?.getWeight);
 	return dijkstraAllPaths(graph, opts?.getWeight);
 }
+function bellmanFordAllPaths(graph, getWeight) {
+	const results = [];
+	for (const node of graph.nodes) {
+		const paths = getShortestPaths(graph, {
+			from: node.id,
+			getWeight,
+			algorithm: "bellman-ford"
+		});
+		results.push(...paths);
+	}
+	return results;
+}
 function dijkstraAllPaths(graph, getWeight) {
 	const results = [];
 	for (const node of graph.nodes) {
@@ -2204,4 +3010,4 @@ function joinPaths(headPath, tailPath) {
 }
 
 //#endregion
-export { addEntities as A, deleteNode as B, hasPath as C, joinPaths as D, isTree as E, createGraphNode as F, updateEdge as G, getNode as H, createGraphPort as I, updateEntities as K, createVisualGraph as L, createGraph as M, createGraphEdge as N, GraphInstance as O, createGraphFromTransition as P, deleteEdge as R, getTopologicalSort as S, isConnected as T, hasEdge as U, getEdge as V, hasNode 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, updateNode as q, genCycles as r, genSimplePaths as s, bfs as t, getConnectedComponents as u, getShortestPaths as v, isAcyclic as w, getStronglyConnectedComponents as x, getSimplePath as y, deleteEntities as z };
+export { createGraphPort as $, getBiconnectedComponents as A, getEigenvectorCentrality as B, hasPath as C, joinPaths as D, isTree as E, getLabelPropagationCommunities as F, GraphInstance as G, getInDegreeCentrality as H, getModularity as I, addNode as J, addEdge as K, getBetweennessCentrality as L, genGirvanNewmanCommunities as M, getGirvanNewmanCommunities as N, isIsomorphic as O, getGreedyModularityCommunities as P, createGraphNode as Q, getClosenessCentrality as R, getTopologicalSort as S, isConnected as T, getOutDegreeCentrality as U, getHITS as V, getPageRank as W, createGraphEdge as X, createGraph as Y, createGraphFromTransition as Z, getShortestPath as _, genPreorders as a, getNode as at, getSimplePaths as b, getAStarPath as c, updateEdge as ct, getCycles as d, createVisualGraph as et, getMinimumSpanningTree as f, getPreorders as g, getPreorder as h, genPostorders as i, getEdge as it, getBridges as j, getArticulationPoints as k, getAllPairsShortestPaths as l, updateEntities as lt, getPostorders as m, dfs as n, deleteEntities as nt, genShortestPaths as o, hasEdge as ot, getPostorder as p, addEntities as q, genCycles as r, deleteNode as rt, genSimplePaths as s, hasNode as st, bfs as t, deleteEdge as tt, getConnectedComponents as u, updateNode as ut, getShortestPaths as v, isAcyclic as w, getStronglyConnectedComponents as x, getSimplePath as y, getDegreeCentrality as z };