pass rule-results to success and failure events

Author: Cache Hamm

docs/engine.md

@@ -128,42 +128,22 @@ the same priority may still emit events, even though the engine has been told to
 engine.stop()
 ```
 
-### engine.on(String event, Function callback) -> Engine
-
-Listens for events emitted as rules are being evaluated.  "event" is determined by the [rule event](./rules.md#Events).
-
-```js
-let rule = new Rule({
-  event: {
-    type: 'my-event',
-    params: {
-      customValue: 'my-custom-value'
-    }
-  }
-})
-
-// whenever rule is evaluated and conditions pass, 'my-event' will trigger
-engine.on('my-event', function(params) {
-  console.log(params) // { customValue: 'my-custom-value' }
-})
-```
-
 There are two generic event emissions that trigger automatically:
 
 #### ```engine.on('success', cb)```
 
-Fires when *any* rule passes.  In this case the callback will receive the entire event object.
+Fires when a rule passes. In this case the callback will receive the entire event object.
 
 ```js
-engine.on('success', function(event, almanac) {
+engine.on('success', function(event, almanac, ruleResult) {
 })
 ```
 
 #### ```engine.on('failure', cb)```
 
-Companion to 'success', except fires when any rule fails.
+Companion to 'success', except fires when a rule fails.
 
 ```js
-engine.on('failure', function(rule, almanac) {
+engine.on('failure', function(rule, almanac, ruleResult) {
 })
 ```

docs/rules.md

@@ -221,16 +221,16 @@ See the [fact-comparison](../examples/08-fact-comparison.js) example
 
 Listen for `success` and `failure` events emitted when rule is evaluated.
 
-#### ```rule.on('success', Function(Object event, Almanac almanac))```
+#### ```rule.on('success', Function(Object event, Almanac almanac, RuleResult ruleResult))```
 
 ```js
 // whenever rule is evaluated and the conditions pass, 'success' will trigger
-rule.on('success', function(event, almanac) {
+rule.on('success', function(event, almanac, ruleResult) {
   console.log(event) // { type: 'my-event', params: { id: 1 }
 })
 ```
 
-#### ```rule.on('failure', Function(Object event, Almanac almanac))```
+#### ```rule.on('failure', Function(Object event, Almanac almanac, RuleResult ruleResult))```
 
 Companion to `success`, except fires when the rule fails.
 

package.json

@@ -66,6 +66,7 @@
   },
   "dependencies": {
     "debug": "2.2.0",
+    "lodash.clonedeep": "4.5.0",
     "lodash.isplainobject": "4.0.6",
     "object-hash": "1.1.5",
     "params": "0.1.1",

src/engine.js

@@ -144,14 +144,15 @@ class Engine extends EventEmitter {
         debug(`engine::run status:${this.status}; skipping remaining rules`)
         return
       }
-      return rule.evaluate(almanac).then((rulePasses) => {
-        debug(`engine::run ruleResult:${rulePasses}`)
-        if (rulePasses) {
-          this.emit('success', rule.event, almanac)
-          this.emit(rule.event.type, rule.event.params, this)
+      return rule.evaluate(almanac).then((ruleResult) => {
+        debug(`engine::run ruleResult:${ruleResult.result}`)
+        if (ruleResult.result) {
+          this.emit('success', rule.event, almanac, ruleResult)
+          this.emit(rule.event.type, rule.event.params, this) // DEPRECATED; todo - remove from docs
           almanac.factValue('success-events', { event: rule.event })
+        } else {
+          this.emit('failure', rule, almanac, ruleResult)
         }
-        if (!rulePasses) this.emit('failure', rule, almanac)
       })
     }))
   }

src/rule.js

@@ -3,6 +3,7 @@
 import params from 'params'
 import Condition from './condition'
 import { EventEmitter } from 'events'
+import deepClone from 'lodash.clonedeep'
 
 let debug = require('debug')('json-rules-engine')
 
@@ -124,9 +125,15 @@ class Rule extends EventEmitter {
   /**
    * Evaluates the rule, starting with the root boolean operator and recursing down
    * All evaluation is done within the context of an almanac
-   * @return {Promise(boolean)} rule evaluation result
+   * @return {Promise(RuleResult)} rule evaluation result
    */
   async evaluate (almanac) {
+    let ruleResult = {
+      conditions: deepClone(this.conditions),
+      event: deepClone(this.event),
+      priority: deepClone(this.priority)
+    }
+
     /**
      * Evaluates the rule conditions
      * @param  {Condition} condition - condition to evaluate
@@ -153,11 +160,11 @@ class Rule extends EventEmitter {
           else throw err
         }
       }
-
+      condition.result = passes
       if (passes) {
-        this.emit('success', this.event, almanac)
+        this.emit('success', this.event, almanac, ruleResult)
       } else {
-        this.emit('failure', this.event, almanac)
+        this.emit('failure', this.event, almanac, ruleResult)
       }
       return passes
     }
@@ -238,10 +245,14 @@ class Rule extends EventEmitter {
       return prioritizeAndRun(conditions, 'all')
     }
 
-    if (this.conditions.any) {
-      return await any(this.conditions.any)
+    if (ruleResult.conditions.any) {
+      let result = await any(ruleResult.conditions.any)
+      ruleResult.result = result
+      return ruleResult
     } else {
-      return await all(this.conditions.all)
+      let result = await all(ruleResult.conditions.all)
+      ruleResult.result = result
+      return ruleResult
     }
   }
 }

test/engine-event.test.js

@@ -30,10 +30,12 @@ describe('Engine: event', () => {
 
   describe('engine events', () => {
     it('passes the event type and params', (done) => {
-      engine.on('success', function (a, engine) {
+      engine.on('success', function (a, almanac, ruleResult) {
         try {
           expect(a).to.eql(event)
-          expect(engine).to.eql(engine)
+          expect(almanac).to.be.an.instanceof(Almanac)
+          expect(ruleResult.result).to.be.true()
+          expect(ruleResult.conditions.any[0].result).to.be.true()
         } catch (e) { return done(e) }
         done()
       })
@@ -71,7 +73,7 @@ describe('Engine: event', () => {
       })
       engine.addRule(drinkOrderRule)
       return new Promise((resolve, reject) => {
-        engine.on('success', function (event, almanac) {
+        engine.on('success', function (event, almanac, ruleResult) {
           switch (event.type) {
             case 'setDrinkingFlag':
               almanac.addRuntimeFact('canOrderDrinks', event.params.canOrderDrinks)
@@ -91,11 +93,12 @@ describe('Engine: event', () => {
     it('on-success, it passes the event type and params', (done) => {
       let failureSpy = sinon.spy()
       let rule = engine.rules[0]
-      rule.on('success', function (e, a) {
+      rule.on('success', function (e, almanac, ruleResult) {
         try {
           expect(e).to.eql(event)
-          expect(a).to.be.an.instanceof(Almanac)
+          expect(almanac).to.be.an.instanceof(Almanac)
           expect(failureSpy.callCount).to.equal(0)
+          expect(ruleResult.conditions.any[0].result).to.be.true()
         } catch (err) { return done(err) }
         done()
       })
@@ -106,11 +109,12 @@ describe('Engine: event', () => {
     it('on-failure, it passes the event type and params', (done) => {
       let successSpy = sinon.spy()
       let rule = engine.rules[0]
-      rule.on('failure', function (e, a) {
+      rule.on('failure', function (e, almanac, ruleResult) {
         try {
           expect(e).to.eql(event)
-          expect(a).to.be.an.instanceof(Almanac)
+          expect(almanac).to.be.an.instanceof(Almanac)
           expect(successSpy.callCount).to.equal(0)
+          expect(ruleResult.conditions.any[0].result).to.be.false()
         } catch (err) { return done(err) }
         done()
       })