xstate-plantuml

Visualize a xstate or react-automata statechart as a plantuml state diagram.

This fork was created to add improved support for xstate@v4 and is currently installable by adding the following to package.json:

  "@karfau/xstate-plantuml": "github:karfau/xstate-plantuml#{TAG OR HASH}"

Installation

  "@karfau/xstate-plantuml": "github:karfau/xstate-plantuml#{TAG OR HASH}"

peerDependencies

Peer dependencies are optional: the methods that need them have an optional argument to pass alternatives that provide the same API.

xstate
used by visualize(see Options)
to install, run npm install xstate
execa used by src/transfer:transfer.plantuml
to install, run npm install execa

Usage

visualize

import @karfau/xstate-plantuml and call it's default export using a xstate config or machine

import visualize from '@karfau/xstate-plantuml';

const config = {
  key: 'light',
  initial: 'green',
  states: {
    green: {
      on: {
        TIMER: 'red'
      }
    },
    red: {
      on: {
        TIMER: 'green'
      }
    }
  }
};

visualize(config);

Which returns a string, containing the following plantuml source

@startuml
left to right direction
state "light" as light {
  [*] --> light.green

  state "green" as light.green {
    light.green --> light.red : TIMER
  }

  state "red" as light.red {
    light.red --> light.green : TIMER
  }
}
@enduml

Which you can render to the following image

Options

In addition to a state machine, visualize accepts an options map

option	default	description
leftToRight	true	whether to render left to right or top to bottom
skinParams	[]	Additional skinparams to include
xstate	xstate (resolved module with that name)	to pass alternative implementaitons (e.g. for testing)

Our previous example with different options

visualize(config, {
  leftToRight: false,
  skinParams: ['monochrome true']
});

@startuml
skinparam monochrome true

state "light" as light {
  [*] --> light.green

  state "green" as light.green {
    light.green --> light.red : TIMER
  }

  state "red" as light.red {
    light.red --> light.green : TIMER
  }
}
@enduml

compiles to

transfer

To directly use plantuml to transform a puml file to an image (or anything else) and only do that after updating the puml file.

There are some extra dependencies required for that:

execa (see peerDependencies)
depending on the command used to execute plantuml:
- docker
- java and a local copy of plantuml.jar

test-transfer.js shows how it can be used.

To import the transfer module in your project:

import transfer from '@karfau/xstate-plantuml/src/transfer';

transfer({...});

Examples

Not all examples are listed here, please check examples for more

Guards, actions and activities

xstate@v3:

json
puml

xstate@v4:

json
puml

karfau/xstate-plantuml