Other Formats

Additional graph format converters for specialized use cases.

JSON Graph Format (JGF)

JGF is a standardized JSON format for representing graphs.

Import

import { toJGF, fromJGF, jgfConverter } from '@statelyai/graph';
// Or:
import { toJGF } from '@statelyai/graph/jgf';

Example

import { createGraph, toJGF } from '@statelyai/graph';

const graph = createGraph({
  id: 'MyGraph',
  nodes: [
    { id: 'a', label: 'Node A', data: { priority: 1 } },
    { id: 'b', label: 'Node B', parentId: 'container' }
  ],
  edges: [
    { id: 'e0', sourceId: 'a', targetId: 'b', data: { weight: 5 } }
  ],
  data: { version: '1.0' }
});

const jgf = toJGF(graph);

Result:

{
  "graph": {
    "id": "MyGraph",
    "directed": true,
    "metadata": {
      "data": { "version": "1.0" }
    },
    "nodes": [
      {
        "id": "a",
        "label": "Node A",
        "metadata": {
          "data": { "priority": 1 }
        }
      },
      {
        "id": "b",
        "label": "Node B",
        "metadata": {
          "parentId": "container"
        }
      }
    ],
    "edges": [
      {
        "id": "e0",
        "source": "a",
        "target": "b",
        "metadata": {
          "data": { "weight": 5 }
        }
      }
    ]
  }
}

Features

✅ Compound graphs (via parentId in metadata)
✅ Visual properties (position, size, color in metadata)
✅ Custom data preservation
✅ No dependencies

Type Definitions

interface JGFNode {
  id: string;
  label?: string;
  metadata?: Record<string, any>;
}

interface JGFEdge {
  id?: string;
  source: string;
  target: string;
  label?: string;
  metadata?: Record<string, any>;
}

interface JGFGraph {
  graph: {
    id?: string;
    directed?: boolean;
    metadata?: Record<string, any>;
    nodes: JGFNode[];
    edges: JGFEdge[];
  };
}

GML (Graph Modelling Language)

Text-based format with simple key-value syntax.

Import

import { toGML, fromGML, gmlConverter } from '@statelyai/graph';
// Or:
import { toGML } from '@statelyai/graph/gml';

Example

import { createGraph, toGML } from '@statelyai/graph';

const graph = createGraph({
  id: 'MyGraph',
  nodes: [
    { id: 'a', label: 'Node A', x: 0, y: 0 },
    { id: 'b', label: 'Node B', x: 100, y: 100, parentId: 'container' },
    { id: 'container', label: 'Container' }
  ],
  edges: [
    { id: 'e0', sourceId: 'a', targetId: 'b' }
  ]
});

const gml = toGML(graph);

Result:

graph [
  directed 1
  id "MyGraph"
  node [
    id "a"
    label "Node A"
    graphics [
      x 0
      y 0
    ]
  ]
  node [
    id "container"
    label "Container"
    node [
      id "b"
      label "Node B"
      graphics [
        x 100
        y 100
      ]
    ]
  ]
  edge [
    id "e0"
    source "a"
    target "b"
  ]
]

Features

✅ Compound graphs (nested node syntax)
✅ Graphics properties (x, y, width, height)
✅ Custom data (JSON-serialized)
✅ No dependencies
✅ Human-readable format

Graphics Block

Visual properties are stored in a graphics block:

Property	GML Key
`node.x`	`graphics { x ... }`
`node.y`	`graphics { y ... }`
`node.width`	`graphics { w ... }`
`node.height`	`graphics { h ... }`

TGF (Trivial Graph Format)

Minimalist format: nodes, separator, edges.

Import

import { toTGF, fromTGF, tgfConverter } from '@statelyai/graph';
// Or:
import { toTGF } from '@statelyai/graph/tgf';

Example

import { createGraph, toTGF } from '@statelyai/graph';

const graph = createGraph({
  nodes: [
    { id: 'a', label: 'Alice' },
    { id: 'b', label: 'Bob' },
    { id: 'c', label: 'Charlie' }
  ],
  edges: [
    { id: 'e0', sourceId: 'a', targetId: 'b', label: 'knows' },
    { id: 'e1', sourceId: 'b', targetId: 'c', label: 'works with' }
  ]
});

