@statelyai/graph 0.13.0 → 2.0.0

package/dist/queries-BfXeTXRf.d.mts

@@ -0,0 +1,547 @@
+import { d as Graph, m as GraphEdge, v as GraphNode, x as GraphPort } from "./types-DNYdIU21.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<N, E>(graph: Graph<N, E>, nodeId: string): GraphEdge<E>[];
+/**
+ * Returns incoming edges to a node, by *authored* direction
+ * (`edge.targetId === nodeId`), regardless of edge mode. For mode-aware
+ * traversal use {@link getPredecessors} or {@link getEdgesOf}.
+ *
+ * @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<N, E>(graph: Graph<N, E>, nodeId: string): GraphEdge<E>[];
+/**
+ * Returns outgoing edges from a node, by *authored* direction
+ * (`edge.sourceId === nodeId`), regardless of edge mode. For mode-aware
+ * traversal use {@link getSuccessors} or {@link getEdgesOf}.
+ *
+ * @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<N, E>(graph: Graph<N, E>, nodeId: string): GraphEdge<E>[];
+/**
+ * Returns all edges from `sourceId` to `targetId`.
+ * Edges whose effective mode is not `'directed'` are matched both ways.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+ * });
+ * getEdgesBetween(graph, 'a', 'b');
+ * // => [edge e1]
+ * getEdgesBetween(graph, 'b', 'a');
+ * // => [] (directed edge)
+ * ```
+ */
+declare function getEdgesBetween<N, E>(graph: Graph<N, E>, sourceId: string, targetId: string): GraphEdge<E>[];
+/**
+ * Returns direct successor nodes — nodes reachable by traversing one edge
+ * away from `nodeId`. Edges whose effective mode is not `'directed'` are
+ * traversable both ways, so their other endpoint also counts as a successor.
+ *
+ * @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 — nodes from which `nodeId` is reachable
+ * by traversing one edge. Edges whose effective mode is not `'directed'` are
+ * traversable both ways, so their other endpoint also counts as a predecessor.
+ *
+ * @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 (number of incident edge endpoints).
+ * Each incident edge whose effective mode is not `'directed'` is counted
+ * once (a non-directed self-loop counts once; a directed self-loop counts
+ * twice — once in, once out).
+ *
+ * @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 — the number of edges traversable *into*
+ * the node. Edges whose effective mode is not `'directed'` count toward both
+ * endpoints' in-degree (once per edge).
+ *
+ * @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 — the number of edges traversable *out of*
+ * the node. Edges whose effective mode is not `'directed'` count toward both
+ * endpoints' out-degree (once per edge).
+ *
+ * @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).
+ *
+ * If the parent chain contains a cycle (authored `parentId` cycles are not
+ * rejected by `createGraph`), the walk stops at the first repeated node and
+ * returns the ancestors collected so far — each ancestor appears exactly once.
+ *
+ * @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).
+ *
+ * If the hierarchy contains a parent cycle (authored `parentId` cycles are
+ * not rejected by `createGraph`), each node is visited at most once: the walk
+ * stops at the first repeated node and returns the descendants collected so far.
+ *
+ * @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).
+ *
+ * @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).
+ *
+ * @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).
+ * Returns -1 if the node is not found.
+ *
+ * If the parent chain contains a cycle (authored `parentId` cycles are not
+ * rejected by `createGraph`), the walk stops at the first repeated node and
+ * returns the number of unique ancestors walked up to that point.
+ *
+ * @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).
+ *
+ * @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.
+ * A proper ancestor excludes the input nodes themselves.
+ *
+ * If a parent chain contains a cycle (authored `parentId` cycles are not
+ * rejected by `createGraph`), each chain walk stops at the first repeated
+ * node, so every ancestor is considered exactly once.
+ *
+ * @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;
+/**
+ * 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). A node incident to an edge whose
+ * effective mode is not `'directed'` is never a source (the edge points in).
+ *
+ * @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). A node incident to an edge whose
+ * effective mode is not `'directed'` is never a sink (the edge points out).
+ *
+ * @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>[];
+/**
+ * Get a port by name on a node, or `undefined` if not found.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{
+ *     id: 'a',
+ *     ports: [{ name: 'out', direction: 'out' }],
+ *   }],
+ * });
+ * getPort(graph, 'a', 'out'); // => { name: 'out', direction: 'out', ... }
+ * getPort(graph, 'a', 'missing'); // => undefined
+ * ```
+ */
+declare function getPort<N, E, G, P>(graph: Graph<N, E, G, P>, nodeId: string, portName: string): GraphPort<P> | undefined;
+/**
+ * Get all ports on a node. Returns `[]` if the node has no ports or doesn't exist.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{
+ *     id: 'a',
+ *     ports: [
+ *       { name: 'in', direction: 'in' },
+ *       { name: 'out', direction: 'out' },
+ *     ],
+ *   }],
+ * });
+ * getPorts(graph, 'a'); // => [port in, port out]
+ * ```
+ */
+declare function getPorts<N, E, G, P>(graph: Graph<N, E, G, P>, nodeId: string): GraphPort<P>[];
+/**
+ * Get all edges connected to a specific port on a node.
+ *
+ * Returns edges where:
+ * - `sourceId === nodeId && sourcePort === portName`, or
+ * - `targetId === nodeId && targetPort === portName`
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [
+ *     { id: 'a', ports: [{ name: 'out', direction: 'out' }] },
+ *     { id: 'b', ports: [{ name: 'in', direction: 'in' }] },
+ *   ],
+ *   edges: [{
+ *     id: 'e1', sourceId: 'a', targetId: 'b',
+ *     sourcePort: 'out', targetPort: 'in',
+ *   }],
+ * });
+ * getEdgesByPort(graph, 'a', 'out'); // => [edge e1]
+ * ```
+ */
+declare function getEdgesByPort<N, E>(graph: Graph<N, E>, nodeId: string, portName: string): GraphEdge<E>[];
+//#endregion
+export { getSinks as C, isLeaf as D, isCompound as E, getSiblings as S, getSuccessors as T, getPorts as _, getDescendants as a, getRelativeDistanceMap as b, getEdgesOf as c, getLCA as d, getNeighbors as f, getPort as g, getParent as h, getDepth as i, getInDegree as l, getOutEdges as m, getChildren as n, getEdgesBetween as o, getOutDegree as p, getDegree as r, getEdgesByPort as s, getAncestors as t, getInEdges as u, getPredecessors as v, getSources as w, getRoots as x, getRelativeDistance as y };