@ts-graphviz/common

What is @ts-graphviz/common?

@ts-graphviz/common is a TypeScript library that provides common utilities and types for working with Graphviz, a graph visualization software. It is part of the ts-graphviz project, which aims to provide a set of tools for creating and manipulating Graphviz graphs in TypeScript.

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

Graph Creation

This feature allows you to create a directed graph (Digraph), add nodes, and add edges between nodes. The `toDot` method converts the graph to DOT format, which is the plain text graph description language used by Graphviz.

const { Digraph } = require('@ts-graphviz/common');
const g = new Digraph('G');
g.addNode('A');
g.addNode('B');
g.addEdge(['A', 'B']);
console.log(g.toDot());

Node and Edge Attributes

This feature allows you to add attributes to nodes and edges. Attributes can include properties like color, shape, and labels, which customize the appearance and behavior of the graph elements.

const { Digraph } = require('@ts-graphviz/common');
const g = new Digraph('G');
g.addNode('A', { color: 'red' });
g.addNode('B', { shape: 'box' });
g.addEdge(['A', 'B'], { label: 'A to B' });
console.log(g.toDot());

Subgraphs

This feature allows you to create subgraphs within a main graph. Subgraphs can be used to group nodes and edges together, often for the purpose of applying specific attributes or for organizational purposes.

const { Digraph, Subgraph } = require('@ts-graphviz/common');
const g = new Digraph('G');
const sg = new Subgraph('cluster_0');
sg.addNode('A');
sg.addNode('B');
g.addSubgraph(sg);
console.log(g.toDot());

Other packages similar to @ts-graphviz/common

graphlib

Graphlib is a JavaScript library for creating and manipulating directed graphs. It provides a rich set of features for graph creation, traversal, and manipulation. Compared to @ts-graphviz/common, graphlib is more focused on the algorithmic aspects of graph manipulation rather than visualization.

cytoscape

Cytoscape is a JavaScript library for visualizing complex networks and graphs. It provides a wide range of features for graph visualization, including layout algorithms, styling, and interaction. While @ts-graphviz/common focuses on generating DOT files for Graphviz, Cytoscape is more geared towards interactive graph visualization in web applications.

d3-graphviz

d3-graphviz is a library that combines D3.js and Graphviz to render graphs in the browser. It allows you to create and manipulate graphs using D3.js and then render them using Graphviz. Compared to @ts-graphviz/common, d3-graphviz is more focused on rendering and visualizing graphs in a web environment.

README

@ts-graphviz/common

Type information, constants, and utility functions related to the DOT language attributes, attribute values, and models for ts-graphviz.

🔗

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

Features

• Type definitions for DOT language elements, including attributes and attribute values
• Constants representing common attribute names and values
• Comprehensive type guards for runtime type checking and TypeScript type narrowing
• Node reference utilities for parsing and converting complex node references
• Performance-optimized utilities for working with large model collections
• Seamless integration with @ts-graphviz/react for type-safe model filtering
• Dual-mode type handling - runtime validation or trusted user assertions

Usage

Basic Type Definitions

Import the necessary types, constants, or utility functions from the @ts-graphviz/common package:

import {
  NodeAttributesObject,
  EdgeAttributesObject,
  isNodeModel,
  isEdgeModel,
  toNodeRef
} from '@ts-graphviz/common';

Type-Safe Model Operations

The package excels at providing type safety for graph model operations:

const nodeAttr: NodeAttributesObject = {
  label: 'Node label',
  shape: 'ellipse',
};

const edgeAttr: EdgeAttributesObject = {
  label: 'Edge label',
  color: 'red',
};

Type Guards and Model Utilities

The package provides powerful type guards for working with graph models with full TypeScript integration:

import {
  isNodeModel,
  isEdgeModel,
  isRootGraphModel,
  isSubgraphModel,
  isAttributeListModel
} from '@ts-graphviz/common';

// Type-safe model checking
if (isNodeModel(someModel)) {
  // TypeScript knows someModel is NodeModel
  console.log(someModel.id);
}

if (isEdgeModel(someModel)) {
  // TypeScript knows someModel is EdgeModel
  console.log(someModel.targets);
}

Node Reference Utilities

Utilities for working with node references and compass directions:

import {
  isNodeRef,
  isNodeRefLike,
  isCompass,
  toNodeRef,
  toNodeRefGroup
} from '@ts-graphviz/common';

// Check if a value is a valid node reference
if (isNodeRefLike('node1:port:n')) {
  const nodeRef = toNodeRef('node1:port:n');
  console.log(nodeRef); // { id: 'node1', port: 'port', compass: 'n' }
}

// Convert multiple node references
const targets = toNodeRefGroup(['node1', 'node2:port', 'node3::s']);
console.log(targets);
// [
//   { id: 'node1' },
//   { id: 'node2', port: 'port' },
//   { id: 'node3', port: '', compass: 's' }
// ]

// Validate compass directions
if (isCompass('ne')) {
  console.log('Valid compass direction');
}

Advanced Type Checking

The package provides additional utilities for complex type checking scenarios:

import {
  isForwardRefNode,
  isNodeRefGroupLike,
  isNodeRef,
  isNodeRefLike,
  FilterableModel
} from '@ts-graphviz/common';

// Check for forward reference nodes
const forwardRef = { id: 'futureNode' };
if (isForwardRefNode(forwardRef)) {
  console.log('Valid forward reference');
}

// Validate arrays of node references
const targets = ['node1', 'node2:port'];
if (isNodeRefGroupLike(targets)) {
  const nodeRefs = toNodeRefGroup(targets);
  // Process validated node references
}

For more examples and usage details, please refer to the ts-graphviz documentation.

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.