engineering

engineering [![Module Version][npm-img]][npm-url] [![MIT License][license-img]][license-url] [![Build Status][travis-img]][travis-link] [![Coverage Status][coveralls-img]][coveralls-link]
===========

Engineer lightweight finite state machines.

Available in both Node.js and web browsers using Browserify.

Synopsis
--------

Installation is easy via npm:

``
npm install [--save] engineering
`

Defining a state machine is very straightforward:

`js
var engineer = require('engineering');

function Client() {
// Define state machine for WebSocket state
this.connection = engineer({
states: {
// connected -> disconnecting
connected: ['disconnecting'],

// connecting -> connected, disconnected
connecting: ['connected', 'disconnected'],

// disconnecting -> disconnected
disconnecting: ['disconnected'],

// disconnected -> connecting
disconnected: ['connecting']
},

// Default state is disconnected
default: 'disconnected'
});
}
`

React to state machine transitions easily:

`js
function Client() {
// ...same as above

// When connected, relay WebSocket's "message" notification
this.connection.on('connected', function (ws) {
var emit = this.emit.bind(this, 'message');

ws.on('message', function (message) {
emit(message);
});
}, this);
}
`

Effortlessly drive action based on the machine's state:

`js
Client.prototype.connect = function (url) {
var self = this;
var connection = self.connection;

return new Promise(function (resolve, reject) {
connection
// Connected, so resolve immediately
.at('connected', resolve)
// Connecting, so wait until connected or disconnected
.at('connecting', function () {
connection
.when('connected', resolve)
.otherwise(reject);
})
// Disconnecting, so wait until disconnected and attempt to connect again
.at('disconnecting', function () {
connection.once('disconnected', function () {
self.connect(url).then(resolve, reject);
});
})
// Disconnected, so attempt WebSocket connection
.otherwise(function () {
connection.to('connecting');

var onError = function (err) {
connection.to('disconnected');
reject(err);
};

var ws = new WebSocket(url);
ws.on('error', onError);
ws.on('open', function () {
ws.removeListener('error', onError);
connection.to('connected', ws);
resolve(ws);
});
});
});
};
`

Know the machine's state using an expressive and easy-to-understand interface:

`js
Client.prototype.send = function (message) {
var connection = this.connection;

connection
.at('connected', function (ws) {
ws.send(message);
})
.otherwise(function () {
throw new Error('Client not connected');
});
};
`

[View the accompanying examples directory for concrete examples.][examples]

API
---

$3

#### engineer(options) → Machine

Creates a new Machine machine with given options.

The following options can be specified:

* states → Object: A map of state transitions. The keys are states, and the value is an array of transitions. Required.
* default → String: The default state. Required.

$3

#### machine.is(state[, fn[, context]]) → Boolean

Indicates whether state machine is currently at state. If at state and fn was passed, the callback will be invoked immediately. state may be an individual state or an array of states.

Returns true if at state; false otherwise.


#### machine.at(state, fn[, context]) → Query

Begins a chainable query of the machine's current state, queuing fn for invocation if at state.

#### query.at(state, fn[, context]) → Query

Identical to machine.at(). Used to query additional states.

#### query.otherwise(fn[, context]) → Any

Performs check of machine's state. If machine is at a state with a previous query, the appropriate callback is invoked; otherwise, fn is invoked.

Returns invoked callback's return value.

$3

#### machine.on(state, fn[, context]) → Machine

If state machine is at state, invokes fn immediately with context. Additionally, every time the state machine transitions to state, fn will be invoked with context.


#### machine.once(state, fn) → Machine

If state machine is at state, invokes fn immediately with context; otherwise, invokes fn with context when machine transitions to state.


#### machine.when(state, fn[, context]) → Watch

Similar to .once(); however, if state machine is not at state and transitions to state next, fn is invoked.

#### watch.when(state, fn[, context]) → Watch

Identical to machine.watch(). Used to watch additional state transitions.

#### watch.otherwise(fn[, context]) → Machine

If state machine transitions to any state that does not have a watch, fn is invoked with context.

$3

#### machine.to(state[, ...args])

Transitions state machine to state. Any passed args will be applied to any callbacks passed to .is(), .at(), .on(), .once(), and .when()`.

License
-------

MIT

[examples]: https://github.com/alfyboza/engineering.js/tree/master/examples

[npm-img]: https://img.shields.io/npm/v/engineering.svg?style=flat
[npm-url]: https://npmjs.org/package/engineering

[license-img]: https://img.shields.io/npm/l/engineering.svg?style=flat
[license-url]: http://choosealicense.com/licenses/mit/

[coveralls-img]: https://img.shields.io/coveralls/alfyboza/engineering.js.svg?style=flat
[coveralls-link]: https://coveralls.io/r/alfyboza/engineering.js?branch=master

[travis-img]: https://img.shields.io/travis/alfyboza/engineering.js.svg?style=flat
[travis-link]: https://travis-ci.org/alfyboza/engineering.js