Detalhes do pacote

@ts-graphviz/ast

ts-graphviz2.8mMIT3.0.3

Graphviz AST(Abstract Syntax Tree) Utilities

readme (leia-me)

Main CodeQL License: MIT All Contributors OpenSSF Best Practices OpenSSF Scorecard Tidelift npm version node version deno version npm # @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. 🔗 GitHub npm Reference Ask DeepWiki Sponsor OpenCollective format: Biome test: Vitest build: Vite

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

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

Yuki Yamazaki
Yuki Yamazaki

💻 ⚠️ 📖 🤔
LaySent
LaySent

🐛 ⚠️
elasticdotventures
elasticdotventures

📖
Christian Murphy
Christian Murphy

💻 🤔 📖
Artem
Artem

🐛
fredericohpandolfo
fredericohpandolfo

🐛
diegoquinteiro
diegoquinteiro

🐛
robross0606
robross0606

🤔
Blake Regalia
Blake Regalia

🐛
bigbug
bigbug

💬
mrwk
mrwk

💬
svdvonde
svdvonde

💬
Adam
Adam

💬
Trevor Scheer
Trevor Scheer

️️️️♿️
Prem Pillai
Prem Pillai

🐛
nagasawaryoya
nagasawaryoya

💻 ⚠️
YukiSasaki
YukiSasaki

💻 ⚠️
Madd0g
Madd0g

🐛
j4k0xb
j4k0xb

🐛
HKrogstie
HKrogstie

🐛
Nils K
Nils K

🐛
hao2013
hao2013

🚧 👀
Walter Rafelsberger
Walter Rafelsberger

💬
grsjst
grsjst

🐛
Steve
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.

changelog (log de mudanças)

@ts-graphviz/ast

3.0.3

