oklahoma

Minimal promise-based finite state manager

Install

$ npm install --save oklahoma

Usage

var Oklahoma = require('oklahoma')

var fsm = Oklahoma({
  initial: 'alpha',
  states: {
    alpha: {
      leave: [
        action1,
        action2
      ]
    },
    beta: {
      enter: [
        action3,
        action4
      ],
      entered: [
        callMeAfterEnterIsDone
      ]
    }
  }
})

// Will change the state from 'alpha' to 'beta', running alpha's leave functions in order,
// then beta's enter functions in order.
// If any enter/leave function throws an error or rejects a promise, the state transition will abort.
fsm.go('beta')

API

Oklahoma(options) -> fsm

options

options.initial

Required Type: string

The id of the fsm's initial state.

options.states

Required Type: object

An object where the keys are the ids of available states, and the values are an object describing each state:

• enter: function|Array<function> - Function(s) that will be called in order when fsm.go is called to enter this state.
• entered: function|Array<function> - Function(s) that will be called in order after this state is fully entered.
• leave: function|Array<function> - Function(s) that will be called in order when fsm.go is called to leave this state.

Any enter or leave callback that returns a rejected promise will abort the current state transition.

fsm.current() -> string

Returns the id of the current state.

fsm.done() -> Promise

Returns a promise that will resolve once the fsm is done changing states.

fsm.go(state, [...args]) -> Promise

Transition to the given state id. The id must be a valid target of the current state.

args will be passed into each enter/leave function.

Returns a promise that will be resolved or rejected when this state transition finishes.

If multiple state transitions are queued up at once, they will be run in order.

For example, fsm.go('bar'); fsm.go('baz'); will attempt to transition to bar, then once that completes (success or failure), will attempt a transition to baz.

License

MIT © Andrew Joslin