StateMachine

The StateMachine class is the primary interface to manage states, actions, handlers and transitions.

You instantiate the StateMachine via the new operator and an options object to configure transitions and handlers. After instantiation you can add additional transitions and handlers via the public methods, as well as interact with transitions, and test for states and actions to update any connected UI, via event handler callbacks.

For code examples, see:

• the usage page for a full code example
• the options page for more information on instantiation options.
• the demo site for examples of the full StateMachine API.

State functions

# do(action, ...rest)

Attempt to run an action, resulting in a transition to a state. Returns true if the transition is available and false if not.

Generally, you map calls to do() from buttons in your UI. See the demo site for more examples.

You can pass additional parameters to the function which are passed to any registered event handlers triggered during the tranistion.

# go(state, force = false)

Attempt to go to a state. If the current state already transitions to the target state, StateMachine will call the action go to that state. If not, you can pass true as the second parameter to skip any transition and go straight to the state.

Modification functions

# add(action, from, to)

Add a transition to the StateMachine.

# remove(state)

Remove a state from the StateMachine. If the removal results in any orphaned actions or states, they are removed as well.

Handler functions

Use these functions to manage event callbacks as the StateMachine transitions.

# on(pattern, fn)

Add an event handler callback. To view available patterns, see the handlers section.

# off(pattern, fn)

Remove an event handler added with the same pattern and handler.

# trigger(pattern, ...rest)

Trigger an event handler, optionally passing arguments.

Transition functions

Use these functions from transition event handler callbacks to manipulate the current transition.

# pause()

Pause any current transition.

# resume()

Resume any paused transition.

# cancel()

Cancel any current transition.

# end()

End any current transition, skipping remaining handlers.

Query functions

Use these functions to query the state of the state machine to update any connected UI.

# canDo(action)

Query the transition map to see if an action is available from the current state.

# canGo(to)

Query the transition map to see if a state is available to go to.

# has(state)

Test if a state exists.

# is(state)

Test if the current state is the same as the supplied one.

# isStarted()

Test if the StateMachine has started.

# isTransitioning()

Test if the StateMachine is transitioning.

# isPaused()

Test if the StateMachine is paused (whilst transitioning).

# isComplete()

Test if the StateMachine is on the "final" state.

Initialisation functions

# start()

Starts the StateMachine if not already started.

# reset(initial = '')

Reset the StateMachine to the initial, or supplied, state