@statelyai/graph 0.1.0 → 0.3.1

package/README.md

@@ -4,6 +4,18 @@ A TypeScript graph library built on plain JSON objects. Supports directed/undire
 
 Made from our experience at [stately.ai](https://stately.ai), where we build visual tools for complex systems.
 
+## Why this library?
+
+Graph file formats (GEXF, GraphML) define how to _store_ graphs. Visualization libraries (Cytoscape.js, D3) define how to _render_ them. Neither gives you a good way to _work with_ them in between.
+
+This library is the computational layer: plain JSON objects in, algorithms and mutations, plain JSON objects out. No classes, no DOM, no rendering engine — just data and functions.
+
+```
+GEXF file → fromGEXF() → Graph → run algorithms, mutate → toCytoscapeJSON() → render
+```
+
+Your `Graph` is a plain object that survives `JSON.stringify`, `structuredClone`, `postMessage`, and `localStorage` without adapters. Format converters are the I/O ports — read from any supported format, do your work, export to whatever your renderer or database expects.
+
 ## Install
 
 ```bash
@@ -77,22 +89,41 @@ const diagram = createVisualGraph({
 });
 ```
 
-### Serialization
+### Format Conversion
 
 ```ts
-import { toDOT, toGraphML, toAdjacencyList, toEdgeList } from '@statelyai/graph';
+import { toCytoscapeJSON } from '@statelyai/graph/cytoscape';
+import { fromJGF } from '@statelyai/graph/jgf';
+import { toD3Graph } from '@statelyai/graph/d3';
+import { toDOT } from '@statelyai/graph/dot';
+import { toGraphML } from '@statelyai/graph/graphml';
+import { fromGEXF } from '@statelyai/graph/gexf';
+
+// Export to web visualization libraries
+const cytoData = toCytoscapeJSON(graph); // Cytoscape.js JSON (compound graphs preserved)
+const d3Data = toD3Graph(graph);         // D3.js { nodes, links }
+
+// Export to text formats
+const dot = toDOT(graph);               // Graphviz DOT
+const xml = toGraphML(graph);            // GraphML XML
+
+// Import from any format
+const g1 = fromJGF(jsonGraphData);       // JSON Graph Format
+const g2 = fromGEXF(gexfXmlString);      // GEXF (Gephi)
+```
 
-console.log(toDOT(graph));
-// Logs a Graphviz DOT string
+Each bidirectional format also has a converter object for a unified interface:
 
-console.log(toGraphML(graph));
-// Logs a GraphML XML string
+```ts
+import { createFormatConverter } from '@statelyai/graph';
+import { cytoscapeConverter } from '@statelyai/graph/cytoscape';
 
-console.log(toAdjacencyList(graph));
-// Logs an adjacency object, e.g. { a: ['b'], b: ['c'] }
+// Use a built-in converter
+const cyto = cytoscapeConverter.to(graph);
+const back = cytoscapeConverter.from(cyto);
 
-console.log(toEdgeList(graph));
-// Logs an array of [sourceId, targetId] pairs, e.g. [['a', 'b'], ['b', 'c']]
+// Create your own
+const myConverter = createFormatConverter(myToFn, myFromFn);
 ```
 
 ## API
@@ -176,15 +207,34 @@ console.log(toEdgeList(graph));
 
 Generator variants: `genShortestPaths`, `genSimplePaths`, `genCycles`, `genPreorders`, `genPostorders`.
 
-### Transforms & Formats
+### Transforms
 
 | Function | Description |
 |----------|-------------|
 | `flatten(graph)` | Decompose hierarchy into flat leaf-node graph |
-| `toDOT` / `toGraphML` | Export to Graphviz DOT / GraphML |
-| `fromGraphML` | Import from GraphML |
-| `toAdjacencyList` / `fromAdjacencyList` | Adjacency list conversion |
-| `toEdgeList` / `fromEdgeList` | Edge list conversion |
+
+### Formats
+
+Import format converters from subpaths (for example, `@statelyai/graph/dot` or `@statelyai/graph/mermaid`).
+
+| Format | Export | Import | Compound? | Notes |
+|--------|--------|--------|-----------|-------|
+| **Cytoscape.js JSON** | `toCytoscapeJSON` | `fromCytoscapeJSON` | Yes | `parent` maps to `parentId` |
+| **D3.js JSON** | `toD3Graph` | `fromD3Graph` | No | `{ nodes, links }` for force layouts |
+| **JSON Graph Format** | `toJGF` | `fromJGF` | Yes | Formal spec, metadata-extensible |
+| **GEXF** | `toGEXF` | `fromGEXF` | Yes | Gephi native, `pid` hierarchy, viz module |
+| **GraphML** | `toGraphML` | `fromGraphML` | Yes | XML standard, requires `fast-xml-parser` |
+| **GML** | `toGML` | `fromGML` | Yes | Nested node blocks for hierarchy |
+| **TGF** | `toTGF` | `fromTGF` | No | Minimal (id + label only) |
+| **DOT** | `toDOT` | `fromDOT` | Yes (subgraphs) | Graphviz DOT (`dotparser` peer dep) |
+| **Mermaid** | `toMermaid*` | `fromMermaid*` | Varies by diagram | Sequence, flowchart, state, class, ER, mindmap, block |
+| **Adjacency list** | `toAdjacencyList` | `fromAdjacencyList` | No | `Record<string, string[]>` |
+| **Edge list** | `toEdgeList` | `fromEdgeList` | No | `[source, target][]` |
+
+Optional peer deps by format:
+- `@statelyai/graph/gexf` and `@statelyai/graph/graphml` use `fast-xml-parser`
+- `@statelyai/graph/dot` uses `dotparser`
+- Other formats are dependency-free
 
 ## License
 

package/dist/{adjacency-list-CXpOCibq.mjs → adjacency-list-ITO40kmn.mjs}

@@ -1,4 +1,20 @@
-//#region src/formats/adjacency-list.ts
+//#region src/formats/adjacency-list/index.ts
+/**
+* Converts a graph to an adjacency list representation.
+*
+* @example
+* ```ts
+* import { createGraph, toAdjacencyList } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: { a: {}, b: {}, c: {} },
+*   edges: [{ source: 'a', target: 'b' }, { source: 'a', target: 'c' }],
+* });
+*
+* toAdjacencyList(graph);
+* // { a: ['b', 'c'], b: [], c: [] }
+* ```
+*/
 function toAdjacencyList(graph) {
 	const adj = {};
 	for (const node of graph.nodes) adj[node.id] = [];
@@ -8,6 +24,23 @@ function toAdjacencyList(graph) {
 	}
 	return adj;
 }
+/**
+* Parses an adjacency list into a graph.
+*
+* @example
+* ```ts
+* import { fromAdjacencyList } from '@statelyai/graph';
+*
+* const graph = fromAdjacencyList({
+*   a: ['b', 'c'],
+*   b: ['c'],
+*   c: [],
+* });
+*
+* graph.nodes; // [{id: 'a', ...}, {id: 'b', ...}, {id: 'c', ...}]
+* graph.edges; // [{sourceId: 'a', targetId: 'b', ...}, ...]
+* ```
+*/
 function fromAdjacencyList(adj, options) {
 	const directed = options?.directed ?? true;
 	const seen = /* @__PURE__ */ new Set();