Sunday, October 2, 2011

A State Manager in JavaScript

The following is an implementation for a state manager written in JavaScript. More than one state can be "on" at one moment but mutual exclusivity rules can be set up to allow certain states to not be "on" at the same time i.e. if one of the states is switched on while the other is already on, the latter will be switched off since they can't be both on at the same time.

It also supports two hooks which can be used if you want to be notified when states are changed.

It's implemented with a fluent interface to allow for method-chaining.

The source is here: https://github.com/dreasgrech/statemanager-js

I've set up a simple demo to show how it can be used. You can view it here: http://dreasgrech.com/upload/statemanager-js/demo.html


Basic Usage

var state = stateManager();
state.turnOn("state 1", "state 2");

state.on("state 1"); // true
state.on("state 2"); // true
state.on("state 3"); // false

state.toggle("state 2"); // "state 2" is now off
state.on("state 2"); // false
toggle returns the new state after it's been toggled.

Mutual Exclusivity

var state = stateManager();

state.mutex("state 1", "state 3"); // "state 1" and "state 2" now cannot be both on at the same time
state.mutex("state 2", "state 3"); // "state 2" and "state 3" now cannot be both on at the same time

state.turnOn("state 1");
state.turnOn("state 3"); // "state 1" will now be turned off since 1 and 3 are mutually exclusive
state.turnOn("state 1"); // turning "state 1" on, but switching "state 3" off for the same reason
state.turnOn("state 2"); // if "state 3" was on at this point, it would have been switched off

Hooks

var state = stateManager();

state.onStateChanged(function (state, value) { // The global event; fires every time a state changes
  console.log(state + " is now " + value);
});

state.onStateChanged("state 1", function (value) { // The event that will only fire when "state 1" changes
  console.log("[Custom hook] state 1 has been changed.  New value: " + value); 
});

state.turnOn("state 1");
state.turnOn("state 3", "state 2"); 
state.toggle("state 1"); 
state.turnOn("state 2"); 
Output:
state 1 is now 1
[Custom hook] state 1 has been changed. New value: 1
state 3 is now 1
state 2 is now 1
state 1 is now 0
[Custom hook] state 1 has been changed. New value: 0
Note that the onStateChanged event fires only when a state changes. For example, if you turnOn("state 2") while "state 2" is already on, the event will not fire. The same goes for when a state is off and you try to turnOff.