@statelyai/graph 0.1.0 → 0.3.1

package/dist/formats/tgf/index.d.mts

@@ -0,0 +1,54 @@
+import { c as Graph, f as GraphFormatConverter } from "../../types-BDXC1O5b.mjs";
+
+//#region src/formats/tgf/index.d.ts
+
+/**
+ * Converts a graph to TGF (Trivial Graph Format) string.
+ *
+ * @example
+ * ```ts
+ * import { createGraph } from '@statelyai/graph';
+ * import { toTGF } from '@statelyai/graph/formats/tgf';
+ *
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }],
+ *   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b', label: 'go' }],
+ * });
+ *
+ * const tgf = toTGF(graph);
+ * // "a A\nb B\n#\na b go"
+ * ```
+ */
+declare function toTGF(graph: Graph): string;
+/**
+ * Parses a TGF (Trivial Graph Format) string into a graph.
+ *
+ * @example
+ * ```ts
+ * import { fromTGF } from '@statelyai/graph/formats/tgf';
+ *
+ * const graph = fromTGF('a A\nb B\n#\na b go');
+ * // graph.nodes = [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }]
+ * ```
+ */
+declare function fromTGF(tgf: string): Graph;
+/**
+ * Bidirectional converter for TGF (Trivial Graph Format).
+ *
+ * @example
+ * ```ts
+ * import { createGraph } from '@statelyai/graph';
+ * import { tgfConverter } from '@statelyai/graph/formats/tgf';
+ *
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b' }],
+ * });
+ *
+ * const tgf = tgfConverter.to(graph);
+ * const roundTripped = tgfConverter.from(tgf);
+ * ```
+ */
+declare const tgfConverter: GraphFormatConverter<string>;
+//#endregion
+export { fromTGF, tgfConverter, toTGF };

package/dist/formats/tgf/index.mjs

@@ -0,0 +1,111 @@
+import { n as createFormatConverter } from "../../converter-CchokMDg.mjs";
+
+//#region src/formats/tgf/index.ts
+/**
+* Converts a graph to TGF (Trivial Graph Format) string.
+*
+* @example
+* ```ts
+* import { createGraph } from '@statelyai/graph';
+* import { toTGF } from '@statelyai/graph/formats/tgf';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }],
+*   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b', label: 'go' }],
+* });
+*
+* const tgf = toTGF(graph);
+* // "a A\nb B\n#\na b go"
+* ```
+*/
+function toTGF(graph) {
+	const lines = [];
+	for (const node of graph.nodes) lines.push(node.label ? `${node.id} ${node.label}` : node.id);
+	lines.push("#");
+	for (const edge of graph.edges) {
+		const parts = [edge.sourceId, edge.targetId];
+		if (edge.label) parts.push(edge.label);
+		lines.push(parts.join(" "));
+	}
+	return lines.join("\n");
+}
+/**
+* Parses a TGF (Trivial Graph Format) string into a graph.
+*
+* @example
+* ```ts
+* import { fromTGF } from '@statelyai/graph/formats/tgf';
+*
+* const graph = fromTGF('a A\nb B\n#\na b go');
+* // graph.nodes = [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }]
+* ```
+*/
+function fromTGF(tgf) {
+	if (typeof tgf !== "string") throw new Error("TGF: expected a string");
+	const lines = tgf.split("\n");
+	const sepIdx = lines.indexOf("#");
+	const nodeLines = sepIdx >= 0 ? lines.slice(0, sepIdx) : lines;
+	const edgeLines = sepIdx >= 0 ? lines.slice(sepIdx + 1) : [];
+	const nodes = [];
+	for (const line of nodeLines) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		const spaceIdx = trimmed.indexOf(" ");
+		const id = spaceIdx >= 0 ? trimmed.slice(0, spaceIdx) : trimmed;
+		const label = spaceIdx >= 0 ? trimmed.slice(spaceIdx + 1) : "";
+		nodes.push({
+			type: "node",
+			id,
+			parentId: null,
+			initialNodeId: null,
+			label,
+			data: void 0
+		});
+	}
+	const edges = [];
+	for (const line of edgeLines) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		const parts = trimmed.split(" ");
+		const sourceId = parts[0];
+		const targetId = parts[1];
+		const label = parts.slice(2).join(" ");
+		edges.push({
+			type: "edge",
+			id: `e${edges.length}`,
+			sourceId,
+			targetId,
+			label,
+			data: void 0
+		});
+	}
+	return {
+		id: "",
+		type: "directed",
+		initialNodeId: null,
+		nodes,
+		edges,
+		data: void 0
+	};
+}
+/**
+* Bidirectional converter for TGF (Trivial Graph Format).
+*
+* @example
+* ```ts
+* import { createGraph } from '@statelyai/graph';
+* import { tgfConverter } from '@statelyai/graph/formats/tgf';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b' }],
+* });
+*
+* const tgf = tgfConverter.to(graph);
+* const roundTripped = tgfConverter.from(tgf);
+* ```
+*/
+const tgfConverter = createFormatConverter(toTGF, fromTGF);
+
+//#endregion
+export { fromTGF, tgfConverter, toTGF };

package/dist/index.d.mts

