@statelyai/graph 1.0.0 → 2.0.0

package/dist/{queries-BlkA1HAN.d.mts → queries-BfXeTXRf.d.mts}

@@ -1,4 +1,4 @@
-import { _ as GraphNode, b as GraphPort, p as GraphEdge, u as Graph } from "./types-3-FS9NV2.mjs";
+import { d as Graph, m as GraphEdge, v as GraphNode, x as GraphPort } from "./types-DNYdIU21.mjs";
 
 //#region src/queries.d.ts
 
@@ -20,7 +20,9 @@ import { _ as GraphNode, b as GraphPort, p as GraphEdge, u as Graph } from "./ty
  */
 declare function getEdgesOf<N, E>(graph: Graph<N, E>, nodeId: string): GraphEdge<E>[];
 /**
- * Returns incoming edges to a node.
+ * 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
@@ -36,7 +38,9 @@ declare function getEdgesOf<N, E>(graph: Graph<N, E>, nodeId: string): GraphEdge
  */
 declare function getInEdges<N, E>(graph: Graph<N, E>, nodeId: string): GraphEdge<E>[];
 /**
- * Returns outgoing edges from a node.
+ * 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
@@ -69,7 +73,9 @@ declare function getOutEdges<N, E>(graph: Graph<N, E>, nodeId: string): GraphEdg
  */
 declare function getEdgesBetween<N, E>(graph: Graph<N, E>, sourceId: string, targetId: string): GraphEdge<E>[];
 /**
- * Returns direct successor nodes (targets of outgoing edges).
+ * 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
@@ -86,7 +92,9 @@ declare function getEdgesBetween<N, E>(graph: Graph<N, E>, sourceId: string, tar
  */
 declare function getSuccessors<N>(graph: Graph<N>, nodeId: string): GraphNode<N>[];
 /**
- * Returns direct predecessor nodes (sources of incoming edges).
+ * 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
@@ -120,9 +128,10 @@ declare function getPredecessors<N>(graph: Graph<N>, nodeId: string): GraphNode<
  */
 declare function getNeighbors<N>(graph: Graph<N>, nodeId: string): GraphNode<N>[];
 /**
- * Returns the total degree of a node (inDegree + outDegree).
- * For graphs whose default mode is not `'directed'`, each incident edge is
- * counted once.
+ * 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
@@ -139,7 +148,9 @@ declare function getNeighbors<N>(graph: Graph<N>, nodeId: string): GraphNode<N>[
  */
 declare function getDegree(graph: Graph, nodeId: string): number;
 /**
- * Returns the in-degree of a node (number of incoming edges).
+ * 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
@@ -153,7 +164,9 @@ declare function getDegree(graph: Graph, nodeId: string): number;
  */
 declare function getInDegree(graph: Graph, nodeId: string): number;
 /**
- * Returns the out-degree of a node (number of outgoing edges).
+ * 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
@@ -207,6 +220,10 @@ declare function getParent<N>(graph: Graph<N>, nodeId: string): GraphNode<N> | u
 /**
  * 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({
@@ -224,6 +241,10 @@ 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({
@@ -291,6 +312,10 @@ 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({
@@ -328,6 +353,10 @@ 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({
@@ -422,7 +451,8 @@ 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). A node incident to an edge whose
+ * effective mode is not `'directed'` is never a source (the edge points in).
  *
  * @example
  * ```ts
@@ -439,7 +469,8 @@ declare function getRelativeDistance(graph: Graph, nodeId: string): number | und
  */
 declare function getSources<N>(graph: Graph<N>): GraphNode<N>[];
 /**
- * Nodes with no outgoing edges (outDegree 0).
+ * 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