Allow event to be cancelled by returning false from onleavestate handler (issue jakesgordon#13)

 - WARNING: this breaks backward compatibility for async transitions
   (you now need to return `StateMachine.ASYNC` instead of `false`)

Author: jakesgordon

README.md

@@ -96,10 +96,11 @@ Callbacks
  * onenter**state**  - fired when entering the new state
  * onafter**event**  - fired after the event
 
-You can affect the event in 2 ways:
+You can affect the event in 3 ways:
 
  * return `false` from an `onbeforeevent` handler to cancel the event.
- * return `false` from an `onleavestate` handler to perform an asynchronous state transition (see next section)
+ * return `false` from an `onleavestate` handler to cancel the event.
+ * return `ASYNC` from an `onleavestate` handler to perform an asynchronous state transition (see next section)
 
 For convenience, the 2 most useful callbacks can be shortened:
 
@@ -155,7 +156,7 @@ A good example of this is when you transition out of a `menu` state, perhaps you
 fade the menu away, or slide it off the screen and don't want to transition to your `game` state
 until after that animation has been performed.
 
-**New in v2.0** you can now return `false` from your `onleavestate` handler and the state machine
+You can now return `StateMachine.ASYNC` from your `onleavestate` handler and the state machine
 will be _'put on hold'_ until you are ready to trigger the transition using the new `transition()`
 method.
 
@@ -179,14 +180,14 @@ For example, using jQuery effects:
           $('#menu').fadeOut('fast', function() {
             fsm.transition();
           });
-          return false; // tell StateMachine to defer next state until we call transition (in fadeOut callback above)
+          return StateMachine.ASYNC; // tell StateMachine to defer next state until we call transition (in fadeOut callback above)
         },
 
         onleavegame: function() {
           $('#game').slideDown('slow', function() {
             fsm.transition();
           };
-          return false; // tell StateMachine to defer next state until we call transition (in slideDown callback above)
+          return StateMachine.ASYNC; // tell StateMachine to defer next state until we call transition (in slideDown callback above)
         }
 
       }

RELEASE_NOTES.md

@@ -1,6 +1,7 @@
 Version 2.1.0 (January 7th 2012)
 --------------------------------
 