const tgf = toTGF(graph);

Result:

a Alice
b Bob
c Charlie
#
a b knows
b c works with

Format Specification

Node section: id [label] (one per line)
Separator: # on its own line
Edge section: source target [label] (one per line)

Features

❌ No compound graphs
❌ No visual properties
✅ Extremely simple format
✅ No dependencies
✅ Easy to hand-write

Edge List

Simplest format: array of [source, target] tuples.

Import

import { toEdgeList, fromEdgeList, edgeListConverter } from '@statelyai/graph';

Example

import { createGraph, toEdgeList } from '@statelyai/graph';

const graph = createGraph({
  nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
  edges: [
    { sourceId: 'a', targetId: 'b' },
    { sourceId: 'b', targetId: 'c' }
  ]
});

const edges = toEdgeList(graph);
// [['a', 'b'], ['b', 'c']]

Parsing

import { fromEdgeList } from '@statelyai/graph';

const graph = fromEdgeList(
  [['a', 'b'], ['b', 'c']],
  { directed: true, id: 'MyGraph' }
);

Type Signature

function toEdgeList(graph: Graph): [string, string][]

function fromEdgeList(
  edges: [string, string][],
  options?: { directed?: boolean; id?: string }
): Graph

Features

❌ No node metadata
❌ No edge metadata
❌ No compound graphs
✅ Minimal format
✅ No dependencies

Adjacency List

Object mapping node IDs to arrays of neighbor IDs.

Import

import { toAdjacencyList, fromAdjacencyList, adjacencyListConverter } from '@statelyai/graph';

Example

import { createGraph, toAdjacencyList } from '@statelyai/graph';

const graph = createGraph({
  nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
  edges: [
    { sourceId: 'a', targetId: 'b' },
    { sourceId: 'a', targetId: 'c' }
  ]
});

const adj = toAdjacencyList(graph);
// { a: ['b', 'c'], b: [], c: [] }

Undirected Graphs

import { createGraph, toAdjacencyList } from '@statelyai/graph';

const graph = createGraph({
  type: 'undirected',
  nodes: [{ id: 'a' }, { id: 'b' }],
  edges: [{ sourceId: 'a', targetId: 'b' }]
});

const adj = toAdjacencyList(graph);
// { a: ['b'], b: ['a'] }  // Symmetric!

Parsing

import { fromAdjacencyList } from '@statelyai/graph';

const graph = fromAdjacencyList(
  {
    a: ['b', 'c'],
    b: ['c'],
    c: []
  },
  { directed: true, id: 'MyGraph' }
);

Type Signature

function toAdjacencyList(graph: Graph): Record<string, string[]>

function fromAdjacencyList(
  adj: Record<string, string[]>,
  options?: { directed?: boolean; id?: string }
): Graph

Features

❌ No node metadata
❌ No edge metadata
❌ No compound graphs
✅ Compact representation
✅ No dependencies
✅ Natural for algorithms

XYFlow (React Flow / Svelte Flow)

Format for React Flow and Svelte Flow.

Installation

Requires the @xyflow/system peer dependency:

pnpm add @xyflow/system

Import

import { toXYFlow, fromXYFlow, xyflowConverter } from '@statelyai/graph';
// Or:
import { toXYFlow } from '@statelyai/graph/xyflow';

Example

import { createVisualGraph, toXYFlow } from '@statelyai/graph';

const graph = createVisualGraph({
  nodes: [
    { id: 'a', x: 0, y: 0, width: 100, height: 50, label: 'Node A' },
    { id: 'b', x: 200, y: 100, width: 100, height: 50, label: 'Node B' }
  ],
  edges: [
    { id: 'e0', sourceId: 'a', targetId: 'b' }
  ]
});

const flow = toXYFlow(graph);

Result:

