feat: allow methods to pass arguments to force update status (#5)

* feat: listen to allowForce component and allow to force status change

* chore: delete the unwanted code from tests

* test: add some test to cover force status update

* documentation: update readme for force status change option

* remove .only from new tests

* test: clean up force change tests

* docs: reword docs for allowForce setting

* test: add additional test to verify sequential state change

* refactor: improve code readability

* refactor: always expect params as first method argument

* docs: document the params method argument

Author: rahulbile

README.md

@@ -30,6 +30,9 @@ When a model method that is controlled by the Finite State Machine is called it
   "mixins": {
     "StateMachine": {
       "stateProperty": "status",
+      "settings": {
+        "allowForce": true
+      },
       "events": [
         { "name": "activate", "from": "none", "to": "active", "transitionOptions": { "skipBeforeSave" : true } },
         { "name": "cancel", "from": "active", "to": "canceled" },
@@ -46,6 +49,10 @@ When a model method that is controlled by the Finite State Machine is called it
 
   [String] : The name of the model's state property. *(default: 'state')*
 
+- `settings`
+
+  [Object] : Settings used to control state machine operations. Currently the only supported option is `allowForce` which when set to `true` makes it possible to carry out an otherwise invalid state change by passing in `{ force: true }` at method call time. This option can also be set per event. *(default: {})*
+
 - `events`
 
   [Array] : A list of events available to the state machine. Refer to the [FSM As Promised documentation](https://github.com/vstirbu/fsm-as-promised) for details on how events should be defined. *(default: [])*
@@ -86,7 +93,7 @@ example, the above mixin configuration will result in the following methods bein
 - `MyModel.prototype.reactivate`
 - `MyModel.prototype.expire`
 
-These methods can be called as any other:
+These methods all accept a first argument that is a settings object that is used by the fsm to determine how it functions (eg passing `{ force: true }` (see `allowForce` above). All arguments will be available from within the various fsm notifications.
 
 ```javascript
 MyModel.findOne()
@@ -96,7 +103,7 @@ MyModel.findOne()
   })
   .then(instance => {
     log.debug(`Current state is: ${instance.state}`) // Current state is: canceled
-    return instance.reactivate()
+    return instance.reactivate({ force: true })
   })
   .then(instance => {
     log.debug(`Current state is: ${instance.state}`) // Current state is: active

lib/mixins/state-machine.js

@@ -127,9 +127,21 @@ module.exports = function StateMachine(Model, settings) {
 
   // Add event methods to the prototype.
   Model.getEventNames(settings.events).forEach(eventName => {
-    Model.prototype[eventName] = function event(...args) {
+    Model.prototype[eventName] = function event(params = {}, ...args) {
+      const eventNameIndex = _.findKey(settings.events, { 'name': eventName })
+      const forceFsmSetting = _.get(settings, 'settings.allowForce')
+      const forceEventSetting = _.get(settings, `events[${eventNameIndex}].settings.allowForce`)
+      const force = _.get(params, 'force')
+
+      // If force has been requested, override the state machine config.
+      if (force && (forceFsmSetting || forceEventSetting)) {
+        _.assign(settings.events[eventNameIndex].from, [ this.status ])
+      }
+
+      // Get the FSM.
       const fms = Model.app.getStateMachine(this)
 
+      // Run the event method.
       return fms[eventName](this, ...args)
         .then(result => result)
         .finally(() => Model.app.deleteStateMachine(this))

test/fullcube-state-machine/.apiconnect/config

@@ -0,0 +1,88 @@
+{
+  "name": "Order",
+  "base": "PersistedModel",
+  "idInjection": true,
+  "options": {
+    "validateUpsert": true
+  },
+  "properties": {
+    "status": {
+      "type": "string",
+      "required": true,
+      "default": "prepare"
+    }
+  },
+  "validations": [],
+  "relations": {},
+  "acls": [],
+  "methods": {
+    "cancel": {
+      "isStatic": false,
+      "accepts": [],
+      "returns": {
+        "arg": "order",
+        "type": "Order",
+        "root": true,
+        "description": "The updated order"
+      },
+      "description": "Cancel a order",
+      "http": [
+        {
+          "path": "/cancel",
+          "verb": "put"
+        }
+      ]
+    },
+    "deliver": {
+      "isStatic": false,
+      "accepts": [],
+      "returns": {
+        "arg": "order",
+        "type": "Order",
+        "root": true,
+        "description": "The updated order"
+      },
+      "description": "Deliver a canceled order",
+      "http": [
+        {
+          "path": "/deliver",
+          "verb": "put"
+        }
+      ]
+    },
+    "prepare": {
+      "isStatic": false,
+      "accepts": [{
+        "arg": "params",
+        "type": "Object",
+        "description": "Transition params."
+      }],
+      "returns": {
+        "arg": "order",
+        "type": "Order",
+        "root": true,
+        "description": "The updated order"
+      },
+      "description": "Prepare a order",
+      "http": [
+        {
+          "path": "/prepare",
+          "verb": "put"
+        }
+      ]
+    }
+  },
+  "mixins": {
+    "StateMachine": {
+      "stateProperty": "status",
+      "settings": {
+        "allowForce": true
+      },
+      "events": [
+        { "name": "cancel", "from": "prepare", "to": "canceled" },
+        { "name": "deliver", "from": "prepare", "to": "delivered", "settings": { "allowForce" : true } },
+        { "name": "prepare", "from": [ "none" ], "to": "prepared" }
+      ]
+    }
+  }
+}

test/fullcube-state-machine/common/models/order.json

@@ -0,0 +1,29 @@
+'use strict'
+
+const Promise = require('bluebird')
+const log = require('loglevel')
+
+log.enableAll()
+
+module.exports = class FcOrder {
+  constructor(instance) {
+    this.instance = instance
+  }
+  prepare() {
+    return Promise.delay(2000).then(() => {
+      log.info(`Order ${this.instance.id} prepared`)
+    })
+  }
+
+  cancel() {
+    return Promise.delay(2000).then(() => {
+      log.info(`Order ${this.instance.id} canceled`)
+    })
+  }
+
+  deliver() {
+    return Promise.delay(2000).then(() => {
+      log.info(`Order ${this.instance.id} delivered`)
+    })
+  }
+}