@statelyai/graph 0.3.0 → 0.3.1

package/dist/queries.mjs

@@ -1,6 +1,22 @@
-import { t as getIndex } from "./indexing-BFFVMnjF.mjs";
+import { t as getIndex } from "./indexing-eNDrXdDA.mjs";
 
 //#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) ?? [];
@@ -18,14 +34,60 @@ function getEdgesOf(graph, nodeId) {
 	}
 	return result;
 }
+/**
+* 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');
+* // => []
+* ```
+*/
 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.
+*
+* @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 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)
+* ```
+*/
 function getEdgeBetween(graph, sourceId, targetId) {
 	const idx = getIndex(graph);
 	const outIds = idx.outEdges.get(sourceId) ?? [];
@@ -43,6 +105,22 @@ function getEdgeBetween(graph, sourceId, targetId) {
 		}
 	}
 }
+/**
+* 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]
+* ```
+*/
 function getSuccessors(graph, nodeId) {
 	const idx = getIndex(graph);
 	const edgeIds = idx.outEdges.get(nodeId) ?? [];
@@ -58,6 +136,22 @@ function getSuccessors(graph, nodeId) {
 	}
 	return result;
 }
+/**
+* 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]
+* ```
+*/
 function getPredecessors(graph, nodeId) {
 	const idx = getIndex(graph);
 	const edgeIds = idx.inEdges.get(nodeId) ?? [];
@@ -73,6 +167,22 @@ function getPredecessors(graph, nodeId) {
 	}
 	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();
@@ -80,6 +190,23 @@ function getNeighbors(graph, nodeId) {
 	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 (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
+* ```
+*/
 function getDegree(graph, nodeId) {
 	const idx = getIndex(graph);
 	if (graph.type === "undirected") {
@@ -89,16 +216,78 @@ function getDegree(graph, nodeId) {
 	}
 	return (idx.inEdges.get(nodeId)?.length ?? 0) + (idx.outEdges.get(nodeId)?.length ?? 0);
 }
+/**
+* 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
+* ```
+*/
 function getInDegree(graph, nodeId) {
 	return getIndex(graph).inEdges.get(nodeId)?.length ?? 0;
 }
+/**
+* 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
+* ```
+*/
 function getOutDegree(graph, nodeId) {
 	return getIndex(graph).outEdges.get(nodeId)?.length ?? 0;
 }
+/**
+* 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);
@@ -108,6 +297,22 @@ function getParent(graph, nodeId) {
 	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).
+*
+* @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 = [];
@@ -123,6 +328,22 @@ function getAncestors(graph, nodeId) {
 	}
 	return result;
 }
+/**
+* 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]
+* ```
+*/
 function getDescendants(graph, nodeId) {
 	const idx = getIndex(graph);
 	const result = [];
@@ -139,19 +360,80 @@ function getDescendants(graph, nodeId) {
 	collect(nodeId);
 	return result;
 }
+/**
+* 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]
+* ```
+*/
 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). */
+/**
+* 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). */
+/**
+* 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). */
+/**
+* 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
+* ```
+*/
 function getDepth(graph, nodeId) {
 	const idx = getIndex(graph);
 	let d = 0;
@@ -166,7 +448,23 @@ function getDepth(graph, nodeId) {
 	}
 	return d;
 }
-/** 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]
+* ```
+*/
 function getSiblings(graph, nodeId) {
 	const idx = getIndex(graph);
 	const ni = idx.nodeById.get(nodeId);
@@ -175,8 +473,24 @@ function getSiblings(graph, nodeId) {
 	return (idx.childNodes.get(node.parentId) ?? []).filter((id) => id !== nodeId).map((id) => graph.nodes[idx.nodeById.get(id)]).filter(Boolean);
 }
 /**
-* 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
+* ```
 */
 function getLCA(graph, ...nodeIds) {
 	if (nodeIds.length === 0) return void 0;
@@ -325,12 +639,42 @@ function getRelativeDistance(graph, nodeId) {
 	const node = graph.nodes[ni];
 	return getRelativeDistanceMap(graph, node.parentId)[nodeId];
 }
-/** 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]
+* ```
+*/
 function getSources(graph) {
 	const idx = getIndex(graph);
 	return graph.nodes.filter((n) => (idx.inEdges.get(n.id)?.length ?? 0) === 0);
 }
-/** 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]
+* ```
+*/
 function getSinks(graph) {
 	const idx = getIndex(graph);
 	return graph.nodes.filter((n) => (idx.outEdges.get(n.id)?.length ?? 0) === 0);

package/dist/{types-B6Tpeerk.d.mts → types-BDXC1O5b.d.mts}

@@ -94,7 +94,7 @@ interface GraphEdge<TEdgeData = any> {
   style?: Record<string, string | number>;
 }
 interface VisualNode<TNodeData = any> extends Omit<GraphNode<TNodeData>, keyof EntityRect>, EntityRect {
-  shape: string;
+  shape?: string;
 }
 interface VisualEdge<TEdgeData = any> extends Omit<GraphEdge<TEdgeData>, keyof EntityRect>, EntityRect {}
 interface VisualGraph<TNodeData = any, TEdgeData = any, TGraphData = any> extends Omit<Graph<TNodeData, TEdgeData, TGraphData>, 'nodes' | 'edges'> {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@statelyai/graph",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "A TypeScript-first graph library with plain JSON-serializable objects",
   "author": "David Khourshid <david@stately.ai>",
   "license": "MIT",

package/dist/converter-DnbeyE_p.mjs

@@ -1,33 +0,0 @@
-import { n as toAdjacencyList, t as fromAdjacencyList } from "./adjacency-list-A4_Eiwj3.mjs";
-import { n as toEdgeList, t as fromEdgeList } from "./edge-list-DuHMz8hf.mjs";
-
-//#region src/formats/converter/index.ts
-/**
-* Create a `GraphFormatConverter` from a pair of `to`/`from` functions.
-*
-* @example
-* ```ts
-* import { createFormatConverter } from '@statelyai/graph';
-*
-* const yamlConverter = createFormatConverter(
-*   (graph) => toYAML(graph),
-*   (yaml) => fromYAML(yaml),
-* );
-*
-* const yaml = yamlConverter.to(graph);
-* const graph = yamlConverter.from(yaml);
-* ```
-*/
-function createFormatConverter(to, from) {
-	return {
-		to,
-		from
-	};
-}
-/** Bidirectional converter for adjacency-list format (`Record<string, string[]>`). */
-const adjacencyListConverter = createFormatConverter(toAdjacencyList, fromAdjacencyList);
-/** Bidirectional converter for edge-list format (`[source, target][]`). */
-const edgeListConverter = createFormatConverter(toEdgeList, fromEdgeList);
-
-//#endregion
-export { createFormatConverter as n, edgeListConverter as r, adjacencyListConverter as t };