@statelyai/graph 0.3.0 → 0.3.1

package/dist/index.d.mts

@@ -1,38 +1,135 @@
-import { C as TraversalOptions, D as VisualNode, E as VisualGraphConfig, S as TransitionOptions, T as VisualGraph, _ as MSTOptions, a as EntitiesConfig, b as PathOptions, c as Graph, d as GraphEdge, f as GraphFormatConverter, g as GraphStep, h as GraphPath, i as EdgeConfig, l as GraphConfig, m as GraphPatch, n as DeleteNodeOptions, o as EntitiesUpdate, p as GraphNode, r as EdgeChange, s as EntityRect, t as AllPairsShortestPathsOptions, u as GraphDiff, v as NodeChange, w as VisualEdge, x as SinglePathOptions, y as NodeConfig } from "./types-B6Tpeerk.mjs";
+import { C as TraversalOptions, D as VisualNode, E as VisualGraphConfig, S as TransitionOptions, T as VisualGraph, _ as MSTOptions, a as EntitiesConfig, b as PathOptions, c as Graph, d as GraphEdge, f as GraphFormatConverter, g as GraphStep, h as GraphPath, i as EdgeConfig, l as GraphConfig, m as GraphPatch, n as DeleteNodeOptions, o as EntitiesUpdate, p as GraphNode, r as EdgeChange, s as EntityRect, t as AllPairsShortestPathsOptions, u as GraphDiff, v as NodeChange, w as VisualEdge, x as SinglePathOptions, y as NodeConfig } from "./types-BDXC1O5b.mjs";
 import { bfs, dfs, genCycles, genPostorders, genPreorders, genShortestPaths, genSimplePaths, getAllPairsShortestPaths, getConnectedComponents, getCycles, getMinimumSpanningTree, getPostorder, getPostorders, getPreorder, getPreorders, getShortestPath, getShortestPaths, getSimplePath, getSimplePaths, getStronglyConnectedComponents, getTopologicalSort, hasPath, isAcyclic, isConnected, isTree, joinPaths } from "./algorithms.mjs";
 import { createFormatConverter } from "./formats/converter/index.mjs";
 import { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf } from "./queries.mjs";
 
 //#region src/graph.d.ts
-/** Create a graph from a config. Resolves defaults for all fields. */
+
+/**
+ * Create a graph from a config. Resolves defaults for all fields.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+ * });
+ * ```
+ */
 declare function createGraph<N = any, E = any, G = any>(config?: GraphConfig<N, E, G>): Graph<N, E, G>;
-/** Create a visual graph with required position/size on all nodes and edges. */
+/**
+ * Create a visual graph with required position/size on all nodes and edges.
+ *
+ * @example
+ * ```ts
+ * const graph = createVisualGraph({
+ *   nodes: [{ id: 'a', x: 0, y: 0, width: 100, height: 50 }],
+ *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'a', x: 0, y: 0, width: 0, height: 0 }],
+ * });
+ * // graph.nodes[0].x === 0
+ * ```
+ */
 declare function createVisualGraph<N = any, E = any, G = any>(config?: VisualGraphConfig<N, E, G>): VisualGraph<N, E, G>;
 /**
  * Create a graph by BFS exploration of a transition function.
- * Each unique state becomes a node; each (state, event) → nextState becomes an edge.
+ * Each unique state becomes a node; each (state, event) -> nextState becomes an edge.
  *
  * - Node IDs are determined by `serializeState` (default: `JSON.stringify`).
  * - Edge IDs use the format `sourceId|serializedEvent|targetId` for uniqueness
  *   and debuggability. Edge labels are just the serialized event string.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraphFromTransition(
+ *   (state, event) => {
+ *     if (state === 'green' && event === 'TIMER') return 'yellow';
+ *     if (state === 'yellow' && event === 'TIMER') return 'red';
+ *     if (state === 'red' && event === 'TIMER') return 'green';
+ *     return state;
+ *   },
+ *   {
+ *     initialState: 'green',
+ *     events: ['TIMER'],
+ *     serializeState: (s) => s,
+ *     serializeEvent: (e) => e,
+ *   },
+ * );
+ * // graph.nodes.length === 3
+ * ```
  */
 declare function createGraphFromTransition<TState, TEvent>(transition: (state: TState, event: TEvent) => TState, options: TransitionOptions<TState, TEvent>): Graph<TState, TEvent>;