+ * Allow event to be cancelled by returning `false` from `onleavestate` handler (issue #13) - WARNING: this breaks backward compatibility for async transitions (you now need to return `StateMachine.ASYNC` instead of `false`)
  * Added explicit return values for event methods (issue #12)
  * Added support for wildcard events that can be fired 'from' any state (issue #11)
  * Added support for no-op events that transition 'to' the same state  (issue #5)

state-machine.js

@@ -20,6 +20,7 @@ StateMachine = {
   },
 
   WILDCARD: '*',
+  ASYNC: 'async',
 
   //---------------------------------------------------------------------------
 
@@ -105,29 +106,35 @@ StateMachine = {
       if (false === StateMachine.beforeEvent(this, name, from, to, args))
         return StateMachine.CANCELLED;
 
-      if (from !== to) {
-
-        var fsm = this;
-        this.transition = function() { // prepare transition method for use either lower down, or by caller if they want an async transition (indicated by a false return value from leaveState)
-          fsm.transition = null; // this method should only ever be called once
-          fsm.current = to;
-          StateMachine.enterState( fsm, name, from, to, args);
-          StateMachine.changeState(fsm, name, from, to, args);
-          StateMachine.afterEvent( fsm, name, from, to, args);
-          return StateMachine.SUCCEEDED;
-        };
-
-        if (false !== StateMachine.leaveState(this, name, from, to, args)) {
-          if (this.transition) // in case user manually called it but forgot to return false
-            return this.transition();
-        }
-
-        return StateMachine.ASYNC; // transition method took care of (or, if async, will take care of) the afterEvent, DONT fall through
+      if (from === to) {
+        StateMachine.afterEvent(this, name, from, to, args);
+        return StateMachine.NOTRANSITION;
       }
 
-      StateMachine.afterEvent(this, name, from, to, args); // this is only ever called if there was NO transition (e.g. if from === to)
+      // prepare a transition method for use EITHER lower down, or by caller if they want an async transition (indicated by an ASYNC return value from leaveState)
+      var fsm = this;
+      this.transition = function() {
+        fsm.transition = null; // this method should only ever be called once
+        fsm.current = to;
+        StateMachine.enterState( fsm, name, from, to, args);
+        StateMachine.changeState(fsm, name, from, to, args);
+        StateMachine.afterEvent( fsm, name, from, to, args);
+      };
+
+      var leave = StateMachine.leaveState(this, name, from, to, args);
+      if (false === leave) {
+        this.transition = null;
+        return StateMachine.CANCELLED;
+      }
+      else if ("async" === leave) {
+        return StateMachine.ASYNC;
+      }
+      else {
+        if (this.transition)
+          this.transition(); // in case user manually called transition() but forgot to return ASYNC
+        return StateMachine.SUCCEEDED;
+      }
 
-      return StateMachine.SUCCEEDED;
     };
   }
 

test/test_async.js

@@ -15,9 +15,9 @@ test("state transitions", function() {
       { name: 'clear', from: 'yellow', to: 'green'  }
     ],
     callbacks: {
-      onleavegreen:  function() { return false; },
-      onleaveyellow: function() { return false; },
-      onleavered:    function() { return false; }
+      onleavegreen:  function() { return StateMachine.ASYNC; },
+      onleaveyellow: function() { return StateMachine.ASYNC; },
+      onleavered:    function() { return StateMachine.ASYNC; }
     }
   });
 
@@ -48,9 +48,9 @@ test("state transitions with delays", function() {
       { name: 'clear', from: 'yellow', to: 'green'  }
     ],
     callbacks: {
-      onleavegreen:  function() { return false; },
-      onleaveyellow: function() { return false; },
-      onleavered:    function() { return false; }
+      onleavegreen:  function() { return StateMachine.ASYNC; },
+      onleaveyellow: function() { return StateMachine.ASYNC; },
+      onleavered:    function() { return StateMachine.ASYNC; }
     }
   });
 
@@ -88,9 +88,9 @@ test("state transition fired during onleavestate callback - immediate", function
       { name: 'clear', from: 'yellow', to: 'green'  }
     ],
     callbacks: {
-      onleavegreen:  function() { this.transition(); return false; },
-      onleaveyellow: function() { this.transition(); return false; },
-      onleavered:    function() { this.transition(); return false; }
+      onleavegreen:  function() { this.transition(); return StateMachine.ASYNC; },
+      onleaveyellow: function() { this.transition(); return StateMachine.ASYNC; },
+      onleavered:    function() { this.transition(); return StateMachine.ASYNC; }
     }
   });
 
