@statelyai/graph 0.13.0 → 2.0.0

package/dist/index-DWmo1mIp.d.mts

@@ -0,0 +1,697 @@
+import { E as NodeUpdate, F as VisualGraphConfig, H as WeightedWalkOptions, O as PortConfig, P as VisualGraph, S as GraphStep, T as NodeConfig, V as WalkOptions, _ as GraphMode, c as EntitiesConfig, d as Graph, f as GraphConfig, i as DeleteNodeOptions, j as TransitionOptions, l as EntitiesUpdate, m as GraphEdge, o as EdgeConfig, p as GraphDiff, r as CoverageStats, s as EdgeUpdate, v as GraphNode, x as GraphPort, y as GraphPatch } from "./types-DNYdIU21.mjs";
+
+//#region src/graph.d.ts
+
+/**
+ * Create a resolved graph port from a config. Fills in defaults.
+ *
+ * @example
+ * ```ts
+ * const port = createGraphPort({ name: 'output', direction: 'out' });
+ * // { name: 'output', direction: 'out', data: null }
+ * ```
+ */
+declare function createGraphPort<P = any>(config: PortConfig<P>): GraphPort<P>;
+/**
+ * Create a resolved graph node from a config. Fills in defaults.
+ *
+ * @example
+ * ```ts
+ * const node = createGraphNode({ id: 'a', data: { label: 'hi' } });
+ * // { type: 'node', id: 'a', label: '', data: { label: 'hi' } }
+ * ```
+ */
+declare function createGraphNode<N = any, P = any>(config: NodeConfig<N, P>): GraphNode<N, P>;
+/**
+ * Create a resolved graph edge from a config. Fills in defaults.
+ *
+ * @example
+ * ```ts
+ * const edge = createGraphEdge({ id: 'e1', sourceId: 'a', targetId: 'b' });
+ * // { type: 'edge', id: 'e1', sourceId: 'a', targetId: 'b', label: null, data: null }
+ * ```
+ */
+declare function createGraphEdge<T = any>(config: EdgeConfig<T>): GraphEdge<T>;
+/**
+ * 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, P = any>(config?: GraphConfig<N, E, G, P>): Graph<N, E, G, P>;
+/**
+ * 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, P = any>(config?: VisualGraphConfig<N, E, G, P>): VisualGraph<N, E, G, P>;
+/**
+ * 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.
+ *
+ * @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<N, E>(graph: Graph<N, E>, id: string): GraphEdge<E> | undefined;
+/**
+ * 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.
+ *
+ * @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, P = any>(graph: Graph<N, any, any, P>, config: NodeConfig<N, P>): GraphNode<N, P>;
+/**
+ * **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<N, E>(graph: Graph<N, E>, config: EdgeConfig<E>): GraphEdge<E>;
+/**
+ * **Mutable.** Delete a node and its connected edges. Mutates `graph.nodes`
+ * and `graph.edges` in place.
+ *
+ * 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.
+ * Optional fields (`x`, `y`, `width`, `height`, `shape`, `color`, `style`,
+ * `ports`) accept `null` to unset; `undefined` leaves them unchanged.
+ * @returns The updated node.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({ nodes: [{ id: 'a', label: 'old' }] });
+ * const updated = updateNode(graph, 'a', { label: 'new', x: 100 });
+ * // updated.label === 'new', updated.x === 100
+ * ```
+ */
+declare function updateNode<N, P = any>(graph: Graph<N, any, any, P>, id: string, update: NodeUpdate<N, P>): GraphNode<N, P>;
+/**
+ * **Mutable.** Update an edge in place.
+ * Optional fields (`weight`, `mode`, `sourcePort`, `targetPort`, `x`, `y`,
+ * `width`, `height`, `color`, `style`) accept `null` to unset; `undefined`
+ * leaves them unchanged.
+ * @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', weight: 2 });
+ * // updated.label === 'new', updated.weight === 2
+ * ```
+ */
+declare function updateEdge<N, E>(graph: Graph<N, E>, id: string, update: EdgeUpdate<E>): 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, P = any> {
+  graph: Graph<N, E, G, P>;
+  constructor(config?: GraphConfig<N, E, G, P>);
+  /**
+   * 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, P = any>(graph: Graph<N, E, G, P>): GraphInstance<N, E, G, P>;
+  get id(): string;
+  /** Default directedness for all edges. */
+  get mode(): GraphMode;
+  get nodes(): GraphNode<N, P>[];
+  get edges(): GraphEdge<E>[];
+  get data(): G;
+  getNode(id: string): GraphNode<N, any> | undefined;
+  getEdge(id: string): GraphEdge<E> | undefined;
+  hasNode(id: string): boolean;
+  hasEdge(id: string): boolean;
+  addNode(config: NodeConfig<N, P>): GraphNode<N, P>;
+  addEdge(config: EdgeConfig<E>): GraphEdge<E>;
+  deleteNode(id: string, opts?: DeleteNodeOptions): void;
+  deleteEdge(id: string): void;
+  updateNode(id: string, update: NodeUpdate<N, P>): GraphNode<N, P>;
+  updateEdge(id: string, update: EdgeUpdate<E>): GraphEdge<E>;
+  addEntities(entities: EntitiesConfig<N, E, P>): void;
+  deleteEntities(ids: string | string[], opts?: DeleteNodeOptions): void;
+  updateEntities(updates: EntitiesUpdate<N, E, P>): void;
+  toJSON(): Graph<N, E, G, P>;
+}
+//#endregion
+//#region src/mode.d.ts
+/**
+ * Resolve an edge's effective directedness. Falls back to the graph's
+ * {@link Graph.mode} when the edge has no per-edge override.
+ */
+declare function getEdgeMode(graph: Graph, edge: GraphEdge): GraphMode;
+/** Whether an edge points only from source to target. */
+declare function isEdgeDirected(graph: Graph, edge: GraphEdge): boolean;
+//#endregion
+//#region src/validate.d.ts
+/**
+ * A structural problem found in a graph by {@link getGraphIssues}.
+ */
+interface GraphIssue {
+  /** Stable machine-readable code, e.g. `'duplicate-node-id'`. */
+  code: string;
+  /** What is wrong, which entity is affected, and how to fix it. */
+  message: string;
+  /** Location of the offending value, e.g. `['nodes', 0, 'id']`. */
+  path?: (string | number)[];
+}
+/**
+ * Validates the structural invariants of a graph and returns the issues
+ * found, or `[]` when the graph is valid. Pure — never throws, never mutates.
+ *
+ * This is the recommended gate for untrusted or imported graphs (e.g. parsed
+ * from a file or received over the wire) before handing them to queries and
+ * algorithms: the mutation APIs (`addNode`, `addEdge`, `updateNode`, …)
+ * validate incrementally, but `createGraph` does **not** — it accepts
+ * dangling `parentId`/edge references and even `parentId` cycles as-is.
+ *
+ * For Zod-based shape validation of arbitrary unknown values, see
+ * `validateGraph` in `@statelyai/graph/schemas` (which reuses these checks).
+ *
+ * Issue codes: `duplicate-node-id`, `duplicate-edge-id`,
+ * `missing-initial-node`, `missing-parent`, `missing-node-initial`,
+ * `duplicate-port-name`, `parent-cycle`, `dangling-edge-endpoint`,
+ * `missing-source-port`, `missing-target-port`.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a', parentId: 'ghost' }],
+ *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+ * });
+ * getGraphIssues(graph);
+ * // => [
+ * //   { code: 'missing-parent', message: '...', path: ['nodes', 0, 'parentId'] },
+ * //   { code: 'dangling-edge-endpoint', message: '...', path: ['edges', 0, 'targetId'] },
+ * // ]
+ * ```
+ */
+declare function getGraphIssues(graph: Graph): GraphIssue[];
+//#endregion
+//#region src/indexing.d.ts
+/**
+ * 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()
+ * ```
+ */
+declare function invalidateIndex(graph: Graph): void;
+//#endregion
+//#region src/equivalence.d.ts
+declare const LAYOUT_KEYS: {
+  node: readonly ["x", "y", "width", "height", "style", "color", "shape"];
+  edge: readonly ["x", "y", "width", "height", "style", "color"];
+};
+/**
+ * Compare two entities on a given set of keys.
+ * If `keys` is omitted or empty, compares all own keys of `a`.
+ *
+ * @example
+ * ```ts
+ * import { createGraphNode, areEntitiesEqual, LAYOUT_KEYS } from '@statelyai/graph';
+ *
+ * const a = createGraphNode({ id: 'n1', label: 'hello', x: 0 });
+ * const b = createGraphNode({ id: 'n1', label: 'hello', x: 100 });
+ *
+ * areEntitiesEqual(a, b, LAYOUT_KEYS.node); // false (x differs)
+ * areEntitiesEqual(a, b, NON_LAYOUT_KEYS.node); // true
+ * areEntitiesEqual(a, b); // false (compares all keys)
+ * ```
+ */
+declare function areEntitiesEqual<T extends GraphNode | GraphEdge>(a: T, b: T, keys?: readonly (keyof T)[]): boolean;
+/**
+ * Compare two entities on layout keys only (position, size, style, color, shape).
+ *
+ * @example
+ * ```ts
+ * import { createGraphNode, isLayoutEqual } from '@statelyai/graph';
+ *
+ * const a = createGraphNode({ id: 'n1', x: 0, y: 0 });
+ * const b = createGraphNode({ id: 'n1', x: 100, y: 200 });
+ *
+ * isLayoutEqual(a, b); // false
+ * ```
+ */
+declare function isLayoutEqual<T extends GraphNode | GraphEdge>(a: T, b: T): boolean;
+/**
+ * Compare two entities on non-layout keys only (id, data, connections, labels, etc.).
+ *
+ * @example
+ * ```ts
+ * import { createGraphNode, isNonLayoutEqual } from '@statelyai/graph';
+ *
+ * const a = createGraphNode({ id: 'n1', label: 'hello', x: 0 });
+ * const b = createGraphNode({ id: 'n1', label: 'hello', x: 100 });
+ *
+ * isNonLayoutEqual(a, b); // true (layout changed, but non-layout didn't)
+ * ```
+ */
+declare function isNonLayoutEqual<T extends GraphNode | GraphEdge>(a: T, b: T): boolean;
+//#endregion
+//#region src/diff.d.ts
+/**
+ * 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.
+ *
+ * @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.
+ *
+ * @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 (see {@link toPatches}): add nodes → update edges → delete edges →
+ * delete nodes → add edges → update nodes.
+ *
+ * @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;
+/**
+ * Flatten a structured diff into an ordered patch list.
+ * 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.
+ *
+ * @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
+/**
+ * Flattens a hierarchical graph into a flat graph with only leaf nodes.
+ *
+ * - Edges targeting a compound node resolve to its initial child (recursively).
+ * - 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>;
+/**
+ * Returns the induced subgraph containing only the given node IDs
+ * and edges whose endpoints are both in the set.
+ *
+ * Parent references to nodes outside the set are removed.
+ *
+ * @example
+ * ```ts
+ * import { createGraph, getSubgraph } from '@statelyai/graph';
+ *
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+ *   edges: [
+ *     { id: 'ab', sourceId: 'a', targetId: 'b' },
+ *     { id: 'bc', sourceId: 'b', targetId: 'c' },
+ *   ],
+ * });
+ *
+ * const sub = getSubgraph(graph, ['a', 'b']);
+ * // sub.nodes: [a, b], sub.edges: [ab]
+ * ```
+ */
+declare function getSubgraph<N, E, G>(graph: Graph<N, E, G>, nodeIds: string[]): Graph<N, E, G>;
+/**
+ * Returns a new graph with all edge directions flipped (source ↔ target).
+ * Optionally filters which edges to include.
+ *
+ * @example
+ * ```ts
+ * import { createGraph, reverseGraph } from '@statelyai/graph';
+ *
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+ *   edges: [
+ *     { id: 'ab', sourceId: 'a', targetId: 'b' },
+ *     { id: 'bc', sourceId: 'b', targetId: 'c' },
+ *   ],
+ * });
+ *
+ * const rev = reverseGraph(graph);
+ * // rev edges: b→a, c→b
+ *
+ * const filtered = reverseGraph(graph, (e) => e.id !== 'bc');
+ * // filtered edges: b→a (only ab reversed, bc excluded)
+ * ```
+ */
+declare function reverseGraph<N, E, G>(graph: Graph<N, E, G>, filterEdge?: (edge: GraphEdge<E>) => boolean): Graph<N, E, G>;
+//#endregion
+//#region src/walks.d.ts
+/**
+ * Random walk. At each node, picks a uniformly random traversable edge
+ * (outgoing edges, plus non-directed edges both ways).
+ * Yields steps indefinitely (may revisit nodes) until a sink node is reached.
+ */
+declare function genRandomWalk<N, E>(graph: Graph<N, E>, options?: WalkOptions<E>): Generator<GraphStep<N, E>>;
+/**
+ * Weighted random walk. Edge selection probability proportional to weight.
+ */
+declare function genWeightedRandomWalk<N, E>(graph: Graph<N, E>, options?: WeightedWalkOptions<E>): Generator<GraphStep<N, E>>;
+/**
+ * Quick random walk targeting unvisited edges.
+ * If unvisited traversable edges exist at the current node, picks one randomly.
+ * Otherwise, walks the fewest-hop path (BFS, honoring `filter` and edge modes)
+ * to the nearest unvisited edge. Ends when no unvisited edge is reachable.
+ */
+declare function genQuickRandomWalk<N, E>(graph: Graph<N, E>, options?: WalkOptions<E>): Generator<GraphStep<N, E>>;
+/**
+ * Walk a predefined sequence of edge IDs.
+ * Validates each edge exists and connects from the current position.
+ * Edges whose effective mode is not `'directed'` may be traversed
+ * target → source as well.
+ */
+declare function genPredefinedWalk<N, E>(graph: Graph<N, E>, edgeIds: string[], options?: Pick<WalkOptions<E>, 'from'>): Generator<GraphStep<N, E>>;
+/**
+ * Yield at most `n` steps from the source generator.
+ */
+declare function takeSteps<N, E>(gen: Generator<GraphStep<N, E>>, n: number): Generator<GraphStep<N, E>>;
+/**
+ * Yield steps until a specific node is reached.
+ */
+declare function takeUntilNode<N, E>(gen: Generator<GraphStep<N, E>>, nodeId: string): Generator<GraphStep<N, E>>;
+/**
+ * Yield steps until a specific edge is traversed.
+ */
+declare function takeUntilEdge<N, E>(gen: Generator<GraphStep<N, E>>, edgeId: string): Generator<GraphStep<N, E>>;
+/**
+ * Yield steps until node coverage reaches the target (0–1).
+ */
+declare function takeUntilNodeCoverage<N, E>(gen: Generator<GraphStep<N, E>>, graph: Graph<N, E>, coverage: number, options?: {
+  from?: string;
+}): Generator<GraphStep<N, E>>;
+/**
+ * Yield steps until edge coverage reaches the target (0–1).
+ */
+declare function takeUntilEdgeCoverage<N, E>(gen: Generator<GraphStep<N, E>>, graph: Graph<N, E>, coverage: number): Generator<GraphStep<N, E>>;
+/**
+ * Compute coverage statistics for a completed walk.
+ */
+declare function getCoverage<N, E>(graph: Graph<N, E>, steps: GraphStep<N, E>[], options?: {
+  from?: string;
+}): CoverageStats;
+//#endregion
+export { GraphInstance as A, deleteEdge as B, isLayoutEqual as C, getGraphIssues as D, GraphIssue as E, createGraphEdge as F, hasEdge as G, deleteNode as H, createGraphFromTransition as I, updateEntities as J, hasNode as K, createGraphNode as L, addEntities as M, addNode as N, getEdgeMode as O, createGraph as P, createGraphPort as R, areEntitiesEqual as S, invalidateIndex as T, getEdge as U, deleteEntities as V, getNode as W, updateNode as Y, invertDiff as _, getCoverage as a, toPatches as b, takeUntilEdgeCoverage as c, flatten as d, getSubgraph as f, getPatches as g, getDiff as h, genWeightedRandomWalk as i, addEdge as j, isEdgeDirected as k, takeUntilNode as l, applyPatches as m, genQuickRandomWalk as n, takeSteps as o, reverseGraph as p, updateEdge as q, genRandomWalk as r, takeUntilEdge as s, genPredefinedWalk as t, takeUntilNodeCoverage as u, isEmptyDiff as v, isNonLayoutEqual as w, LAYOUT_KEYS as x, toDiff as y, createVisualGraph as z };