README.md

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

Hierarchical state

• json
• puml

Parallel state

• json
• puml

History state

• json
• puml

Internal transitions

• json
• puml

Guards, actions and activities

xstate@v3:

• json
• puml

xstate@v4:

• json
• puml