@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):

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.