@statelyai/graph 0.3.0 → 0.4.0

package/README.md

@@ -4,17 +4,6 @@ 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
 
@@ -126,6 +115,18 @@ const back = cytoscapeConverter.from(cyto);
 const myConverter = createFormatConverter(myToFn, myFromFn);
 ```
 
+## 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.
+
 ## API
 
 ### Graph Creation

package/dist/{adjacency-list-A4_Eiwj3.mjs → adjacency-list-Bv4tfiM3.mjs}

@@ -1,4 +1,20 @@
 //#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();