machina.Fsm

machina.Fsm

machina.Fsm instance members

machina.Fsm instances receive properties provided by machina.utils.getDefaultOptions as well as getDefaultClientMeta (as defaults) in addition to what you provide to the constructor's options argument. The most common instance members you'll utilize are as follows:

Member	Description
initialState	A string value indicating the initial state in which the FSM should exist. Defaults to uninitialized.
eventListeners	An object which holds event subscribers for events emitted from the FSM. It is an object that has a key for any event emitted, and the value of the key is an array of subscriber callbacks. Normally, subscribers get added by calling fsmInstance.on("eventName", callback), but providing this argument allows you to set multiple subscribers up in advance as part of creating the FSM.
states	An object where each top-level (own) property is a 'state', and each state property is an object containing the input handlers the FSM should utilize while in that state. Input handlers can be functions, a string value that matches another state name, or one of the special handlers (_onEnter, _onExit or the * catch-All handler). Please note that not including a states object will render your FSM useless (unless it's being used a base for more constructor extensions).
inputQueue	An array of any events that have been deferred via deferUntilTransition
namespace	A string value used as a namespace for the FSM, should it be (for example) wired into a message bus.
targetReplayState	A value used internally as the FSM transitions - it tells the FSM which state should be used to play any queued events when a single transition could result in multiple transitions in one call stack.
state	The current state in which the FSM resides.
priorState	The state the FSM was in prior to the current state.
priorAction	The last action/input the FSM handled.
currentAction	The action/input the FSM is currently handling.
currentActionArgs	The args provided to the input the FSM is currently handling.
initialize	A function that is executed once the instance of the FSM has been created. This gives you a chance to perform any initialization concerns on the FSM before machina itself triggers the newfsm event and before the FSM transitions into the initialState.

machina.Fsm prototype members

Member	Description
initialize()	The prototype implementation is simply a no-op. The intention is for the developer to override this method if needed.
emit(eventName [, arg1, arg2…])	Method used to trigger/emit an event. The first argument is the string name of the event. Subsequent arguments are optional, and will be passed to the subscriber callback(s) in the same order. This method is aliased to trigger as well. Use what you prefer.
handle( event [, arg1, arg2…])	The handle call is the primary way you tell the FSM to handle input. The event argument is the name of the event. Subsequent arguments will be passed to the handler method (if one exists) for that event. Calling handle tells the FSM to look in the current state for an explicit handler for the event. If one does not exist, the FSM checks the current state for a * ('catch-all') handler, and if one isn't found, it checks the FSM for a top level * handler. If none of these are found, the FSM will ignore the input other than emitting a nohandler event.
transition(state)	The method used to transition the FSM to a new state. This should always be used instead of manually assigning the state instance property. transition will cause the current state's _onExit handler to run (if applicable), the new state's _onEnter handler to run, and for any queued events to be run in the new state.
processQueue(type)	Called internally by machina during a transition. It iterates over any queued events (in the eventQueue array) and replays any that fit the constraints of the new state. The type argument can be transition or handler.
clearQueue( [type [, stateName]] )	Helper method that empties part or all of the eventQueue array. Not providing any arguments will empty the entire queue. The type (string) argument can be transition or handler - and providing it will only clear events that have been queued for the next transition or queued for the next handler, respectively. If the type argument is transition, you can optionally provide the stateName (string) argument value. This will clear the queue of any events that have been deferred until a state transition into the state matching stateName.
deferUntilTransition( [ stateName ] )	Calling this method inside an input handler will defer the current input until the next state transition. Providing the optional stateName argument allows you to tell the FSM to wait until it transitions into that state at a later time before it attempts to replay the input. Input that is deferred is replayed after the new state's _onEnter handler has executed.
deferAndTransition( stateName )	Defers the current input and immediately transitions to the specified state. The same as calling deferUntilTransition( targetState) and transition( targetState ) in that order.
compositeState()	Returns the "composite" state for an FSM hierarchy, where each state is separated by a period. For example, if a crosswalk FSM has a parent state of vehiclesEnabled and the child FSM for that parent state has a state value of green, then the composite state will be vehiclesEnabled.green.
on( eventName, callback )	Method that adds a new subscriber callback to be fired whenever the FSM triggers an event matching the eventName. This method returns an object which contains a reference to the callback, eventName and an off method that can be invoked to unsubscribe the listener.
off( [eventName [, callback]] )	In addition to being able to unsubscribe via the object returned by calling on(), this method can also be used to unsubscribe events. Not providing any arguments will clear ALL event listeners from the FSM. Providing only the eventName argument will clear all callbacks for that event. Providing both eventName and callback will unsubscribe the specific listener.