@@ -115,7 +115,7 @@ test("state transition fired during onleavestate callback - with delay", functio
       { name: 'panic', from: 'green', to: 'red' }
     ],
     callbacks: {
-      onleavegreen: function() { setTimeout(function() { fsm.transition(); }, 10); return false; },
+      onleavegreen: function() { setTimeout(function() { fsm.transition(); }, 10); return StateMachine.ASYNC; },
       onenterred:   function() { 
         equals(fsm.current, 'red', "panic event should transition from green to red");
         start();
@@ -130,7 +130,7 @@ test("state transition fired during onleavestate callback - with delay", functio
 
 //-----------------------------------------------------------------------------
 
-test("state transition fired during onleavestate callback - but forgot to return false!", function() {
+test("state transition fired during onleavestate callback - but forgot to return ASYNC!", function() {
 
   var fsm = StateMachine.create({
     initial: 'green',
@@ -141,9 +141,9 @@ test("state transition fired during onleavestate callback - but forgot to return
       { name: 'clear', from: 'yellow', to: 'green'  }
     ],
     callbacks: {
-      onleavegreen:  function() { this.transition(); /* return false; */ },
-      onleaveyellow: function() { this.transition(); /* return false; */ },
-      onleavered:    function() { this.transition(); /* return false; */ }
+      onleavegreen:  function() { this.transition(); /* return StateMachine.ASYNC; */ },
+      onleaveyellow: function() { this.transition(); /* return StateMachine.ASYNC; */ },
+      onleavered:    function() { this.transition(); /* return StateMachine.ASYNC; */ }
     }
   });
 
@@ -178,11 +178,11 @@ test("state transitions sometimes synchronous and sometimes asynchronous", funct
   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 callbacks that return false and it magically becomes asynchronous
+  // but add callbacks that return ASYNC and it magically becomes asynchronous
 
-  fsm.onleavegreen  = function() { return false; }
-  fsm.onleaveyellow = function() { return false; }
-  fsm.onleavered    = function() { return false; }
+  fsm.onleavegreen  = function() { return StateMachine.ASYNC; }
+  fsm.onleaveyellow = function() { return StateMachine.ASYNC; }
+  fsm.onleavered    = function() { return StateMachine.ASYNC; }
 
                     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");
@@ -202,7 +202,7 @@ test("state transitions sometimes synchronous and sometimes asynchronous", funct
         fsm.transition(); equals(fsm.current, 'yellow', "warn event should transition from green to yellow");
         start(); // move on to next test
       }, 10);
-      return false;
+      return StateMachine.ASYNC;
     }
   }
   fsm.onleaveyellow = fsm.onleavered = null;
@@ -229,9 +229,9 @@ test("state transition fired without completing previous transition", function()
       { name: 'clear', from: 'yellow', to: 'green'  }
     ],
     callbacks: {
-      onleavegreen:  function() { return false; },
-      onleaveyellow: function() { return false; },
-      onleavered:    function() { return false; }
+      onleavegreen:  function() { return StateMachine.ASYNC; },
+      onleaveyellow: function() { return StateMachine.ASYNC; },
+      onleavered:    function() { return StateMachine.ASYNC; }
     }
   });
 
@@ -261,12 +261,12 @@ test("callbacks are ordered correctly", function() {
     callbacks: {
       onchangestate: function(event,from,to) { called.push('onchange from ' + from + ' to ' + to); },
 
-      onentergreen:  function() { called.push('onentergreen');                },
-      onenteryellow: function() { called.push('onenteryellow');               },
-      onenterred:    function() { called.push('onenterred');                  },
-      onleavegreen:  function() { called.push('onleavegreen');  return false; },
-      onleaveyellow: function() { called.push('onleaveyellow'); return false; },
-      onleavered:    function() { called.push('onleavered');    return false; },
+      onentergreen:  function() { called.push('onentergreen');                             },
+      onenteryellow: function() { called.push('onenteryellow');                            },
+      onenterred:    function() { called.push('onenterred');                               },
+      onleavegreen:  function() { called.push('onleavegreen');  return StateMachine.ASYNC; },
+      onleaveyellow: function() { called.push('onleaveyellow'); return StateMachine.ASYNC; },
+      onleavered:    function() { called.push('onleavered');    return StateMachine.ASYNC; },
 
       onbeforewarn:  function() { called.push('onbeforewarn');                },
       onbeforepanic: function() { called.push('onbeforepanic');               },
@@ -310,9 +310,9 @@ test("cannot fire event during existing transition", function() {
       { name: 'clear', from: 'yellow', to: 'green'  }
     ],
     callbacks: {
-      onleavegreen:  function() { return false; },
-      onleaveyellow: function() { return false; },
-      onleavered:    function() { return false; }
+      onleavegreen:  function() { return StateMachine.ASYNC; },
+      onleaveyellow: function() { return StateMachine.ASYNC; },
+      onleavered:    function() { return StateMachine.ASYNC; }
     }
   });
 

test/test_basics.js

@@ -460,8 +460,8 @@ test("event return values (github issue #12) ", function() {
       { name: 'start',   from: 'ready',   to: 'running' }
     ],
     callbacks: {
-      onbeforefake: function(event,from,to,a,b,c) { return false; }, // this event will be cancelled
-      onleaveready: function(event,from,to,a,b,c) { return false; }  // this state transition is ASYNC
+      onbeforefake: function(event,from,to,a,b,c) { return false;              }, // this event will be cancelled
+      onleaveready: function(event,from,to,a,b,c) { return StateMachine.ASYNC; } // this state transition is ASYNC
     }
   });