Engine.run now returns almanac in addition to events

Author: MattCopenhaver

Diff for: docs/engine.md

@@ -139,7 +139,7 @@ engine.removeOperator('startsWithLetter');
 
 
 
-### engine.run([Object facts], [Object options]) -> Promise (Events)
+### engine.run([Object facts], [Object options]) -> Promise ({ events: Events, almanac: Almanac})
 
 Runs the rules engine.  Returns a promise which resolves when all rules have been run.
 
@@ -153,10 +153,12 @@ engine.run({ userId: 1 })
 // returns rule events that were triggered
 engine
   .run({ userId: 1 })
-  .then(function(events) {
-    console.log(events)
+  .then(function(results) {
+    console.log(results.events)
+    // almanac available via results.almanac to interact with as defined in Almanac docs
   })
 ```
+Link to the [Almanac documentation](./almanac.md)
 
 ### engine.stop() -> Engine
 

Diff for: examples/01-hello-world.js

@@ -53,8 +53,8 @@ let facts = { displayMessage: true }
 // run the engine
 engine
   .run(facts)
-  .then(triggeredEvents => { // engine returns a list of events with truthy conditions
-    triggeredEvents.map(event => console.log(event.params.data.green))
+  .then(results => { // engine returns an object with a list of events with truthy conditions
+    results.events.map(event => console.log(event.params.data.green))
   })
   .catch(console.log)
 

Diff for: examples/02-nested-boolean-logic.js

@@ -64,8 +64,8 @@ let facts = {
 // run the engine
 engine
   .run(facts)
-  .then(events => { // run() return events with truthy conditions
-    events.map(event => console.log(event.params.message.red))
+  .then(results => { // run() return and object containing events with truthy conditions
+    results.events.map(event => console.log(event.params.message.red))
   })
   .catch(console.log)
 

Diff for: examples/03-dynamic-facts.js

@@ -71,9 +71,9 @@ engine.addFact('account-information', function (params, almanac) {
 let facts = { accountId: 'lincoln' }
 engine
   .run(facts)
-  .then(events => {
-    if (!events.length) return
-    console.log(facts.accountId + ' is a ' + events.map(event => event.params.message))
+  .then(results => {
+    if (!results.events.length) return
+    console.log(facts.accountId + ' is a ' + results.events.map(event => event.params.message))
   })
   .catch(err => console.log(err.stack))
 

Diff for: examples/07-rule-chaining.js

@@ -2,7 +2,8 @@
 
 /*
  * This is an advanced example demonstrating rules that passed based off the
- * results of other rules
+ * results of other rules by adding runtime facts.  It also demonstrates
+ * accessing the runtime facts after engine execution.
  *
  * Usage:
  *   node ./examples/07-rule-chaining.js
@@ -83,17 +84,35 @@ engine
 facts = { accountId: 'washington', drinksOrangeJuice: true, enjoysVodka: true, isSociable: true }
 engine
   .run(facts) // first run, using washington's facts
+  .then((results) => {
+    // access whether washington is a screwdriverAficionado,
+    // which was determined at runtime via the rules `drinkRules`
+    return results.almanac.factValue('screwdriverAficionado')
+  })
+  .then(isScrewdriverAficionado => {
+    console.log(`${facts.accountId} ${isScrewdriverAficionado ? 'IS'.green : 'IS NOT'.red} a screwdriver aficionado`)
+  })
   .then(() => {
     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
   })
+  .then((results) => {
+    // access whether jefferson is a screwdriverAficionado,
+    // which was determined at runtime via the rules `drinkRules`
+    return results.almanac.factValue('screwdriverAficionado')
+  })
+  .then(isScrewdriverAficionado => {
+    console.log(`${facts.accountId} ${isScrewdriverAficionado ? 'IS'.green : 'IS NOT'.red} a screwdriver aficionado`)
+  })
   .catch(console.log)
 
 /*
  * OUTPUT:
  *
  * washington DID meet conditions for the drinks-screwdrivers rule.
  * washington DID meet conditions for the invite-to-screwdriver-social rule.
+ * washington IS a screwdriver aficionado
  * jefferson did NOT meet conditions for the drinks-screwdrivers rule.
  * jefferson did NOT meet conditions for the invite-to-screwdriver-social rule.
+ * jefferson IS NOT a screwdriver aficionado
  */

Diff for: src/engine.js

@@ -227,7 +227,12 @@ class Engine extends EventEmitter {
       cursor.then(() => {
         this.status = FINISHED
         debug(`engine::run completed`)
-        resolve(almanac.factValue('success-events'))
+        return almanac.factValue('success-events')
+      }).then(events => {
+        resolve({
+          events,
+          almanac
+        })
       }).catch(reject)
     })
   }

Diff for: test/engine-run.test.js

@@ -13,7 +13,6 @@ describe('Engine: run', () => {
     sandbox.restore()
   })
 
-  let event = { type: 'generic' }
   let condition21 = {
     any: [{
       fact: 'age',
@@ -33,9 +32,9 @@ describe('Engine: run', () => {
   beforeEach(() => {
     eventSpy = sandbox.spy()
     engine = engineFactory()
-    rule = factories.rule({ conditions: condition21, event })
+    rule = factories.rule({ conditions: condition21, event: { type: 'generic1' } })
     engine.addRule(rule)
-    rule2 = factories.rule({ conditions: condition75, event })
+    rule2 = factories.rule({ conditions: condition75, event: { type: 'generic2' } })
     engine.addRule(rule2)
     engine.on('success', eventSpy)
   })
@@ -65,22 +64,52 @@ describe('Engine: run', () => {
   describe('returns', () => {
     it('activated events', () => {
       return engine.run({ age: 30 }).then(results => {
-        expect(results.length).to.equal(1)
-        expect(results).to.deep.include(rule.event)
+        expect(results.events.length).to.equal(1)
+        expect(results.events).to.deep.include(rule.event)
       })
     })
 
     it('multiple activated events', () => {
       return engine.run({ age: 90 }).then(results => {
-        expect(results.length).to.equal(2)
-        expect(results).to.deep.include(rule.event)
-        expect(results).to.deep.include(rule2.event)
+        expect(results.events.length).to.equal(2)
+        expect(results.events).to.deep.include(rule.event)
+        expect(results.events).to.deep.include(rule2.event)
       })
     })
 
     it('does not include unactived triggers', () => {
       return engine.run({ age: 10 }).then(results => {
-        expect(results.length).to.equal(0)
+        expect(results.events.length).to.equal(0)
+      })
+    })
+
+    it('includes the almanac', () => {
+      return engine.run({ age: 10 }).then(results => {
+        // expect(results.almanac).assert.instanceOf
+        return results.almanac.factValue('age')
+      }).then(ageFact => expect(ageFact).to.equal(10))
+    })
+  })
+
+  describe('facts updated during run', () => {
+    beforeEach(() => {
+      engine.on('success', (event, almanac, ruleResult) => {
+        console.log(ruleResult)
+        // Assign unique runtime facts per event
+        almanac.addRuntimeFact(`runtime-fact-${event.type}`, ruleResult.conditions.any[0].value)
+      })
+    })
+
+    it('returns an almanac with runtime facts added', () => {
+      return engine.run({ age: 90 }).then(results => {
+        console.log(results)
+        return Promise.all([
+          results.almanac.factValue('runtime-fact-generic1'),
+          results.almanac.factValue('runtime-fact-generic2')
+        ])
+      }).then(promiseValues => {
+        expect(promiseValues[0]).to.equal(21)
+        expect(promiseValues[1]).to.equal(75)
       })
     })
   })