---

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

This library enables rendering DOT language strings into different output formats through platform-specific implementations for Node.js, and Deno.

Graphviz must be installed so that the dot command can be executed.

Execute the dot command to output a DOT language string to a stream or file.

!Adapter State Machine

Core Functions

The adapter provides two main functions for working with DOT language strings:

$3

The toStream function converts a DOT language string to a readable stream of the specified output format.

``ts
import { toStream } from '@ts-graphviz/adapter';

const dot =
digraph example {
node1 [
label = "My Node",
]
}
;

const stream = await toStream(dot, { format: 'svg' });
// Node.js
stream.pipe(process.stdout);
// Deno
await stream.pipeTo(Deno.stdout.writable);
`

$3

The toFile function writes the rendered output directly to a file at the specified path.

`ts
import { toFile } from '@ts-graphviz/adapter';

const dot =
digraph example {
node1 [
label = "My Node",
]
}
;

await toFile(dot, './result.svg', { format: 'svg' });
`

Both functions accept configuration options to customize the rendering process.

Configuration Options

$3

The dotCommand and library options are intended to be configured by application developers, not derived from end-user input:

- dotCommand: Specifies the path to the Graphviz executable. This should be a trusted, hardcoded path in your application configuration.
- library: Specifies external libraries to load. These should be trusted library names defined in your application code.

Important: This library executes external commands using spawn (Node.js) or Deno.Command (Deno), which do not invoke a shell interpreter. This prevents shell injection attacks through metacharacters (;, `, |, $, etc.). However, these options should not be exposed to end-user input.

#### Processing User-Provided DOT Files

When rendering DOT files uploaded by users or generated from user input, implement validation before passing them to this library:

Validation Steps:
1. Syntax validation: Verify the DOT file is well-formed and parseable
2. Attribute filtering: Check for potentially dangerous attributes that reference file system resources:
- image, shapefile - Can reference arbitrary image files
- fontpath, fontname - Can reference font files
- imagepath - Defines search path for images
3. Content sanitization: Consider using a DOT parser to rebuild the graph with only allowed attributes
4. Sandboxing: Run Graphviz in a sandboxed environment with restricted file system access when processing untrusted input

Example Risk Scenario:

⚠️ Warning: The following is an example of unsafe DOT content that should be rejected by validation:

`dot
digraph G {
node [image="/etc/passwd"]; // ⚠️ DANGEROUS: Attempts to access sensitive file
node1;
}
`

While Graphviz will handle file access errors gracefully, processing untrusted DOT files without validation may expose information about your file system or cause unexpected behavior. Always validate and sanitize user-provided DOT files before processing.

Example: Validating and Sanitizing User-Provided DOT Files

Here's an example of how to use the @ts-graphviz/ast package to parse, validate, and sanitize DOT files:

`typescript
import { parse, stringify } from '@ts-graphviz/ast';

// Potentially dangerous attributes that can access file system
const DANGEROUS_ATTRIBUTES = new Set([
'image',
'shapefile',
'fontpath',
'fontname',
'imagepath',
]);

/**
* Validates and sanitizes a DOT file by removing dangerous attributes
*/
function validateAndSanitizeDOT(dotString: string): string {
try {
// Parse the DOT string into an AST
const ast = parse(dotString);

// Remove dangerous attributes from the AST
sanitizeAST(ast);

// Convert back to DOT string
return stringify(ast);
} catch (error) {
throw new Error(Invalid DOT syntax: ${error.message});
}
}

/**
* Recursively sanitize AST nodes by removing dangerous attributes
*/
function sanitizeAST(node: any): void {
if (!node || typeof node !== 'object') return;

// Handle nodes with children
if (Array.isArray(node.children)) {
node.children = node.children.filter((child: any) => {
// Filter out dangerous attribute nodes
if (child.type === 'Attribute') {
const attributeName = child.key?.value;
if (DANGEROUS_ATTRIBUTES.has(attributeName)) {
console.warn(Removed dangerous attribute: ${attributeName});
return false;
}
}
// Recursively sanitize child nodes
sanitizeAST(child);
return true;
});
}
}

// Usage example
const userUploadedDOT =
digraph G {
node [image="/etc/passwd"];
node1 [label="Safe label"];
}
;

const sanitizedDOT = validateAndSanitizeDOT(userUploadedDOT);
// Result: digraph G { node1 [label="Safe label"]; }
`

Best Practices:
- Use the default dot command when possible
- If you need to customize dotCommand`, use a hardcoded path or environment variable controlled by the deployment environment
- Do not allow end-user input to control the configuration options
- Validate and sanitize DOT strings from untrusted sources before rendering
- Consider using a whitelist approach for allowed attributes when processing user-provided DOT files
- Run Graphviz in a restricted environment when handling untrusted input

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.