@ts-graphviz/ast

This package contains the module for processing the DOT language at the Abstract Syntax Tree (AST) level for the ts-graphviz library.

🔗

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

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

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.

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

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):

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.