allow the choice between sync and async transition to be made at run-time if desired by using onleavestate return value (false) instead of an explicit design-time async attribute on the event (although still support both methods)

Author: jakesgordon

state-machine.js

@@ -48,32 +48,32 @@ StateMachine = {
 
   beforeEvent: function(name, args) {
     var func = this['onbefore' + name];
-    if (func && (false === func.apply(this, args)))
-      return false;
+    if (func)
+      return func.apply(this, args);
+  },
+
+  afterEvent: function(name, args) {
+    var func = this['onafter'  + name] || this['on' + name];
+    if (func)
+      return func.apply(this, args);
   },
 
-  exitState: function(from, args) {
+  leaveState: function(from, args) {
     var func = this['onleave' + from];
     if (func)
-      func.apply(this, args);
+      return func.apply(this, args);
   },
 
   enterState: function(to, args) {
     var func = this['onenter' + to] || this['on' + to];
     if (func)
-      func.apply(this, args);
+      return func.apply(this, args);
   },
 
   changeState: function(from, to, args) {
     var func = this['onchangestate'];
     if (func)
-      func.apply(this, [from,to].concat(args));
-  },
-
-  afterEvent: function(name, args) {
-    var func = this['onafter'  + name] || this['on' + name];
-    if (func)
-      func.apply(this, args);
+      return func.apply(this, [from,to].concat(args));
   },
 
   transition: function(name, from, to, args) {
@@ -96,16 +96,21 @@ StateMachine = {
       var to    = map[from].to;
       var async = map[from].async;
       var self  = this;
-      var args  = Array.prototype.slice.call(arguments);
+      var args  = Array.prototype.slice.call(arguments); // turn arguments into pure array
 
       if (this.current != to) {
-        if (StateMachine.beforeEvent.call(this, name, args) === false)
+
+        if (false === StateMachine.beforeEvent.call(this, name, args))
           return;
+
         this.transition      = function() { StateMachine.transition.call(self, name, from, to, args); self.transition = null; };
         this.transition.from = from;
         this.transition.to   = to;
-        StateMachine.exitState.call(this, this.current, arguments);
-        if (!async && this.transition) // if not async OR user already called transition method (e.g. in an onleavestate hook)
+
+        if (false === StateMachine.leaveState.call(this, this.current, args))
+          async = true;
+
+        if (!async && this.transition) // if not async OR user already called transition method (e.g. explicitly in an onleavestate hook)
           this.transition();
       }
 

test/test_async.js

@@ -135,6 +135,61 @@ test("state transition fired during onleavestate hook - with MIXED async and non
 
 //-----------------------------------------------------------------------------
 
+test("state transitions using onleavestate run-time return value instead of design-time async attribute", function() {
+
+  var fsm = StateMachine.create({
+    initial: 'green',
+    events: [
+      { name: 'warn',  from: 'green',  to: 'yellow' },
+      { name: 'panic', from: 'yellow', to: 'red'    },
+      { name: 'calm',  from: 'red',    to: 'yellow' },
+      { name: 'clear', from: 'yellow', to: 'green'  }
+  ]});
+
+  // default behavior is synchronous
+
+                    equals(fsm.current, 'green',  "initial state should be green");
+  fsm.warn();       equals(fsm.current, 'yellow', "warn event should transition from green to yellow");
+  fsm.panic();      equals(fsm.current, 'red',    "panic event should transition from yellow to red");
+  fsm.calm();       equals(fsm.current, 'yellow', "calm event should transition from red to yellow");
+  fsm.clear();      equals(fsm.current, 'green',  "clear event should transition from yellow to green");
+
+  // but add hooks that return false and it magically becomes asynchronous
+
+  fsm.onleavegreen  = function() { return false; }
+  fsm.onleaveyellow = function() { return false; }
+  fsm.onleavered    = function() { return false; }
+
+                    equals(fsm.current, 'green',  "initial state should be green");
+  fsm.warn();       equals(fsm.current, 'green',  "should still be green because we haven't transitioned yet");
+  fsm.transition(); equals(fsm.current, 'yellow', "warn event should transition from green to yellow");
+  fsm.panic();      equals(fsm.current, 'yellow', "should still be yellow because we haven't transitioned yet");
+  fsm.transition(); equals(fsm.current, 'red',    "panic event should transition from yellow to red");
+  fsm.calm();       equals(fsm.current, 'red',    "should still be red because we haven't transitioned yet");
+  fsm.transition(); equals(fsm.current, 'yellow', "calm event should transition from red to yellow");
+  fsm.clear();      equals(fsm.current, 'yellow', "should still be yellow because we haven't transitioned yet");
+  fsm.transition(); equals(fsm.current, 'green',  "clear event should transition from yellow to green");
+
+  // this allows you to make on-the-fly decisions about whether async or not ...
+
+  fsm.onleavegreen = function(async) {
+    if (async) {
+      setTimeout(function() { fsm.transition() }, 10);
+      return false;
+    }
+  }
+  fsm.onleaveyellow = fsm.onleavered = null;
+
+  fsm.warn(false);  equals(fsm.current, 'yellow', "expected synchronous transition from green to yellow");
+  fsm.clear();      equals(fsm.current, 'green',  "clear event should transition from yellow to green");
+  fsm.warn(true);   equals(fsm.current, 'green',  "should still be green because we haven't transitioned yet");
+  fsm.transition(); equals(fsm.current, 'yellow', "warn event should transition from green to yellow");
+
+});
+
+//-----------------------------------------------------------------------------
+
+
 test("state transition fired without completing previous transition", function() {
 
   var fsm = StateMachine.create({