@statelyai/graph 0.3.0 → 0.4.0

package/dist/index.mjs

@@ -1,13 +1,13 @@
-import { o as invalidateIndex, t as getIndex } from "./indexing-BFFVMnjF.mjs";
-import { A as addNode, B as hasNode, C as isAcyclic, D as GraphInstance, E as joinPaths, F as deleteEntities, H as updateEntities, I as deleteNode, L as getEdge, M as createGraphFromTransition, N as createVisualGraph, O as addEdge, P as deleteEdge, R as getNode, S as hasPath, T as isTree, U as updateNode, V as updateEdge, _ 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, j as createGraph, k as addEntities, 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, z as hasEdge } from "./algorithms-DBU7nmIV.mjs";
+import { o as invalidateIndex, t as getIndex } from "./indexing-DitHphT7.mjs";
+import { A as addNode, B as hasNode, C as isAcyclic, D as GraphInstance, E as joinPaths, F as deleteEntities, H as updateEntities, I as deleteNode, L as getEdge, M as createGraphFromTransition, N as createVisualGraph, O as addEdge, P as deleteEdge, R as getNode, S as hasPath, T as isTree, U as updateNode, V as updateEdge, _ 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, j as createGraph, k as addEntities, 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, z as hasEdge } from "./algorithms-CnTmuX9t.mjs";
 import { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf } from "./queries.mjs";
