@statelyai/graph 0.3.0 → 0.4.0

package/dist/algorithms.d.mts

@@ -1,81 +1,531 @@
-import { C as TraversalOptions, _ as MSTOptions, b as PathOptions, c as Graph, h as GraphPath, p as GraphNode, t as AllPairsShortestPathsOptions, x as SinglePathOptions } from "./types-B6Tpeerk.mjs";
+import { C as TraversalOptions, _ as MSTOptions, b as PathOptions, c as Graph, h as GraphPath, p as GraphNode, t as AllPairsShortestPathsOptions, x as SinglePathOptions } from "./types-Bq_fmLwW.mjs";
 
 //#region src/algorithms.d.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'
+ * }
+ * ```
+ */
 declare function bfs<N>(graph: Graph<N>, startId: string): Generator<GraphNode<N>>;
+/**
+ * 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'
+ * }
+ * ```
+ */
 declare function dfs<N>(graph: Graph<N>, startId: string): Generator<GraphNode<N>>;
+/**
+ * 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
+ * ```
+ */
 declare function isAcyclic(graph: Graph): boolean;
+/**
+ * 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]]
+ * ```
+ */
 declare function getConnectedComponents<N>(graph: Graph<N>): GraphNode<N>[][];
+/**
+ * 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]
+ * ```
+ */
 declare function getTopologicalSort<N>(graph: Graph<N>): GraphNode<N>[] | null;
+/**
+ * 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
+ * ```
+ */
 declare function hasPath(graph: Graph, sourceId: string, targetId: string): boolean;
+/**
+ * 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
+ * ```
+ */
 declare function isConnected(graph: Graph): boolean;
+/**
+ * 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
+ * ```
+ */
 declare function isTree(graph: Graph): boolean;
 /**
  * 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));
+ * }
+ * ```
  */
 declare function genShortestPaths<N, E>(graph: Graph<N, E>, opts?: PathOptions<E>): Generator<GraphPath<N, E>>;
+/**
+ * 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'
+ * ```
+ */
 declare function getShortestPaths<N, E>(graph: Graph<N, E>, opts?: PathOptions<E>): GraphPath<N, E>[];
 /**
- * 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: ...}]
+ * ```
  */
 declare function getShortestPath<N, E>(graph: Graph<N, E>, opts: SinglePathOptions<E>): GraphPath<N, E> | undefined;
 /**
- * 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
+ * ```
  */
 declare function getSimplePaths<N, E>(graph: Graph<N, E>, opts?: PathOptions<E>): GraphPath<N, E>[];
 /**
- * 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']
+ * }
+ * ```
  */
 declare function genSimplePaths<N, E>(graph: Graph<N, E>, opts?: PathOptions<E>): Generator<GraphPath<N, E>>;
 /**
- * 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: ...}]
+ * ```
  */
 declare function getSimplePath<N, E>(graph: Graph<N, E>, opts: SinglePathOptions<E>): GraphPath<N, E> | undefined;
+/**
+ * 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]]
+ * ```
+ */
 declare function getStronglyConnectedComponents<N>(graph: Graph<N>): GraphNode<N>[][];
+/**
+ * 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
+ * ```
+ */
 declare function getCycles<N, E>(graph: Graph<N, E>): GraphPath<N, E>[];
 /**
- * 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']
+ * }
+ * ```
  */
 declare function genCycles<N, E>(graph: Graph<N, E>): Generator<GraphPath<N, E>>;
 /**
  * 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]
+ * ```
  */
 declare function getPreorder<N>(graph: Graph<N>, opts?: TraversalOptions): GraphNode<N>[];
 /**
  * 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]
+ * ```
  */
 declare function getPostorder<N>(graph: Graph<N>, opts?: TraversalOptions): GraphNode<N>[];
-/** 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]]
+ * ```
+ */
 declare function getPreorders<N>(graph: Graph<N>, opts?: TraversalOptions): GraphNode<N>[][];
-/** 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]]
+ * ```
+ */
 declare function getPostorders<N>(graph: Graph<N>, opts?: TraversalOptions): GraphNode<N>[][];
 /**
  * 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']
+ * }
+ * ```
  */
 declare function genPreorders<N>(graph: Graph<N>, opts?: TraversalOptions): Generator<GraphNode<N>[]>;
 /**
  * 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']
+ * }
+ * ```
  */
 declare function genPostorders<N>(graph: Graph<N>, opts?: TraversalOptions): Generator<GraphNode<N>[]>;
 /**
  * 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)
+ * ```
  */
 declare function getMinimumSpanningTree<N, E>(graph: Graph<N, E>, opts?: MSTOptions<E>): Graph<N, E>;
 /**
  * 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
+ * ```
  */
 declare function getAllPairsShortestPaths<N, E>(graph: Graph<N, E>, opts?: AllPairsShortestPathsOptions<E>): GraphPath<N, E>[];
 /**
@@ -84,6 +534,25 @@ declare function getAllPairsShortestPaths<N, E>(graph: Graph<N, E>, opts?: AllPa
  *
  * 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
+ * ```
  */
 declare function joinPaths<N, E>(headPath: GraphPath<N, E>, tailPath: GraphPath<N, E>): GraphPath<N, E>;
 //#endregion

package/dist/algorithms.mjs