@@ -1,33 +1,135 @@
-import { C as VisualGraph, S as VisualEdge, T as VisualNode, _ as NodeChange, a as EntitiesConfig, b as SinglePathOptions, c as Graph, d as GraphEdge, f as GraphNode, g as MSTOptions, h as GraphStep, i as EdgeConfig, l as GraphConfig, m as GraphPath, n as DeleteNodeOptions, o as EntitiesUpdate, p as GraphPatch, r as EdgeChange, s as EntityRect, t as AllPairsShortestPathsOptions, u as GraphDiff, v as NodeConfig, w as VisualGraphConfig, x as TraversalOptions, y as PathOptions } from "./types-XV3S5Jnh.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 } from "./algorithms.mjs";
-import { n as toAdjacencyList, t as fromAdjacencyList } from "./adjacency-list-DW-lAUe8.mjs";
-import { t as toDOT } from "./dot-HmJeUMsj.mjs";
-import { n as toEdgeList, t as fromEdgeList } from "./edge-list-CJmfoNu2.mjs";
-import { n as toGraphML, t as fromGraphML } from "./graphml-CMjPzSfY.mjs";
-import { EdgeSchema, GraphSchema, NodeSchema } from "./schemas.mjs";
-import { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPredecessors, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf } from "./queries.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>;
-/** Get a node by id, or `undefined` if not found. */
+/**
+ * Create a graph by BFS exploration of a transition function.
+ * 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.
+ *
+ * @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>;
 /**
@@ -36,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";
@@ -98,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;
 /**
@@ -123,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
@@ -136,7 +428,26 @@ 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
-export { type AllPairsShortestPathsOptions, type DeleteNodeOptions, type EdgeChange, type EdgeConfig, EdgeSchema, type EntitiesConfig, type EntitiesUpdate, type Graph, type GraphConfig, type GraphDiff, type GraphEdge, GraphInstance, type GraphNode, type GraphPatch, type GraphPath, GraphSchema, type GraphStep, type MSTOptions, type NodeChange, type NodeConfig, NodeSchema, type PathOptions, type EntityRect as Positioned, type SinglePathOptions, type TraversalOptions, type VisualEdge, type VisualGraph, type VisualGraphConfig, type VisualNode, addEdge, addEntities, addNode, applyPatches, bfs, createGraph, createVisualGraph, deleteEdge, deleteEntities, deleteNode, dfs, flatten, fromAdjacencyList, fromEdgeList, fromGraphML, genCycles, genPostorders, genPreorders, genShortestPaths, genSimplePaths, getAllPairsShortestPaths, getAncestors, getChildren, getConnectedComponents, getCycles, getDegree, getDepth, getDescendants, getDiff, getEdge, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getMinimumSpanningTree, getNeighbors, getNode, getOutDegree, getOutEdges, getParent, getPatches, getPostorder, getPostorders, getPredecessors, getPreorder, getPreorders, getRoots, getShortestPath, getShortestPaths, getSiblings, getSimplePath, getSimplePaths, getSinks, getSources, getStronglyConnectedComponents, getSuccessors, getTopologicalSort, hasEdge, hasNode, hasPath, invalidateIndex, invertDiff, isAcyclic, isCompound, isConnected, isEmptyDiff, isLeaf, isTree, toAdjacencyList, toDOT, toDiff, toEdgeList, toGraphML, toPatches, updateEdge, updateEntities, updateNode };
+export { type AllPairsShortestPathsOptions, type DeleteNodeOptions, type EdgeChange, type EdgeConfig, type EntitiesConfig, type EntitiesUpdate, type Graph, type GraphConfig, type GraphDiff, type GraphEdge, type GraphFormatConverter, GraphInstance, type GraphNode, type GraphPatch, type GraphPath, type GraphStep, type MSTOptions, type NodeChange, type NodeConfig, type PathOptions, type EntityRect as Positioned, type SinglePathOptions, type TransitionOptions, type TraversalOptions, type VisualEdge, type VisualGraph, type VisualGraphConfig, type VisualNode, addEdge, addEntities, addNode, applyPatches, bfs, createFormatConverter, createGraph, createGraphFromTransition, createVisualGraph, deleteEdge, deleteEntities, deleteNode, dfs, flatten, genCycles, genPostorders, genPreorders, genShortestPaths, genSimplePaths, getAllPairsShortestPaths, getAncestors, getChildren, getConnectedComponents, getCycles, getDegree, getDepth, getDescendants, getDiff, getEdge, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getMinimumSpanningTree, getNeighbors, getNode, getOutDegree, getOutEdges, getParent, getPatches, getPostorder, getPostorders, getPredecessors, getPreorder, getPreorders, getRelativeDistance, getRelativeDistanceMap, getRoots, getShortestPath, getShortestPaths, getSiblings, getSimplePath, getSimplePaths, getSinks, getSources, getStronglyConnectedComponents, getSuccessors, getTopologicalSort, hasEdge, hasNode, hasPath, invalidateIndex, invertDiff, isAcyclic, isCompound, isConnected, isEmptyDiff, isLeaf, isTree, joinPaths, toDiff, toPatches, updateEdge, updateEntities, updateNode };