Document almanac events and results methods

Author: Cache Hamm

docs/almanac.md

@@ -4,6 +4,8 @@
 * [Methods](#methods)
     * [almanac.factValue(Fact fact, Object params, String path) -> Promise](#almanacfactvaluefact-fact-object-params-string-path---promise)
     * [almanac.addRuntimeFact(String factId, Mixed value)](#almanacaddruntimefactstring-factid-mixed-value)
+    * [almanac.getEvents(String outcome) -> Events[]](#almanacgeteventsstring-outcome---events)
+    * [almanac.getResults() -> RuleResults[]](#almanacgetresults---ruleresults)
 * [Common Use Cases](#common-use-cases)
     * [Fact dependencies](#fact-dependencies)
     * [Retrieve fact values when handling events](#retrieve-fact-values-when-handling-events)
@@ -39,6 +41,26 @@ Sets a constant fact mid-run.  Often used in conjunction with rule and engine ev
 almanac.addRuntimeFact('account-id', 1)
 ```
 
+### almanac.getEvents(String outcome) -> Events[]
+
+Returns events by outcome ("success" or "failure") for the current engine run()
+
+```js
+almanac.getEvents() // all events for every rule evaluated thus far
+
+almanac.getEvents('success') // array of success events
+
+almanac.getEvents('failure') // array of failure events
+```
+
+### almanac.getResults() -> RuleResults[]
+
+Returns [rule results](./rules#rule-results) for the current engine run()
+
+```js
+almanac.getResults()
+```
+
 ## Common Use Cases
 
 ### Fact dependencies

docs/engine.md

@@ -3,18 +3,18 @@
 The Engine stores and executes rules, emits events, and maintains state.
 
 * [Methods](#methods)
-  * [constructor([Array rules], Object [options])](#constructorarray-rules-object-options)
-    * [Options](#options)
-  * [engine.addFact(String id, Function [definitionFunc], Object [options])](#engineaddfactstring-id-function-definitionfunc-object-options)
-  * [engine.removeFact(String id)](#engineremovefactstring-id)
-  * [engine.addRule(Rule instance|Object options)](#engineaddrulerule-instanceobject-options)
-  * [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, results: [], 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)
+    * [constructor([Array rules], Object [options])](#constructorarray-rules-object-options)
+      * [Options](#options)
+    * [engine.addFact(String id, Function [definitionFunc], Object [options])](#engineaddfactstring-id-function-definitionfunc-object-options)
+    * [engine.removeFact(String id)](#engineremovefactstring-id)
+    * [engine.addRule(Rule instance|Object options)](#engineaddrulerule-instanceobject-options)
+    * [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: [], failureEvents: [], almanac: Almanac, results: [], failureResults: []})](#enginerunobject-facts-object-options---promise--events--failureevents--almanac-almanac-results--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)
 
 ## Methods
 
@@ -153,7 +153,7 @@ engine.removeOperator('startsWithLetter');
 
 
 
-### engine.run([Object facts], [Object options]) -> Promise ({ events: Events, almanac: Almanac, results: [], failureResults: []})
+### engine.run([Object facts], [Object options]) -> Promise ({ events: [], failureEvents: [], almanac: Almanac, results: [], failureResults: []})
 
 Runs the rules engine.  Returns a promise which resolves when all rules have been run.
 
@@ -165,13 +165,20 @@ await engine.run()
 await engine.run({ userId: 1 })
 
 // results
-const { results, failureResults, events } = await engine.run({ userId: 1 })
+const {
+  results,
+  failureResults,
+  events,
+  failureEvents,
+  almanac
+} = await engine.run({ userId: 1 })
 
 /**
  * almanac: Almanac instance for the run
  * results: rule results for successful rules
  * failureResults: rule results for failed rules
- * events: successful events
+ * events: successful rule events
+ * failureEvents: failed rule events
  */
 ```
 Link to the [Almanac documentation](./almanac.md)

docs/rules.md

@@ -4,28 +4,28 @@
 Rules contain a set of _conditions_ and a single _event_.  When the engine is run, each rule condition is evaluated.  If the results are truthy, the rule's _event_ is triggered.
 
 * [Methods](#methods)
-  * [constructor([Object options|String json])](#constructorobject-optionsstring-json)
-  * [setConditions(Array conditions)](#setconditionsarray-conditions)
-  * [getConditions() -> Object](#getconditions---object)
-  * [setEvent(Object event)](#seteventobject-event)
-  * [getEvent() -> Object](#getevent---object)
-  * [setPriority(Integer priority = 1)](#setpriorityinteger-priority--1)
-  * [getPriority() -> Integer](#getpriority---integer)
-  * [toJSON(Boolean stringify = true)](#tojsonboolean-stringify--true)
+    * [constructor([Object options|String json])](#constructorobject-optionsstring-json)
+    * [setConditions(Array conditions)](#setconditionsarray-conditions)
+    * [getConditions() -> Object](#getconditions---object)
+    * [setEvent(Object event)](#seteventobject-event)
+    * [getEvent() -> Object](#getevent---object)
+    * [setPriority(Integer priority = 1)](#setpriorityinteger-priority--1)
+    * [getPriority() -> Integer](#getpriority---integer)
+    * [toJSON(Boolean stringify = true)](#tojsonboolean-stringify--true)
 * [Conditions](#conditions)
-  * [Basic conditions](#basic-conditions)
-  * [Boolean expressions: all and any](#boolean-expressions-all-and-any)
-  * [Condition helpers: params](#condition-helpers-params)
-  * [Condition helpers: path](#condition-helpers-path)
-  * [Condition helpers: custom path resolver](#condition-helpers-custom-path-resolver)
-  * [Comparing facts](#comparing-facts)
+    * [Basic conditions](#basic-conditions)
+    * [Boolean expressions: all and any](#boolean-expressions-all-and-any)
+    * [Condition helpers: params](#condition-helpers-params)
+    * [Condition helpers: path](#condition-helpers-path)
+    * [Condition helpers: custom path resolver](#condition-helpers-custom-path-resolver)
+    * [Comparing facts](#comparing-facts)
 * [Events](#events)
-    * [rule.on('success', Function(Object event, Almanac almanac, RuleResult ruleResult))](#ruleonsuccess-functionobject-event-almanac-almanac-ruleresult-ruleresult)
-    * [rule.on('failure', Function(Object event, Almanac almanac, RuleResult ruleResult))](#ruleonfailure-functionobject-event-almanac-almanac-ruleresult-ruleresult)
+      * [rule.on('success', Function(Object event, Almanac almanac, RuleResult ruleResult))](#ruleonsuccess-functionobject-event-almanac-almanac-ruleresult-ruleresult)
+      * [rule.on('failure', Function(Object event, Almanac almanac, RuleResult ruleResult))](#ruleonfailure-functionobject-event-almanac-almanac-ruleresult-ruleresult)
 * [Operators](#operators)
-  * [String and Numeric operators:](#string-and-numeric-operators)
-  * [Numeric operators:](#numeric-operators)
-  * [Array operators:](#array-operators)
+    * [String and Numeric operators:](#string-and-numeric-operators)
+    * [Numeric operators:](#numeric-operators)
+    * [Array operators:](#array-operators)
 * [Rule Results](#rule-results)
 
 ## Methods

src/almanac.js

@@ -59,14 +59,14 @@ export default class Almanac {
    * Adds a rule result
    * @param {Object} event
    */
-  addRuleResult (ruleResult) {
+  addResult (ruleResult) {
     this.ruleResults.push(ruleResult)
   }
 
   /**
    * retrieve successful events
    */
-  getRuleResults () {
+  getResults () {
     return this.ruleResults
   }
 

src/engine.js

@@ -191,7 +191,7 @@ class Engine extends EventEmitter {
       }
       return rule.evaluate(almanac).then((ruleResult) => {
         debug(`engine::run ruleResult:${ruleResult.result}`)
-        almanac.addRuleResult(ruleResult)
+        almanac.addResult(ruleResult)
         if (ruleResult.result) {
           almanac.addEvent(ruleResult.event, 'success')
           return this.emitAsync('success', ruleResult.event, almanac, ruleResult)
@@ -232,7 +232,7 @@ class Engine extends EventEmitter {
       cursor.then(() => {
         this.status = FINISHED
         debug('engine::run completed')
-        const ruleResults = almanac.getRuleResults()
+        const ruleResults = almanac.getResults()
         const { results, failureResults } = ruleResults.reduce((hash, ruleResult) => {
           const group = ruleResult.result ? 'results' : 'failureResults'
           hash[group].push(ruleResult)