@ts-graphviz/core

What is @ts-graphviz/core?

@ts-graphviz/core is a TypeScript library for creating and manipulating Graphviz graphs. It provides a programmatic way to build and render graphs using the Graphviz DOT language.

What are @ts-graphviz/core's main functionalities?

Creating a Graph

This feature allows you to create a directed graph, add nodes, and create edges between them. The `toDot` method converts the graph to DOT format.

const { digraph } = require('@ts-graphviz/core');
const g = digraph('G');
g.node('A');
g.node('B');
g.edge(['A', 'B']);
console.log(g.toDot());

Subgraphs

This feature allows you to create subgraphs within a main graph. Subgraphs can be used to group nodes together.

const { digraph, subgraph } = require('@ts-graphviz/core');
const g = digraph('G');
const s = subgraph('cluster_0');
s.node('A');
s.node('B');
g.subgraph(s);
console.log(g.toDot());

Graph Attributes

This feature allows you to set attributes for the graph, such as the direction of the graph layout.

const { digraph } = require('@ts-graphviz/core');
const g = digraph('G', { rankdir: 'LR' });
g.node('A');
g.node('B');
g.edge(['A', 'B']);
console.log(g.toDot());

Other packages similar to @ts-graphviz/core

graphviz

The 'graphviz' package is a Node.js wrapper for the Graphviz command-line tool. It allows you to generate DOT files and render them to various formats like PNG, PDF, etc. Unlike @ts-graphviz/core, it relies on the Graphviz installation on your system.

viz.js

The 'viz.js' package is a JavaScript port of Graphviz that runs in the browser and Node.js. It allows you to render DOT files directly in the browser without needing a Graphviz installation. It is more focused on rendering rather than programmatic graph creation.

d3-graphviz

The 'd3-graphviz' package integrates Graphviz with D3.js, allowing you to create and manipulate graphs using D3's data-driven approach. It is more suitable for dynamic and interactive visualizations compared to @ts-graphviz/core.

README

@ts-graphviz/core

Models and functions provided to users for the ts-graphviz library.

🔗

It is part of the ts-graphviz library, which is split into modular packages to improve maintainability, flexibility, and ease of use.

Features

The package adheres to object-oriented programming principles, allowing for:

• Creation and manipulation of graph elements
• Composition of complex graph structures
• Extension through inheritance and customization
• Type-safe graph construction with TypeScript

Usage Patterns

@ts-graphviz/core supports several patterns for creating and manipulating graphs:

Basic Object Creation

The most straightforward approach is to instantiate the model classes directly:

// Create a directed graph
const graph = new Digraph();

// Create nodes with attributes
const node1 = new Node('node1', { color: 'red' });
const node2 = new Node('node2', { color: 'blue' });

// Create an edge between nodes with attributes
const edge = new Edge([node1, node2], { label: 'Edge Label' });

// Add elements to the graph
graph.addNode(node1);
graph.addNode(node2);
graph.addEdge(edge);

Factory Methods

Graph models provide factory methods to create and automatically add elements:

// Create a directed graph
const graph = new Digraph();

// Create and add nodes using factory methods
const node1 = graph.createNode('node1', { color: 'red' });
const node2 = graph.createNode('node2', { color: 'blue' });

// Create and add an edge using factory method
graph.createEdge([node1, node2], { label: 'Edge Label' });

Composition with Subgraphs

Graphs can be composed with subgraphs to create hierarchical structures:

// Create a directed graph
const graph = new Digraph();

// Create a subgraph
const subgraph = new Subgraph('cluster_0');

// Create nodes in the subgraph
const node1 = new Node('node1');
const node2 = new Node('node2');

// Add nodes to the subgraph
subgraph.addNode(node1);
subgraph.addNode(node2);

// Add the subgraph to the main graph
graph.addSubgraph(subgraph);

Customization and Extension

@ts-graphviz/core provides several mechanisms for customizing and extending its functionality:

Class Inheritance

You can create custom graph element classes by extending the base classes:

class MyCustomNode extends Node {
  constructor(id: string) {
    super(`node_${id}`, {
      label: `Custom Node ${id}`,
      shape: 'box'
    });
  }
}

class MyCustomEdge extends Edge {
  constructor(targets: EdgeTargetTuple) {
    super(targets, {
      color: 'blue',
      penwidth: '2.0'
    });
  }
}

// Use custom classes
const node1 = new MyCustomNode('A');
const node2 = new MyCustomNode('B');
const edge = new MyCustomEdge([node1, node2]);

Models Context API

The Models Context API allows you to specify which model classes should be used when creating graph element.

This is implemented through the with method on graph models:

// Create a directed graph
const graph = new Digraph();

// Set up the context with custom classes
graph.with({
  Node: MyCustomNode,
  Edge: MyCustomEdge
});

// Now factory methods will use the custom classes
const nodeA = graph.createNode('A'); // Creates a MyCustomNode
const nodeB = graph.createNode('B'); // Creates a MyCustomNode
const edge = graph.createEdge([nodeA, nodeB]); // Creates a MyCustomEdge

Integration with AST

@ts-graphviz/core integrates with @ts-graphviz/ast to convert between the object model and the DOT language.

This integration enables:

• Converting graph models to DOT strings
• Parsing DOT strings into graph models
• Working with the abstract syntax tree directly

The main conversion functions that link @ts-graphviz/core with @ts-graphviz/ast are:

• fromModel: Converts a graph model to an AST
• toModel: Converts an AST to a graph model

These are then used by the main ts-graphviz package to implement the toDot and fromDot functions.

Contributors 👥

Thanks goes to these wonderful people (emoji key):

Yuki Yamazaki 💻 ⚠️ 📖 🤔	LaySent 🐛 ⚠️	elasticdotventures 📖	Christian Murphy 💻 🤔 📖	Artem 🐛	fredericohpandolfo 🐛	diegoquinteiro 🐛
robross0606 🤔	Blake Regalia 🐛	bigbug 💬	mrwk 💬	svdvonde 💬	Adam 💬	Trevor Scheer ️️️️♿️
Prem Pillai 🐛	nagasawaryoya 💻 ⚠️	YukiSasaki 💻 ⚠️	Madd0g 🐛	j4k0xb 🐛	HKrogstie 🐛	Nils K 🐛
hao2013 🚧 👀	Walter Rafelsberger 💬	grsjst 🐛	Steve 🐛

This project follows the all-contributors specification. Contributions of any kind welcome!

Changelog 📜

See CHANGELOG.md for more details.

License ⚖️

This software is released under the MIT License, see LICENSE.