@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 🐛