@statelyai/graph 0.1.0 → 0.3.1

package/dist/queries.d.mts

@@ -1,37 +1,458 @@
-import { c as Graph, d as GraphEdge, f as GraphNode } from "./types-XV3S5Jnh.mjs";
+import { c as Graph, d as GraphEdge, p as GraphNode } from "./types-BDXC1O5b.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, i.e. `parentId === null`).
+ *
+ * @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;
-/** Nodes with no incoming edges (inDegree 0). */
+/**
+ * Returns a map of nodeId → shortest-path distance for all sibling nodes
+ * (same parentId). Distance is measured from the parent's `initialNodeId`
+ * (or `graph.initialNodeId` for root-level nodes).
+ *
+ * Only follows edges between siblings. Unreachable siblings are omitted.
+ *
+ * @example Root-level nodes (uses `graph.initialNodeId`):
+ * ```ts
+ * const graph = createGraph({
+ *   initialNodeId: 'a',
+ *   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+ *   edges: [
+ *     { id: 'e1', sourceId: 'a', targetId: 'b' },
+ *     { id: 'e2', sourceId: 'b', targetId: 'c' },
+ *   ],
+ * });
+ * getRelativeDistanceMap(graph, null);
+ * // => { a: 0, b: 1, c: 2 }
+ * ```
+ *
+ * @example Nested nodes (uses parent's `initialNodeId`):
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [
+ *     { id: 'parent', initialNodeId: 's1' },
+ *     { id: 's1', parentId: 'parent' },
+ *     { id: 's2', parentId: 'parent' },
+ *     { id: 's3', parentId: 'parent' },
+ *   ],
+ *   edges: [
+ *     { id: 'e1', sourceId: 's1', targetId: 's2' },
+ *     { id: 'e2', sourceId: 's2', targetId: 's3' },
+ *   ],
+ * });
+ * getRelativeDistanceMap(graph, 'parent');
+ * // => { s1: 0, s2: 1, s3: 2 }
+ * ```
+ */
+declare function getRelativeDistanceMap(graph: Graph, parentId: string | null): Record<string, number>;
+/**
+ * Returns the shortest-path distance of a node from its parent's initial node.
+ * Automatically scopes to the node's sibling group (same `parentId`).
+ *
+ * Returns `undefined` if the node is not found or unreachable.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   initialNodeId: 'a',
+ *   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+ *   edges: [
+ *     { id: 'e1', sourceId: 'a', targetId: 'b' },
+ *     { id: 'e2', sourceId: 'b', targetId: 'c' },
+ *   ],
+ * });
+ * getRelativeDistance(graph, 'a'); // => 0
+ * getRelativeDistance(graph, 'b'); // => 1
+ * getRelativeDistance(graph, 'c'); // => 2
+ * ```
+ *
+ * @example Nested nodes:
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [
+ *     { id: 'parent', initialNodeId: 's1' },
+ *     { id: 's1', parentId: 'parent' },
+ *     { id: 's2', parentId: 'parent' },
+ *   ],
+ *   edges: [{ id: 'e1', sourceId: 's1', targetId: 's2' }],
+ * });
+ * getRelativeDistance(graph, 's1'); // => 0
+ * getRelativeDistance(graph, 's2'); // => 1
+ * ```
+ */
+declare function getRelativeDistance(graph: Graph, nodeId: string): number | undefined;
+/**
+ * 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, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf };
+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 };