@statelyai/graph 0.3.0 → 0.4.0

package/dist/{algorithms-DBU7nmIV.mjs → algorithms-CnTmuX9t.mjs}

@@ -1,12 +1,14 @@
-import { a as indexUpdateEdgeEndpoints, i as indexReparentNode, n as indexAddEdge, o as invalidateIndex, r as indexAddNode, t as getIndex } from "./indexing-BFFVMnjF.mjs";
+import { a as indexUpdateEdgeEndpoints, i as indexReparentNode, n as indexAddEdge, o as invalidateIndex, r as indexAddNode, t as getIndex } from "./indexing-DitHphT7.mjs";
 
 //#region src/graph.ts
 function resolveNode(config) {
+	if (!config.id) throw new Error("Node id must be a non-empty string");
+	if (config.parentId === "") throw new Error("Node parentId must be a non-empty string");
 	const node = {
 		type: "node",
 		id: config.id,
-		parentId: config.parentId ?? null,
-		initialNodeId: config.initialNodeId ?? null,
+		...config.parentId !== void 0 && { parentId: config.parentId ?? null },
+		...config.initialNodeId !== void 0 && { initialNodeId: config.initialNodeId ?? null },
 		label: config.label ?? "",
 		data: config.data
 	};
@@ -20,6 +22,9 @@ function resolveNode(config) {
 	return node;
 }
 function resolveEdge(config) {
+	if (!config.id) throw new Error("Edge id must be a non-empty string");
+	if (!config.sourceId) throw new Error("Edge sourceId must be a non-empty string");
+	if (!config.targetId) throw new Error("Edge targetId must be a non-empty string");
 	const edge = {
 		type: "edge",
 		id: config.id,
@@ -36,7 +41,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 +65,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 +88,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,
@@ -75,11 +101,30 @@ function createVisualGraph(config) {
 }
 /**
 * Create a graph by BFS exploration of a transition function.
-* Each unique state becomes a node; each (state, event) → nextState becomes an edge.
+* 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;
@@ -139,46 +184,102 @@ function createGraphFromTransition(transition, options) {
 		edges
 	});
 }
-/** Get a node by id, or `undefined` if not found. */
+/**
+* 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 node = resolveNode(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);
+	if (config.parentId && !idx.nodeById.has(config.parentId)) throw new Error(`Parent node "${config.parentId}" does not exist`);
 	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.
+*
+* @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 edge = resolveEdge(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;
 }
@@ -188,6 +289,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);
@@ -205,6 +316,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`);
@@ -214,6 +335,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);
@@ -238,6 +366,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);
@@ -262,6 +400,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);
@@ -270,6 +418,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];
@@ -279,6 +437,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 ?? []) {
@@ -293,13 +463,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;
@@ -377,6 +567,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();
@@ -393,6 +600,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();
@@ -424,6 +648,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;
@@ -468,6 +707,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();
@@ -504,6 +760,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();
@@ -528,16 +803,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);
 }
@@ -671,6 +995,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);
@@ -681,25 +1023,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);
@@ -741,11 +1159,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;
@@ -784,12 +1240,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);
@@ -912,6 +1405,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);
@@ -938,6 +1448,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);
@@ -960,11 +1487,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)];
 }
@@ -972,6 +1537,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);
@@ -1017,6 +1601,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);
@@ -1061,6 +1664,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";
@@ -1157,7 +1780,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);
@@ -1264,6 +1903,25 @@ function fwReconstruct(graph, prev, idxOf, nodeIds, sourceNode, sourceIdx, targe
 *
 * 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;