Add rule event emissions; formalize rule chaining

Author: Cache Hamm

docs/almanac.md

@@ -22,6 +22,14 @@ almanac
   .then( values => console.log(values))
 ```
 
+### almanac.addRuntimeFact(String factId, Mixed value)
+
+Sets a constant fact mid-run.  Often used in conjunction with rule and engine event emissions.
+
+```js
+almanac.addRuntimeFact('account-id', 1)
+```
+
 ## Common Use Cases
 
 ### Fact dependencies
@@ -101,4 +109,39 @@ engine.on('success', (event, almanac) => {
       return request.post({ url: `http://my-service/toggle?funded=${!info.funded}`)
     })
 })
-```
+```
+
+### Rule Chaining
+
+The `almanac.addRuntimeFact()` method may be used in conjunction with event emissions to
+set fact values during runtime, effectively enabling _rule-chaining_.  Note that ordering
+of rule execution is enabled via the `priority` option, and is crucial component to propertly
+configuring rule chaining.
+
+```js
+engine.addRule({
+  conditions,
+  event,
+  onSuccess: function (event, almanac) {
+    almanac.addRuntimeFact('rule-1-passed', true) // track that the rule passed
+  },
+  onFailure: function (event, almanac) {
+    almanac.addRuntimeFact('rule-1-passed', false) // track that the rule failed
+  },
+  priority: 10 // a higher priority ensures this rule will be run prior to subsequent rules
+})
+
+// in a later rule:
+engine.addRule({
+  conditions: {
+    all: [{
+      fact: 'rule-1-passed',
+      operator: 'equal',
+      value: true
+    }
+  },
+  priority: 1 // lower priority ensures this is run AFTER its predecessor
+}
+```
+
+See the [full example](../examples/07-rule-chaining.js)

docs/engine.md

@@ -43,7 +43,9 @@ let Rule = require('json-rules-engine').Rule
 engine.addRule({
   conditions: {},
   event: {},
-  priority: 1
+  priority: 1,                             // optional, default: 1
+  onSuccess: function (event, almanac) {}, // optional
+  onFailure: function (event, almanac) {}, // optional
 })
 
 // or rule instance:

docs/rules.md

@@ -76,6 +76,29 @@ let rule = new Rule(jsonString) // restored rule; same conditions, priority, eve
 let jsonObject = rule.toJSON(false) // object: {conditions:{ all: [] }, priority: 50 ...
 ```
 
+### Events
+
+Listen for 'success' and 'failure' events emitted when rule is evaluated.
+
+#### ```rule.on('success', Function(Object event, Almanac almanac))```
+
+```js
+// whenever rule is evaluated and the conditions pass, 'success' will trigger
+rule.on('success', function(event, almanac) {
+  console.log(event) // { type: 'my-event', params: { id: 1 }
+})
+```
+
+#### ```rule.on('failure', Function(Object event, Almanac almanac))```
+
+Companion to 'success', except fires when the rule fails.
+
+```js
+engine.on('failure', function(event, almanac) {
+  console.log(event) // { type: 'my-event', params: { id: 1 }
+})
+```
+
 ## Conditions
 
 Each rule condition must begin with a boolean operator(```all``` or ```any```) at its root.

examples/07-rule-chaining.js

@@ -35,7 +35,13 @@ let drinkRule = {
     }]
   },
   event: { type: 'drinks-screwdrivers' },
-  priority: 10 // IMPORTANT!  Set a higher priority for the drinkRule, so it runs first
+  priority: 10, // IMPORTANT!  Set a higher priority for the drinkRule, so it runs first
+  onSuccess: function (event, almanac) {
+    almanac.addRuntimeFact('screwdriverAficionado', true)
+  },
+  onFailure: function (event, almanac) {
+    almanac.addRuntimeFact('screwdriverAficionado', false)
+  },
 }
 engine.addRule(drinkRule)
 
@@ -68,18 +74,17 @@ let facts
 engine
   .on('success', (event, almanac) => {
     console.log(facts.accountId + ' DID '.green + 'meet conditions for the ' + event.type.underline + ' rule.')
-    almanac.addRuntimeFact('screwdriverAficionado', true)
   })
   .on('failure', rule => {
     console.log(facts.accountId + ' did ' + 'NOT'.red + ' meet conditions for the ' + rule.event.type.underline + ' rule.')
   })
 
 // define fact(s) known at runtime
-facts = { accountId: 'washington', drinksOrangeJuice: true, enjoysVodka: true, isSociable: true, screwdriverAficionado: false }
+facts = { accountId: 'washington', drinksOrangeJuice: true, enjoysVodka: true, isSociable: true }
 engine
   .run(facts)  // first run, using washington's facts
   .then(() => {
-    facts = { accountId: 'jefferson', drinksOrangeJuice: true, enjoysVodka: false, isSociable: true, screwdriverAficionado: false }
+    facts = { accountId: 'jefferson', drinksOrangeJuice: true, enjoysVodka: false, isSociable: true }
     return engine.run(facts) // second run, using jefferson's facts; facts & evaluation are independent of the first run
   })
   .catch(console.log)