@statelyai/graph 0.1.0

package/dist/queries.mjs

@@ -0,0 +1,221 @@
+import { t as getIndex } from "./indexing-BHg1VhqN.mjs";
+
+//#region src/queries.ts
+function getEdgesOf(graph, nodeId) {
+	const idx = getIndex(graph);
+	const outIds = idx.outEdges.get(nodeId) ?? [];
+	const inIds = idx.inEdges.get(nodeId) ?? [];
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	for (const eid of outIds) {
+		seen.add(eid);
+		const ai = idx.edgeById.get(eid);
+		if (ai !== void 0) result.push(graph.edges[ai]);
+	}
+	for (const eid of inIds) if (!seen.has(eid)) {
+		const ai = idx.edgeById.get(eid);
+		if (ai !== void 0) result.push(graph.edges[ai]);
+	}
+	return result;
+}
+function getInEdges(graph, nodeId) {
+	const idx = getIndex(graph);
+	return (idx.inEdges.get(nodeId) ?? []).map((eid) => graph.edges[idx.edgeById.get(eid)]);
+}
+function getOutEdges(graph, nodeId) {
+	const idx = getIndex(graph);
+	return (idx.outEdges.get(nodeId) ?? []).map((eid) => graph.edges[idx.edgeById.get(eid)]);
+}
+function getEdgeBetween(graph, sourceId, targetId) {
+	const idx = getIndex(graph);
+	const outIds = idx.outEdges.get(sourceId) ?? [];
+	for (const eid of outIds) {
+		const ai = idx.edgeById.get(eid);
+		const e = graph.edges[ai];
+		if (e.targetId === targetId) return e;
+	}
+	if (graph.type === "undirected") {
+		const outIds2 = idx.outEdges.get(targetId) ?? [];
+		for (const eid of outIds2) {
+			const ai = idx.edgeById.get(eid);
+			const e = graph.edges[ai];
+			if (e.targetId === sourceId) return e;
+		}
+	}
+}
+function getSuccessors(graph, nodeId) {
+	const idx = getIndex(graph);
+	const edgeIds = idx.outEdges.get(nodeId) ?? [];
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	for (const eid of edgeIds) {
+		const e = graph.edges[idx.edgeById.get(eid)];
+		if (!seen.has(e.targetId)) {
+			seen.add(e.targetId);
+			const ni = idx.nodeById.get(e.targetId);
+			if (ni !== void 0) result.push(graph.nodes[ni]);
+		}
+	}
+	return result;
+}
+function getPredecessors(graph, nodeId) {
+	const idx = getIndex(graph);
+	const edgeIds = idx.inEdges.get(nodeId) ?? [];
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	for (const eid of edgeIds) {
+		const e = graph.edges[idx.edgeById.get(eid)];
+		if (!seen.has(e.sourceId)) {
+			seen.add(e.sourceId);
+			const ni = idx.nodeById.get(e.sourceId);
+			if (ni !== void 0) result.push(graph.nodes[ni]);
+		}
+	}
+	return result;
+}
+function getNeighbors(graph, nodeId) {
+	const idx = getIndex(graph);
+	const ids = /* @__PURE__ */ new Set();
+	for (const eid of idx.outEdges.get(nodeId) ?? []) ids.add(graph.edges[idx.edgeById.get(eid)].targetId);
+	for (const eid of idx.inEdges.get(nodeId) ?? []) ids.add(graph.edges[idx.edgeById.get(eid)].sourceId);
+	return [...ids].map((id) => graph.nodes[idx.nodeById.get(id)]).filter(Boolean);
+}
+function getDegree(graph, nodeId) {
+	const idx = getIndex(graph);
+	if (graph.type === "undirected") {
+		const out = idx.outEdges.get(nodeId) ?? [];
+		const inE = idx.inEdges.get(nodeId) ?? [];
+		return new Set([...out, ...inE]).size;
+	}
+	return (idx.inEdges.get(nodeId)?.length ?? 0) + (idx.outEdges.get(nodeId)?.length ?? 0);
+}
+function getInDegree(graph, nodeId) {
+	return getIndex(graph).inEdges.get(nodeId)?.length ?? 0;
+}
+function getOutDegree(graph, nodeId) {
+	return getIndex(graph).outEdges.get(nodeId)?.length ?? 0;
+}
+function getChildren(graph, nodeId) {
+	const idx = getIndex(graph);
+	return (idx.childNodes.get(nodeId) ?? []).map((id) => graph.nodes[idx.nodeById.get(id)]).filter(Boolean);
+}
+function getParent(graph, nodeId) {
+	const idx = getIndex(graph);
+	const ni = idx.nodeById.get(nodeId);
+	if (ni === void 0) return void 0;
+	const node = graph.nodes[ni];
+	if (node.parentId === null) return void 0;
+	const pi = idx.nodeById.get(node.parentId);
+	return pi !== void 0 ? graph.nodes[pi] : void 0;
+}
+function getAncestors(graph, nodeId) {
+	const idx = getIndex(graph);
+	const result = [];
+	let ni = idx.nodeById.get(nodeId);
+	if (ni === void 0) return result;
+	let current = graph.nodes[ni];
+	while (current && current.parentId !== null) {
+		const pi = idx.nodeById.get(current.parentId);
+		if (pi === void 0) break;
+		const p = graph.nodes[pi];
+		result.push(p);
+		current = p;
+	}
+	return result;
+}
+function getDescendants(graph, nodeId) {
+	const idx = getIndex(graph);
+	const result = [];
+	const collect = (id) => {
+		const childIds = idx.childNodes.get(id) ?? [];
+		for (const childId of childIds) {
+			const ci = idx.nodeById.get(childId);
+			if (ci !== void 0) {
+				result.push(graph.nodes[ci]);
+				collect(childId);
+			}
+		}
+	};
+	collect(nodeId);
+	return result;
+}
+function getRoots(graph) {
+	const idx = getIndex(graph);
+	return idx.childNodes.get(null)?.map((id) => graph.nodes[idx.nodeById.get(id)]).filter(Boolean) ?? [];
+}
+/** Whether a node has children (is a compound/group node). */
+function isCompound(graph, nodeId) {
+	return (getIndex(graph).childNodes.get(nodeId) ?? []).length > 0;
+}
+/** Whether a node has no children (is a leaf/atomic node). */
+function isLeaf(graph, nodeId) {
+	return !isCompound(graph, nodeId);
+}
+/** Depth of a node in the hierarchy (root = 0). */
+function getDepth(graph, nodeId) {
+	const idx = getIndex(graph);
+	let d = 0;
+	let ni = idx.nodeById.get(nodeId);
+	if (ni === void 0) return -1;
+	let current = graph.nodes[ni];
+	while (current.parentId !== null) {
+		d++;
+		const pi = idx.nodeById.get(current.parentId);
+		if (pi === void 0) break;
+		current = graph.nodes[pi];
+	}
+	return d;
+}
+/** Sibling nodes (same parentId, excluding the node itself). */
+function getSiblings(graph, nodeId) {
+	const idx = getIndex(graph);
+	const ni = idx.nodeById.get(nodeId);
+	if (ni === void 0) return [];
+	const node = graph.nodes[ni];
+	return (idx.childNodes.get(node.parentId) ?? []).filter((id) => id !== nodeId).map((id) => graph.nodes[idx.nodeById.get(id)]).filter(Boolean);
+}
+/**
+* Least Common Ancestor — deepest proper ancestor of all given nodes.
+* A proper ancestor excludes the input nodes themselves.
+*/
+function getLCA(graph, ...nodeIds) {
+	if (nodeIds.length === 0) return void 0;
+	const idx = getIndex(graph);
+	const getAncestorChain = (id) => {
+		const result = [id];
+		let ni$1 = idx.nodeById.get(id);
+		if (ni$1 === void 0) return result;
+		let current = graph.nodes[ni$1];
+		while (current.parentId !== null) {
+			result.push(current.parentId);
+			const pi = idx.nodeById.get(current.parentId);
+			if (pi === void 0) break;
+			current = graph.nodes[pi];
+		}
+		return result;
+	};
+	let common = getAncestorChain(nodeIds[0]);
+	for (let i = 1; i < nodeIds.length; i++) {
+		const set = new Set(getAncestorChain(nodeIds[i]));
+		common = common.filter((id) => set.has(id));
+	}
+	const inputSet = new Set(nodeIds);
+	common = common.filter((id) => !inputSet.has(id));
+	if (common.length === 0) return void 0;
+	const lcaId = common[0];
+	const ni = idx.nodeById.get(lcaId);
+	return ni !== void 0 ? graph.nodes[ni] : void 0;
+}
+/** Nodes with no incoming edges (inDegree 0). */
+function getSources(graph) {
+	const idx = getIndex(graph);
+	return graph.nodes.filter((n) => (idx.inEdges.get(n.id)?.length ?? 0) === 0);
+}
+/** Nodes with no outgoing edges (outDegree 0). */
+function getSinks(graph) {
+	const idx = getIndex(graph);
+	return graph.nodes.filter((n) => (idx.outEdges.get(n.id)?.length ?? 0) === 0);
+}
+
+//#endregion
+export { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPredecessors, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf };

