@statelyai/graph 1.0.0 → 2.0.0

package/dist/queries-KirMDR7e.mjs

@@ -0,0 +1,980 @@
+import { t as getEdgeMode } from "./mode-D8OnHFBk.mjs";
+
+//#region src/indexing.ts
+const indexes = /* @__PURE__ */ new WeakMap();
+/**
+* Get or lazily build the index for a graph.
+* Auto-rebuilds when `graph.nodes`/`graph.edges` are **replaced** (e.g. an
+* immutable-style `map`/`filter` update) or when their length changes.
+*
+* Mutating *fields* of an existing node/edge in place (e.g.
+* `edge.sourceId = 'x'`, `node.parentId = 'y'`) is not detectable in O(1) —
+* call {@link invalidateIndex} afterwards, or use the mutation API
+* (`updateNode`/`updateEdge`), which keeps the index in sync.
+*
+* @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.nodesRef !== graph.nodes || idx.edgesRef !== graph.edges || idx.nodeCount !== graph.nodes.length || idx.edgeCount !== graph.edges.length) {
+		idx = buildIndex(graph);
+		indexes.set(graph, idx);
+	}
+	return idx;
+}
+/**
+* Clear the cached index. Call this if you mutate fields of existing
+* nodes/edges in place (e.g. `edge.targetId = 'a'`) — such mutations are not
+* auto-detected. Array replacement and length changes are auto-detected.
+*
+* @example
+* ```ts
+* import { createGraph, invalidateIndex, getIndex } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+* });
+* graph.edges[0].targetId = 'a'; // in-place field mutation
+* invalidateIndex(graph); // forces rebuild on next getIndex()
+* ```
+*/
+function invalidateIndex(graph) {
+	indexes.delete(graph);
+}
+function buildIndex(graph) {
+	const nodeById = /* @__PURE__ */ new Map();
+	const edgeById = /* @__PURE__ */ new Map();
+	const outEdges = /* @__PURE__ */ new Map();
+	const inEdges = /* @__PURE__ */ new Map();
+	const childNodes = /* @__PURE__ */ new Map();
+	for (let i = 0; i < graph.nodes.length; i++) {
+		const n = graph.nodes[i];
+		nodeById.set(n.id, i);
+		outEdges.set(n.id, []);
+		inEdges.set(n.id, []);
+		const parent = n.parentId ?? null;
+		if (!childNodes.has(parent)) childNodes.set(parent, []);
+		childNodes.get(parent).push(n.id);
+	}
+	for (let i = 0; i < graph.edges.length; i++) {
+		const e = graph.edges[i];
+		edgeById.set(e.id, i);
+		outEdges.get(e.sourceId)?.push(e.id);
+		inEdges.get(e.targetId)?.push(e.id);
+	}
+	return {
+		nodeById,
+		edgeById,
+		outEdges,
+		inEdges,
+		childNodes,
+		nodeCount: graph.nodes.length,
+		edgeCount: graph.edges.length,
+		nodesRef: graph.nodes,
+		edgesRef: graph.edges,
+		version: 0
+	};
+}
+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 ?? null;
+	if (!idx.childNodes.has(parent)) idx.childNodes.set(parent, []);
+	idx.childNodes.get(parent).push(node.id);
+	idx.nodeCount++;
+	idx.version++;
+}
+function indexAddEdge(idx, edge, arrayIndex) {
+	idx.edgeById.set(edge.id, arrayIndex);
+	idx.outEdges.get(edge.sourceId)?.push(edge.id);
+	idx.inEdges.get(edge.targetId)?.push(edge.id);
+	idx.edgeCount++;
+	idx.version++;
+}
+/** Update childNodes index when a node's parentId changes. */
+function indexReparentNode(idx, nodeId, oldParentId, newParentId) {
+	const oldSiblings = idx.childNodes.get(oldParentId ?? null);
+	if (oldSiblings) {
+		const pos = oldSiblings.indexOf(nodeId);
+		if (pos !== -1) oldSiblings.splice(pos, 1);
+	}
+	const np = newParentId ?? null;
+	if (!idx.childNodes.has(np)) idx.childNodes.set(np, []);
+	idx.childNodes.get(np).push(nodeId);
+	idx.version++;
+}
+/**
+* Bump the index version without touching adjacency. Used by mutations that
+* change fields derived caches depend on (e.g. per-edge `mode` affects the
+* CSR arc structure but not the id-based adjacency lists).
+*/
+function touchIndex(idx) {
+	idx.version++;
+}
+/** Update adjacency lists when an edge's sourceId/targetId changes. */
+function indexUpdateEdgeEndpoints(idx, edgeId, oldSourceId, oldTargetId, newSourceId, newTargetId) {
+	if (oldSourceId !== newSourceId) {
+		const oldOut = idx.outEdges.get(oldSourceId);
+		if (oldOut) {
+			const pos = oldOut.indexOf(edgeId);
+			if (pos !== -1) oldOut.splice(pos, 1);
+		}
+		idx.outEdges.get(newSourceId)?.push(edgeId);
+	}
+	if (oldTargetId !== newTargetId) {
+		const oldIn = idx.inEdges.get(oldTargetId);
+		if (oldIn) {
+			const pos = oldIn.indexOf(edgeId);
+			if (pos !== -1) oldIn.splice(pos, 1);
+		}
+		idx.inEdges.get(newTargetId)?.push(edgeId);
+	}
+	idx.version++;
+}
+
+//#endregion
+//#region src/queries.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]
+* ```
+*/
+function getEdgesOf(graph, nodeId) {
+	const idx = getIndex(graph);
+	const outIds = idx.outEdges.get(nodeId) ?? [];
+	const inIds = idx.inEdges.get(nodeId) ?? [];
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	for (const eid of outIds) {
+		seen.add(eid);
+		const ai = idx.edgeById.get(eid);
+		if (ai !== void 0) result.push(graph.edges[ai]);
+	}
+	for (const eid of inIds) if (!seen.has(eid)) {
+		const ai = idx.edgeById.get(eid);
+		if (ai !== void 0) result.push(graph.edges[ai]);
+	}
+	return result;
+}
+/**
+* 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');
+* // => []
+* ```
+*/
+function getInEdges(graph, nodeId) {
+	const idx = getIndex(graph);
+	return (idx.inEdges.get(nodeId) ?? []).map((eid) => graph.edges[idx.edgeById.get(eid)]);
+}
+/**
+* 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');
+* // => []
+* ```
+*/
+function getOutEdges(graph, nodeId) {
+	const idx = getIndex(graph);
+	return (idx.outEdges.get(nodeId) ?? []).map((eid) => graph.edges[idx.edgeById.get(eid)]);
+}
+/**
+* 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)
+* ```
+*/
+function getEdgesBetween(graph, sourceId, targetId) {
+	const idx = getIndex(graph);
+	const result = [];
+	const seen = /* @__PURE__ */ new Set();
+	const outIds = idx.outEdges.get(sourceId) ?? [];
+	for (const eid of outIds) {
+		const ai = idx.edgeById.get(eid);
+		const e = graph.edges[ai];
+		if (e.targetId === targetId) {
+			seen.add(eid);
+			result.push(e);
+		}
+	}
+	const outIds2 = idx.outEdges.get(targetId) ?? [];
+	for (const eid of outIds2) {
+		if (seen.has(eid)) continue;
+		const ai = idx.edgeById.get(eid);
+		const e = graph.edges[ai];
+		if (e.targetId === sourceId && getEdgeMode(graph, e) !== "directed") result.push(e);
+	}
+	return result;
+}
+/**
+* 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]
+* ```
+*/
+function getSuccessors(graph, nodeId) {
+	const idx = getIndex(graph);
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	const add = (id) => {
+		if (seen.has(id)) return;
+		seen.add(id);
+		const ni = idx.nodeById.get(id);
+		if (ni !== void 0) result.push(graph.nodes[ni]);
+	};
+	for (const eid of idx.outEdges.get(nodeId) ?? []) add(graph.edges[idx.edgeById.get(eid)].targetId);
+	for (const eid of idx.inEdges.get(nodeId) ?? []) {
+		const e = graph.edges[idx.edgeById.get(eid)];
+		if (getEdgeMode(graph, e) !== "directed") add(e.sourceId);
+	}
+	return result;
+}
+/**
+* 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]
+* ```
+*/
+function getPredecessors(graph, nodeId) {
+	const idx = getIndex(graph);
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	const add = (id) => {
+		if (seen.has(id)) return;
+		seen.add(id);
+		const ni = idx.nodeById.get(id);
+		if (ni !== void 0) result.push(graph.nodes[ni]);
+	};
+	for (const eid of idx.inEdges.get(nodeId) ?? []) add(graph.edges[idx.edgeById.get(eid)].sourceId);
+	for (const eid of idx.outEdges.get(nodeId) ?? []) {
+		const e = graph.edges[idx.edgeById.get(eid)];
+		if (getEdgeMode(graph, e) !== "directed") add(e.targetId);
+	}
+	return result;
+}
+/**
+* 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]
+* ```
+*/
+function getNeighbors(graph, nodeId) {
+	const idx = getIndex(graph);
+	const ids = /* @__PURE__ */ new Set();
+	for (const eid of idx.outEdges.get(nodeId) ?? []) ids.add(graph.edges[idx.edgeById.get(eid)].targetId);
+	for (const eid of idx.inEdges.get(nodeId) ?? []) ids.add(graph.edges[idx.edgeById.get(eid)].sourceId);
+	return [...ids].map((id) => graph.nodes[idx.nodeById.get(id)]).filter(Boolean);
+}
+/**
+* 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
+* ```
+*/
+function getDegree(graph, nodeId) {
+	const idx = getIndex(graph);
+	const out = idx.outEdges.get(nodeId) ?? [];
+	const inE = idx.inEdges.get(nodeId) ?? [];
+	let degree = 0;
+	const countedNonDirected = /* @__PURE__ */ new Set();
+	for (const eid of [...out, ...inE]) {
+		const e = graph.edges[idx.edgeById.get(eid)];
+		if (getEdgeMode(graph, e) === "directed") degree++;
+		else if (!countedNonDirected.has(eid)) {
+			countedNonDirected.add(eid);
+			degree++;
+		}
+	}
+	return degree;
+}
+/**
+* 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
+* ```
+*/
+function getInDegree(graph, nodeId) {
+	const idx = getIndex(graph);
+	let degree = idx.inEdges.get(nodeId)?.length ?? 0;
+	for (const eid of idx.outEdges.get(nodeId) ?? []) {
+		const e = graph.edges[idx.edgeById.get(eid)];
+		if (getEdgeMode(graph, e) !== "directed" && e.targetId !== nodeId) degree++;
+	}
+	return degree;
+}
+/**
+* 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
+* ```
+*/
+function getOutDegree(graph, nodeId) {
+	const idx = getIndex(graph);
+	let degree = idx.outEdges.get(nodeId)?.length ?? 0;
+	for (const eid of idx.inEdges.get(nodeId) ?? []) {
+		const e = graph.edges[idx.edgeById.get(eid)];
+		if (getEdgeMode(graph, e) !== "directed" && e.sourceId !== nodeId) degree++;
+	}
+	return degree;
+}
+/**
+* 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]
+* ```
+*/
+function getChildren(graph, nodeId) {
+	const idx = getIndex(graph);
+	return (idx.childNodes.get(nodeId) ?? []).map((id) => graph.nodes[idx.nodeById.get(id)]).filter(Boolean);
+}
+/**
+* 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
+* ```
+*/
+function getParent(graph, nodeId) {
+	const idx = getIndex(graph);
+	const ni = idx.nodeById.get(nodeId);
+	if (ni === void 0) return void 0;
+	const node = graph.nodes[ni];
+	if (!node.parentId) return void 0;
+	const pi = idx.nodeById.get(node.parentId);
+	return pi !== void 0 ? graph.nodes[pi] : void 0;
+}
+/**
+* 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]
+* ```
+*/
+function getAncestors(graph, nodeId) {
+	const idx = getIndex(graph);
+	const result = [];
+	let ni = idx.nodeById.get(nodeId);
+	if (ni === void 0) return result;
+	let current = graph.nodes[ni];
+	const seen = new Set([nodeId]);
+	while (current && current.parentId) {
+		if (seen.has(current.parentId)) break;
+		const pi = idx.nodeById.get(current.parentId);
+		if (pi === void 0) break;
+		const p = graph.nodes[pi];
+		seen.add(p.id);
+		result.push(p);
+		current = p;
+	}
+	return result;
+}
+/**
+* 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]
+* ```
+*/
+function getDescendants(graph, nodeId) {
+	const idx = getIndex(graph);
+	const result = [];
+	const seen = new Set([nodeId]);
+	const collect = (id) => {
+		const childIds = idx.childNodes.get(id) ?? [];
+		for (const childId of childIds) {
+			if (seen.has(childId)) continue;
+			seen.add(childId);
+			const ci = idx.nodeById.get(childId);
+			if (ci !== void 0) {
+				result.push(graph.nodes[ci]);
+				collect(childId);
+			}
+		}
+	};
+	collect(nodeId);
+	return result;
+}
+/**
+* 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]
+* ```
+*/
+function getRoots(graph) {
+	const idx = getIndex(graph);
+	return idx.childNodes.get(null)?.map((id) => graph.nodes[idx.nodeById.get(id)]).filter(Boolean) ?? [];
+}
+/**
+* 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
+* ```
+*/
+function isCompound(graph, nodeId) {
+	return (getIndex(graph).childNodes.get(nodeId) ?? []).length > 0;
+}
+/**
+* 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
+* ```
+*/
+function isLeaf(graph, nodeId) {
+	return !isCompound(graph, nodeId);
+}
+/**
+* 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
+* ```
+*/
+function getDepth(graph, nodeId) {
+	const idx = getIndex(graph);
+	let d = 0;
+	let ni = idx.nodeById.get(nodeId);
+	if (ni === void 0) return -1;
+	let current = graph.nodes[ni];
+	const seen = new Set([nodeId]);
+	while (current.parentId) {
+		if (seen.has(current.parentId)) break;
+		seen.add(current.parentId);
+		d++;
+		const pi = idx.nodeById.get(current.parentId);
+		if (pi === void 0) break;
+		current = graph.nodes[pi];
+	}
+	return d;
+}
+/**
+* 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]
+* ```
+*/
+function getSiblings(graph, nodeId) {
+	const idx = getIndex(graph);
+	const ni = idx.nodeById.get(nodeId);
+	if (ni === void 0) return [];
+	const node = graph.nodes[ni];
+	return (idx.childNodes.get(node.parentId ?? null) ?? []).filter((id) => id !== nodeId).map((id) => graph.nodes[idx.nodeById.get(id)]).filter(Boolean);
+}
+/**
+* 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
+* ```
+*/
+function getLCA(graph, ...nodeIds) {
+	if (nodeIds.length === 0) return void 0;
+	const idx = getIndex(graph);
+	const getAncestorChain = (id) => {
+		const result = [id];
+		const seen = new Set([id]);
+		let ni$1 = idx.nodeById.get(id);
+		if (ni$1 === void 0) return result;
+		let current = graph.nodes[ni$1];
+		while (current.parentId) {
+			if (seen.has(current.parentId)) break;
+			seen.add(current.parentId);
+			result.push(current.parentId);
+			const pi = idx.nodeById.get(current.parentId);
+			if (pi === void 0) break;
+			current = graph.nodes[pi];
+		}
+		return result;
+	};
+	let common = getAncestorChain(nodeIds[0]);
+	for (let i = 1; i < nodeIds.length; i++) {
+		const set = new Set(getAncestorChain(nodeIds[i]));
+		common = common.filter((id) => set.has(id));
+	}
+	const inputSet = new Set(nodeIds);
+	common = common.filter((id) => !inputSet.has(id));
+	if (common.length === 0) return void 0;
+	const lcaId = common[0];
+	const ni = idx.nodeById.get(lcaId);
+	return ni !== void 0 ? graph.nodes[ni] : void 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 }
+* ```
+*/
+function getRelativeDistanceMap(graph, parentId) {
+	const idx = getIndex(graph);
+	let sourceId = null;
+	if (parentId !== null) {
+		const pi = idx.nodeById.get(parentId);
+		if (pi !== void 0) sourceId = graph.nodes[pi].initialNodeId ?? null;
+	} else sourceId = graph.initialNodeId ?? null;
+	if (!sourceId) return {};
+	const siblingSet = new Set(idx.childNodes.get(parentId) ?? []);
+	if (!siblingSet.has(sourceId)) return {};
+	const dist = /* @__PURE__ */ new Map();
+	dist.set(sourceId, 0);
+	const queue = [sourceId];
+	while (queue.length > 0) {
+		const id = queue.shift();
+		const d = dist.get(id);
+		for (const eid of idx.outEdges.get(id) ?? []) {
+			const ai = idx.edgeById.get(eid);
+			if (ai === void 0) continue;
+			const neighborId = graph.edges[ai].targetId;
+			if (siblingSet.has(neighborId) && !dist.has(neighborId)) {
+				dist.set(neighborId, d + 1);
+				queue.push(neighborId);
+			}
+		}
+		for (const eid of idx.inEdges.get(id) ?? []) {
+			const ai = idx.edgeById.get(eid);
+			if (ai === void 0) continue;
+			const edge = graph.edges[ai];
+			if (getEdgeMode(graph, edge) === "directed") continue;
+			const neighborId = edge.sourceId;
+			if (siblingSet.has(neighborId) && !dist.has(neighborId)) {
+				dist.set(neighborId, d + 1);
+				queue.push(neighborId);
+			}
+		}
+	}
+	const result = {};
+	for (const [id, d] of dist) result[id] = d;
+	return result;
+}
+/**
+* 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
+* ```
+*/
+function getRelativeDistance(graph, nodeId) {
+	const ni = getIndex(graph).nodeById.get(nodeId);
+	if (ni === void 0) return void 0;
+	const node = graph.nodes[ni];
+	return getRelativeDistanceMap(graph, node.parentId ?? null)[nodeId];
+}
+/**
+* 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]
+* ```
+*/
+function getSources(graph) {
+	return graph.nodes.filter((n) => getInDegree(graph, n.id) === 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
+* 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]
+* ```
+*/
+function getSinks(graph) {
+	return graph.nodes.filter((n) => getOutDegree(graph, n.id) === 0);
+}
+/**
+* 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
+* ```
+*/
+function getPort(graph, nodeId, portName) {
+	const ni = getIndex(graph).nodeById.get(nodeId);
+	if (ni === void 0) return void 0;
+	return graph.nodes[ni].ports?.find((p) => p.name === portName);
+}
+/**
+* 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]
+* ```
+*/
+function getPorts(graph, nodeId) {
+	const ni = getIndex(graph).nodeById.get(nodeId);
+	if (ni === void 0) return [];
+	return graph.nodes[ni].ports ?? [];
+}
+/**
+* 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]
+* ```
+*/
+function getEdgesByPort(graph, nodeId, portName) {
+	const idx = getIndex(graph);
+	const result = [];
+	for (const eid of idx.outEdges.get(nodeId) ?? []) {
+		const ai = idx.edgeById.get(eid);
+		if (ai !== void 0 && graph.edges[ai].sourcePort === portName) result.push(graph.edges[ai]);
+	}
+	for (const eid of idx.inEdges.get(nodeId) ?? []) {
+		const ai = idx.edgeById.get(eid);
+		if (ai !== void 0 && graph.edges[ai].targetPort === portName) result.push(graph.edges[ai]);
+	}
+	return result;
+}
+
+//#endregion
+export { indexAddNode as A, getSinks as C, isLeaf as D, isCompound as E, indexUpdateEdgeEndpoints as M, invalidateIndex as N, getIndex as O, touchIndex as P, 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, indexReparentNode as j, indexAddEdge as k, 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 };