yoshuawuyts / fsm-event Goto Github PK

View Code? Open in Web Editor NEW

91.0 5.0 3.0 169 KB

:slot_machine: stateful finite state machine

License: MIT License

JavaScript 100.00%

fsm-event's Introduction

fsm-event

Stateful finite state machine wrapper around fsm. Emits events when transitioning states.

Installation

$ npm install fsm-event

Usage

const fsm = require('fsm-event')

const m = fsm('START', {
  START: { pause: 'PAUSED' },
  PAUSED: { resume: 'START' }
})

m.on('START:leave', cb => console.log('leaving start!'); cb())
m.on('PAUSED', () => console.log('paused state!'))

m('pause')
// 'leaving start'
// 'paused state!'

API

m = fsm([start,] events)

Create a state machine. start defaults to START.

m.on(event, cb)

Attach a listener to the state machine. See events for an overview of all events.

m(event)

Transition states in the state machine. Must be a valid transition defined on initalization. Will throw if an invalid transition is triggered. Alias: m.emit(event).

Events

Each state transition triggers 3 events. important: When listening to :enter or :leave events, the callback must be called so that the state machine can proceed to the next state.

error           incorrect transition
<state>         when new state is entered
<state>:enter   when transitioning into state
<state>:leave   when transitioning away from state
done            when state transition finished

Why?

Most state machines have overly complicated interfaces for managing state. The fsm state machine is simple but doesn't manage state for you, so I wrote a wrapper around it that manages state in an event-driven way. The initial use case was to manage complex, stateful UI elements but it can be used anywhere.

License

MIT

fsm-event's People

Contributors

Stargazers

Watchers

Forkers

fuzzyalej nvdnkpr

fsm-event's Issues

return instead of throw on invalid state?

Maybe we're being overly strict, and a return suffices. Curious to hear what other people think. - https://github.com/yoshuawuyts/fsm-event/blob/master/index.js#L32

transitions

forgive me, I don't understand the purpose of defining transitions in your lib other than for defining which states can reach each other. i.e.

It makes more sense in my head to use transition names rather than the states.

m.init('START') // set initial state
m('pause') // PAUSED state

Can you elaborate on your design? I'm not sure I understand. Not your fault, probably mine.

be more explicit with event documentation

Move to h3-based events section in docs with code examples + descriptions. A single code block doesn't suffice.

Passing values with event

Is there a way, or is it unwise, to allow passing of arguments to state transitions?

e.g. m('play', 'path/to/some/file')

m.on('PLAYING', (arg1) => console.log(arg1) // 'path/to/some/file')

non-direct transition chains

fsm supports checking for non-direct transitions. e.g. given a -> b it can figure out it needs to do a -> b -> c. fsm-event doesn't support this yet, though it might be neat to have. I currently don't have a use case for this, but if anyone want to implement it patches would be more than welcome.

optional callback when transitioning

Right now if :leave or :enter events require a callback to be called lest the state machine hangs. We could detect whether the callback is defined and proceed synchronously if it isn't.

// works now
m.on('START:leave', cb => console.log('leaving start!'); cb())

// doesn't work currently; expected
m.on('START:leave', cb => console.log('leaving start!'))

// doesn't work currently, but will work after detection is added
m.on('START:leave', () => console.log('leaving start!'))

expose a `.on('done')` event

.on('done') / .on('success') to indicate the transition finished and we're ready to accept new transitions. Works nicely with queueing / buffer mechanisms. If async / delayed actions happen there's the possibility of race conditions. I think exposing a hook is better than building queueing straight in.