Skip to content

Latest commit

 

History

History
225 lines (156 loc) · 7.94 KB

README.md

File metadata and controls

225 lines (156 loc) · 7.94 KB

Jakmar.js

Jakmar is a finite state machine for Javascript.

Example

If you want to see Jakmar in action, please consult the following:

Usage

For Node.js, just include the library:

var jakmar = require('jakmar')

Stateful objects creation

First, build a MachineDefinition:

var definition = jakmar.create('foo-def') // foo-def is an identifier

Once it's created, start by adding states:

definition
	.state('opened') // a state is just defined by a string
	.state('closed')

And some transitions:

definition
	.transition('open', 'closed', 'opened') // 'open' transition, from the 'closed' state to the 'opened' state
	.transition('close', 'opened', 'closed') // 'close' transition, from the 'opened' state to the 'closed' state

Then just build the definition to get your stateful instance:

var stateful = definition.build('opened') // opened will be the initial state

Changing state

Your stateful instance has been enriched with methods defined by transitions. You can also verify the current state using the state property:

console.log(stateful.state) // opened
stateful.close()
console.log(stateful.state) // closed
stateful.open()
console.log(stateful.state) // opened

API

jakmar.create(id, options)

The create method creates and returns a new instance of a MachineDefinition with id as an identifier. The following options are valid (and all are optional):

  • errorOnInvalidTransition: will throw an Error if a transition tries to be applied but the stateful object is not in an expected state. Default is true.
  • errorOnUnknownState: will throw an Error if a transition tries to be applied to or from a state that does not exist. Default is true.
machineDefinition = jakmar.create('fooDef', {errorOnInvalidTransition: false, errorOnUnknownState: false})

jakmar.get(id)

The get method will return the MachineDefinition with id as an identifier. If there is no machine definition found, returns undefined.

machineDefinition = jakmar.get('fooDef')

jakmar.reset()

The reset method will remove all stored MachineDefinitions from Jakmar.

jakmar.reset()

machineDefinition.state(stateId)

Register a new state with stateId as an identifier to the machineDefinition. Returns this for chained calls.

machineDefinition.state('opened')

machineDefinition.states(stateIds)

Register an array of new states with stateIds being an Array of identifier for the machineDefinition. Returns this for chained calls.

machineDefinition.states(['opened', 'closed'])

machineDefinition.states(...args)

Alternate way of registering new states, using any number of string, each a stateIdfor the machineDefinition. Returns this for chained calls.

machineDefinition.states('opened', 'closed')

machineDefinition.transition(transitionId, fromStateId, toStateId)

Register a new transition with transitionId as an identifier to the machineDefinition. The transition will change the stateful object from the state defined by fromStateId to the state defined by toStateId. Returns this for chained calls.

machineDefinition.transition('open', 'closed', 'opened')

machineDefinition.build(initialState, target)

Transform the target into a statefulObject with the current machineDefinition states and transitions applied to it. target is optional ; a new object is created if missing. The stateful object initial state is mandatory and defined by the initialState. Returns a statefulObject.

var statefulObject = machineDefinition.build('opened', {})

machineDefinition.getStates()

Expose the registered states of the machineDefinition. Returns an object with key / value pairs, key being the state ids and the value being the State objects. A State object only has an id at the moment.

var states = machineDefinition.getStates()
console.log(states)
// {
//	opened: { id: 'opened' },
//	closed: { id: 'closed' }
// }

machineDefinition.getTransitions()

Expose the registered transitions of the machineDefinition. Returns an Arrat of Transition objects. A Transition object has two properties: the transition id and an applicableStates object of key / value pairs, where the key is the applicable fromState and the value is the corresponding toState for that transition.

machineDefinition.transition('toggle', 'opened', 'closed')
machineDefinition.transition('toggle', 'closed', 'opened')
var transitions = machineDefinition.getTransitions()
console.log(transitions)
// [
//	{ id: 'toggle', applicableStates : { opened: 'closed', closed: 'opened' } }
// ]

machineDefinition.onEnter(onEnterFn)

Register a function that will be called every time the statefulObject enter a new state. It is called after the onExitFn, once the new state has been applied. The onEnterFn should be a function accepting one argument, being the id of state that has just been entered. Returns this for chained calls.

var onEnter = function(stateId) {
	console.log('Entering', stateId)
}
machineDefinition.onEnterFn(onEnter)
var statefulObject = machineDefinition.build('opened')
statefulObject.close()
// Entering closed

machineDefinition.onExit(onExitFn)

Register a function that will be called every time the statefulObject exits a state. It is called before the onEnterFn, once the new state has been applied. The onExitFn should be a function accepting one argument, being the id of state that will be exited. Returns this for chained calls.

var onExit = function(stateId) {
	console.log('Exiting', stateId)
}
machineDefinition.onExitFn(onExit)
var statefulObject = machineDefinition.build('opened')
statefulObject.close()
// Exiting opened

statefulObject.state

Return the current state id of the statefulObject.

var statefulObject = machineDefinition.build('opened')
statefulObject.state // 'opened'

statefulObject.stateChange

Function that gets called every time the statefulObject changes state. It gets called with three arguments: the transition id that trigerred the change of state, the fromState id and the toState id. It gets called ```after the state has changed.

var statefulObject = machineDefinition.build('opened')
statefulObject.stateChange = function(transitionId, fromStateId, toStateId) {
	console.log('Going from', fromStateId, 'to', toStateId, 'because of transition', transitionId)
}
statefulObject.open()
// Going from opened to closed because of transition open

statefulObject.<transition>

Apply a registered transition to the statefulObject. Returns true id the transitions was applied, throws an Error if the transition can't be applied (because the statefulObject is not in a state where the transition can be applied) or returns false if the errorOnInvalidTransition option is set to false.

statefulObject.state // closed
statefulObject.open() // returns true
statefulObject.state // opened
statefulObject.open() // throws an Error

TODO

  • Add a minified version

Status

Build Status Coverage Status