[issue jakesgordon#28] - Added generalized callbacks for intercepting all events and state transitions (instead of having a callback per-event/state)

 * onbeforeevent
 * onleavestate
 * onenterstate
 * onafterevent

E.g.

 * `onbeforeevent` is called for every event, while `onbeforeGO`   is only called before the GO event.
 * `onleavestate`  is called for every state, while `onleaveRED`   is only called when leaving the RED state.
 * `onenterstate`  is called for every state, while `onenterGREEN` is only called when entering the GREEN state.
 * `onafterevent`  is called for every event, while `onafterGO`    is only called after the GO event.

NOTE: deprecated the legacy `onchangestate` callback (its the same as `onenterstate`)

Author: jakesgordon

README.md

@@ -89,25 +89,47 @@ the same name if you prefer the verbose approach.
 Callbacks
 =========
 
-4 callbacks are available if your state machine has methods using the following naming conventions:
+4 types of callback are available using the following naming conventions:
 
- * onbefore**event** - fired before the event
- * onleave**state**  - fired when leaving the old state
- * onenter**state**  - fired when entering the new state
- * onafter**event**  - fired after the event
+ * `onbeforeEVENT` - fired before the event
+ * `onleaveSTATE`  - fired when leaving the old state
+ * `onenterSTATE`  - fired when entering the new state
+ * `onafterEVENT`  - fired after the event
+
+>> (using your specific EVENT and STATE names)
 
 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 cancel the event.
- * return `ASYNC` from an `onleavestate` handler to perform an asynchronous state transition (see next section)
+ * return `false` from an `onbeforeEVENT` handler to cancel the event.
+ * 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:
 
- * on**event** - convenience shorthand for onafter**event**
- * on**state** - convenience shorthand for onenter**state**
+ * `onEVENT` - convenience shorthand for `onafterEVENT`
+ * `onSTATE` - convenience shorthand for `onenterSTATE`
+
+In addition, 4 general-purpose callbacks can be used to capture **all** event and state changes:
+
+ * `onbeforeevent` - fired before any event
+ * `onleavestate`  - fired when leaving any state
+ * `onenterstate`  - fired when entering any state
+ * `onafterevent`  - fired after any event
+
+The order in which callbacks occur is as follows:
+
+>> assume event **go** transitions from **red** state to **green**
+
+ * `onbeforego`    - specific handler for the **go** event only
+ * `onbeforeevent` - generic  handler for all events
+ * `onleavered`    - specific handler for the **red** state only
+ * `onleavestate`  - generic  handler for all states
+ * `onentergreen`  - specific handler for the **green** state only
+ * `onenterstate`  - generic  handler for all states
+ * `onaftergo`     - specific handler for the **go** event only
+ * `onafterevent`  - generic  handler for all events
 
-In addition, a generic `onchangestate()` callback can be used to call a single function for _all_ state changes:
+>> NOTE: the legacy `onchangestate` handler has been deprecated and will be removed in a future version
 
 All callbacks will be passed the same arguments:
 
@@ -141,10 +163,10 @@ Callbacks can be specified when the state machine is first created:
 
 Additionally, they can be added and removed from the state machine at any time:
 
-    fsm.ongreen       = null;
-    fsm.onyellow      = null;
-    fsm.onred         = null;
-    fsm.onchangestate = function(event, from, to) { document.body.className = to; };
+    fsm.ongreen      = null;
+    fsm.onyellow     = null;
+    fsm.onred        = null;
+    fsm.onenterstate = function(event, from, to) { document.body.className = to; };
 
 Asynchronous State Transitions
 ==============================

RELEASE_NOTES.md

@@ -1,6 +1,8 @@
 Version 2.2.0 (unreleased)
 --------------------------
 
+ * Added generic event callbacks 'onbeforeevent' and 'onafterevent' (issue #28)
+ * Added generic state callbacks 'onleavestate' and 'onenterstate'  (issue #28)
  * Fixed 'undefined' event return codes (issue #34) - pull from gentooboontoo (thanks!)
  * Allow async event transition to be cancelled (issue #22)
 

state-machine.js

@@ -85,12 +85,43 @@
       }
     },
 
-    beforeEvent: function(fsm, name, from, to, args) { return StateMachine.doCallback(fsm, fsm['onbefore' + name],                     name, from, to, args); },
-    afterEvent:  function(fsm, name, from, to, args) { return StateMachine.doCallback(fsm, fsm['onafter'  + name] || fsm['on' + name], name, from, to, args); },
-    leaveState:  function(fsm, name, from, to, args) { return StateMachine.doCallback(fsm, fsm['onleave'  + from],                     name, from, to, args); },
-    enterState:  function(fsm, name, from, to, args) { return StateMachine.doCallback(fsm, fsm['onenter'  + to]   || fsm['on' + to],   name, from, to, args); },
-    changeState: function(fsm, name, from, to, args) { return StateMachine.doCallback(fsm, fsm['onchangestate'],                       name, from, to, args); },
+    beforeAnyEvent:  function(fsm, name, from, to, args) { return StateMachine.doCallback(fsm, fsm['onbeforeevent'],                       name, from, to, args); },
+    afterAnyEvent:   function(fsm, name, from, to, args) { return StateMachine.doCallback(fsm, fsm['onafterevent'],                        name, from, to, args); },
+    leaveAnyState:   function(fsm, name, from, to, args) { return StateMachine.doCallback(fsm, fsm['onleavestate'],                        name, from, to, args); },
+    enterAnyState:   function(fsm, name, from, to, args) { return StateMachine.doCallback(fsm, fsm['onenterstate'],                        name, from, to, args); },
+    changeState:     function(fsm, name, from, to, args) { return StateMachine.doCallback(fsm, fsm['onchangestate'],                       name, from, to, args); },
+
+    beforeThisEvent: function(fsm, name, from, to, args) { return StateMachine.doCallback(fsm, fsm['onbefore' + name],                     name, from, to, args); },
+    afterThisEvent:  function(fsm, name, from, to, args) { return StateMachine.doCallback(fsm, fsm['onafter'  + name] || fsm['on' + name], name, from, to, args); },
+    leaveThisState:  function(fsm, name, from, to, args) { return StateMachine.doCallback(fsm, fsm['onleave'  + from],                     name, from, to, args); },
+    enterThisState:  function(fsm, name, from, to, args) { return StateMachine.doCallback(fsm, fsm['onenter'  + to]   || fsm['on' + to],   name, from, to, args); },
+
+    beforeEvent: function(fsm, name, from, to, args) {
+      if ((false === StateMachine.beforeThisEvent(fsm, name, from, to, args)) ||
+          (false === StateMachine.beforeAnyEvent( fsm, name, from, to, args)))
+        return false;
+    },
+
+    afterEvent: function(fsm, name, from, to, args) {
+      StateMachine.afterThisEvent(fsm, name, from, to, args);
+      StateMachine.afterAnyEvent( fsm, name, from, to, args);
+    },
+
+    leaveState: function(fsm, name, from, to, args) {
+      var specific = StateMachine.leaveThisState(fsm, name, from, to, args),
+          general  = StateMachine.leaveAnyState( fsm, name, from, to, args);
+      if ((false === specific) || (false === general))
+        return false;
+      else if ((StateMachine.ASYNC === specific) || (StateMachine.ASYNC === general))
+        return StateMachine.ASYNC;
+    },
+
+    enterState: function(fsm, name, from, to, args) {
+      StateMachine.enterThisState(fsm, name, from, to, args);
+      StateMachine.enterAnyState( fsm, name, from, to, args);
+    },
 
+    //===========================================================================
 
     buildEvent: function(name, map) {
       return function() {

state-machine.min.js

@@ -121,8 +121,15 @@ test("callbacks are called when appropriate for multiple 'from' and 'to' transit
       { name: 'rest', from: ['hungry', 'satisfied', 'full', 'sick'], to: 'hungry'    },
     ],
     callbacks: {
-      onchangestate: function(event,from,to) { called.push('onchange from ' + from + ' to ' + to); },
 
+      // generic callbacks
+      onbeforeevent: function(event,from,to) { called.push('onbefore(' + event + ')'); },
+      onafterevent:  function(event,from,to) { called.push('onafter('  + event + ')'); },
+      onleavestate:  function(event,from,to) { called.push('onleave('  + from  + ')'); },
+      onenterstate:  function(event,from,to) { called.push('onenter('  + to    + ')'); },
+      onchangestate: function(event,from,to) { called.push('onchange(' + from + ',' + to + ')'); },
+
+      // specific state callbacks
       onenterhungry:    function() { called.push('onenterhungry');    },
       onleavehungry:    function() { called.push('onleavehungry');    },
       onentersatisfied: function() { called.push('onentersatisfied'); },
@@ -132,6 +139,7 @@ test("callbacks are called when appropriate for multiple 'from' and 'to' transit
       onentersick:      function() { called.push('onentersick');      },
       onleavesick:      function() { called.push('onleavesick');      },
 
+      // specific event callbacks
       onbeforeeat:      function() { called.push('onbeforeeat');      },
       onaftereat:       function() { called.push('onaftereat');       },
       onbeforerest:     function() { called.push('onbeforerest');     },
@@ -141,19 +149,59 @@ test("callbacks are called when appropriate for multiple 'from' and 'to' transit
 
   called = [];
   fsm.eat();
-  deepEqual(called, ['onbeforeeat', 'onleavehungry', 'onentersatisfied', 'onchange from hungry to satisfied', 'onaftereat']);
+  deepEqual(called, [
+    'onbeforeeat',
+    'onbefore(eat)',
+    'onleavehungry',
+    'onleave(hungry)',
+    'onentersatisfied',
+    'onenter(satisfied)',
+    'onchange(hungry,satisfied)',
+    'onaftereat',
+    'onafter(eat)'
+  ]);
 
   called = [];
   fsm.eat();
-  deepEqual(called, ['onbeforeeat', 'onleavesatisfied', 'onenterfull', 'onchange from satisfied to full', 'onaftereat']);
+  deepEqual(called, [
+    'onbeforeeat',
+    'onbefore(eat)',
+    'onleavesatisfied',
+    'onleave(satisfied)',
+    'onenterfull',
+    'onenter(full)',
+    'onchange(satisfied,full)',
+    'onaftereat',
+    'onafter(eat)',
+  ]);
 
   called = [];
   fsm.eat();
-  deepEqual(called, ['onbeforeeat', 'onleavefull', 'onentersick', 'onchange from full to sick', 'onaftereat']);
+  deepEqual(called, [
+    'onbeforeeat',
+    'onbefore(eat)',
+    'onleavefull',
+    'onleave(full)',
+    'onentersick',
+    'onenter(sick)',
+    'onchange(full,sick)',
+    'onaftereat',
+    'onafter(eat)'
+  ]);
 
   called = [];
   fsm.rest();
-  deepEqual(called, ['onbeforerest', 'onleavesick', 'onenterhungry', 'onchange from sick to hungry', 'onafterrest']);
+  deepEqual(called, [
+    'onbeforerest',
+    'onbefore(rest)',
+    'onleavesick',
+    'onleave(sick)',
+    'onenterhungry',
+    'onenter(hungry)',
+    'onchange(sick,hungry)',
+    'onafterrest',
+    'onafter(rest)'
+  ]);
 
 });
 
@@ -168,15 +216,24 @@ test("callbacks are called when appropriate for prototype based state machine",
 
   myFSM.prototype = {
 
-    onchangestate: function(event,from,to) { this.called.push('onchange from ' + from + ' to ' + to); },
+    // generic callbacks
+    onbeforeevent: function(event,from,to) { this.called.push('onbefore(' + event + ')'); },
+    onafterevent:  function(event,from,to) { this.called.push('onafter('  + event + ')'); },
+    onleavestate:  function(event,from,to) { this.called.push('onleave('  + from  + ')'); },
+    onenterstate:  function(event,from,to) { this.called.push('onenter('  + to    + ')'); },
+    onchangestate: function(event,from,to) { this.called.push('onchange(' + from + ',' + to + ')'); },
 
+    // specific state callbacks
+    onenternone:    function() { this.called.push('onenternone');   },
+    onleavenone:    function() { this.called.push('onleavenone');   },
     onentergreen:   function() { this.called.push('onentergreen');  },
     onleavegreen:   function() { this.called.push('onleavegreen');  },
     onenteryellow : function() { this.called.push('onenteryellow'); },
     onleaveyellow:  function() { this.called.push('onleaveyellow'); },
     onenterred:     function() { this.called.push('onenterred');    },
     onleavered:     function() { this.called.push('onleavered');    },
 
+    // specific event callbacks
     onbeforestartup: function() { this.called.push('onbeforestartup'); },
     onafterstartup:  function() { this.called.push('onafterstartup');  },
     onbeforewarn:    function() { this.called.push('onbeforewarn');    },
@@ -203,16 +260,19 @@ test("callbacks are called when appropriate for prototype based state machine",
   equal(a.current, 'green', 'start with correct state');
   equal(b.current, 'green', 'start with correct state');
 
-  deepEqual(a.called, ['onbeforestartup', 'onentergreen', 'onchange from none to green', 'onafterstartup']);
-  deepEqual(b.called, ['onbeforestartup', 'onentergreen', 'onchange from none to green', 'onafterstartup']);
+  deepEqual(a.called, ['onbeforestartup', 'onbefore(startup)', 'onleavenone', 'onleave(none)', 'onentergreen', 'onenter(green)', 'onchange(none,green)', 'onafterstartup', 'onafter(startup)']);
+  deepEqual(b.called, ['onbeforestartup', 'onbefore(startup)', 'onleavenone', 'onleave(none)', 'onentergreen', 'onenter(green)', 'onchange(none,green)', 'onafterstartup', 'onafter(startup)']);
+
+  a.called = [];
+  b.called = [];
 
   a.warn();
 
   equal(a.current, 'yellow', 'maintain independent current state');
   equal(b.current, 'green',  'maintain independent current state');
 
-  deepEqual(a.called, ['onbeforestartup', 'onentergreen', 'onchange from none to green', 'onafterstartup', 'onbeforewarn', 'onleavegreen', 'onenteryellow', 'onchange from green to yellow', 'onafterwarn']);
-  deepEqual(b.called, ['onbeforestartup', 'onentergreen', 'onchange from none to green', 'onafterstartup']);
+  deepEqual(a.called, ['onbeforewarn', 'onbefore(warn)', 'onleavegreen', 'onleave(green)', 'onenteryellow', 'onenter(yellow)', 'onchange(green,yellow)', 'onafterwarn', 'onafter(warn)']);
+  deepEqual(b.called, []);
 
 });