-import { n as createFormatConverter } from "./converter-DnbeyE_p.mjs";
+import { n as createFormatConverter } from "./converter-C5DlzzHs.mjs";
 
 //#region src/diff.ts
 function nodeToConfig(node) {
 	const config = { id: node.id };
-	if (node.parentId !== null) config.parentId = node.parentId;
-	if (node.initialNodeId !== null) config.initialNodeId = node.initialNodeId;
+	if (node.parentId) config.parentId = node.parentId;
+	if (node.initialNodeId) config.initialNodeId = node.initialNodeId;
 	if (node.label !== "") config.label = node.label;
 	if (node.data !== void 0) config.data = node.data;
 	if (node.x !== void 0) config.x = node.x;
@@ -67,7 +67,21 @@ const EDGE_COMPARE_KEYS = [
 	"color",
 	"style"
 ];
-/** Compute a structured diff from graph `a` to graph `b` by matching IDs. */
+/**
+* Compute a structured diff from graph `a` to graph `b` by matching IDs.
+*
+* @example
+* ```ts
+* import { createGraph, getDiff } from '@statelyai/graph';
+*
+* const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+* const b = createGraph({ nodes: [{ id: 'n1', label: 'hello' }, { id: 'n2' }], edges: [] });
+*
+* const diff = getDiff(a, b);
+* // diff.nodes.added → [{ id: 'n2' }]
+* // diff.nodes.updated → [{ id: 'n1', old: { label: '' }, new: { label: 'hello' } }]
+* ```
+*/
 function getDiff(a, b) {
 	const aNodeMap = new Map(a.nodes.map((n) => [n.id, n]));
 	const bNodeMap = new Map(b.nodes.map((n) => [n.id, n]));
@@ -123,11 +137,37 @@ function getDiff(a, b) {
 	for (const [id, edgeA] of aEdgeMap) if (!bEdgeMap.has(id)) diff.edges.removed.push(edgeToConfig(edgeA));
 	return diff;
 }
-/** Check if a diff has zero changes. */
+/**
+* Check if a diff has zero changes.
+*
+* @example
+* ```ts
+* import { createGraph, getDiff, isEmptyDiff } from '@statelyai/graph';
+*
+* const g = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+* const diff = getDiff(g, g);
+* isEmptyDiff(diff); // true
+* ```
+*/
 function isEmptyDiff(diff) {
 	return diff.nodes.added.length === 0 && diff.nodes.removed.length === 0 && diff.nodes.updated.length === 0 && diff.edges.added.length === 0 && diff.edges.removed.length === 0 && diff.edges.updated.length === 0;
 }
-/** Invert a diff: swap added↔removed, swap old↔new in updates. */
+/**
+* Invert a diff: swap added/removed, swap old/new in updates.
+*
+* @example
+* ```ts
+* import { createGraph, getDiff, invertDiff } from '@statelyai/graph';
+*
+* const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+* const b = createGraph({ nodes: [{ id: 'n2' }], edges: [] });
+*
+* const diff = getDiff(a, b);
+* const inv = invertDiff(diff);
+* // inv.nodes.added contains n1 (was removed)
+* // inv.nodes.removed contains n2 (was added)
+* ```
+*/
 function invertDiff(diff) {
 	return {
 		nodes: {
@@ -153,6 +193,17 @@ function invertDiff(diff) {
 /**
 * Compute an ordered patch list from graph `a` to graph `b`.
 * Order: delete edges → delete nodes → add nodes → add edges → update nodes → update edges.
+*
+* @example
+* ```ts
+* import { createGraph, getPatches } from '@statelyai/graph';
+*
+* const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+* const b = createGraph({ nodes: [{ id: 'n1' }, { id: 'n2' }], edges: [] });
+*
+* const patches = getPatches(a, b);
+* // patches → [{ op: 'addNode', node: { id: 'n2' } }]
+* ```
 */
 function getPatches(a, b) {
 	return toPatches(getDiff(a, b));
@@ -160,6 +211,18 @@ function getPatches(a, b) {
 /**
 * **Mutable.** Apply patches to a graph in order.
 * Delegates to addNode/deleteNode/updateNode/addEdge/deleteEdge/updateEdge.
+*
+* @example
+* ```ts
+* import { createGraph, getPatches, applyPatches } from '@statelyai/graph';
+*
+* const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+* const b = createGraph({ nodes: [{ id: 'n1' }, { id: 'n2' }], edges: [] });
+*
+* const patches = getPatches(a, b);
+* applyPatches(a, patches);
+* // a now contains both n1 and n2
+* ```
 */
 function applyPatches(graph, patches) {
 	for (const patch of patches) switch (patch.op) {
@@ -188,6 +251,18 @@ function applyPatches(graph, patches) {
 * Order: add nodes → update edges → delete edges → delete nodes → add edges → update nodes.
 * This avoids cascading deletes removing edges that are being updated,
 * and ensures new nodes exist before edges reference them.
+*
+* @example
+* ```ts
+* import { createGraph, getDiff, toPatches } from '@statelyai/graph';
+*
+* const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+* const b = createGraph({ nodes: [{ id: 'n2' }], edges: [] });
+*
+* const diff = getDiff(a, b);
+* const patches = toPatches(diff);
+* // patches → [{ op: 'addNode', ... }, { op: 'deleteNode', ... }]
+* ```
 */
 function toPatches(diff) {
 	const patches = [];
@@ -227,7 +302,21 @@ function toPatches(diff) {
 	}
 	return patches;
 }
-/** Group a patch list into a structured diff. */
+/**
+* Group a patch list into a structured diff.
+*
+* @example
+* ```ts
+* import { createGraph, getPatches, toDiff } from '@statelyai/graph';
+*
+* const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+* const b = createGraph({ nodes: [{ id: 'n1' }, { id: 'n2' }], edges: [] });
+*
+* const patches = getPatches(a, b);
+* const diff = toDiff(patches);
+* // diff.nodes.added → [{ id: 'n2' }]
+* ```
+*/
 function toDiff(patches) {
 	const diff = {
 		nodes: {
@@ -287,6 +376,25 @@ function toDiff(patches) {
 * - Edges originating from a compound node expand to all leaf descendants.
 * - Only leaf nodes (nodes with no children) appear in the result.
 * - Duplicate edges (same source + target) are deduplicated.
+*
+* @example
+* ```ts
+* import { createGraph, flatten } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [
+*     { id: 'parent', initialNodeId: 'child1' },
+*     { id: 'child1', parentId: 'parent' },
+*     { id: 'child2', parentId: 'parent' },
+*     { id: 'other' },
+*   ],
+*   edges: [{ id: 'e1', sourceId: 'other', targetId: 'parent' }],
+* });
+*
+* const flat = flatten(graph);
+* // flat.nodes → [child1, child2, other] (leaf nodes only)
+* // flat.edges → edge from 'other' → 'child1' (resolved via initialNodeId)
+* ```
 */
 function flatten(graph) {
 	const idx = getIndex(graph);

package/dist/{indexing-BFFVMnjF.mjs → indexing-DitHphT7.mjs}

@@ -1,6 +1,23 @@
 //#region src/indexing.ts
 const indexes = /* @__PURE__ */ new WeakMap();
-/** Get or lazily build the index for a graph. */
+/**
+* Get or lazily build the index for a graph.
+* Auto-rebuilds when node/edge count changes.
+*
+* @example
+* ```ts
+* import { createGraph, getIndex } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+* });
+*
+* const idx = getIndex(graph);
+* idx.nodeById.get('a'); // 0
+* idx.outEdges.get('a'); // ['e1']
+* ```
+*/
 function getIndex(graph) {
 	let idx = indexes.get(graph);
 	if (!idx || idx.nodeCount !== graph.nodes.length || idx.edgeCount !== graph.edges.length) {
@@ -9,7 +26,19 @@ function getIndex(graph) {
 	}
 	return idx;
 }
-/** Clear the cached index. Call this if you mutate graph.nodes/edges directly. */
+/**
+* Clear the cached index. Call this if you mutate graph.nodes/edges directly.
+*
+* @example
+* ```ts
+* import { createGraph, invalidateIndex, getIndex } from '@statelyai/graph';
+*
+* const graph = createGraph({ nodes: [{ id: 'a' }], edges: [] });
+* // manually mutate nodes array
+* graph.nodes.push({ type: 'node', id: 'b', parentId: null, initialNodeId: null, label: '', data: undefined });
+* invalidateIndex(graph); // forces rebuild on next getIndex()
+* ```
+*/
 function invalidateIndex(graph) {
 	indexes.delete(graph);
 }
@@ -24,7 +53,7 @@ function buildIndex(graph) {
 		nodeById.set(n.id, i);
 		outEdges.set(n.id, []);
 		inEdges.set(n.id, []);
-		const parent = n.parentId;
+		const parent = n.parentId ?? null;
 		if (!childNodes.has(parent)) childNodes.set(parent, []);
 		childNodes.get(parent).push(n.id);
 	}
@@ -48,7 +77,7 @@ function indexAddNode(idx, node, arrayIndex) {
 	idx.nodeById.set(node.id, arrayIndex);
 	idx.outEdges.set(node.id, []);
 	idx.inEdges.set(node.id, []);
-	const parent = node.parentId;
+	const parent = node.parentId ?? null;
 	if (!idx.childNodes.has(parent)) idx.childNodes.set(parent, []);
 	idx.childNodes.get(parent).push(node.id);
 	idx.nodeCount++;
@@ -61,13 +90,14 @@ function indexAddEdge(idx, edge, arrayIndex) {
 }
 /** Update childNodes index when a node's parentId changes. */
 function indexReparentNode(idx, nodeId, oldParentId, newParentId) {
-	const oldSiblings = idx.childNodes.get(oldParentId);
+	const oldSiblings = idx.childNodes.get(oldParentId ?? null);
 	if (oldSiblings) {
 		const pos = oldSiblings.indexOf(nodeId);
 		if (pos !== -1) oldSiblings.splice(pos, 1);
 	}
-	if (!idx.childNodes.has(newParentId)) idx.childNodes.set(newParentId, []);
-	idx.childNodes.get(newParentId).push(nodeId);
+	const np = newParentId ?? null;
+	if (!idx.childNodes.has(np)) idx.childNodes.set(np, []);
+	idx.childNodes.get(np).push(nodeId);
 }
 /** Update adjacency lists when an edge's sourceId/targetId changes. */
 function indexUpdateEdgeEndpoints(idx, edgeId, oldSourceId, oldTargetId, newSourceId, newTargetId) {

package/dist/queries.d.mts

@@ -1,32 +1,347 @@
-import { c as Graph, d as GraphEdge, p as GraphNode } from "./types-B6Tpeerk.mjs";
+import { c as Graph, d as GraphEdge, p as GraphNode } from "./types-Bq_fmLwW.mjs";
 
 //#region src/queries.d.ts
+
+/**
+ * Returns all edges (incoming + outgoing) connected to a node.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+ *   edges: [
+ *     { id: 'e1', sourceId: 'a', targetId: 'b' },
+ *     { id: 'e2', sourceId: 'c', targetId: 'b' },
+ *   ],
+ * });
+ * getEdgesOf(graph, 'b');
+ * // => [edge e1, edge e2]
+ * ```
+ */
 declare function getEdgesOf<E>(graph: Graph<any, E>, nodeId: string): GraphEdge<E>[];
+/**
+ * Returns incoming edges to a node.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+ * });
+ * getInEdges(graph, 'b');
+ * // => [edge e1]
+ * getInEdges(graph, 'a');
+ * // => []
+ * ```
+ */
 declare function getInEdges<E>(graph: Graph<any, E>, nodeId: string): GraphEdge<E>[];
+/**
+ * Returns outgoing edges from a node.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+ * });
+ * getOutEdges(graph, 'a');
+ * // => [edge e1]
+ * getOutEdges(graph, 'b');
+ * // => []
+ * ```
+ */
 declare function getOutEdges<E>(graph: Graph<any, E>, nodeId: string): GraphEdge<E>[];
+/**
+ * Returns the edge from `sourceId` to `targetId`, or `undefined` if none exists.
+ * For undirected graphs, checks both directions.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+ * });
+ * getEdgeBetween(graph, 'a', 'b');
+ * // => edge e1
+ * getEdgeBetween(graph, 'b', 'a');
+ * // => undefined (directed graph)
+ * ```
+ */
 declare function getEdgeBetween<E>(graph: Graph<any, E>, sourceId: string, targetId: string): GraphEdge<E> | undefined;
+/**
+ * Returns direct successor nodes (targets of outgoing edges).
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+ *   edges: [
+ *     { id: 'e1', sourceId: 'a', targetId: 'b' },
+ *     { id: 'e2', sourceId: 'a', targetId: 'c' },
+ *   ],
+ * });
+ * getSuccessors(graph, 'a');
+ * // => [node b, node c]
+ * ```
+ */
 declare function getSuccessors<N>(graph: Graph<N>, nodeId: string): GraphNode<N>[];
+/**
+ * Returns direct predecessor nodes (sources of incoming edges).
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+ *   edges: [
+ *     { id: 'e1', sourceId: 'a', targetId: 'c' },
+ *     { id: 'e2', sourceId: 'b', targetId: 'c' },
+ *   ],
+ * });
+ * getPredecessors(graph, 'c');
+ * // => [node a, node b]
+ * ```
+ */
 declare function getPredecessors<N>(graph: Graph<N>, nodeId: string): GraphNode<N>[];
+/**
+ * Returns all neighbor nodes (successors + predecessors).
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+ *   edges: [
+ *     { id: 'e1', sourceId: 'a', targetId: 'b' },
+ *     { id: 'e2', sourceId: 'c', targetId: 'b' },
+ *   ],
+ * });
+ * getNeighbors(graph, 'b');
+ * // => [node a, node c]
+ * ```
+ */
 declare function getNeighbors<N>(graph: Graph<N>, nodeId: string): GraphNode<N>[];
+/**
+ * Returns the total degree of a node (inDegree + outDegree).
+ * For undirected graphs, each edge is counted once.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+ *   edges: [
+ *     { id: 'e1', sourceId: 'a', targetId: 'b' },
+ *     { id: 'e2', sourceId: 'c', targetId: 'b' },
+ *   ],
+ * });
+ * getDegree(graph, 'b'); // => 2
+ * getDegree(graph, 'a'); // => 1
+ * ```
+ */
 declare function getDegree(graph: Graph, nodeId: string): number;
+/**
+ * Returns the in-degree of a node (number of incoming edges).
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+ * });
+ * getInDegree(graph, 'b'); // => 1
+ * getInDegree(graph, 'a'); // => 0
+ * ```
+ */
 declare function getInDegree(graph: Graph, nodeId: string): number;
+/**
+ * Returns the out-degree of a node (number of outgoing edges).
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+ * });
+ * getOutDegree(graph, 'a'); // => 1
+ * getOutDegree(graph, 'b'); // => 0
+ * ```
+ */
 declare function getOutDegree(graph: Graph, nodeId: string): number;
+/**
+ * Returns direct children of a node in the hierarchy.
+ * Pass `null` to get root-level nodes.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [
+ *     { id: 'parent' },
+ *     { id: 'child1', parentId: 'parent' },
+ *     { id: 'child2', parentId: 'parent' },
+ *   ],
+ * });
+ * getChildren(graph, 'parent');
+ * // => [node child1, node child2]
+ * getChildren(graph, null);
+ * // => [node parent]
+ * ```
+ */
 declare function getChildren<N>(graph: Graph<N>, nodeId: string | null): GraphNode<N>[];
+/**
+ * Returns the parent node in the hierarchy, or `undefined` if root-level.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [
+ *     { id: 'parent' },
+ *     { id: 'child', parentId: 'parent' },
+ *   ],
+ * });
+ * getParent(graph, 'child');
+ * // => node parent
+ * getParent(graph, 'parent');
+ * // => undefined
+ * ```
+ */
 declare function getParent<N>(graph: Graph<N>, nodeId: string): GraphNode<N> | undefined;
+/**
+ * Returns all ancestors from the node up to the root (nearest parent first).
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [
+ *     { id: 'root' },
+ *     { id: 'mid', parentId: 'root' },
+ *     { id: 'leaf', parentId: 'mid' },
+ *   ],
+ * });
+ * getAncestors(graph, 'leaf');
+ * // => [node mid, node root]
+ * ```
+ */
 declare function getAncestors<N>(graph: Graph<N>, nodeId: string): GraphNode<N>[];
+/**
+ * Returns all descendants recursively (depth-first).
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [
+ *     { id: 'root' },
+ *     { id: 'child', parentId: 'root' },
+ *     { id: 'grandchild', parentId: 'child' },
+ *   ],
+ * });
+ * getDescendants(graph, 'root');
+ * // => [node child, node grandchild]
+ * ```
+ */
 declare function getDescendants<N>(graph: Graph<N>, nodeId: string): GraphNode<N>[];
+/**
+ * Returns all root nodes (nodes with no parent).
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [
+ *     { id: 'root1' },
+ *     { id: 'root2' },
+ *     { id: 'child', parentId: 'root1' },
+ *   ],
+ * });
+ * getRoots(graph);
+ * // => [node root1, node root2]
+ * ```
+ */
 declare function getRoots<N>(graph: Graph<N>): GraphNode<N>[];
-/** Whether a node has children (is a compound/group node). */
+/**
+ * Whether a node has children (is a compound/group node).
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [
+ *     { id: 'parent' },
+ *     { id: 'child', parentId: 'parent' },
+ *   ],
+ * });
+ * isCompound(graph, 'parent'); // => true
+ * isCompound(graph, 'child');  // => false
+ * ```
+ */
 declare function isCompound(graph: Graph, nodeId: string): boolean;
-/** Whether a node has no children (is a leaf/atomic node). */
+/**
+ * Whether a node has no children (is a leaf/atomic node).
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [
+ *     { id: 'parent' },
+ *     { id: 'child', parentId: 'parent' },
+ *   ],
+ * });
+ * isLeaf(graph, 'child');  // => true
+ * isLeaf(graph, 'parent'); // => false
+ * ```
+ */
 declare function isLeaf(graph: Graph, nodeId: string): boolean;
-/** Depth of a node in the hierarchy (root = 0). */
+/**
+ * Depth of a node in the hierarchy (root = 0).
+ * Returns -1 if the node is not found.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [
+ *     { id: 'root' },
+ *     { id: 'child', parentId: 'root' },
+ *     { id: 'grandchild', parentId: 'child' },
+ *   ],
+ * });
+ * getDepth(graph, 'root');       // => 0
+ * getDepth(graph, 'child');      // => 1
+ * getDepth(graph, 'grandchild'); // => 2
+ * ```
+ */
 declare function getDepth(graph: Graph, nodeId: string): number;
-/** Sibling nodes (same parentId, excluding the node itself). */
+/**
+ * Sibling nodes (same parentId, excluding the node itself).
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [
+ *     { id: 'parent' },
+ *     { id: 'a', parentId: 'parent' },
+ *     { id: 'b', parentId: 'parent' },
+ *     { id: 'c', parentId: 'parent' },
+ *   ],
+ * });
+ * getSiblings(graph, 'a');
+ * // => [node b, node c]
+ * ```
+ */
 declare function getSiblings<N>(graph: Graph<N>, nodeId: string): GraphNode<N>[];
 /**
- * Least Common Ancestor — deepest proper ancestor of all given nodes.
+ * Least Common Ancestor -- deepest proper ancestor of all given nodes.
  * A proper ancestor excludes the input nodes themselves.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [
+ *     { id: 'root' },
+ *     { id: 'a', parentId: 'root' },
+ *     { id: 'b', parentId: 'root' },
+ *     { id: 'a1', parentId: 'a' },
+ *   ],
+ * });
+ * getLCA(graph, 'a1', 'b');
+ * // => node root
+ * getLCA(graph, 'a', 'b');
+ * // => node root
+ * ```
  */
 declare function getLCA<N>(graph: Graph<N>, ...nodeIds: string[]): GraphNode<N> | undefined;
 /**
@@ -105,9 +420,39 @@ declare function getRelativeDistanceMap(graph: Graph, parentId: string | null):
  * ```
  */
 declare function getRelativeDistance(graph: Graph, nodeId: string): number | undefined;
-/** Nodes with no incoming edges (inDegree 0). */
+/**
+ * Nodes with no incoming edges (inDegree 0).
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+ *   edges: [
+ *     { id: 'e1', sourceId: 'a', targetId: 'b' },
+ *     { id: 'e2', sourceId: 'b', targetId: 'c' },
+ *   ],
+ * });
+ * getSources(graph);
+ * // => [node a]
+ * ```
+ */
 declare function getSources<N>(graph: Graph<N>): GraphNode<N>[];
-/** Nodes with no outgoing edges (outDegree 0). */
+/**
+ * Nodes with no outgoing edges (outDegree 0).
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+ *   edges: [
+ *     { id: 'e1', sourceId: 'a', targetId: 'b' },
+ *     { id: 'e2', sourceId: 'b', targetId: 'c' },
+ *   ],
+ * });
+ * getSinks(graph);
+ * // => [node c]
+ * ```
+ */
 declare function getSinks<N>(graph: Graph<N>): GraphNode<N>[];
 //#endregion
 export { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf };