@statelyai/graph 0.1.0 → 0.3.1

package/dist/index.mjs

@@ -1,11 +1,7 @@
-import { o as invalidateIndex, t as getIndex } from "./indexing-BHg1VhqN.mjs";
-import { A as createGraph, B as updateEntities, C as isAcyclic, D as addEdge, E as GraphInstance, F as getEdge, I as getNode, L as hasEdge, M as deleteEdge, N as deleteEntities, O as addEntities, P as deleteNode, R as hasNode, S as hasPath, T as isTree, V as updateNode, _ 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 createVisualGraph, k as addNode, 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 updateEdge } from "./algorithms-R35X6ro4.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 { n as toGraphML, t as fromGraphML } from "./graphml-CUTNRXqd.mjs";
-import { t as toDOT } from "./dot-BRtq3e3c.mjs";
-import { n as toAdjacencyList, t as fromAdjacencyList } from "./adjacency-list-CXpOCibq.mjs";
-import { n as toEdgeList, t as fromEdgeList } from "./edge-list-BRujEnnU.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-CchokMDg.mjs";
 
 //#region src/diff.ts
 function nodeToConfig(node) {
@@ -71,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]));
@@ -127,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: {
@@ -157,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));
@@ -164,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) {
@@ -192,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 = [];
@@ -231,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: {
@@ -291,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);
@@ -353,4 +457,4 @@ function flatten(graph) {
 }
 
 //#endregion
-export { EdgeSchema, GraphInstance, GraphSchema, NodeSchema, 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 { GraphInstance, 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 };

package/dist/{indexing-BHg1VhqN.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);
 }