@@ -1,3 +1,3 @@
-import { C as isAcyclic, E as joinPaths, S as hasPath, T as isTree, _ as getShortestPaths, a as genPreorders, b as getStronglyConnectedComponents, c as getAllPairsShortestPaths, d as getMinimumSpanningTree, f as getPostorder, g as getShortestPath, h as getPreorders, i as genPostorders, l as getConnectedComponents, m as getPreorder, n as dfs, o as genShortestPaths, p as getPostorders, r as genCycles, s as genSimplePaths, t as bfs, u as getCycles, v as getSimplePath, w as isConnected, x as getTopologicalSort, y as getSimplePaths } from "./algorithms-DBU7nmIV.mjs";
+import { C as isAcyclic, E as joinPaths, S as hasPath, T as isTree, _ as getShortestPaths, a as genPreorders, b as getStronglyConnectedComponents, c as getAllPairsShortestPaths, d as getMinimumSpanningTree, f as getPostorder, g as getShortestPath, h as getPreorders, i as genPostorders, l as getConnectedComponents, m as getPreorder, n as dfs, o as genShortestPaths, p as getPostorders, r as genCycles, s as genSimplePaths, t as bfs, u as getCycles, v as getSimplePath, w as isConnected, x as getTopologicalSort, y as getSimplePaths } from "./algorithms-CnTmuX9t.mjs";
 
 export { bfs, dfs, genCycles, genPostorders, genPreorders, genShortestPaths, genSimplePaths, getAllPairsShortestPaths, getConnectedComponents, getCycles, getMinimumSpanningTree, getPostorder, getPostorders, getPreorder, getPreorders, getShortestPath, getShortestPaths, getSimplePath, getSimplePaths, getStronglyConnectedComponents, getTopologicalSort, hasPath, isAcyclic, isConnected, isTree, joinPaths };

package/dist/converter-C5DlzzHs.mjs

@@ -0,0 +1,67 @@
+import { n as toAdjacencyList, t as fromAdjacencyList } from "./adjacency-list-Bv4tfiM3.mjs";
+import { n as toEdgeList, t as fromEdgeList } from "./edge-list-R1SUbHwe.mjs";
+
+//#region src/formats/converter/index.ts
+/**
+* Create a `GraphFormatConverter` from a pair of `to`/`from` functions.
+*
+* @example
+* ```ts
+* import { createFormatConverter } from '@statelyai/graph';
+*
+* const yamlConverter = createFormatConverter(
+*   (graph) => toYAML(graph),
+*   (yaml) => fromYAML(yaml),
+* );
+*
+* const yaml = yamlConverter.to(graph);
+* const graph = yamlConverter.from(yaml);
+* ```
+*/
+function createFormatConverter(to, from) {
+	return {
+		to,
+		from
+	};
+}
+/**
+* Bidirectional converter for adjacency-list format (`Record<string, string[]>`).
+*
+* @example
+* ```ts
+* import { adjacencyListConverter, createGraph } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: { a: {}, b: {} },
+*   edges: [{ source: 'a', target: 'b' }],
+* });
+*
+* const adj = adjacencyListConverter.to(graph);
+* // { a: ['b'], b: [] }
+*
+* const roundTripped = adjacencyListConverter.from(adj);
+* ```
+*/
+const adjacencyListConverter = createFormatConverter(toAdjacencyList, fromAdjacencyList);
+/**
+* Bidirectional converter for edge-list format (`[source, target][]`).
+*
+* @example
+* ```ts
+* import { edgeListConverter, createGraph } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: { a: {}, b: {} },
+*   edges: [{ source: 'a', target: 'b' }],
+* });
+*
+* const edges = edgeListConverter.to(graph);
+* // [['a', 'b']]
+*
+* const roundTripped = edgeListConverter.from(edges);
+* ```
+*/
+const edgeListConverter = createFormatConverter(toEdgeList, fromEdgeList);
+
+//#endregion
+export { createFormatConverter as n, edgeListConverter as r, adjacencyListConverter as t };

package/dist/{edge-list-DuHMz8hf.mjs → edge-list-R1SUbHwe.mjs}

@@ -1,7 +1,39 @@
 //#region src/formats/edge-list/index.ts
+/**
+* Converts a graph to an edge list of `[source, target]` tuples.
+*
+* @example
+* ```ts
+* import { createGraph, toEdgeList } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: { a: {}, b: {}, c: {} },
+*   edges: [{ source: 'a', target: 'b' }, { source: 'b', target: 'c' }],
+* });
+*
+* toEdgeList(graph);
+* // [['a', 'b'], ['b', 'c']]
+* ```
+*/
 function toEdgeList(graph) {
 	return graph.edges.map((e) => [e.sourceId, e.targetId]);
 }
+/**
+* Parses an edge list of `[source, target]` tuples into a graph.
+*
+* @example
+* ```ts
+* import { fromEdgeList } from '@statelyai/graph';
+*
+* const graph = fromEdgeList([
+*   ['a', 'b'],
+*   ['b', 'c'],
+* ]);
+*
+* graph.nodes; // [{id: 'a', ...}, {id: 'b', ...}, {id: 'c', ...}]
+* graph.edges; // [{sourceId: 'a', targetId: 'b', ...}, ...]
+* ```
+*/
 function fromEdgeList(edges, options) {
 	const directed = options?.directed ?? true;
 	const nodeIds = /* @__PURE__ */ new Set();