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

Overview

This package is a foundational component of the ts-graphviz library that enables low-level manipulation of DOT language structures. It provides a parser that converts DOT language strings into AST nodes and a stringifier that converts AST nodes back to DOT language.

Main Functions

The AST package provides several key functions:

• parse(input: string, options?): Parses a DOT language string into an AST structure
• stringify(ast: ASTNode): Converts an AST structure to a DOT language string
• fromModel(model): Converts a Graph Model to an AST structure
• toModel(ast): Converts an AST structure to a Graph Model

Usage Examples

Parsing DOT Language

import { parse } from "@ts-graphviz/ast";

const dotString = "digraph G { A -> B; }";
const ast = parse(dotString);
console.log(ast);
// Output: A DotASTNode representing the DOT structure
Copy

Parser Options

The parse function accepts an optional second argument for configuration:

import { parse } from "@ts-graphviz/ast";

// Parse with custom security limits
const ast = parse(dotString, {
  startRule: 'Dot',              // Specify the starting rule (default: 'Dot')
  maxHtmlNestingDepth: 200,      // Maximum HTML nesting depth (default: 100)
  maxEdgeChainDepth: 2000,       // Maximum edge chain depth (default: 1000)
  maxInputSize: 20971520,        // Maximum input size in bytes (default: 10MB)
  maxASTNodes: 200000            // Maximum AST nodes (default: 100,000)
});
Copy

Available Options:

Security Note:

These limits protect against denial-of-service attacks:

• maxHtmlNestingDepth: Prevents stack overflow from deeply nested HTML-like structures

  • Normal use cases: typically <10 levels
  • HTML-like labels are GraphViz DOT syntax, not browser HTML

• maxEdgeChainDepth: Prevents stack overflow from deeply chained edges

  • Example dangerous input: a -> b -> c -> ... -> z (1000+ nodes)

• maxInputSize: Prevents memory exhaustion from extremely large files

  • Default 10MB is sufficient for most legitimate graphs
  • Can be increased for known large graphs or disabled with 0 (not recommended for untrusted input)

• maxASTNodes: Prevents memory exhaustion from inputs with excessive elements

  • Each DOT element creates multiple AST nodes
  • Example: A single node statement (node1;) creates ~2-3 AST nodes
  • Can be disabled with 0 (not recommended for untrusted input)

Important: When processing untrusted DOT files (e.g., user uploads), keep these limits enabled with conservative values appropriate for your environment. For additional validation of untrusted content, see the validation guide in @ts-graphviz/adapter documentation.

Generating DOT Language

import { parse, stringify } from "@ts-graphviz/ast";

const dotString = "digraph G { A -> B; }";
const ast = parse(dotString);
// Modify the AST if needed
const outputDotString = stringify(ast);
console.log(outputDotString);
// Output: "digraph G { A -> B; }"
Copy

Error Handling

The package provides a specialized error class for handling syntax errors during parsing.

When a parsing error occurs, the parser throws a DotSyntaxError with detailed information about the issue, which helps in debugging DOT language syntax problems.

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.