@statelyai/graph 0.1.0 → 0.3.1

package/dist/{algorithms-R35X6ro4.mjs → algorithms-NWSB2RWj.mjs}

@@ -1,4 +1,4 @@
-import { a as indexUpdateEdgeEndpoints, i as indexReparentNode, n as indexAddEdge, o as invalidateIndex, r as indexAddNode, t as getIndex } from "./indexing-BHg1VhqN.mjs";
+import { a as indexUpdateEdgeEndpoints, i as indexReparentNode, n as indexAddEdge, o as invalidateIndex, r as indexAddNode, t as getIndex } from "./indexing-eNDrXdDA.mjs";
 
 //#region src/graph.ts
 function resolveNode(config) {
@@ -36,7 +36,17 @@ function resolveEdge(config) {
 	if (config.style !== void 0) edge.style = config.style;
 	return edge;
 }
-/** Create a graph from a config. Resolves defaults for all fields. */
+/**
+* Create a graph from a config. Resolves defaults for all fields.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+* });
+* ```
+*/
 function createGraph(config) {
 	const graph = {
 		id: config?.id ?? "",
@@ -50,7 +60,18 @@ function createGraph(config) {
 	if (config?.style !== void 0) graph.style = config.style;
 	return graph;
 }
-/** Create a visual graph with required position/size on all nodes and edges. */
+/**
+* Create a visual graph with required position/size on all nodes and edges.
+*
+* @example
+* ```ts
+* const graph = createVisualGraph({
+*   nodes: [{ id: 'a', x: 0, y: 0, width: 100, height: 50 }],
+*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'a', x: 0, y: 0, width: 0, height: 0 }],
+* });
+* // graph.nodes[0].x === 0
+* ```
+*/
 function createVisualGraph(config) {
 	const base = createGraph(config);
 	return {
@@ -62,7 +83,7 @@ function createVisualGraph(config) {
 			y: n.y ?? 0,
 			width: n.width ?? 0,
 			height: n.height ?? 0,
-			shape: n.shape ?? "rectangle"
+			...n.shape !== void 0 && { shape: n.shape }
 		})),
 		edges: base.edges.map((e) => ({
 			...e,
@@ -73,27 +94,161 @@ function createVisualGraph(config) {
 		}))
 	};
 }
-/** Get a node by id, or `undefined` if not found. */
+/**
+* Create a graph by BFS exploration of a transition function.
+* Each unique state becomes a node; each (state, event) -> nextState becomes an edge.
+*
+* - Node IDs are determined by `serializeState` (default: `JSON.stringify`).
+* - Edge IDs use the format `sourceId|serializedEvent|targetId` for uniqueness
+*   and debuggability. Edge labels are just the serialized event string.
+*
+* @example
+* ```ts
+* const graph = createGraphFromTransition(
+*   (state, event) => {
+*     if (state === 'green' && event === 'TIMER') return 'yellow';
+*     if (state === 'yellow' && event === 'TIMER') return 'red';
+*     if (state === 'red' && event === 'TIMER') return 'green';
+*     return state;
+*   },
+*   {
+*     initialState: 'green',
+*     events: ['TIMER'],
+*     serializeState: (s) => s,
+*     serializeEvent: (e) => e,
+*   },
+* );
+* // graph.nodes.length === 3
+* ```
+*/
+function createGraphFromTransition(transition, options) {
+	const serializeState = options.serializeState ?? JSON.stringify;
+	const serializeEvent = options.serializeEvent ?? JSON.stringify;
+	const limit = options.limit ?? Infinity;
+	const getEvents = typeof options.events === "function" ? options.events : () => options.events;
+	const nodes = [];
+	const edges = [];
+	const visited = /* @__PURE__ */ new Set();
+	const edgeSet = /* @__PURE__ */ new Set();
+	const queue = [options.initialState];
+	const initialStateId = serializeState(options.initialState);
+	visited.add(initialStateId);
+	nodes.push({
+		id: initialStateId,
+		label: initialStateId,
+		data: options.initialState
+	});
+	let iterations = 0;
+	while (queue.length > 0) {
+		const state = queue.shift();
+		const stateId = serializeState(state);
+		if (++iterations > limit) throw new Error("Traversal limit exceeded");
+		if (options.stopWhen?.(state)) continue;
+		const events = getEvents(state);
+		for (const event of events) {
+			const nextState = transition(state, event);
+			const nextStateId = serializeState(nextState);
+			const eventStr = serializeEvent(event);
+			if (!visited.has(nextStateId)) {
+				visited.add(nextStateId);
+				nodes.push({
+					id: nextStateId,
+					label: nextStateId,
+					data: nextState
+				});
+				queue.push(nextState);
+			}
+			const edgeKey = `${stateId}|${eventStr}|${nextStateId}`;
+			if (!edgeSet.has(edgeKey)) {
+				edgeSet.add(edgeKey);
+				edges.push({
+					id: edgeKey,
+					sourceId: stateId,
+					targetId: nextStateId,
+					label: eventStr,
+					data: event
+				});
+			}
+		}
+	}
+	return createGraph({
+		id: options.id ?? "",
+		type: "directed",
+		initialNodeId: initialStateId,
+		nodes,
+		edges
+	});
+}
+/**
+* Get a node by id, or `undefined` if not found.
+*
+* @example
+* ```ts
+* const graph = createGraph({ nodes: [{ id: 'a' }] });
+* const node = getNode(graph, 'a'); // GraphNode
+* const missing = getNode(graph, 'z'); // undefined
+* ```
+*/
 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. */
+/**
+* Get an edge by id, or `undefined` if not found.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+* });
+* const edge = getEdge(graph, 'e1'); // GraphEdge
+* const missing = getEdge(graph, 'z'); // undefined
+* ```
+*/
 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. */
+/**
+* Check if a node exists in the graph.
+*
+* @example
+* ```ts
+* const graph = createGraph({ nodes: [{ id: 'a' }] });
+* hasNode(graph, 'a'); // true
+* hasNode(graph, 'z'); // false
+* ```
+*/
 function hasNode(graph, id) {
 	return getIndex(graph).nodeById.has(id);
 }
-/** Check if an edge exists in the graph. */
+/**
+* Check if an edge exists in the graph.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+* });
+* hasEdge(graph, 'e1'); // true
+* hasEdge(graph, 'z'); // false
+* ```
+*/
 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.
+*
+* @example
+* ```ts
+* const graph = createGraph();
+* const node = addNode(graph, { id: 'a', label: 'Node A' });
+* // graph.nodes.length === 1
+* ```
 */
 function addNode(graph, config) {
 	const idx = getIndex(graph);
@@ -106,6 +261,13 @@ function addNode(graph, config) {
 /**
 * **Mutable.** Add an edge to the graph. Mutates `graph.edges` in place.
 * @returns The resolved edge that was added.
+*
+* @example
+* ```ts
+* const graph = createGraph({ nodes: [{ id: 'a' }, { id: 'b' }] });
+* const edge = addEdge(graph, { id: 'e1', sourceId: 'a', targetId: 'b' });
+* // graph.edges.length === 1
+* ```
 */
 function addEdge(graph, config) {
 	const idx = getIndex(graph);
@@ -122,6 +284,16 @@ function addEdge(graph, config) {
 *
 * By default, children are deleted recursively.
 * With `{ reparent: true }`, children are re-parented to the deleted node's parent.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+* });
+* deleteNode(graph, 'a');
+* // graph.nodes.length === 1, edge e1 also removed
+* ```
 */
 function deleteNode(graph, id, opts) {
 	const node = getNode(graph, id);
@@ -139,6 +311,16 @@ function deleteNode(graph, id, opts) {
 }
 /**
 * **Mutable.** Delete an edge. Mutates `graph.edges` in place.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+* });
+* deleteEdge(graph, 'e1');
+* // graph.edges.length === 0
+* ```
 */
 function deleteEdge(graph, id) {
 	if (!hasEdge(graph, id)) throw new Error(`Edge "${id}" does not exist`);
@@ -148,6 +330,13 @@ function deleteEdge(graph, id) {
 /**
 * **Mutable.** Update a node in place.
 * @returns The updated node.
+*
+* @example
+* ```ts
+* const graph = createGraph({ nodes: [{ id: 'a', label: 'old' }] });
+* const updated = updateNode(graph, 'a', { label: 'new' });
+* // updated.label === 'new'
+* ```
 */
 function updateNode(graph, id, update) {
 	const idx = getIndex(graph);
@@ -172,6 +361,16 @@ function updateNode(graph, id, update) {
 /**
 * **Mutable.** Update an edge in place.
 * @returns The updated edge.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b', label: 'old' }],
+* });
+* const updated = updateEdge(graph, 'e1', { label: 'new' });
+* // updated.label === 'new'
+* ```
 */
 function updateEdge(graph, id, update) {
 	const idx = getIndex(graph);
@@ -196,6 +395,16 @@ function updateEdge(graph, id, update) {
 /**
 * **Mutable.** Add multiple nodes and edges to the graph.
 * Nodes are added first, then edges (so edges can reference new nodes).
+*
+* @example
+* ```ts
+* const graph = createGraph();
+* addEntities(graph, {
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+* });
+* // graph.nodes.length === 2, graph.edges.length === 1
+* ```
 */
 function addEntities(graph, entities) {
 	for (const nodeConfig of entities.nodes ?? []) addNode(graph, nodeConfig);
@@ -204,6 +413,16 @@ function addEntities(graph, entities) {
 /**
 * **Mutable.** Delete entities by id(s). Automatically detects whether each id
 * is a node or edge. Node deletions cascade to children and connected edges.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+* });
+* deleteEntities(graph, ['a', 'e1']);
+* // graph.nodes.length === 1, graph.edges.length === 0
+* ```
 */
 function deleteEntities(graph, ids, opts) {
 	const idArray = Array.isArray(ids) ? ids : [ids];
@@ -213,6 +432,18 @@ function deleteEntities(graph, ids, opts) {
 /**
 * **Mutable.** Update multiple nodes and edges in place.
 * Each entry must include an `id` to identify which entity to update.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a', label: 'old' }],
+*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'a', label: 'old' }],
+* });
+* updateEntities(graph, {
+*   nodes: [{ id: 'a', label: 'new' }],
+*   edges: [{ id: 'e1', label: 'new' }],
+* });
+* ```
 */
 function updateEntities(graph, updates) {
 	for (const nodeUpdate of updates.nodes ?? []) {
@@ -227,13 +458,33 @@ function updateEntities(graph, updates) {
 /**
 * OOP wrapper around a plain `Graph` object.
 * Delegates to the standalone mutable functions.
+*
+* @example
+* ```ts
+* const instance = new GraphInstance({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+* });
+* instance.addNode({ id: 'c' });
+* instance.hasNode('c'); // true
+* instance.toJSON(); // plain Graph object
+* ```
 */
 var GraphInstance = class GraphInstance {
 	graph;
 	constructor(config) {
 		this.graph = createGraph(config);
 	}
-	/** Wrap an existing plain graph object. */
+	/**
+	* Wrap an existing plain graph object.
+	*
+	* @example
+	* ```ts
+	* const graph = createGraph({ nodes: [{ id: 'a' }] });
+	* const instance = GraphInstance.from(graph);
+	* instance.hasNode('a'); // true
+	* ```
+	*/
 	static from(graph) {
 		const instance = Object.create(GraphInstance.prototype);
 		instance.graph = graph;
@@ -311,6 +562,23 @@ function collectDescendants(graph, id) {
 
 //#endregion
 //#region src/algorithms.ts
+/**
+* Breadth-first traversal generator yielding nodes level by level.
+*
+* @example
+* ```ts
+* import { createGraph, bfs } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [{ id: 'ab', sourceId: 'a', targetId: 'b' }, { id: 'bc', sourceId: 'b', targetId: 'c' }],
+* });
+*
+* for (const node of bfs(graph, 'a')) {
+*   console.log(node.id); // 'a', 'b', 'c'
+* }
+* ```
+*/
 function* bfs(graph, startId) {
 	const idx = getIndex(graph);
 	const visited = /* @__PURE__ */ new Set();
@@ -327,6 +595,23 @@ function* bfs(graph, startId) {
 		}
 	}
 }
+/**
+* Depth-first traversal generator yielding nodes as visited.
+*
+* @example
+* ```ts
+* import { createGraph, dfs } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [{ id: 'ab', sourceId: 'a', targetId: 'b' }, { id: 'bc', sourceId: 'b', targetId: 'c' }],
+* });
+*
+* for (const node of dfs(graph, 'a')) {
+*   console.log(node.id); // 'a', 'b', 'c'
+* }
+* ```
+*/
 function* dfs(graph, startId) {
 	const idx = getIndex(graph);
 	const visited = /* @__PURE__ */ new Set();
@@ -358,6 +643,21 @@ function getSuccessorIds(graph, nodeId) {
 	const idx = getIndex(graph);
 	return (idx.outEdges.get(nodeId) ?? []).map((eid) => graph.edges[idx.edgeById.get(eid)].targetId);
 }
+/**
+* Checks whether the graph contains no cycles.
+*
+* @example
+* ```ts
+* import { createGraph, isAcyclic } from '@statelyai/graph';
+*
+* const dag = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'ab', sourceId: 'a', targetId: 'b' }],
+* });
+*
+* isAcyclic(dag); // true
+* ```
+*/
 function isAcyclic(graph) {
 	if (graph.type === "undirected") return isAcyclicUndirected(graph);
 	const WHITE = 0, GRAY = 1, BLACK = 2;
@@ -402,6 +702,23 @@ function isAcyclicUndirected(graph) {
 	for (const n of graph.nodes) if (!visited.has(n.id) && hasCycle(n.id, null)) return false;
 	return true;
 }
+/**
+* Returns connected components as arrays of nodes.
+* Treats all edges as undirected for connectivity.
+*
+* @example
+* ```ts
+* import { createGraph, getConnectedComponents } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [{ id: 'ab', sourceId: 'a', targetId: 'b' }],
+* });
+*
+* const components = getConnectedComponents(graph);
+* // [[nodeA, nodeB], [nodeC]]
+* ```
+*/
 function getConnectedComponents(graph) {
 	const idx = getIndex(graph);
 	const visited = /* @__PURE__ */ new Set();
@@ -438,6 +755,25 @@ function getConnectedComponents(graph) {
 	}
 	return components;
 }
+/**
+* Returns a topological ordering of nodes, or `null` if the graph is cyclic.
+*
+* @example
+* ```ts
+* import { createGraph, getTopologicalSort } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'bc', sourceId: 'b', targetId: 'c' },
+*   ],
+* });
+*
+* const sorted = getTopologicalSort(graph);
+* // [nodeA, nodeB, nodeC]
+* ```
+*/
 function getTopologicalSort(graph) {
 	const idx = getIndex(graph);
 	const inDeg = /* @__PURE__ */ new Map();
@@ -462,16 +798,65 @@ function getTopologicalSort(graph) {
 	if (result.length !== graph.nodes.length) return null;
 	return result;
 }
+/**
+* Checks whether a path exists between two nodes.
+*
+* @example
+* ```ts
+* import { createGraph, hasPath } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [{ id: 'ab', sourceId: 'a', targetId: 'b' }],
+* });
+*
+* hasPath(graph, 'a', 'b'); // true
+* hasPath(graph, 'a', 'c'); // false
+* ```
+*/
 function hasPath(graph, sourceId, targetId) {
 	return getShortestPaths(graph, {
 		from: sourceId,
 		to: targetId
 	}).length > 0;
 }
+/**
+* Checks whether the graph is connected (all nodes reachable from any node).
+*
+* @example
+* ```ts
+* import { createGraph, isConnected } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'ab', sourceId: 'a', targetId: 'b' }],
+* });
+*
+* isConnected(graph); // true
+* ```
+*/
 function isConnected(graph) {
 	if (graph.nodes.length === 0) return true;
 	return getConnectedComponents(graph).length <= 1;
 }
+/**
+* Checks whether the graph is a tree (connected and acyclic).
+*
+* @example
+* ```ts
+* import { createGraph, isTree } from '@statelyai/graph';
+*
+* const tree = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'ac', sourceId: 'a', targetId: 'c' },
+*   ],
+* });
+*
+* isTree(tree); // true
+* ```
+*/
 function isTree(graph) {
 	return isConnected(graph) && isAcyclic(graph);
 }
@@ -605,6 +990,24 @@ function* reconstructPaths(graph, prev, sourceNode, targetId) {
 /**
 * Lazily yields all shortest paths from a source node.
 * Use `getShortestPaths` for the full array.
+*
+* @example
+* ```ts
+* import { createGraph, genShortestPaths } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'bc', sourceId: 'b', targetId: 'c' },
+*   ],
+*   initialNodeId: 'a',
+* });
+*
+* for (const path of genShortestPaths(graph)) {
+*   console.log(path.steps.map(s => s.node.id));
+* }
+* ```
 */
 function* genShortestPaths(graph, opts) {
 	const idx = getIndex(graph);
@@ -615,25 +1018,101 @@ function* genShortestPaths(graph, opts) {
 	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);
 }
+/**
+* Returns all shortest paths from a source node as an array.
+* Delegates to `genShortestPaths` internally.
+*
+* @example
+* ```ts
+* import { createGraph, getShortestPaths } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'bc', sourceId: 'b', targetId: 'c' },
+*   ],
+*   initialNodeId: 'a',
+* });
+*
+* const paths = getShortestPaths(graph);
+* // paths to 'b' and 'c' from 'a'
+* ```
+*/
 function getShortestPaths(graph, opts) {
 	return [...genShortestPaths(graph, opts)];
 }
 /**
-* Returns a single shortest path from source to target, or undefined if unreachable.
+* Returns a single shortest path from source to target, or `undefined` if unreachable.
+*
+* @example
+* ```ts
+* import { createGraph, getShortestPath } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'bc', sourceId: 'b', targetId: 'c' },
+*   ],
+*   initialNodeId: 'a',
+* });
+*
+* const path = getShortestPath(graph, { to: 'c' });
+* // path.steps -> [{node: nodeB, edge: ...}, {node: nodeC, edge: ...}]
+* ```
 */
 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.
+* Returns all simple (acyclic) paths from a source node as an array.
+* Delegates to `genSimplePaths` internally.
+*
+* @example
+* ```ts
+* import { createGraph, getSimplePaths } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'bc', sourceId: 'b', targetId: 'c' },
+*     { id: 'ac', sourceId: 'a', targetId: 'c' },
+*   ],
+*   initialNodeId: 'a',
+* });
+*
+* const paths = getSimplePaths(graph, { to: 'c' });
+* // two paths: a->b->c and a->c
+* ```
 */
 function getSimplePaths(graph, opts) {
 	return [...genSimplePaths(graph, opts)];
 }
 /**
-* Lazily yields all simple (acyclic) paths from a source node.
+* Lazily yields all simple (acyclic) paths from a source node via DFS backtracking.
 * Use `getSimplePaths` for the full array.
+*
+* @example
+* ```ts
+* import { createGraph, genSimplePaths } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'bc', sourceId: 'b', targetId: 'c' },
+*     { id: 'ac', sourceId: 'a', targetId: 'c' },
+*   ],
+*   initialNodeId: 'a',
+* });
+*
+* for (const path of genSimplePaths(graph, { to: 'c' })) {
+*   console.log(path.steps.map(s => s.node.id));
+*   // ['b', 'c'] or ['c']
+* }
+* ```
 */
 function* genSimplePaths(graph, opts) {
 	const idx = getIndex(graph);
@@ -675,11 +1154,49 @@ function* genSimplePaths(graph, opts) {
 	yield* found;
 }
 /**
-* Returns a single simple (acyclic) path from source to target, or undefined if unreachable.
+* Returns a single simple (acyclic) path from source to target, or `undefined` if unreachable.
+*
+* @example
+* ```ts
+* import { createGraph, getSimplePath } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'bc', sourceId: 'b', targetId: 'c' },
+*   ],
+*   initialNodeId: 'a',
+* });
+*
+* const path = getSimplePath(graph, { to: 'c' });
+* // path.steps -> [{node: nodeB, edge: ...}, {node: nodeC, edge: ...}]
+* ```
 */
 function getSimplePath(graph, opts) {
 	for (const path of genSimplePaths(graph, opts)) return path;
 }
+/**
+* Returns strongly connected components using Tarjan's algorithm.
+* Only meaningful for directed graphs.
+*
+* @example
+* ```ts
+* import { createGraph, getStronglyConnectedComponents } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'ba', sourceId: 'b', targetId: 'a' },
+*     { id: 'bc', sourceId: 'b', targetId: 'c' },
+*   ],
+* });
+*
+* const sccs = getStronglyConnectedComponents(graph);
+* // [[nodeA, nodeB], [nodeC]]
+* ```
+*/
 function getStronglyConnectedComponents(graph) {
 	const idx = getIndex(graph);
 	let indexCounter = 0;
@@ -718,12 +1235,49 @@ function getStronglyConnectedComponents(graph) {
 	for (const n of graph.nodes) if (!nodeIndex.has(n.id)) strongconnect(n.id);
 	return result;
 }
+/**
+* Returns all elementary cycles as an array of paths.
+* Delegates to `genCycles` internally.
+*
+* @example
+* ```ts
+* import { createGraph, getCycles } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'ba', sourceId: 'b', targetId: 'a' },
+*   ],
+* });
+*
+* const cycles = getCycles(graph);
+* // one cycle: a -> b -> a
+* ```
+*/
 function getCycles(graph) {
 	return [...genCycles(graph)];
 }
 /**
-* Lazily yields cycles one at a time.
+* Lazily yields elementary cycles one at a time.
 * Use `getCycles` for the full array.
+*
+* @example
+* ```ts
+* import { createGraph, genCycles } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'ba', sourceId: 'b', targetId: 'a' },
+*   ],
+* });
+*
+* for (const cycle of genCycles(graph)) {
+*   console.log(cycle.steps.map(s => s.node.id)); // ['b', 'a']
+* }
+* ```
 */
 function* genCycles(graph) {
 	if (graph.type === "undirected") yield* genCyclesUndirected(graph);
@@ -846,6 +1400,23 @@ function getNeighborEdgesAll(graph, nodeId) {
 /**
 * Returns a single canonical preorder (DFS visit-order) sequence.
 * Visits neighbors in the order they appear in the adjacency list.
+*
+* @example
+* ```ts
+* import { createGraph, getPreorder } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'bc', sourceId: 'b', targetId: 'c' },
+*   ],
+*   initialNodeId: 'a',
+* });
+*
+* const order = getPreorder(graph);
+* // [nodeA, nodeB, nodeC]
+* ```
 */
 function getPreorder(graph, opts) {
 	const idx = getIndex(graph);
@@ -872,6 +1443,23 @@ function getPreorder(graph, opts) {
 /**
 * Returns a single canonical postorder (DFS finish-order) sequence.
 * Visits neighbors in the order they appear in the adjacency list.
+*
+* @example
+* ```ts
+* import { createGraph, getPostorder } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'bc', sourceId: 'b', targetId: 'c' },
+*   ],
+*   initialNodeId: 'a',
+* });
+*
+* const order = getPostorder(graph);
+* // [nodeC, nodeB, nodeA]
+* ```
 */
 function getPostorder(graph, opts) {
 	const idx = getIndex(graph);
@@ -894,11 +1482,49 @@ function getPostorder(graph, opts) {
 	}
 	return result;
 }
-/** Returns all possible preorder sequences as an array. Can be exponential — prefer `genPreorders`. */
+/**
+* Returns all possible preorder sequences as an array. Can be exponential -- prefer `genPreorders`.
+*
+* @example
+* ```ts
+* import { createGraph, getPreorders } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'ac', sourceId: 'a', targetId: 'c' },
+*   ],
+*   initialNodeId: 'a',
+* });
+*
+* const allOrders = getPreorders(graph);
+* // [[nodeA, nodeB, nodeC], [nodeA, nodeC, nodeB]]
+* ```
+*/
 function getPreorders(graph, opts) {
 	return [...genPreorders(graph, opts)];
 }
-/** Returns all possible postorder sequences as an array. Can be exponential — prefer `genPostorders`. */
+/**
+* Returns all possible postorder sequences as an array. Can be exponential -- prefer `genPostorders`.
+*
+* @example
+* ```ts
+* import { createGraph, getPostorders } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'ac', sourceId: 'a', targetId: 'c' },
+*   ],
+*   initialNodeId: 'a',
+* });
+*
+* const allOrders = getPostorders(graph);
+* // [[nodeB, nodeC, nodeA], [nodeC, nodeB, nodeA]]
+* ```
+*/
 function getPostorders(graph, opts) {
 	return [...genPostorders(graph, opts)];
 }
@@ -906,6 +1532,25 @@ function getPostorders(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.
+*
+* @example
+* ```ts
+* import { createGraph, genPreorders } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'ac', sourceId: 'a', targetId: 'c' },
+*   ],
+*   initialNodeId: 'a',
+* });
+*
+* for (const order of genPreorders(graph)) {
+*   console.log(order.map(n => n.id));
+*   // ['a', 'b', 'c'] or ['a', 'c', 'b']
+* }
+* ```
 */
 function* genPreorders(graph, opts) {
 	const idx = getIndex(graph);
@@ -951,6 +1596,25 @@ function* genPreorders(graph, opts) {
 * Lazily yields all possible postorder (DFS finish-order) sequences.
 * Different neighbor exploration orders yield different sequences.
 * Use `getPostorder()` for a single canonical ordering.
+*
+* @example
+* ```ts
+* import { createGraph, genPostorders } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'ac', sourceId: 'a', targetId: 'c' },
+*   ],
+*   initialNodeId: 'a',
+* });
+*
+* for (const order of genPostorders(graph)) {
+*   console.log(order.map(n => n.id));
+*   // ['b', 'c', 'a'] or ['c', 'b', 'a']
+* }
+* ```
 */
 function* genPostorders(graph, opts) {
 	const idx = getIndex(graph);
@@ -995,6 +1659,26 @@ function* genPostorders(graph, opts) {
 * 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).
+*
+* @example
+* ```ts
+* import { createGraph, getMinimumSpanningTree } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   type: 'undirected',
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b', data: { weight: 1 } },
+*     { id: 'bc', sourceId: 'b', targetId: 'c', data: { weight: 2 } },
+*     { id: 'ac', sourceId: 'a', targetId: 'c', data: { weight: 3 } },
+*   ],
+* });
+*
+* const mst = getMinimumSpanningTree(graph, {
+*   getWeight: (e) => e.data.weight,
+* });
+* // mst has edges 'ab' and 'bc' (total weight 3)
+* ```
 */
 function getMinimumSpanningTree(graph, opts) {
 	const algorithm = opts?.algorithm ?? "prim";
@@ -1091,7 +1775,23 @@ 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³) dynamic programming.
+* Algorithm 'floyd-warshall': classic O(V^3) dynamic programming.
+*
+* @example
+* ```ts
+* import { createGraph, getAllPairsShortestPaths } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'bc', sourceId: 'b', targetId: 'c' },
+*   ],
+* });
+*
+* const allPaths = getAllPairsShortestPaths(graph);
+* // paths for every reachable (source, target) pair
+* ```
 */
 function getAllPairsShortestPaths(graph, opts) {
 	if ((opts?.algorithm ?? "dijkstra") === "floyd-warshall") return floydWarshallAllPaths(graph, opts?.getWeight);
@@ -1192,6 +1892,40 @@ function fwReconstruct(graph, prev, idxOf, nodeIds, sourceNode, sourceIdx, targe
 	}
 	return results;
 }
+/**
+* Joins two paths end-to-end. The last node of the head path must equal
+* the source of the tail path (the overlap node).
+*
+* Steps are concatenated: head.steps ++ tail.steps (tail already starts
+* from the overlap node, so no slicing is needed).
+*
+* @example
+* ```ts
+* import { createGraph, getShortestPath, joinPaths } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'bc', sourceId: 'b', targetId: 'c' },
+*   ],
+*   initialNodeId: 'a',
+* });
+*
+* const ab = getShortestPath(graph, { to: 'b' })!;
+* const bc = getShortestPath(graph, { from: 'b', to: 'c' })!;
+* const ac = joinPaths(ab, bc);
+* // ac: a -> b -> c
+* ```
+*/
+function joinPaths(headPath, tailPath) {
+	const headEnd = headPath.steps.length > 0 ? headPath.steps[headPath.steps.length - 1].node : headPath.source;
+	if (headEnd.id !== tailPath.source.id) throw new Error(`Paths cannot be joined: head path ends at "${headEnd.id}" but tail path starts at "${tailPath.source.id}"`);
+	return {
+		source: headPath.source,
+		steps: [...headPath.steps, ...tailPath.steps]
+	};
+}
 
 //#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 };
+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 };