asl-puml

asl-puml

What does it do?

Generates a plantuml state diagram from a valid Amazon States Language file.

But why? There's already good tooling from AWS.

The existing tools are good but I'm looking for a simpler rendering that encodes a little more info than the AWS Toolkit.

I also do all of my development in an IDE and don't want to switch to the browser based AWS Workflow Studio.

Example step function

See __tests__/Definitions/demo.asl.json for the step function used for these examples.

The diagrams below show the same step function rendered by:

• asl-puml (this library)
• AWS Toolkit
• AWS Workflow Studio

Feature comparison

Feature or Style	asl-puml	AWS Toolkit	AWS Workflow Studio
renders the step function as a state diagram
diagram matches the style seen in AWS Console for instance executions	no	yes	no
renders the step function within Webstorm or other JetBrains products	yes, via the existing plantuml plugin	no, not in AWS Toolkit for Webstorm	no
renders the step function within VS Code	yes, via the existing plantuml plugin	yes, available in AWS Toolkit for VS Code	no
conveys the behavior for the state	yes, via colors and some icons	no	yes, very familiar AWS icons and colors.
avoid drawing duplicate paths to reduce clutter (catches)	yes	yes	no, all paths are drawn
identify the compensate path	yes, albeit hard coded by state name regex	no	no
label the state transition if conditional	yes, limited support with StringEquals	no	yes, expression is shown in a note on the line
label the path from a catch	yes, with line weight and color	no	path is labeled with a Catch
label the path to a Fail state	yes, with line weight and color	no	no

Install

# Use via the CLI
npm install -g asl-puml
# Use in your code
npm install asl-puml

CLI

$ asl-puml --help

  Usage: asl-puml [options]

  Amazon States Language to PUML

  Options:

Amazon States Language to PUML

Options:
  -i --input <input>    path to input file
  -o --output <output>  path to output dir
  -h, --help            display help for command

Return status:

• 0 if diagram was generated
• 1 if there was an error

In your code

const aslPuml = require('asl-puml');
const definition = require('./path/to/my/state/machine/json/definition');
const { isValid, puml, message } = aslPuml(definition);
if (isValid) {
  console.log(puml)
} else {
  console.error(message);
}

Test

npm run test

Lint

npm run lint

See also

• ASL specifications
• ASL documentation on AWS website
• PlantUML state diagram documentation

License

See LICENSE.