Update docs to reference successEvents

Author: Cache Hamm

README.md

@@ -86,9 +86,8 @@ let facts = {
 // Run the engine to evaluate
 engine
   .run(facts)
-  .then(results => {
-    // 'results' is an object containing successful events, and an Almanac instance containing facts
-    results.events.map(event => console.log(event.params.message))
+  .then(runResult => {
+    runResult.successResults.map(result => console.log(result.event.params.message))
   })
 
 /*
@@ -171,8 +170,8 @@ engine.addFact('account-information', function (params, almanac) {
 let facts = { accountId: 'lincoln' }
 engine
   .run(facts)
-  .then((results) => {
-    console.log(facts.accountId + ' is a ' + results.events.map(event => event.params.message))
+  .then((runResult) => {
+    console.log(facts.accountId + ' is a ' + runResult.successResults.map(result => result.event.params.message))
   })
   .catch(err => console.log(err.stack))
 

docs/almanac.md

@@ -110,13 +110,13 @@ When a rule evalutes truthy and its ```event``` is called, new facts may be defi
 
 ```js
 engine.on('success', (event, almanac) => {
-  // Handle the event using a fact value to process
-  // Retrieve user's account info and make an api call using the results
-  almanac
-    .factValue('account-information', event.params.accountId)
-    .then(info => {
-      return request.post({ url: `http://my-service/toggle?funded=${!info.funded}`)
-    })
+  // Retrieve user's account info based on the event params
+  const info = await almanac.factValue('account-information', event.params.accountId)
+
+  // make an api call using the results
+  await request.post({ url: `http://my-service/toggle?funded=${!info.funded}`)
+
+  // engine execution continues when promise returned to 'success' callback resolves
 })
 ```
 

docs/engine.md

@@ -11,7 +11,7 @@ The Engine stores and executes rules, emits events, and maintains state.
   * [engine.removeRule(Rule instance)](#engineremoverulerule-instance)
   * [engine.addOperator(String operatorName, Function evaluateFunc(factValue, jsonValue))](#engineaddoperatorstring-operatorname-function-evaluatefuncfactvalue-jsonvalue)
   * [engine.removeOperator(String operatorName)](#engineremoveoperatorstring-operatorname)
-  * [engine.run([Object facts], [Object options]) -> Promise ({ events: Events, almanac: Almanac})](#enginerunobject-facts-object-options---promise--events-events-almanac-almanac)
+  * [engine.run([Object facts], [Object options]) -> Promise ({ events: Events, almanac: Almanac, successResults: [], failureResults: []})](#enginerunobject-facts-object-options---promise--events-events-almanac-almanac-successresults--failureresults-)
   * [engine.stop() -> Engine](#enginestop---engine)
     * [engine.on('success', Function(Object event, Almanac almanac, RuleResult ruleResult))](#engineonsuccess-functionobject-event-almanac-almanac-ruleresult-ruleresult)
     * [engine.on('failure', Function(Object event, Almanac almanac, RuleResult ruleResult))](#engineonfailure-functionobject-event-almanac-almanac-ruleresult-ruleresult)
@@ -156,24 +156,25 @@ engine.removeOperator('startsWithLetter');
 
 
 
-### engine.run([Object facts], [Object options]) -> Promise ({ events: Events, almanac: Almanac})
+### engine.run([Object facts], [Object options]) -> Promise ({ events: Events, almanac: Almanac, successResults: [], failureResults: []})
 
 Runs the rules engine.  Returns a promise which resolves when all rules have been run.
 
 ```js
 // run the engine
-engine.run()
+await engine.run()
 
 // with constant facts
-engine.run({ userId: 1 })
-
-// returns rule events that were triggered
-engine
-  .run({ userId: 1 })
-  .then(function(results) {
-    console.log(results.events)
-    // almanac available via results.almanac to interact with as defined in Almanac docs
-  })
+await engine.run({ userId: 1 })
+
+// results
+const runResult = await engine.run({ userId: 1 })
+
+/**
+ * runResult.almanac: Almanac instance for the run
+ * runResult.successEvents: rule results for successful rules
+ * runResult.failureEvents: rule results for failed rules
+ */
 ```
 Link to the [Almanac documentation](./almanac.md)
 

docs/walkthrough.md

@@ -163,7 +163,7 @@ engine.run({ userId: 1 });  // any time a rule condition requires 'userId', '1'
 
 // run() returns a promise
 engine.run({ userId: 4 }).then((results) => {
-  console.log('all rules executed; the following events were triggered: ', results.events)
+  console.log('all rules executed; the following events were triggered: ', results.successResults.map(result => JSON.stringify(result.event)))
 });
 ```
 Helper methods (for this example)