---

> 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

$3

``ts
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
`

#### Parser Options

The parse function accepts an optional second argument for configuration:

`ts
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)
});
`

Available Options:

| Option | Default | Description |
|--------|---------|-------------|
| startRule | 'Dot' | Starting grammar rule for parsing |
| maxHtmlNestingDepth | 100 | Maximum depth of nested HTML-like structures |
| maxEdgeChainDepth | 1000 | Maximum depth of chained edges (e.g., a -> b -> c -> ...) |
| maxInputSize | 10485760 (10MB) | Maximum input size in bytes |
| maxASTNodes | 100000 | Maximum number of AST nodes to create |

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.

$3

`ts
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; }"
`

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.