@statelyai/graph 0.1.0

package/dist/algorithms.d.mts

@@ -0,0 +1,82 @@
+import { b as SinglePathOptions, c as Graph, f as GraphNode, g as MSTOptions, m as GraphPath, t as AllPairsShortestPathsOptions, x as TraversalOptions, y as PathOptions } from "./types-XV3S5Jnh.mjs";
+
+//#region src/algorithms.d.ts
+declare function bfs<N>(graph: Graph<N>, startId: string): Generator<GraphNode<N>>;
+declare function dfs<N>(graph: Graph<N>, startId: string): Generator<GraphNode<N>>;
+declare function isAcyclic(graph: Graph): boolean;
+declare function getConnectedComponents<N>(graph: Graph<N>): GraphNode<N>[][];
+declare function getTopologicalSort<N>(graph: Graph<N>): GraphNode<N>[] | null;
+declare function hasPath(graph: Graph, sourceId: string, targetId: string): boolean;
+declare function isConnected(graph: Graph): boolean;
+declare function isTree(graph: Graph): boolean;
+/**
+ * Lazily yields all shortest paths from a source node.
+ * Use `getShortestPaths` for the full array.
+ */
+declare function genShortestPaths<N, E>(graph: Graph<N, E>, opts?: PathOptions<E>): Generator<GraphPath<N, E>>;
+declare function getShortestPaths<N, E>(graph: Graph<N, E>, opts?: PathOptions<E>): GraphPath<N, E>[];
+/**
+ * Returns a single shortest path from source to target, or undefined if unreachable.
+ */
+declare function getShortestPath<N, E>(graph: Graph<N, E>, opts: SinglePathOptions<E>): GraphPath<N, E> | undefined;
+/**
+ * Returns all simple (acyclic) paths from a source node.
+ * Uses DFS with backtracking.
+ */
+declare function getSimplePaths<N, E>(graph: Graph<N, E>, opts?: PathOptions<E>): GraphPath<N, E>[];
+/**
+ * Lazily yields all simple (acyclic) paths from a source node.
+ * Use `getSimplePaths` for the full array.
+ */
+declare function genSimplePaths<N, E>(graph: Graph<N, E>, opts?: PathOptions<E>): Generator<GraphPath<N, E>>;
+/**
+ * Returns a single simple (acyclic) path from source to target, or undefined if unreachable.
+ */
+declare function getSimplePath<N, E>(graph: Graph<N, E>, opts: SinglePathOptions<E>): GraphPath<N, E> | undefined;
+declare function getStronglyConnectedComponents<N>(graph: Graph<N>): GraphNode<N>[][];
+declare function getCycles<N, E>(graph: Graph<N, E>): GraphPath<N, E>[];
+/**
+ * Lazily yields cycles one at a time.
+ * Use `getCycles` for the full array.
+ */
+declare function genCycles<N, E>(graph: Graph<N, E>): Generator<GraphPath<N, E>>;
+/**
+ * Returns a single canonical preorder (DFS visit-order) sequence.
+ * Visits neighbors in the order they appear in the adjacency list.
+ */
+declare function getPreorder<N>(graph: Graph<N>, opts?: TraversalOptions): GraphNode<N>[];
+/**
+ * Returns a single canonical postorder (DFS finish-order) sequence.
+ * Visits neighbors in the order they appear in the adjacency list.
+ */
+declare function getPostorder<N>(graph: Graph<N>, opts?: TraversalOptions): GraphNode<N>[];
+/** Returns all possible preorder sequences as an array. Can be exponential — prefer `genPreorders`. */
+declare function getPreorders<N>(graph: Graph<N>, opts?: TraversalOptions): GraphNode<N>[][];
+/** Returns all possible postorder sequences as an array. Can be exponential — prefer `genPostorders`. */
+declare function getPostorders<N>(graph: Graph<N>, opts?: TraversalOptions): GraphNode<N>[][];
+/**
+ * Lazily yields all possible preorder (DFS visit-order) sequences.
+ * Different neighbor exploration orders yield different sequences.
+ * Use `getPreorder()` for a single canonical ordering.
+ */
+declare function genPreorders<N>(graph: Graph<N>, opts?: TraversalOptions): Generator<GraphNode<N>[]>;
+/**
+ * Lazily yields all possible postorder (DFS finish-order) sequences.
+ * Different neighbor exploration orders yield different sequences.
+ * Use `getPostorder()` for a single canonical ordering.
+ */
+declare function genPostorders<N>(graph: Graph<N>, opts?: TraversalOptions): Generator<GraphNode<N>[]>;
+/**
+ * Returns a minimum spanning tree of the graph.
+ * Only meaningful for connected undirected graphs (or the component reachable
+ * from an arbitrary start node in directed graphs).
+ */
+declare function getMinimumSpanningTree<N, E>(graph: Graph<N, E>, opts?: MSTOptions<E>): Graph<N, E>;
+/**
+ * Returns shortest paths between all pairs of nodes.
+ * Algorithm 'dijkstra' (default): runs getShortestPaths per source node.
+ * Algorithm 'floyd-warshall': classic O(V³) dynamic programming.
+ */
+declare function getAllPairsShortestPaths<N, E>(graph: Graph<N, E>, opts?: AllPairsShortestPathsOptions<E>): GraphPath<N, E>[];
+//#endregion
+export { 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 };