package/dist/schemas.d.mts

@@ -0,0 +1,46 @@
+import * as z from "zod";
+
+//#region src/schemas.d.ts
+declare const NodeSchema: z.ZodObject<{
+  type: z.ZodLiteral<"node">;
+  id: z.ZodString;
+  parentId: z.ZodNullable<z.ZodString>;
+  initialNodeId: z.ZodNullable<z.ZodString>;
+  label: z.ZodString;
+  data: z.ZodAny;
+}, z.core.$strip>;
+declare const EdgeSchema: z.ZodObject<{
+  type: z.ZodLiteral<"edge">;
+  id: z.ZodString;
+  sourceId: z.ZodString;
+  targetId: z.ZodString;
+  label: z.ZodString;
+  data: z.ZodAny;
+}, z.core.$strip>;
+declare const GraphSchema: z.ZodObject<{
+  id: z.ZodString;
+  type: z.ZodEnum<{
+    directed: "directed";
+    undirected: "undirected";
+  }>;
+  initialNodeId: z.ZodNullable<z.ZodString>;
+  nodes: z.ZodArray<z.ZodObject<{
+    type: z.ZodLiteral<"node">;
+    id: z.ZodString;
+    parentId: z.ZodNullable<z.ZodString>;
+    initialNodeId: z.ZodNullable<z.ZodString>;
+    label: z.ZodString;
+    data: z.ZodAny;
+  }, z.core.$strip>>;
+  edges: z.ZodArray<z.ZodObject<{
+    type: z.ZodLiteral<"edge">;
+    id: z.ZodString;
+    sourceId: z.ZodString;
+    targetId: z.ZodString;
+    label: z.ZodString;
+    data: z.ZodAny;
+  }, z.core.$strip>>;
+  data: z.ZodAny;
+}, z.core.$strip>;
+//#endregion
+export { EdgeSchema, GraphSchema, NodeSchema };

