node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org ยป



This package provides an expressive way to specify, run and debug finite state machines in Javascript/Livescript/Coffeescript/Whatever:


Main features:

  • Express compact state transitions with regular expressions
  • Debug your FSM on line with a mini-server (powered by socketio).

Note: The fsm runs server-side! This is not compatible with browsers at the moment.


To install, use npm:

npm install fsmexpress


For a complete livescript example, check this link out.


To import in you program (livescript code)[^1]:

fsm = require('fsmexpress').fsm;
any-of = require('fsmexpress').any-of;

Create fsm and instantiate states

Create a finite state machine:

fs = new fsm()

Define states (livescript code):

fs.define-as-states([   'II' 'SI' 'PI' 'OI' 
                        'IS' 'SS' 'PS' 'OS' 
                        'IP' 'SP' 'PP' 'OP' 
                        'IC' 'SC' 'PC' 'OC' 'error' ])

Define transitions

Define a transition (using a regular expression) from all states beginning with 'I', excluding some states (IP, IC) on a specific event (an_event) and register action action_to_trigger (function) when that happens:

  .but-not-from(any-of(['IP' 'IC']))

Note: the target state S- is a state beginning with S and ending with the matched text in (.+) in the from expression. So the above statement will generate only two different state transitions (because 'IP' 'IC' are not allowed from states:

II -> SI
IS -> SS

You can also define what to do when the starting state is not among the allowed ones (by using the otherwise-is function):

  .but-not-from(any-of(['IS' 'SS' 'PS']))

In the above case, whenever the starting state is among ['IS' 'SS' 'PS'], the next state associated with another_event is error.

Unfold and optimize

After the state transitions have been setup, invoke unfold to generate actual state transition rules:


Prune states that are not reachable:


Linking to an event emitter

To register an event emitter:


So, everytime the_event_emitter emits a signal the fsm is triggered according to the rules. Practically, let's assume that we have the following event emitter:

class tester extends EventEmitter
    run_op: ~> 
        @emit 'anEvent'
        setTimeout(@run_tr, 300)
    run_tr: ~> 
        @emit 'anEvent2'
        setTimeout(@run_fl, 300)
    run_fl: ~> 
        @emit 'anotherEvent'
        setTimeout(@run_op, 300)

        # @emit 'triggerOpen'
        # @emit 'executedOpen'

Let's register it and start the finite state machine:

tst = new tester()

# Register event emitter and start the fsm

# Start the event generation:

State transitions will happen according to the emitted events.

GUI debug

You can have a visual representation of the FSM that is served through a small web service (screenshot above):

red = "#9d261d"
gre = "#46a546"
blu = "#049cdb"

# GUI related stuff..
fs.mark transition: '.+',       with-color: 'lightgrey'
fs.mark transition: '.+Open',   with-color: "#gre"
fs.mark transition: '.+Close',  with-dashed-color: "#gre"
fs.mark transition: 'failed.+', with-color: "indianred"
fs.mark state:      '.+',       with-color: 'lightgrey'
fs.mark state:      'error',    with-color: 'indianred'
fs.mark state:      fs.initial, with-color: "#gre"
fs.mark state:,   with-color: "lightsteelblue"

fs.serve(6970, 'my fsm')

You can see live state transitions (wherever the fsm is, even remotely, provided that the port can be accessed).


  • 4/6/2013 - Release of 0.0.1
  • 4/9/2013 - Update of Readme file



[^1]: In livescript, dashes "-" are used to create camelized Javascript identifiers. So, any-of is translated to anyOf by the livescript compiler.