Patch Changes

  • #1513 9d52d28 Thanks @kamiazya! - Fix @next tag publishing pipeline to prevent incorrect releases

    This fix addresses issues with the @next tag publishing workflow where stable versions were incorrectly published with @next tag, and subsequently, @next versions stopped being published entirely.

    Problem 1 (PR #1513): Stable package versions were being incorrectly published with the @next tag instead of the latest tag. The Changesets action switches to changeset-release/main and updates package.json versions, but the @next publish step would run on this branch where no unreleased changesets remain, causing stable versions to be published with @next tag.

    Solution 1: Added a branch check step to verify the current working directory is on the main branch before executing @next publish.

    Problem 2 (This PR): The branch check from PR #1513 prevented ALL @next publishes because the changesets action never switches back to main, causing the branch check to always fail.

    Solution 2: Added a step to switch back to the main branch after the changesets action completes. This ensures the working directory is in the correct state for snapshot versioning while maintaining the safety check.

    Changes:

    • Added branch check to verify current branch before @next publish
    • Added git checkout main step after changesets action
    • Updated @next publish condition to include branch verification
    • Removed redundant commit message check that was ineffective
  • #1514 d74172a Thanks @kamiazya! - Migrate npm publishing to OIDC trusted publishing

    This change migrates the npm publishing workflow from using long-lived NPM_TOKEN secrets to OIDC (OpenID Connect) trusted publishing, following GitHub's security recommendations announced in September 2025.

    Benefits:

    • Enhanced security: No more long-lived tokens to manage, rotate, or accidentally expose
    • Automatic provenance: Provenance attestations are generated automatically without the --provenance flag
    • Compliance: Aligns with npm's new authentication requirements (token expiration limits)
    • Short-lived credentials: Each publish uses workflow-specific, ephemeral credentials

    Changes:

    • Added environment: npm to the release job to match trusted publisher configuration
    • Upgraded npm CLI to latest version (≥11.5.1) for OIDC support
    • Removed NPM_TOKEN from changesets action and snapshot publish steps
    • Removed manual .npmrc creation as authentication now uses OIDC tokens
    • Updated id-token permission comment to reflect OIDC usage

    Requirements:

    • npm CLI v11.5.1 or later (automatically installed in workflow)
    • Trusted publisher configured for each package on npmjs.com
    • GitHub Actions environment named "npm" configured for the repository
  • #1512 de566db Thanks @anubhav-goel! - Updated broken monorepo package links to valid URLs

  • #1458 9f72aed Thanks @dependabot! - build(deps-dev): bump peggy from 5.0.3 to 5.0.6

  • Updated dependencies [9d52d28, d74172a, de566db]:

    • @ts-graphviz/common@3.0.3

3.0.2

Patch Changes

  • #1483 a07d3b7 Thanks @kamiazya! - Fix CI workflow to prevent @next tag publishing after Version Packages PR merge

  • Updated dependencies [a07d3b7]:

    • @ts-graphviz/common@3.0.2

3.0.1

Patch Changes

  • #1479 c9653aa Thanks @kamiazya! - Fix TypeScript compilation error when skipLibCheck is false

    This fixes issue #1478 where importing from ts-graphviz would cause a TypeScript error: "Cannot find module './_parse.js' or its corresponding type declarations."

    The issue was caused by the Rule type referencing StartRuleNames from the auto-generated _parse.ts file, which was not properly exported. The fix removes the dependency on the generated type and defines the Rule type directly in parse.ts.

    Changes:

    • Remove import of non-existent StartRuleNames type from _parse.ts
    • Fix import of PeggySyntaxError to use the correct export name
    • Define Rule type directly as a union of rule name string literals
  • #1480 ab5d0c7 Thanks @kamiazya! - Fix CI workflow to prevent publishing stable releases with @next tag

  • Updated dependencies [ab5d0c7]:

    • @ts-graphviz/common@3.0.1

3.0.0

Major Changes

  • #1363 9328563 Thanks @kamiazya! - 🚨 Breaking Changes: Drop Node.js 18 support

    Minimum required version is now Node.js 20+

    ESM-Only Distribution

    • Remove CommonJS builds: All packages now distribute only ESM (ECMAScript Modules)
    • Package exports: Removed require fields from package.json exports
    • Module type: All packages are now "type": "module"

    🔄 Migration Guide

    For ESM Projects (Recommended)

    {
      "type": "module"
    }
    
    // Import syntax remains unchanged
    import { Digraph, Node, Edge, toDot } from "ts-graphviz";
    import { toFile } from "ts-graphviz/adapter";
    import { parse } from "ts-graphviz/ast";
    

    For CommonJS Projects

    If you are using CommonJS (CJS) and need to migrate to ESM, you will need to update your project to support dynamic imports. This is necessary because the packages no longer provide CommonJS builds.

    Before (CJS)

    // JavaScript (CommonJS)
    function createGraph() {
      // Dynamic import is required because the packages no longer provide CommonJS builds.
      const { Digraph, Node, Edge, toDot } = require("ts-graphviz");
      const graph = new Digraph();
      return toDot(graph);
    }
    

    After (ESM)

    async function createGraph() {
      const { Digraph, Node, Edge, toDot } = await import("ts-graphviz");
    
      const graph = new Digraph();
      // Create your graph...
      return toDot(graph);
    }
    
    // TypeScript (CommonJS)
    // Update tsconfig.json
    {
      "compilerOptions": {
        "module": "Node16",
        "moduleResolution": "Node16"
      }
    }
    
    // Use dynamic imports
    async function createGraph() {
      const tsGraphviz = await import('ts-graphviz');
      const { Digraph, Node, Edge, toDot } = tsGraphviz;
    
      const graph = new Digraph();
      // Create your graph...
      return toDot(graph);
    }
    

    🎯 Benefits

    • Modern JavaScript: Leveraging native ES modules for better performance
    • Smaller bundle sizes: ESM enables better tree-shaking
    • Future-proof: Aligning with the JavaScript ecosystem direction
    • Better TypeScript support: Enhanced module resolution
  • #1363 9328563 Thanks @kamiazya! - Adjust HTML label AST handling for consistent behavior #1335

    Improves the handling of HTML-like labels in the fromDot and toDot functions to ensure valid Dot output.

Minor Changes

  • #1363 9328563 Thanks @kamiazya! - Define Supported environment and Support levels

    To provide clarity on the environments in which ts-graphviz operates, we have categorized support levels:

    Support Levels

    Tier 1: Full Support

    • Definition: Environments that are fully supported, with comprehensive automated testing and maintenance.
    • Environments:
      • Node.js LTS versions: All active Long-Term Support (LTS) versions.
        • If a Node.js LTS version is released, we will ensure compatibility with it.
        • If a Node.js LTS version is deprecated, we will drop support for it in the next major release.
    • Details:
      • We run automated tests on all LTS versions of Node.js.
      • Full compatibility and performance are ensured.
      • Critical issues are prioritized for fixes.

    Tier 2: Active Support

    • Definition: Environments that receive active support with limited automated testing.
    • Environments:
      • Deno Latest LTS version: The latest Long-Term Support (LTS) version of Deno.
        • If a new Deno LTS version is released, we will ensure compatibility with it.
        • If a Deno LTS version is deprecated, we will drop support for it in the next minor release.
      • Node.js Current Release: The latest Node.js release outside the LTS schedule.
        • If a new Node.js current release is available, we will ensure compatibility with it.
        • If a Node.js current release is deprecated, we will drop support for it in the next minor release.
    • Details:
      • Compatibility is maintained, and issues are addressed.

    Tier 3: Community Support

    • Definition: Environments that are not officially tested but are supported on a best-effort basis.
    • Environments:
      • Modern Browsers: Latest versions of major browsers, including:
        • Google Chrome
        • Mozilla Firefox
        • Microsoft Edge
        • Apple Safari
      • Deno Current Release: The latest Deno release outside the LTS schedule.
    • Details:
      • Installation methods are provided.
      • No automated testing is performed.
      • Issues reported by users will be addressed.
      • Targeting the latest versions ensures compatibility with modern web standards.
      • We will not actively test or maintain compatibility with older versions of browsers.

Patch Changes

  • #1363 9328563 Thanks @kamiazya! - Update Develop Environment

    • Drop turbo
    • Upgrade biome to 2.0
    • Upgrade TypeScript to 5.8
    • Upgrade Vite to 7.0
    • Upgrade Vitest to 3.2
    • Upgrade Peggy to 5.0 and drop ts-pegjs
    • Implement new E2E test workflow
  • #1363 9328563 Thanks @kamiazya! - New GitHub Action main workflow and tests

  • Updated dependencies [9328563, 9328563, 9328563, 9328563, 9328563]:

    • @ts-graphviz/common@3.0.0

2.0.7

Patch Changes

  • #1318 c043ba9 Thanks @kamiazya! - Improve error handling and documentation in the @ts-graphviz/ast package.

    The most important changes include fixing an unexpected parsing error, updating the error class used in the parse function, and enhancing the documentation for the DotSyntaxError class.

2.0.6

Patch Changes

  • #1218 d7ff421 Thanks @kamiazya! - Fix AST printing not to be destroyed during stringify even in HTML-Like format

  • Updated dependencies [d7ff421]:

    • @ts-graphviz/common@2.1.5

2.0.5

Patch Changes

2.0.4

Patch Changes

2.0.3

Patch Changes

2.0.2

Patch Changes

2.0.1

Patch Changes

2.0.0

Initial release

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

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

Features

  • Parsing and generating DOT language ASTs
  • Functions for manipulating and transforming ASTs
  • Support for custom AST nodes and attributes

Usage

Import the necessary functions and classes from the @ts-graphviz/ast package:

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

Use the imported items in your project to work with DOT language ASTs:

const dotString = "digraph G { A -> B; }";
const ast = parse(dotString);

const outputDotString = stringify(ast);
console.log("Output DOT string:", outputDotString);