{
  "nodes": [
    {
      "id": "a",
      "position": { "x": 0, "y": 0 },
      "data": {},
      "width": 100,
      "height": 50
    },
    {
      "id": "b",
      "position": { "x": 200, "y": 100 },
      "data": {},
      "width": 100,
      "height": 50
    }
  ],
  "edges": [
    {
      "id": "e0",
      "source": "a",
      "target": "b"
    }
  ]
}

Features

✅ Compound graphs (via parentId)
✅ Required position and size
✅ Custom data
✅ Node types (mapped to shape)

Mapping

Graph Property	XYFlow Property	Notes
`node.id`	`id`	Required
`node.x, node.y`	`position: { x, y }`	Required
`node.width, node.height`	`width`, `height`	Dimensions
`node.shape`	`type`	Node type
`node.parentId`	`parentId`	Parent node
`node.data`	`data`	Custom data
`edge.label`	`data.label`	Stored in data

Usage with React Flow

import { toXYFlow } from '@statelyai/graph';
import { ReactFlow } from '@xyflow/react';

function FlowChart() {
  const { nodes, edges } = toXYFlow(graph);
  
  return (
    <ReactFlow 
      nodes={nodes} 
      edges={edges}
    />
  );
}

Type Definitions

import type { NodeBase, EdgeBase } from '@xyflow/system';

type XYFlowNode<TNodeData = Record<string, unknown>> = NodeBase<TNodeData>;
type XYFlowEdge<TEdgeData = Record<string, unknown>> = EdgeBase<TEdgeData>;

interface XYFlow<TNodeData = any, TEdgeData = any> {
  nodes: XYFlowNode<TNodeData>[];
  edges: XYFlowEdge<TEdgeData>[];
}

Format Comparison

Format	Type	Metadata	Compound	Dependencies
JGF	JSON	✅ Full	✅ Yes	None
GML	Text	✅ Full	✅ Nested	None
TGF	Text	⚠️ Labels only	❌ No	None
Edge List	Array	❌ None	❌ No	None
Adjacency List	Object	❌ None	❌ No	None
XYFlow	JSON	✅ Full	✅ Yes	`@xyflow/system`

Use Cases

JGF

Interoperability with other tools
Full graph data preservation
Web APIs and data exchange

GML

yEd graph editor
Human-readable storage
Version control friendly

TGF

Quick prototyping
Hand-written graphs
Educational examples

Edge List

Algorithm input
Network analysis
Large sparse graphs

Adjacency List

Traversal algorithms
Graph algorithms textbooks
Performance-critical code

XYFlow

React Flow applications
Svelte Flow applications
Interactive graph editors

Graph Operations

Queries

Algorithms

Transforms

Diff & Patches

Format Conversion

Documentation Index

​Other Formats

​JSON Graph Format (JGF)

​Import

​Example

​Features

​Type Definitions

​GML (Graph Modelling Language)

​Import

​Example

​Features

​Graphics Block

​TGF (Trivial Graph Format)

​Import

​Example

​Format Specification

​Features

​Edge List

​Import

​Example

​Parsing

​Type Signature

​Features

​Adjacency List

​Import

​Example

​Undirected Graphs

​Parsing

​Type Signature

​Features

​XYFlow (React Flow / Svelte Flow)

​Installation

​Import

​Example

​Features

​Mapping

​Usage with React Flow

​Type Definitions

​Format Comparison

​Use Cases

​JGF

​GML

​TGF

​Edge List

​Adjacency List

​XYFlow

​See Also

Build docs developers (and LLMs) love

Other Formats

JSON Graph Format (JGF)

Import

Example

Features

Type Definitions

GML (Graph Modelling Language)

Import

Example

Features

Graphics Block

TGF (Trivial Graph Format)

Import

Example

Format Specification

Features

Edge List

Import

Example

Parsing

Type Signature

Features

Adjacency List

Import

Example

Undirected Graphs

Parsing

Type Signature

Features

XYFlow (React Flow / Svelte Flow)

Installation

Import

Example

Features

Mapping

Usage with React Flow

Type Definitions

Format Comparison

Use Cases

JGF

GML

TGF

Edge List

Adjacency List

XYFlow

See Also