-/** Get a node by id, or `undefined` if not found. */
+/**
+ * Get a node by id, or `undefined` if not found.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({ nodes: [{ id: 'a' }] });
+ * const node = getNode(graph, 'a'); // GraphNode
+ * const missing = getNode(graph, 'z'); // undefined
+ * ```
+ */
 declare function getNode<N>(graph: Graph<N>, id: string): GraphNode<N> | undefined;
-/** Get an edge by id, or `undefined` if not found. */
+/**
+ * Get an edge by id, or `undefined` if not found.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+ * });
+ * const edge = getEdge(graph, 'e1'); // GraphEdge
+ * const missing = getEdge(graph, 'z'); // undefined
+ * ```
+ */
 declare function getEdge<E>(graph: Graph<any, E>, id: string): GraphEdge<E> | undefined;
-/** Check if a node exists in the graph. */
+/**
+ * Check if a node exists in the graph.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({ nodes: [{ id: 'a' }] });
+ * hasNode(graph, 'a'); // true
+ * hasNode(graph, 'z'); // false
+ * ```
+ */
 declare function hasNode(graph: Graph, id: string): boolean;
-/** Check if an edge exists in the graph. */
+/**
+ * Check if an edge exists in the graph.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+ * });
+ * hasEdge(graph, 'e1'); // true
+ * hasEdge(graph, 'z'); // false
+ * ```
+ */
 declare function hasEdge(graph: Graph, id: string): boolean;
 /**
  * **Mutable.** Add a node to the graph. Mutates `graph.nodes` in place.
  * @returns The resolved node that was added.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph();
+ * const node = addNode(graph, { id: 'a', label: 'Node A' });
+ * // graph.nodes.length === 1
+ * ```
  */
 declare function addNode<N>(graph: Graph<N>, config: NodeConfig<N>): GraphNode<N>;
 /**
  * **Mutable.** Add an edge to the graph. Mutates `graph.edges` in place.
  * @returns The resolved edge that was added.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({ nodes: [{ id: 'a' }, { id: 'b' }] });
+ * const edge = addEdge(graph, { id: 'e1', sourceId: 'a', targetId: 'b' });
+ * // graph.edges.length === 1
+ * ```
  */
 declare function addEdge<E>(graph: Graph<any, E>, config: EdgeConfig<E>): GraphEdge<E>;
 /**
@@ -41,45 +138,134 @@ declare function addEdge<E>(graph: Graph<any, E>, config: EdgeConfig<E>): GraphE
  *
  * By default, children are deleted recursively.
  * With `{ reparent: true }`, children are re-parented to the deleted node's parent.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+ * });
+ * deleteNode(graph, 'a');
+ * // graph.nodes.length === 1, edge e1 also removed
+ * ```
  */
 declare function deleteNode(graph: Graph, id: string, opts?: DeleteNodeOptions): void;
 /**
  * **Mutable.** Delete an edge. Mutates `graph.edges` in place.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+ * });
+ * deleteEdge(graph, 'e1');
+ * // graph.edges.length === 0
+ * ```
  */
 declare function deleteEdge(graph: Graph, id: string): void;
 /**
  * **Mutable.** Update a node in place.
  * @returns The updated node.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({ nodes: [{ id: 'a', label: 'old' }] });
+ * const updated = updateNode(graph, 'a', { label: 'new' });
+ * // updated.label === 'new'
+ * ```
  */
 declare function updateNode<N>(graph: Graph<N>, id: string, update: Partial<Omit<NodeConfig<N>, 'id'>>): GraphNode<N>;
 /**
  * **Mutable.** Update an edge in place.
  * @returns The updated edge.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b', label: 'old' }],
+ * });
+ * const updated = updateEdge(graph, 'e1', { label: 'new' });
+ * // updated.label === 'new'
+ * ```
  */
 declare function updateEdge<E>(graph: Graph<any, E>, id: string, update: Partial<Omit<EdgeConfig<E>, 'id'>>): GraphEdge<E>;
 /**
  * **Mutable.** Add multiple nodes and edges to the graph.
  * Nodes are added first, then edges (so edges can reference new nodes).
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph();
+ * addEntities(graph, {
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+ * });
+ * // graph.nodes.length === 2, graph.edges.length === 1
+ * ```
  */
 declare function addEntities<N, E>(graph: Graph<N, E>, entities: EntitiesConfig<N, E>): void;
 /**
  * **Mutable.** Delete entities by id(s). Automatically detects whether each id
  * is a node or edge. Node deletions cascade to children and connected edges.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+ * });
+ * deleteEntities(graph, ['a', 'e1']);
+ * // graph.nodes.length === 1, graph.edges.length === 0
+ * ```
  */
 declare function deleteEntities(graph: Graph, ids: string | string[], opts?: DeleteNodeOptions): void;
 /**
  * **Mutable.** Update multiple nodes and edges in place.
  * Each entry must include an `id` to identify which entity to update.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a', label: 'old' }],
+ *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'a', label: 'old' }],
+ * });
+ * updateEntities(graph, {
+ *   nodes: [{ id: 'a', label: 'new' }],
+ *   edges: [{ id: 'e1', label: 'new' }],
+ * });
+ * ```
  */
 declare function updateEntities<N, E>(graph: Graph<N, E>, updates: EntitiesUpdate<N, E>): void;
 /**
  * OOP wrapper around a plain `Graph` object.
  * Delegates to the standalone mutable functions.
+ *
+ * @example
+ * ```ts
+ * const instance = new GraphInstance({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+ * });
+ * instance.addNode({ id: 'c' });
+ * instance.hasNode('c'); // true
+ * instance.toJSON(); // plain Graph object
+ * ```
  */
 declare class GraphInstance<N = any, E = any, G = any> {
   graph: Graph<N, E, G>;
   constructor(config?: GraphConfig<N, E, G>);
-  /** Wrap an existing plain graph object. */
+  /**
+   * Wrap an existing plain graph object.
+   *
+   * @example
+   * ```ts
+   * const graph = createGraph({ nodes: [{ id: 'a' }] });
+   * const instance = GraphInstance.from(graph);
+   * instance.hasNode('a'); // true
+   * ```
+   */
   static from<N = any, E = any, G = any>(graph: Graph<N, E, G>): GraphInstance<N, E, G>;
   get id(): string;
   get type(): "directed" | "undirected";
@@ -103,24 +289,99 @@ declare class GraphInstance<N = any, E = any, G = any> {
 }
 //#endregion
 //#region src/indexing.d.ts
-/** Clear the cached index. Call this if you mutate graph.nodes/edges directly. */
+/**
+ * Clear the cached index. Call this if you mutate graph.nodes/edges directly.
+ *
+ * @example
+ * ```ts
+ * import { createGraph, invalidateIndex, getIndex } from '@statelyai/graph';
+ *
+ * const graph = createGraph({ nodes: [{ id: 'a' }], edges: [] });
+ * // manually mutate nodes array
+ * graph.nodes.push({ type: 'node', id: 'b', parentId: null, initialNodeId: null, label: '', data: undefined });
+ * invalidateIndex(graph); // forces rebuild on next getIndex()
+ * ```
+ */
 declare function invalidateIndex(graph: Graph): void;
 //#endregion
 //#region src/diff.d.ts
-/** Compute a structured diff from graph `a` to graph `b` by matching IDs. */
+/**
+ * Compute a structured diff from graph `a` to graph `b` by matching IDs.
+ *
+ * @example
+ * ```ts
+ * import { createGraph, getDiff } from '@statelyai/graph';
+ *
+ * const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+ * const b = createGraph({ nodes: [{ id: 'n1', label: 'hello' }, { id: 'n2' }], edges: [] });
+ *
+ * const diff = getDiff(a, b);
+ * // diff.nodes.added → [{ id: 'n2' }]
+ * // diff.nodes.updated → [{ id: 'n1', old: { label: '' }, new: { label: 'hello' } }]
+ * ```
+ */
 declare function getDiff<N, E>(a: Graph<N, E>, b: Graph<N, E>): GraphDiff<N, E>;
-/** Check if a diff has zero changes. */
+/**
+ * Check if a diff has zero changes.
+ *
+ * @example
+ * ```ts
+ * import { createGraph, getDiff, isEmptyDiff } from '@statelyai/graph';
+ *
+ * const g = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+ * const diff = getDiff(g, g);
+ * isEmptyDiff(diff); // true
+ * ```
+ */
 declare function isEmptyDiff(diff: GraphDiff): boolean;
-/** Invert a diff: swap added↔removed, swap old↔new in updates. */
+/**
+ * Invert a diff: swap added/removed, swap old/new in updates.
+ *
+ * @example
+ * ```ts
+ * import { createGraph, getDiff, invertDiff } from '@statelyai/graph';
+ *
+ * const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+ * const b = createGraph({ nodes: [{ id: 'n2' }], edges: [] });
+ *
+ * const diff = getDiff(a, b);
+ * const inv = invertDiff(diff);
+ * // inv.nodes.added contains n1 (was removed)
+ * // inv.nodes.removed contains n2 (was added)
+ * ```
+ */
 declare function invertDiff<N, E>(diff: GraphDiff<N, E>): GraphDiff<N, E>;
 /**
  * Compute an ordered patch list from graph `a` to graph `b`.
  * Order: delete edges → delete nodes → add nodes → add edges → update nodes → update edges.
+ *
+ * @example
+ * ```ts
+ * import { createGraph, getPatches } from '@statelyai/graph';
+ *
+ * const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+ * const b = createGraph({ nodes: [{ id: 'n1' }, { id: 'n2' }], edges: [] });
+ *
+ * const patches = getPatches(a, b);
+ * // patches → [{ op: 'addNode', node: { id: 'n2' } }]
+ * ```
  */
 declare function getPatches<N, E>(a: Graph<N, E>, b: Graph<N, E>): GraphPatch<N, E>[];
 /**
  * **Mutable.** Apply patches to a graph in order.
  * Delegates to addNode/deleteNode/updateNode/addEdge/deleteEdge/updateEdge.
+ *
+ * @example
+ * ```ts
+ * import { createGraph, getPatches, applyPatches } from '@statelyai/graph';
+ *
+ * const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+ * const b = createGraph({ nodes: [{ id: 'n1' }, { id: 'n2' }], edges: [] });
+ *
+ * const patches = getPatches(a, b);
+ * applyPatches(a, patches);
+ * // a now contains both n1 and n2
+ * ```
  */
 declare function applyPatches<N, E>(graph: Graph<N, E>, patches: GraphPatch<N, E>[]): void;
 /**
@@ -128,9 +389,35 @@ declare function applyPatches<N, E>(graph: Graph<N, E>, patches: GraphPatch<N, E
  * Order: add nodes → update edges → delete edges → delete nodes → add edges → update nodes.
  * This avoids cascading deletes removing edges that are being updated,
  * and ensures new nodes exist before edges reference them.
+ *
+ * @example
+ * ```ts
+ * import { createGraph, getDiff, toPatches } from '@statelyai/graph';
+ *
+ * const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+ * const b = createGraph({ nodes: [{ id: 'n2' }], edges: [] });
+ *
+ * const diff = getDiff(a, b);
+ * const patches = toPatches(diff);
+ * // patches → [{ op: 'addNode', ... }, { op: 'deleteNode', ... }]
+ * ```
  */
 declare function toPatches<N, E>(diff: GraphDiff<N, E>): GraphPatch<N, E>[];
-/** Group a patch list into a structured diff. */
+/**
+ * Group a patch list into a structured diff.
+ *
+ * @example
+ * ```ts
+ * import { createGraph, getPatches, toDiff } from '@statelyai/graph';
+ *
+ * const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+ * const b = createGraph({ nodes: [{ id: 'n1' }, { id: 'n2' }], edges: [] });
+ *
+ * const patches = getPatches(a, b);
+ * const diff = toDiff(patches);
+ * // diff.nodes.added → [{ id: 'n2' }]
+ * ```
+ */
 declare function toDiff<N, E>(patches: GraphPatch<N, E>[]): GraphDiff<N, E>;
 //#endregion
 //#region src/transforms.d.ts
@@ -141,6 +428,25 @@ declare function toDiff<N, E>(patches: GraphPatch<N, E>[]): GraphDiff<N, E>;
  * - Edges originating from a compound node expand to all leaf descendants.
  * - Only leaf nodes (nodes with no children) appear in the result.
  * - Duplicate edges (same source + target) are deduplicated.
+ *
+ * @example
+ * ```ts
+ * import { createGraph, flatten } from '@statelyai/graph';
+ *
+ * const graph = createGraph({
+ *   nodes: [
+ *     { id: 'parent', initialNodeId: 'child1' },
+ *     { id: 'child1', parentId: 'parent' },
+ *     { id: 'child2', parentId: 'parent' },
+ *     { id: 'other' },
+ *   ],
+ *   edges: [{ id: 'e1', sourceId: 'other', targetId: 'parent' }],
+ * });
+ *
+ * const flat = flatten(graph);
+ * // flat.nodes → [child1, child2, other] (leaf nodes only)
+ * // flat.edges → edge from 'other' → 'child1' (resolved via initialNodeId)
+ * ```
  */
 declare function flatten<N, E, G>(graph: Graph<N, E, G>): Graph<N, E, G>;
 //#endregion

package/dist/index.mjs

@@ -1,7 +1,7 @@
-import { o as invalidateIndex, t as getIndex } from "./indexing-BFFVMnjF.mjs";
-import { A as addNode, B as hasNode, C as isAcyclic, D as GraphInstance, E as joinPaths, F as deleteEntities, H as updateEntities, I as deleteNode, L as getEdge, M as createGraphFromTransition, N as createVisualGraph, O as addEdge, P as deleteEdge, R as getNode, S as hasPath, T as isTree, U as updateNode, V as updateEdge, _ as getShortestPaths, a as genPreorders, b as getStronglyConnectedComponents, c as getAllPairsShortestPaths, d as getMinimumSpanningTree, f as getPostorder, g as getShortestPath, h as getPreorders, i as genPostorders, j as createGraph, k as addEntities, l as getConnectedComponents, m as getPreorder, n as dfs, o as genShortestPaths, p as getPostorders, r as genCycles, s as genSimplePaths, t as bfs, u as getCycles, v as getSimplePath, w as isConnected, x as getTopologicalSort, y as getSimplePaths, z as hasEdge } from "./algorithms-DBU7nmIV.mjs";
+import { o as invalidateIndex, t as getIndex } from "./indexing-eNDrXdDA.mjs";
+import { A as addNode, B as hasNode, C as isAcyclic, D as GraphInstance, E as joinPaths, F as deleteEntities, H as updateEntities, I as deleteNode, L as getEdge, M as createGraphFromTransition, N as createVisualGraph, O as addEdge, P as deleteEdge, R as getNode, S as hasPath, T as isTree, U as updateNode, V as updateEdge, _ as getShortestPaths, a as genPreorders, b as getStronglyConnectedComponents, c as getAllPairsShortestPaths, d as getMinimumSpanningTree, f as getPostorder, g as getShortestPath, h as getPreorders, i as genPostorders, j as createGraph, k as addEntities, l as getConnectedComponents, m as getPreorder, n as dfs, o as genShortestPaths, p as getPostorders, r as genCycles, s as genSimplePaths, t as bfs, u as getCycles, v as getSimplePath, w as isConnected, x as getTopologicalSort, y as getSimplePaths, z as hasEdge } from "./algorithms-NWSB2RWj.mjs";
 import { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf } from "./queries.mjs";
-import { n as createFormatConverter } from "./converter-DnbeyE_p.mjs";
+import { n as createFormatConverter } from "./converter-CchokMDg.mjs";
 
 //#region src/diff.ts
 function nodeToConfig(node) {
@@ -67,7 +67,21 @@ const EDGE_COMPARE_KEYS = [
 	"color",
 	"style"
 ];
-/** Compute a structured diff from graph `a` to graph `b` by matching IDs. */
+/**
+* Compute a structured diff from graph `a` to graph `b` by matching IDs.
+*
+* @example
+* ```ts
+* import { createGraph, getDiff } from '@statelyai/graph';
+*
+* const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+* const b = createGraph({ nodes: [{ id: 'n1', label: 'hello' }, { id: 'n2' }], edges: [] });
+*
+* const diff = getDiff(a, b);
+* // diff.nodes.added → [{ id: 'n2' }]
+* // diff.nodes.updated → [{ id: 'n1', old: { label: '' }, new: { label: 'hello' } }]
+* ```
+*/
 function getDiff(a, b) {
 	const aNodeMap = new Map(a.nodes.map((n) => [n.id, n]));
 	const bNodeMap = new Map(b.nodes.map((n) => [n.id, n]));
@@ -123,11 +137,37 @@ function getDiff(a, b) {
 	for (const [id, edgeA] of aEdgeMap) if (!bEdgeMap.has(id)) diff.edges.removed.push(edgeToConfig(edgeA));
 	return diff;
 }
-/** Check if a diff has zero changes. */
+/**
+* Check if a diff has zero changes.
+*
+* @example
+* ```ts
+* import { createGraph, getDiff, isEmptyDiff } from '@statelyai/graph';
+*
+* const g = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+* const diff = getDiff(g, g);
+* isEmptyDiff(diff); // true
+* ```
+*/
 function isEmptyDiff(diff) {
 	return diff.nodes.added.length === 0 && diff.nodes.removed.length === 0 && diff.nodes.updated.length === 0 && diff.edges.added.length === 0 && diff.edges.removed.length === 0 && diff.edges.updated.length === 0;
 }
-/** Invert a diff: swap added↔removed, swap old↔new in updates. */
+/**
+* Invert a diff: swap added/removed, swap old/new in updates.
+*
+* @example
+* ```ts
+* import { createGraph, getDiff, invertDiff } from '@statelyai/graph';
+*
+* const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+* const b = createGraph({ nodes: [{ id: 'n2' }], edges: [] });
+*
+* const diff = getDiff(a, b);
+* const inv = invertDiff(diff);
+* // inv.nodes.added contains n1 (was removed)
+* // inv.nodes.removed contains n2 (was added)
+* ```
+*/
 function invertDiff(diff) {
 	return {
 		nodes: {
@@ -153,6 +193,17 @@ function invertDiff(diff) {
 /**
 * Compute an ordered patch list from graph `a` to graph `b`.
 * Order: delete edges → delete nodes → add nodes → add edges → update nodes → update edges.
+*
+* @example
+* ```ts
+* import { createGraph, getPatches } from '@statelyai/graph';
+*
+* const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+* const b = createGraph({ nodes: [{ id: 'n1' }, { id: 'n2' }], edges: [] });
+*
+* const patches = getPatches(a, b);
+* // patches → [{ op: 'addNode', node: { id: 'n2' } }]
+* ```
 */
 function getPatches(a, b) {
 	return toPatches(getDiff(a, b));
@@ -160,6 +211,18 @@ function getPatches(a, b) {
 /**
 * **Mutable.** Apply patches to a graph in order.
 * Delegates to addNode/deleteNode/updateNode/addEdge/deleteEdge/updateEdge.
+*
+* @example
+* ```ts
+* import { createGraph, getPatches, applyPatches } from '@statelyai/graph';
+*
+* const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+* const b = createGraph({ nodes: [{ id: 'n1' }, { id: 'n2' }], edges: [] });
+*
+* const patches = getPatches(a, b);
+* applyPatches(a, patches);
+* // a now contains both n1 and n2
+* ```
 */
 function applyPatches(graph, patches) {
 	for (const patch of patches) switch (patch.op) {
@@ -188,6 +251,18 @@ function applyPatches(graph, patches) {
 * Order: add nodes → update edges → delete edges → delete nodes → add edges → update nodes.
 * This avoids cascading deletes removing edges that are being updated,
 * and ensures new nodes exist before edges reference them.
+*
+* @example
+* ```ts
+* import { createGraph, getDiff, toPatches } from '@statelyai/graph';
+*
+* const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+* const b = createGraph({ nodes: [{ id: 'n2' }], edges: [] });
+*
+* const diff = getDiff(a, b);
+* const patches = toPatches(diff);
+* // patches → [{ op: 'addNode', ... }, { op: 'deleteNode', ... }]
+* ```
 */
 function toPatches(diff) {
 	const patches = [];
@@ -227,7 +302,21 @@ function toPatches(diff) {
 	}
 	return patches;
 }
-/** Group a patch list into a structured diff. */
+/**
+* Group a patch list into a structured diff.
+*
+* @example
+* ```ts
+* import { createGraph, getPatches, toDiff } from '@statelyai/graph';
+*
+* const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
+* const b = createGraph({ nodes: [{ id: 'n1' }, { id: 'n2' }], edges: [] });
+*
+* const patches = getPatches(a, b);
+* const diff = toDiff(patches);
+* // diff.nodes.added → [{ id: 'n2' }]
+* ```
+*/
 function toDiff(patches) {
 	const diff = {
 		nodes: {
@@ -287,6 +376,25 @@ function toDiff(patches) {
 * - Edges originating from a compound node expand to all leaf descendants.
 * - Only leaf nodes (nodes with no children) appear in the result.
 * - Duplicate edges (same source + target) are deduplicated.
+*
+* @example
+* ```ts
+* import { createGraph, flatten } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [
+*     { id: 'parent', initialNodeId: 'child1' },
+*     { id: 'child1', parentId: 'parent' },
+*     { id: 'child2', parentId: 'parent' },
+*     { id: 'other' },
+*   ],
+*   edges: [{ id: 'e1', sourceId: 'other', targetId: 'parent' }],
+* });
+*
+* const flat = flatten(graph);
+* // flat.nodes → [child1, child2, other] (leaf nodes only)
+* // flat.edges → edge from 'other' → 'child1' (resolved via initialNodeId)
+* ```
 */
 function flatten(graph) {
 	const idx = getIndex(graph);

package/dist/{indexing-BFFVMnjF.mjs → indexing-eNDrXdDA.mjs}

@@ -1,6 +1,23 @@
 //#region src/indexing.ts
 const indexes = /* @__PURE__ */ new WeakMap();
-/** Get or lazily build the index for a graph. */
+/**
+* Get or lazily build the index for a graph.
+* Auto-rebuilds when node/edge count changes.
+*
+* @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.nodeCount !== graph.nodes.length || idx.edgeCount !== graph.edges.length) {
@@ -9,7 +26,19 @@ function getIndex(graph) {
 	}
 	return idx;
 }
-/** Clear the cached index. Call this if you mutate graph.nodes/edges directly. */
+/**
+* Clear the cached index. Call this if you mutate graph.nodes/edges directly.
+*
+* @example
+* ```ts
+* import { createGraph, invalidateIndex, getIndex } from '@statelyai/graph';
+*
+* const graph = createGraph({ nodes: [{ id: 'a' }], edges: [] });
+* // manually mutate nodes array
+* graph.nodes.push({ type: 'node', id: 'b', parentId: null, initialNodeId: null, label: '', data: undefined });
+* invalidateIndex(graph); // forces rebuild on next getIndex()
+* ```
+*/
 function invalidateIndex(graph) {
 	indexes.delete(graph);
 }