package/dist/schemas.mjs

@@ -0,0 +1,30 @@
+import * as z from "zod";
+
+//#region src/schemas.ts
+const NodeSchema = z.object({
+	type: z.literal("node"),
+	id: z.string(),
+	parentId: z.string().nullable(),
+	initialNodeId: z.string().nullable(),
+	label: z.string(),
+	data: z.any()
+});
+const EdgeSchema = z.object({
+	type: z.literal("edge"),
+	id: z.string(),
+	sourceId: z.string(),
+	targetId: z.string(),
+	label: z.string(),
+	data: z.any()
+});
+const GraphSchema = z.object({
+	id: z.string(),
+	type: z.enum(["directed", "undirected"]),
+	initialNodeId: z.string().nullable(),
+	nodes: z.array(NodeSchema),
+	edges: z.array(EdgeSchema),
+	data: z.any()
+});
+
+//#endregion
+export { EdgeSchema, GraphSchema, NodeSchema };

package/dist/types-XV3S5Jnh.d.mts

@@ -0,0 +1,219 @@
+//#region src/types.d.ts
+interface EntityRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+interface GraphConfig<TNodeData = any, TEdgeData = any, TGraphData = any> {
+  id?: string;
+  type?: 'directed' | 'undirected';
+  initialNodeId?: string;
+  nodes?: NodeConfig<TNodeData>[];
+  edges?: EdgeConfig<TEdgeData>[];
+  data?: TGraphData;
+  direction?: 'up' | 'down' | 'left' | 'right';
+  style?: Record<string, string | number>;
+}
+interface NodeConfig<TNodeData = any> {
+  id: string;
+  parentId?: string | null;
+  initialNodeId?: string;
+  label?: string;
+  data?: TNodeData;
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  shape?: string;
+  color?: string;
+  style?: Record<string, string | number>;
+}
+interface EdgeConfig<TEdgeData = any> {
+  /**
+   * The id of the edge.
+   */
+  id: string;
+  /**
+   * The id of the source node.
+   */
+  sourceId: string;
+  /**
+   * The id of the target node.
+   */
+  targetId: string;
+  /**
+   * The label of the edge.
+   */
+  label?: string;
+  data?: TEdgeData;
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  color?: string;
+  style?: Record<string, string | number>;
+}
+interface Graph<TNodeData = any, TEdgeData = any, TGraphData = any> {
+  id: string;
+  type: 'directed' | 'undirected';
+  initialNodeId: string | null;
+  nodes: GraphNode<TNodeData>[];
+  edges: GraphEdge<TEdgeData>[];
+  data: TGraphData;
+  direction?: 'up' | 'down' | 'left' | 'right';
+  style?: Record<string, string | number>;
+}
+interface GraphNode<TNodeData = any> {
+  type: 'node';
+  id: string;
+  parentId: string | null;
+  initialNodeId: string | null;
+  label: string;
+  data: TNodeData;
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  shape?: string;
+  color?: string;
+  style?: Record<string, string | number>;
+}
+interface GraphEdge<TEdgeData = any> {
+  type: 'edge';
+  id: string;
+  sourceId: string;
+  targetId: string;
+  label: string;
+  data: TEdgeData;
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  color?: string;
+  style?: Record<string, string | number>;
+}
+interface VisualNode<TNodeData = any> extends Omit<GraphNode<TNodeData>, keyof EntityRect>, EntityRect {
+  shape: string;
+}
+interface VisualEdge<TEdgeData = any> extends Omit<GraphEdge<TEdgeData>, keyof EntityRect>, EntityRect {}
+interface VisualGraph<TNodeData = any, TEdgeData = any, TGraphData = any> extends Omit<Graph<TNodeData, TEdgeData, TGraphData>, 'nodes' | 'edges'> {
+  nodes: VisualNode<TNodeData>[];
+  edges: VisualEdge<TEdgeData>[];
+  direction: 'up' | 'down' | 'left' | 'right';
+}
+interface VisualGraphConfig<TNodeData = any, TEdgeData = any, TGraphData = any> extends GraphConfig<TNodeData, TEdgeData, TGraphData> {
+  direction?: 'up' | 'down' | 'left' | 'right';
+}
+interface DeleteNodeOptions {
+  reparent?: boolean;
+}
+interface EntitiesConfig<TNodeData = any, TEdgeData = any> {
+  nodes?: NodeConfig<TNodeData>[];
+  edges?: EdgeConfig<TEdgeData>[];
+}
+interface EntitiesUpdate<TNodeData = any, TEdgeData = any> {
+  nodes?: (Partial<Omit<NodeConfig<TNodeData>, 'id'>> & {
+    id: string;
+  })[];
+  edges?: (Partial<Omit<EdgeConfig<TEdgeData>, 'id'>> & {
+    id: string;
+  })[];
+}
+interface GraphStep<TNodeData = any, TEdgeData = any> {
+  /** Edge traversed to reach this node */
+  edge: GraphEdge<TEdgeData>;
+  /** Node reached after traversing the edge */
+  node: GraphNode<TNodeData>;
+}
+interface GraphPath<TNodeData = any, TEdgeData = any> {
+  /** The source node where this path begins. */
+  source: GraphNode<TNodeData>;
+  /** Ordered steps from source to target.
+   *  `path.steps.at(-1)?.node` is the final/target node.
+   *  Empty steps = source-only path. */
+  steps: GraphStep<TNodeData, TEdgeData>[];
+}
+interface PathOptions<TEdgeData = any> {
+  /** Source node ID. Default: graph.initialNodeId, else sole inDegree-0 node */
+  from?: string;
+  /** Target node ID. If omitted → paths to all reachable nodes */
+  to?: string;
+  /** Edge weight function. Default: every edge = 1. */
+  getWeight?: (edge: GraphEdge<TEdgeData>) => number;
+}
+interface SinglePathOptions<TEdgeData = any> {
+  /** Source node ID. Default: graph.initialNodeId, else sole inDegree-0 node */
+  from?: string;
+  /** Target node ID. Required for single-path queries. */
+  to: string;
+  /** Edge weight function. Default: every edge = 1. */
+  getWeight?: (edge: GraphEdge<TEdgeData>) => number;
+}
+interface TraversalOptions {
+  /** Source node ID. Default: graph.initialNodeId, else sole inDegree-0 node */
+  from?: string;
+}
+interface MSTOptions<TEdgeData = any> {
+  /** Algorithm to use. Default: 'prim'. */
+  algorithm?: 'prim' | 'kruskal';
+  /** Edge weight function. Default: every edge = 1. */
+  getWeight?: (edge: GraphEdge<TEdgeData>) => number;
+}
+interface AllPairsShortestPathsOptions<TEdgeData = any> {
+  /** Algorithm to use. Default: 'dijkstra'. */
+  algorithm?: 'floyd-warshall' | 'dijkstra';
+  /** Edge weight function. Default: every edge = 1. */
+  getWeight?: (edge: GraphEdge<TEdgeData>) => number;
+}
+interface NodeChange<TNodeData = any> {
+  id: string;
+  old: Partial<GraphNode<TNodeData>>;
+  new: Partial<GraphNode<TNodeData>>;
+}
+interface EdgeChange<TEdgeData = any> {
+  id: string;
+  old: Partial<GraphEdge<TEdgeData>>;
+  new: Partial<GraphEdge<TEdgeData>>;
+}
+interface GraphDiff<TNodeData = any, TEdgeData = any> {
+  nodes: {
+    added: NodeConfig<TNodeData>[];
+    removed: NodeConfig<TNodeData>[];
+    updated: NodeChange<TNodeData>[];
+  };
+  edges: {
+    added: EdgeConfig<TEdgeData>[];
+    removed: EdgeConfig<TEdgeData>[];
+    updated: EdgeChange<TEdgeData>[];
+  };
+}
+type GraphPatch<TNodeData = any, TEdgeData = any> = {
+  op: 'addNode';
+  node: NodeConfig<TNodeData>;
+  description?: string;
+} | {
+  op: 'updateNode';
+  id: string;
+  data: Partial<Omit<NodeConfig<TNodeData>, 'id'>>;
+  description?: string;
+} | {
+  op: 'deleteNode';
+  id: string;
+  description?: string;
+} | {
+  op: 'addEdge';
+  edge: EdgeConfig<TEdgeData>;
+  description?: string;
+} | {
+  op: 'updateEdge';
+  id: string;
+  data: Partial<Omit<EdgeConfig<TEdgeData>, 'id'>>;
+  description?: string;
+} | {
+  op: 'deleteEdge';
+  id: string;
+  description?: string;
+};
+//#endregion
+export { VisualGraph as C, VisualEdge as S, VisualNode as T, NodeChange as _, EntitiesConfig as a, SinglePathOptions as b, Graph as c, GraphEdge as d, GraphNode as f, MSTOptions as g, GraphStep as h, EdgeConfig as i, GraphConfig as l, GraphPath as m, DeleteNodeOptions as n, EntitiesUpdate as o, GraphPatch as p, EdgeChange as r, EntityRect as s, AllPairsShortestPathsOptions as t, GraphDiff as u, NodeConfig as v, VisualGraphConfig as w, TraversalOptions as x, PathOptions as y };

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@statelyai/graph",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "A TypeScript-first graph library with plain JSON-serializable objects",
+  "author": "David Khourshid <david@stately.ai>",
+  "license": "MIT",
+  "homepage": "https://github.com/statelyai/graph#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/statelyai/graph.git"
+  },
+  "bugs": {
+    "url": "https://github.com/statelyai/graph/issues"
+  },
+  "keywords": [
+    "graph",
+    "directed",
+    "undirected",
+    "dag",
+    "algorithms",
+    "typescript"
+  ],
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./algorithms": "./dist/algorithms.mjs",
+    "./formats/adjacency-list": "./dist/formats/adjacency-list.mjs",
+    "./formats/dot": "./dist/formats/dot.mjs",
+    "./formats/edge-list": "./dist/formats/edge-list.mjs",
+    "./formats/graphml": "./dist/formats/graphml.mjs",
+    "./queries": "./dist/queries.mjs",
+    "./schemas": "./dist/schemas.mjs",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "schemas"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit",
+    "generate-schema": "tsx scripts/generate-json-schema.ts",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "pnpm run build && changeset publish",
+    "prepublishOnly": "pnpm run build"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.29.8",
+    "@types/node": "^25.0.3",
+    "bumpp": "^10.3.2",
+    "fast-xml-parser": "^5.3.4",
+    "tsdown": "^0.18.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "fast-xml-parser": "^5.0.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "fast-xml-parser": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  }
+}

package/schemas/edge.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "edge"
+    },
+    "id": {
+      "type": "string"
+    },
+    "sourceId": {
+      "type": "string"
+    },
+    "targetId": {
+      "type": "string"
+    },
+    "label": {
+      "type": "string"
+    },
+    "data": {}
+  },
+  "required": [
+    "type",
+    "id",
+    "sourceId",
+    "targetId",
+    "label",
+    "data"
+  ],
+  "additionalProperties": false
+}