package/dist/algorithms.mjs

@@ -0,0 +1,3 @@
+import { C as isAcyclic, S as hasPath, T as isTree, _ 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, 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 } from "./algorithms-R35X6ro4.mjs";
+
+export { 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 };

package/dist/dot-BRtq3e3c.mjs

@@ -0,0 +1,59 @@
+//#region src/formats/dot.ts
+/** Escape a DOT identifier */
+function escapeId(id) {
+	if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(id)) return id;
+	return `"${id.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+}
+/** Escape a DOT label string */
+function escapeLabel(label) {
+	return label.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+}
+const DIRECTION_TO_RANKDIR = {
+	down: "TB",
+	up: "BT",
+	right: "LR",
+	left: "RL"
+};
+const SHAPE_TO_DOT = {
+	rectangle: "box",
+	ellipse: "ellipse",
+	circle: "circle",
+	diamond: "diamond",
+	hexagon: "hexagon",
+	cylinder: "cylinder",
+	parallelogram: "parallelogram"
+};
+function toDOT(graph) {
+	const isDirected = graph.type === "directed";
+	const keyword = isDirected ? "digraph" : "graph";
+	const edgeOp = isDirected ? "->" : "--";
+	const lines = [];
+	lines.push(`${keyword} ${escapeId(graph.id)} {`);
+	if (graph.direction) {
+		const rankdir = DIRECTION_TO_RANKDIR[graph.direction] ?? "TB";
+		lines.push(`  rankdir=${rankdir};`);
+	}
+	for (const node of graph.nodes) {
+		const attrs = [];
+		if (node.label) attrs.push(`label="${escapeLabel(node.label)}"`);
+		if (node.shape) {
+			const dotShape = SHAPE_TO_DOT[node.shape] ?? node.shape;
+			attrs.push(`shape=${dotShape}`);
+		}
+		if (node.color) attrs.push(`fillcolor="${escapeLabel(node.color)}" style=filled`);
+		if (attrs.length > 0) lines.push(`  ${escapeId(node.id)} [${attrs.join(", ")}];`);
+		else lines.push(`  ${escapeId(node.id)};`);
+	}
+	for (const edge of graph.edges) {
+		const attrs = [];
+		if (edge.label) attrs.push(`label="${escapeLabel(edge.label)}"`);
+		if (edge.color) attrs.push(`color="${escapeLabel(edge.color)}"`);
+		const attrStr = attrs.length > 0 ? ` [${attrs.join(", ")}]` : "";
+		lines.push(`  ${escapeId(edge.sourceId)} ${edgeOp} ${escapeId(edge.targetId)}${attrStr};`);
+	}
+	lines.push("}");
+	return lines.join("\n");
+}
+
+//#endregion
+export { toDOT as t };

package/dist/dot-HmJeUMsj.d.mts

@@ -0,0 +1,6 @@
+import { c as Graph } from "./types-XV3S5Jnh.mjs";
+
+//#region src/formats/dot.d.ts
+declare function toDOT(graph: Graph): string;
+//#endregion
+export { toDOT as t };

package/dist/edge-list-BRujEnnU.mjs

@@ -0,0 +1,39 @@
+//#region src/formats/edge-list.ts
+function toEdgeList(graph) {
+	return graph.edges.map((e) => [e.sourceId, e.targetId]);
+}
+function fromEdgeList(edges, options) {
+	const directed = options?.directed ?? true;
+	const nodeIds = /* @__PURE__ */ new Set();
+	for (const [source, target] of edges) {
+		nodeIds.add(source);
+		nodeIds.add(target);
+	}
+	const nodes = [...nodeIds].map((id) => ({
+		type: "node",
+		id,
+		parentId: null,
+		initialNodeId: null,
+		label: "",
+		data: void 0
+	}));
+	const edgeObjects = edges.map(([sourceId, targetId], i) => ({
+		type: "edge",
+		id: `e${i}`,
+		sourceId,
+		targetId,
+		label: "",
+		data: void 0
+	}));
+	return {
+		id: options?.id ?? "",
+		type: directed ? "directed" : "undirected",
+		initialNodeId: null,
+		nodes,
+		edges: edgeObjects,
+		data: void 0
+	};
+}
+
+//#endregion
+export { toEdgeList as n, fromEdgeList as t };

package/dist/edge-list-CJmfoNu2.d.mts

@@ -0,0 +1,10 @@
+import { c as Graph } from "./types-XV3S5Jnh.mjs";
+
+//#region src/formats/edge-list.d.ts
+declare function toEdgeList(graph: Graph): [string, string][];
+declare function fromEdgeList(edges: [string, string][], options?: {
+  directed?: boolean;
+  id?: string;
+}): Graph;
+//#endregion
+export { toEdgeList as n, fromEdgeList as t };

package/dist/formats/adjacency-list.d.mts

@@ -0,0 +1,2 @@
+import { n as toAdjacencyList, t as fromAdjacencyList } from "../adjacency-list-DW-lAUe8.mjs";
+export { fromAdjacencyList, toAdjacencyList };

package/dist/formats/adjacency-list.mjs

@@ -0,0 +1,3 @@
+import { n as toAdjacencyList, t as fromAdjacencyList } from "../adjacency-list-CXpOCibq.mjs";
+
+export { fromAdjacencyList, toAdjacencyList };

package/dist/formats/dot.d.mts

@@ -0,0 +1,2 @@
+import { t as toDOT } from "../dot-HmJeUMsj.mjs";
+export { toDOT };

package/dist/formats/dot.mjs

@@ -0,0 +1,3 @@
+import { t as toDOT } from "../dot-BRtq3e3c.mjs";
+
+export { toDOT };

package/dist/formats/edge-list.d.mts

@@ -0,0 +1,2 @@
+import { n as toEdgeList, t as fromEdgeList } from "../edge-list-CJmfoNu2.mjs";
+export { fromEdgeList, toEdgeList };

package/dist/formats/edge-list.mjs

@@ -0,0 +1,3 @@
+import { n as toEdgeList, t as fromEdgeList } from "../edge-list-BRujEnnU.mjs";
+
+export { fromEdgeList, toEdgeList };

package/dist/formats/graphml.d.mts

@@ -0,0 +1,2 @@
+import { n as toGraphML, t as fromGraphML } from "../graphml-CMjPzSfY.mjs";
+export { fromGraphML, toGraphML };

package/dist/formats/graphml.mjs

@@ -0,0 +1,3 @@
+import { n as toGraphML, t as fromGraphML } from "../graphml-CUTNRXqd.mjs";
+
+export { fromGraphML, toGraphML };

package/dist/graphml-CMjPzSfY.d.mts

@@ -0,0 +1,7 @@
+import { c as Graph } from "./types-XV3S5Jnh.mjs";
+
+//#region src/formats/graphml.d.ts
+declare function toGraphML(graph: Graph): string;
+declare function fromGraphML(xml: string): Graph;
+//#endregion
+export { toGraphML as n, fromGraphML as t };

package/dist/graphml-CUTNRXqd.mjs

@@ -0,0 +1,240 @@
+import { XMLBuilder, XMLParser } from "fast-xml-parser";
+
+//#region src/formats/graphml.ts
+const GRAPHML_NS = "http://graphml.graphdrawing.org/xmlns";
+function toGraphML(graph) {
+	const keys = [
+		{
+			"@_id": "label",
+			"@_for": "all",
+			"@_attr.name": "label",
+			"@_attr.type": "string"
+		},
+		{
+			"@_id": "parentId",
+			"@_for": "node",
+			"@_attr.name": "parentId",
+			"@_attr.type": "string"
+		},
+		{
+			"@_id": "data",
+			"@_for": "all",
+			"@_attr.name": "data",
+			"@_attr.type": "string"
+		},
+		{
+			"@_id": "graphData",
+			"@_for": "graph",
+			"@_attr.name": "data",
+			"@_attr.type": "string"
+		},
+		{
+			"@_id": "x",
+			"@_for": "all",
+			"@_attr.name": "x",
+			"@_attr.type": "double"
+		},
+		{
+			"@_id": "y",
+			"@_for": "all",
+			"@_attr.name": "y",
+			"@_attr.type": "double"
+		},
+		{
+			"@_id": "width",
+			"@_for": "all",
+			"@_attr.name": "width",
+			"@_attr.type": "double"
+		},
+		{
+			"@_id": "height",
+			"@_for": "all",
+			"@_attr.name": "height",
+			"@_attr.type": "double"
+		},
+		{
+			"@_id": "shape",
+			"@_for": "node",
+			"@_attr.name": "shape",
+			"@_attr.type": "string"
+		},
+		{
+			"@_id": "color",
+			"@_for": "all",
+			"@_attr.name": "color",
+			"@_attr.type": "string"
+		}
+	];
+	const nodes = graph.nodes.map((n) => {
+		const data = [];
+		if (n.label) data.push({
+			"@_key": "label",
+			"#text": n.label
+		});
+		if (n.parentId !== null) data.push({
+			"@_key": "parentId",
+			"#text": n.parentId
+		});
+		if (n.data !== void 0) data.push({
+			"@_key": "data",
+			"#text": JSON.stringify(n.data)
+		});
+		if (n.x !== void 0) data.push({
+			"@_key": "x",
+			"#text": n.x
+		});
+		if (n.y !== void 0) data.push({
+			"@_key": "y",
+			"#text": n.y
+		});
+		if (n.width !== void 0) data.push({
+			"@_key": "width",
+			"#text": n.width
+		});
+		if (n.height !== void 0) data.push({
+			"@_key": "height",
+			"#text": n.height
+		});
+		if (n.shape) data.push({
+			"@_key": "shape",
+			"#text": n.shape
+		});
+		if (n.color) data.push({
+			"@_key": "color",
+			"#text": n.color
+		});
+		return {
+			"@_id": n.id,
+			...data.length > 0 && { data }
+		};
+	});
+	const edges = graph.edges.map((e) => {
+		const data = [];
+		if (e.label) data.push({
+			"@_key": "label",
+			"#text": e.label
+		});
+		if (e.data !== void 0) data.push({
+			"@_key": "data",
+			"#text": JSON.stringify(e.data)
+		});
+		if (e.x !== void 0) data.push({
+			"@_key": "x",
+			"#text": e.x
+		});
+		if (e.y !== void 0) data.push({
+			"@_key": "y",
+			"#text": e.y
+		});
+		if (e.width !== void 0) data.push({
+			"@_key": "width",
+			"#text": e.width
+		});
+		if (e.height !== void 0) data.push({
+			"@_key": "height",
+			"#text": e.height
+		});
+		if (e.color) data.push({
+			"@_key": "color",
+			"#text": e.color
+		});
+		return {
+			"@_id": e.id,
+			"@_source": e.sourceId,
+			"@_target": e.targetId,
+			...data.length > 0 && { data }
+		};
+	});
+	const graphData = [];
+	if (graph.data !== void 0) graphData.push({
+		"@_key": "graphData",
+		"#text": JSON.stringify(graph.data)
+	});
+	const obj = {
+		"?xml": {
+			"@_version": "1.0",
+			"@_encoding": "UTF-8"
+		},
+		graphml: {
+			"@_xmlns": GRAPHML_NS,
+			key: keys,
+			graph: {
+				"@_id": graph.id,
+				"@_edgedefault": graph.type === "directed" ? "directed" : "undirected",
+				...graphData.length > 0 && { data: graphData },
+				node: nodes,
+				edge: edges
+			}
+		}
+	};
+	return new XMLBuilder({
+		ignoreAttributes: false,
+		format: true,
+		suppressEmptyNode: true
+	}).build(obj);
+}
+function fromGraphML(xml) {
+	const graphEl = new XMLParser({
+		ignoreAttributes: false,
+		isArray: (name) => [
+			"node",
+			"edge",
+			"data",
+			"key"
+		].includes(name)
+	}).parse(xml).graphml.graph;
+	const graphType = graphEl["@_edgedefault"] === "undirected" ? "undirected" : "directed";
+	let graphData = void 0;
+	if (graphEl.data) {
+		for (const d of asArray(graphEl.data)) if (d["@_key"] === "graphData") graphData = tryParseJSON(String(d["#text"]));
+	}
+	const nodes = asArray(graphEl.node).map((n) => {
+		const dataMap = parseDataElements(n.data);
+		return {
+			type: "node",
+			id: String(n["@_id"]),
+			parentId: dataMap.parentId ?? null,
+			initialNodeId: dataMap.initialNodeId ?? null,
+			label: dataMap.label ?? "",
+			data: dataMap.data !== void 0 ? tryParseJSON(dataMap.data) : void 0
+		};
+	});
+	const edges = asArray(graphEl.edge).map((e) => {
+		const dataMap = parseDataElements(e.data);
+		return {
+			type: "edge",
+			id: String(e["@_id"]),
+			sourceId: String(e["@_source"]),
+			targetId: String(e["@_target"]),
+			label: dataMap.label ?? "",
+			data: dataMap.data !== void 0 ? tryParseJSON(dataMap.data) : void 0
+		};
+	});
+	return {
+		id: String(graphEl["@_id"] ?? ""),
+		type: graphType,
+		initialNodeId: null,
+		nodes,
+		edges,
+		data: graphData
+	};
+}
+function asArray(val) {
+	if (val === void 0) return [];
+	return Array.isArray(val) ? val : [val];
+}
+function parseDataElements(dataEls) {
+	const map = {};
+	for (const d of asArray(dataEls)) if (d && d["@_key"]) map[d["@_key"]] = String(d["#text"] ?? "");
+	return map;
+}
+function tryParseJSON(str) {
+	try {
+		return JSON.parse(str);
+	} catch {
+		return str;
+	}
+}
+
+//#endregion
+export { toGraphML as n, fromGraphML as t };

package/dist/index.d.mts

@@ -0,0 +1,142 @@
+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";
+
+//#region src/graph.d.ts
+/** Create a graph from a config. Resolves defaults for all fields. */
+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. */
+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. */
+declare function getNode<N>(graph: Graph<N>, id: string): GraphNode<N> | undefined;
+/** Get an edge by id, or `undefined` if not found. */
+declare function getEdge<E>(graph: Graph<any, E>, id: string): GraphEdge<E> | undefined;
+/** Check if a node exists in the graph. */
+declare function hasNode(graph: Graph, id: string): boolean;
+/** Check if an edge exists in the graph. */
+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.
+ */
+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.
+ */
+declare function addEdge<E>(graph: Graph<any, 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.
+ */
+declare function deleteNode(graph: Graph, id: string, opts?: DeleteNodeOptions): void;
+/**
+ * **Mutable.** Delete an edge. Mutates `graph.edges` in place.
+ */
+declare function deleteEdge(graph: Graph, id: string): void;
+/**
+ * **Mutable.** Update a node in place.
+ * @returns The updated node.
+ */
+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.
+ */
+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).
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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. */
+  static from<N = any, E = any, G = any>(graph: Graph<N, E, G>): GraphInstance<N, E, G>;
+  get id(): string;
+  get type(): "directed" | "undirected";
+  get nodes(): GraphNode<N>[];
+  get edges(): GraphEdge<E>[];
+  get data(): G;
+  getNode(id: string): GraphNode<N> | undefined;
+  getEdge(id: string): GraphEdge<E> | undefined;
+  hasNode(id: string): boolean;
+  hasEdge(id: string): boolean;
+  addNode(config: NodeConfig<N>): GraphNode<N>;
+  addEdge(config: EdgeConfig<E>): GraphEdge<E>;
+  deleteNode(id: string, opts?: DeleteNodeOptions): void;
+  deleteEdge(id: string): void;
+  updateNode(id: string, update: Partial<Omit<NodeConfig<N>, 'id'>>): GraphNode<N>;
+  updateEdge(id: string, update: Partial<Omit<EdgeConfig<E>, 'id'>>): GraphEdge<E>;
+  addEntities(entities: EntitiesConfig<N, E>): void;
+  deleteEntities(ids: string | string[], opts?: DeleteNodeOptions): void;
+  updateEntities(updates: EntitiesUpdate<N, E>): void;
+  toJSON(): Graph<N, E, G>;
+}
+//#endregion
+//#region src/indexing.d.ts
+/** Clear the cached index. Call this if you mutate graph.nodes/edges directly. */
+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. */
+declare function getDiff<N, E>(a: Graph<N, E>, b: Graph<N, E>): GraphDiff<N, E>;
+/** Check if a diff has zero changes. */
+declare function isEmptyDiff(diff: GraphDiff): boolean;
+/** Invert a diff: swap added↔removed, swap old↔new in updates. */
+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.
+ */
+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.
+ */
+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.
+ */
+declare function toPatches<N, E>(diff: GraphDiff<N, E>): GraphPatch<N, E>[];
+/** Group a patch list into a structured diff. */
+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.
+ */
+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 };