Skip to content

Latest commit

 

History

History
189 lines (133 loc) · 4.5 KB

README.md

File metadata and controls

189 lines (133 loc) · 4.5 KB

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

usage

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

options

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

alarm

Parallel state

text-editor

History state

payment

Internal transitions

word

Guards, actions and activities

xstate@v3:

download

xstate@v4:

download