Skip to main content

​
Format Conversion

The @statelyai/graph library provides comprehensive support for converting graphs to and from popular graph formats. All converters follow a consistent bidirectional pattern with to* and from* functions.

​
Supported Formats

Cytoscape.js

JSON format for Cytoscape.js visualization

D3.js

Force-directed graph format for D3

DOT (Graphviz)

Text format for Graphviz rendering

GraphML

XML-based graph markup language

GEXF

Graph Exchange XML Format

Mermaid

Diagram-as-code with 7 diagram types

Other Formats

JGF, GML, TGF, edge lists, and more

​
Format Comparison

FormatTypeCompound GraphsVisual DataPeer Dependency
Cytoscape.jsJSON✅ Yes✅ Position, color, shapeNone
D3.jsJSON❌ No✅ Position, colorNone
DOTText✅ Yes (subgraphs)✅ Color, shape, layoutdotparser
GraphMLXML✅ Yes✅ Full visual supportfast-xml-parser
GEXFXML✅ Yes✅ Full visual + viz modulefast-xml-parser
JGFJSON✅ Yes✅ Full visual supportNone
GMLText✅ Yes (nested)✅ Graphics blockNone
TGFText❌ No❌ Labels onlyNone
Edge ListArray❌ No❌ No metadataNone
Adjacency ListObject❌ No❌ No metadataNone
XYFlowJSON✅ Yes✅ Position, size@xyflow/system
MermaidTextVaries by type✅ LimitedNone

​
Creating Custom Converters

​
createFormatConverter()

Create a bidirectional converter from a pair of to/from functions. 
import { createFormatConverter } from '@statelyai/graph';

const yamlConverter = createFormatConverter(
  (graph) => toYAML(graph),
  (yaml) => fromYAML(yaml),
);

const yaml = yamlConverter.to(graph);
const graph = yamlConverter.from(yaml);

​
Type Signature

function createFormatConverter<TSerial>(
  to: (graph: Graph) => TSerial,
  from: (input: TSerial) => Graph,
): GraphFormatConverter<TSerial>

​
Parameters

​
to
function
required
Function that converts a Graph to the serialized format
​
from
function
required
Function that parses the serialized format back into a Graph

​
Returns

A GraphFormatConverter<TSerial> object with to and from methods.

​
Converter Pattern

All format converters follow this pattern: 
// Standalone functions
const json = toCytoscapeJSON(graph);
const graph = fromCytoscapeJSON(json);

// Or use the converter object
const json = cytoscapeConverter.to(graph);
const graph = cytoscapeConverter.from(json);

​
Peer Dependencies

Some format converters require peer dependencies: 
# For DOT format
pnpm add dotparser

# For GraphML and GEXF formats
pnpm add fast-xml-parser

# For XYFlow format
pnpm add @xyflow/system
All peer dependencies are optional and only needed when using the corresponding format.

​
Installation

Format converters are included in the main package: 
pnpm add @statelyai/graph
Then import from subpaths: 
import { toCytoscapeJSON, fromCytoscapeJSON } from '@statelyai/graph';
// Or from format-specific paths:
import { toCytoscapeJSON } from '@statelyai/graph/cytoscape';

​
Error Handling

All from* parsers validate input and throw descriptive errors: 
try {
  const graph = fromDOT(invalidDotString);
} catch (error) {
  console.error(error.message);
  // "DOT: parse error — unexpected token"
}

​
Next Steps

Cytoscape.js Format

Learn about Cytoscape.js conversion

Mermaid Diagrams

Convert to/from Mermaid diagrams

Build docs developers (and LLMs) love

Get started for freeTalk to us