update events arguments to be consistent (breaking change)

Author: Cache Hamm

docs/engine.md

@@ -144,6 +144,6 @@ engine.on('success', function(event, almanac, ruleResult) {
 Companion to 'success', except fires when a rule fails.
 
 ```js
-engine.on('failure', function(rule, almanac, ruleResult) {
+engine.on('failure', function(event, almanac, ruleResult) {
 })
 ```

docs/rules.md

@@ -235,7 +235,7 @@ rule.on('success', function(event, almanac, ruleResult) {
 Companion to `success`, except fires when the rule fails.
 
 ```js
-engine.on('failure', function(event, almanac) {
+engine.on('failure', function(event, almanac, ruleResult) {
   console.log(event) // { type: 'my-event', params: { id: 1 }
 })
 ```

src/engine.js

@@ -148,10 +148,9 @@ class Engine extends EventEmitter {
         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)
+          this.emit('failure', rule.event, almanac, ruleResult)
         }
       })
     }))

test/engine-event.test.js

@@ -4,7 +4,7 @@ import engineFactory from '../src/index'
 import Almanac from '../src/almanac'
 import sinon from 'sinon'
 
-describe('Engine: event', () => {
+describe.only('Engine: event', () => {
   let engine
 
   let event = {
@@ -13,18 +13,21 @@ describe('Engine: event', () => {
       canOrderDrinks: true
     }
   }
-  let conditions = {
-    any: [{
-      fact: 'age',
-      operator: 'greaterThanInclusive',
-      value: 21
-    }, {
-      fact: 'qualified',
-      operator: 'equal',
-      value: true
-    }]
-  }
-  beforeEach(() => {
+  /**
+   * sets up a simple 'any' rule with 2 conditions
+   */
+  function simpleSetup () {
+    let conditions = {
+      any: [{
+        fact: 'age',
+        operator: 'greaterThanInclusive',
+        value: 21
+      }, {
+        fact: 'qualified',
+        operator: 'equal',
+        value: true
+      }]
+    }
     engine = engineFactory()
     let ruleOptions = { conditions, event, priority: 100 }
     let determineDrinkingAgeRule = factories.rule(ruleOptions)
@@ -33,10 +36,48 @@ describe('Engine: event', () => {
     engine.addFact('age', 21)
     // set 'qualified' to fail. rule will succeed because of 'any'
     engine.addFact('qualified', false)
-  })
+  }
+
+  /**
+   * sets up a complex rule with nested conditions
+   */
+  function advancedSetup () {
+    let conditions = {
+      any: [{
+        fact: 'age',
+        operator: 'greaterThanInclusive',
+        value: 21
+      }, {
+        fact: 'qualified',
+        operator: 'equal',
+        value: true
+      }, {
+        all: [{
+          fact: 'zipCode',
+          operator: 'in',
+          value: [80211, 80403]
+        }, {
+          fact: 'gender',
+          operator: 'notEqual',
+          value: 'female'
+        }]
+      }]
+    }
+    engine = engineFactory()
+    let ruleOptions = { conditions, event, priority: 100 }
+    let determineDrinkingAgeRule = factories.rule(ruleOptions)
+    engine.addRule(determineDrinkingAgeRule)
+    engine.addFact('age', 10) // age fails
+    engine.addFact('qualified', false) // qualified fails.
+    engine.addFact('zipCode', 80403) // zipCode succeeds
+    engine.addFact('gender', 'male') // gender succeeds
+    // rule will succeed because of 'any'
+  }
+
+  context('engine events: simple', () => {
+    beforeEach(() => simpleSetup())
 
-  context('engine events', () => {
-    it('passes the event type and params', async () => {
+    it('"success" passes the event, almanac, and results', async () => {
       let failureSpy = sinon.spy()
       let successSpy = sinon.spy()
       engine.on('success', function (e, almanac, ruleResult) {
@@ -53,15 +94,22 @@ describe('Engine: event', () => {
       expect(successSpy.callCount).to.equal(1)
     })
 
-    it('emits using the event "type"', (done) => {
-      engine.on('setDrinkingFlag', function (params, e) {
-        try {
-          expect(params).to.eql(event.params)
-          expect(engine).to.eql(e)
-        } catch (e) { return done(e) }
-        done()
+    it('"failure" passes the event, almanac, and results', async () => {
+      let failureSpy = sinon.spy()
+      let successSpy = sinon.spy()
+      engine.on('failure', function (e, almanac, ruleResult) {
+        expect(e).to.eql(event)
+        expect(almanac).to.be.an.instanceof(Almanac)
+        expect(ruleResult.result).to.be.false()
+        expect(ruleResult.conditions.any[0].result).to.be.false()
+        expect(ruleResult.conditions.any[1].result).to.be.false()
+        failureSpy()
       })
-      engine.run()
+      engine.on('success', successSpy)
+      engine.addFact('age', 10) // age fails
+      await engine.run()
+      expect(failureSpy.callCount).to.equal(1)
+      expect(successSpy.callCount).to.equal(0)
     })
 
     it('allows facts to be added by the event handler, affecting subsequent rules', () => {
@@ -101,7 +149,54 @@ describe('Engine: event', () => {
     })
   })
 
-  context('rule events', () => {
+  context('engine events: advanced', () => {
+    beforeEach(() => advancedSetup())
+
+    it('"success" passes the event, almanac, and results', async () => {
+      let failureSpy = sinon.spy()
+      let successSpy = sinon.spy()
+      engine.on('success', function (e, almanac, ruleResult) {
+        expect(e).to.eql(event)
+        expect(almanac).to.be.an.instanceof(Almanac)
+        expect(ruleResult.result).to.be.true()
+        expect(ruleResult.conditions.any[0].result).to.be.false()
+        expect(ruleResult.conditions.any[1].result).to.be.false()
+        expect(ruleResult.conditions.any[2].result).to.be.true()
+        expect(ruleResult.conditions.any[2].all[0].result).to.be.true()
+        expect(ruleResult.conditions.any[2].all[1].result).to.be.true()
+        successSpy()
+      })
+      engine.on('failure', failureSpy)
+      await engine.run()
+      expect(failureSpy.callCount).to.equal(0)
+      expect(successSpy.callCount).to.equal(1)
+    })
+
+    it('"failure" passes the event, almanac, and results', async () => {
+      let failureSpy = sinon.spy()
+      let successSpy = sinon.spy()
+      engine.on('failure', function (e, almanac, ruleResult) {
+        expect(e).to.eql(event)
+        expect(almanac).to.be.an.instanceof(Almanac)
+        expect(ruleResult.result).to.be.false()
+        expect(ruleResult.conditions.any[0].result).to.be.false()
+        expect(ruleResult.conditions.any[1].result).to.be.false()
+        expect(ruleResult.conditions.any[2].result).to.be.false()
+        expect(ruleResult.conditions.any[2].all[0].result).to.be.false()
+        expect(ruleResult.conditions.any[2].all[1].result).to.be.false()
+        failureSpy()
+      })
+      engine.on('success', successSpy)
+      engine.addFact('zipCode', 99992) // zipCode fails
+      engine.addFact('gender', 'female') // gender fails
+      await engine.run()
+      expect(failureSpy.callCount).to.equal(1)
+      expect(successSpy.callCount).to.equal(0)
+    })
+  })
+
+  context('rule events: simple', () => {
+    beforeEach(() => simpleSetup())
     it('on-success, it passes the event type and params', async () => {
       let failureSpy = sinon.spy()
       let successSpy = sinon.spy()
@@ -118,6 +213,7 @@ describe('Engine: event', () => {
       rule.on('failure', failureSpy)
       await engine.run()
       expect(successSpy.callCount).to.equal(1)
+      expect(failureSpy.callCount).to.equal(0)
     })
 
     it('on-failure, it passes the event type and params', async () => {
@@ -138,6 +234,7 @@ describe('Engine: event', () => {
       engine.addFact('age', 10)
       await engine.run()
       expect(failureSpy.callCount).to.equal(1)
+      expect(successSpy.callCount).to.equal(0)
     })
   })
 })

test/engine-failure.test.js

@@ -25,7 +25,7 @@ describe('Engine: failure', () => {
     let failureSpy = sinon.spy()
     engine.on('failure', failureSpy)
     await engine.run()
-    expect(failureSpy).to.have.been.calledWith(engine.rules[0])
+    expect(failureSpy).to.have.been.calledWith(engine.rules[0].event)
   })
 
   it('does not emit when a rule passes', async () => {