Added optional final state(s) and isFinished() helper method (issue jakesgordon#23)

Author: jakesgordon

RELEASE_NOTES.md

@@ -1,6 +1,7 @@
 Version 2.2.0 (unreleased)
 --------------------------
 
+ * Added optional `final` state(s) and `isFinished()` helper method (issue #23)
  * extended `fsm.is()` to accept an array of states (in addition to a single state)
  * Added generic event callbacks 'onbeforeevent' and 'onafterevent' (issue #28)
  * Added generic state callbacks 'onleavestate' and 'onenterstate'  (issue #28)

state-machine.js

@@ -38,6 +38,7 @@
     create: function(cfg, target) {
 
       var initial   = (typeof cfg.initial == 'string') ? { state: cfg.initial } : cfg.initial; // allow for a simple string, or an object with { state: 'foo', event: 'setup', defer: true|false }
+      var terminal  = cfg.terminal || cfg['final'];
       var fsm       = target || cfg.target  || {};
       var events    = cfg.events || [];
       var callbacks = cfg.callbacks || {};
@@ -74,6 +75,8 @@
       fsm.cannot  = function(event) { return !this.can(event); };
       fsm.error   = cfg.error || function(name, from, to, args, error, msg, e) { throw e || msg; }; // default behavior when something unexpected happens is to throw an exception, but caller can override this behavior if desired (see github issue #3 and #17)
 
+      fsm.isFinished = function() { return this.is(terminal); };
+
       if (initial && !initial.defer)
         fsm[initial.event]();
 

state-machine.min.js

@@ -111,6 +111,53 @@ test("is", function() {
 
 //-----------------------------------------------------------------------------
 
+test("isFinished", function() {
+
+  var fsm = StateMachine.create({
+    initial: 'green', terminal: 'red',
+    events: [
+      { name: 'warn',  from: 'green',  to: 'yellow' },
+      { name: 'panic', from: 'yellow', to: 'red'    }
+  ]});
+
+  equals(fsm.current,     'green');
+  equals(fsm.isFinished(), false);
+
+  fsm.warn();
+  equals(fsm.current,     'yellow');
+  equals(fsm.isFinished(), false);
+
+  fsm.panic();
+  equals(fsm.current,     'red');
+  equals(fsm.isFinished(), true);
+
+});
+
+//-----------------------------------------------------------------------------
+
+test("isFinished - without specifying terminal state", function() {
+
+  var fsm = StateMachine.create({
+    initial: 'green',
+    events: [
+      { name: 'warn',  from: 'green',  to: 'yellow' },
+      { name: 'panic', from: 'yellow', to: 'red'    }
+  ]});
+
+  equals(fsm.current,     'green');
+  equals(fsm.isFinished(), false);
+
+  fsm.warn();
+  equals(fsm.current,     'yellow');
+  equals(fsm.isFinished(), false);
+
+  fsm.panic();
+  equals(fsm.current,     'red');
+  equals(fsm.isFinished(), false);
+
+});
+//-----------------------------------------------------------------------------
+
 test("inappropriate events", function() {
 
   var fsm = StateMachine.create({