[](https://github.com/ts-graphviz/ts-graphviz/actions/workflows/main.yaml)
[](https://github.com/ts-graphviz/ts-graphviz/actions/workflows/codeql-analysis.yml)
[](https://github.com/ts-graphviz/ts-graphviz/blob/main/LICENSE)
[](#contributors-)
[](https://www.bestpractices.dev/projects/8396)
[](https://scorecard.dev/viewer/?uri=github.com/ts-graphviz/ts-graphviz)
[](https://tidelift.com/subscription/pkg/npm-ts-graphviz?utm_source=npm-ts-graphviz&utm_medium=readme)
[](https://badge.fury.io/js/ts-graphviz)
[](https://github.com/denoland/deno)
[](https://npmtrends.com/ts-graphviz)
# @ts-graphviz/common
Type information, constants, and utility functions related to the DOT language attributes, attribute values, and models for ts-graphviz.
🔗
[](https://github.com/ts-graphviz/ts-graphviz)
[](https://www.npmjs.com/package/ts-graphviz)
[](https://ts-graphviz.github.io/ts-graphviz/)
[](https://deepwiki.com/ts-graphviz/ts-graphviz)
[](https://github.com/sponsors/ts-graphviz)
[](https://opencollective.com/ts-graphviz)
[](https://biomejs.dev/)
[](https://vitest.dev/)
[](https://rollupjs.org/)
---
> 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:
```ts
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:
```ts
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:
```ts
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:
```ts
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:
```ts
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](https://allcontributors.org/docs/en/emoji-key)):
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors)
specification. Contributions of any kind welcome!
## Changelog 📜
See [CHANGELOG.md](https://github.com/ts-graphviz/ts-graphviz/blob/main/packages/common/CHANGELOG.md) for more details.
## License ⚖️
This software is released under the MIT License, see [LICENSE](https://github.com/ts-graphviz/ts-graphviz/blob/main/LICENSE).
