tsplot

Warning: This project is still in its early stages. Since most of the codebase is currently experimental, major changes shall be expected to happen!

A CLI and tooling library to plot Typescript project information to different template targets. Either using built-in targets, such as PlantUML or Mermaid, but also supporting custom templates and targets.

Features

Important: This library does not render output in an image format! It's sole purpose is to generate the intermediate code for a declarative diagram dialect or any other text based output format, like markdown or html, to be further processed.

• Full and partial project views A unified access point for a flat list of all members and files within a project view (e.g. classes, interfaces, enums, etc.) with the ability to filter and work with them.

• Project member graphs Resolution of the relationships between members into a collection edges.

• Namespace grouping Configurable grouping mechanism based on the common Typescript paths format.

• Filtering Preset and custom filters to include or exclude project files and members based on various criteria (e.g. name, path, kind, decorators, etc.). Works as the basis for partial project views.

• Rendering Template based output generation for different targets, such as PlantUML or Mermaid, with extensive customization support.

• Template engine Customizable and extendable templating based on Nunjucks for generating output code.

• CLI A command line interface to interact with the library and generate output code with a rich set of options, that support all the library features.

Usage

You can always use the help to get an overview of the available commands and options.

npx tsplot --help

Tip: Make sure to take a look at the --help output of the subcommands to get a full overview of the available options.

Rendering

To render the project view and graph information you can use the render command. The following example generates a class diagram using the plant-uml target.

Note: The default output target is plant-uml. To change it, use the --target option.

npx tsplot render class-diagram --output './output.puml'

Statistics

The CLI can collect and display various statistics about the project. Make sure the check the options available for the stats command using the --help option.

npx tsplot stats

Templates

Templates are used to generate the output code for a target format. This project tries to provide a fair amount of configuration options for the different output formats, but it is also possible to create custom templates and targets.

Following are the built-in targets:

• plant-uml
• mermaid

They can be set using the --target option when using the render command.

Built-in templates are implemented using Nunjucks and can also be customized and extended. For more information, check the template engine concept. You can also take a look at the template implementations in lib/render2/templates for inspiration.

Examples

This is an example showcasing a class diagram for a subset of this project.

Note: The diagrams might be outdated.

PlantUML

Executing the shell command below:

$tsp render class-diagram \ 
  --project $tsconfig \ 
  --output './tsplot.project-view.puml' \
  --groupBy 'tsplot/core:**/lib/core/**' 'tsplot/filter:**/lib/filter/**' \
  --exclude '**/utils/**' '**/cli/**' \
  --excludeKind 'variable' 'function' \
  --from 'ProjectView' \
  --depth 0

Generates the PlantUML code in example.puml, which results in the following diagram:

A full overview of this project might look like this:

Using the following command:

npx tsplot render class-diagram \
  --project './packages/tsplot/tsconfig.lib.json' \
  --groupBy 'tsplot:**/lib/**' 'tsplot/cli:**/cli/**' \
  --exclude '**/render/**' '**/utils/**' \
  --excludeKind 'variable' 'function' \
  --output './tsplot.puml'

Make sure to check the roadmap and concept documents for more information about the library and its features.