Merge pull request #242 from CacheControl/engine-run-results

Author: CacheControl

CHANGELOG.md

@@ -10,9 +10,13 @@
       (fixes #205)
     * Engine and Rule events `on('success')`, `on('failure')`, and Rule callbacks `onSuccess` and `onFailure` now honor returned promises; any event handler that returns a promise will be waited upon to resolve before engine execution continues. (fixes #235)
     * Private `rule.event` property renamed. Use `rule.getEvent()` to avoid breaking changes in the future.
-    * The 'success-events' fact used to store successful events has been converted to an internal data structure and will no longer appear in the almanac's facts. (fixes #187)
+    * The `success-events` fact used to store successful events has been converted to an internal data structure and will no longer appear in the almanac's facts. (fixes #187)
   * NEW FEATURES
     * Engine constructor now accepts a `pathResolver` option for resolving condition `path` properties. Read more [here](./docs/rules.md#condition-helpers-custom-path-resolver). (fixes #210)
+    * Engine.run() now returns three additional data structures:
+      * `failureEvents`, an array of all failed rules events. (fixes #192)
+      * `results`, an array of RuleResults for each successful rule (fixes #216)
+      * `failureResults`, an array of RuleResults for each failed rule
 
 
 #### 5.3.0 / 2020-12-02

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(({ events }) => {
+    events.map(event => console.log(event.params.message))
   })
 
 /*
@@ -171,10 +170,9 @@ 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(({ events }) => {
+    console.log(facts.accountId + ' is a ' + events.map(event => event.params.message))
   })
-  .catch(err => console.log(err.stack))
 
 /*
  * OUTPUT:

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
@@ -110,13 +132,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

@@ -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})](#enginerunobject-facts-object-options---promise--events-events-almanac-almanac)
-  * [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
 
@@ -104,9 +104,6 @@ engine.addRule(rule)
 engine.removeRule(rule)
 ```
 
-
-
-
 ### engine.addOperator(String operatorName, Function evaluateFunc(factValue, jsonValue))
 
 Adds a custom operator to the engine.  For situations that require going beyond the generic, built-in operators (`equal`, `greaterThan`, etc).
@@ -156,24 +153,24 @@ engine.removeOperator('startsWithLetter');
 
 
 
-### engine.run([Object facts], [Object options]) -> Promise ({ events: Events, almanac: Almanac})
+### 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.
 
 ```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 })
+
+const {
+  results,         // rule results for successful rules
+  failureResults,  // rule results for failed rules
+  events,          // array of successful rule events
+  failureEvents,   // array of failed rule events
+  almanac          // Almanac instance representing the run
+} = await engine.run({ userId: 1 })
 ```
 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

docs/walkthrough.md

@@ -138,7 +138,7 @@ engine.on('young-adult-rocky-mnts', (params) => {
 // - OR -
 
 // subscribe to any event emitted by the engine
-engine.on('success', function (event, engine) {
+engine.on('success', function (event, almanac, ruleResult) {
     console.log('Success event:\n', event);
   // event: {
   //   type: "young-adult-rocky-mnts",
@@ -162,8 +162,8 @@ Running an engine executes the rules, and fires off event events for conditions
 engine.run({ userId: 1 });  // any time a rule condition requires 'userId', '1' will be returned
 
 // run() returns a promise
-engine.run({ userId: 4 }).then((results) => {
-  console.log('all rules executed; the following events were triggered: ', results.events)
+engine.run({ userId: 4 }).then(({ events }) => {
+  console.log('all rules executed; the following events were triggered: ', events.map(result => JSON.stringify(event)))
 });
 ```
 Helper methods (for this example)

examples/01-hello-world.js

@@ -10,52 +10,49 @@
  */
 
 require('colors')
-const { Engine, Rule } = require('json-rules-engine')
+const { Engine } = require('json-rules-engine')
 
-/**
- * Setup a new engine
- */
-const engine = new Engine()
+async function start () {
+  /**
+   * Setup a new engine
+   */
+  const engine = new Engine()
 
-/**
- * Create a rule
- */
-const rule = new Rule({
-  // define the 'conditions' for when "hello world" should display
-  conditions: {
-    all: [{
-      fact: 'displayMessage',
-      operator: 'equal',
-      value: true
-    }]
-  },
-  // define the 'event' that will fire when the condition evaluates truthy
-  event: {
-    type: 'message',
-    params: {
-      data: 'hello-world!'
+  /**
+   * Create a rule
+   */
+  engine.addRule({
+    // define the 'conditions' for when "hello world" should display
+    conditions: {
+      all: [{
+        fact: 'displayMessage',
+        operator: 'equal',
+        value: true
+      }]
+    },
+    // define the 'event' that will fire when the condition evaluates truthy
+    event: {
+      type: 'message',
+      params: {
+        data: 'hello-world!'
+      }
     }
-  }
-})
+  })
 
-// add rule to engine
-engine.addRule(rule)
+  /**
+   * Define a 'displayMessage' as a constant value
+   * Fact values do NOT need to be known at engine runtime; see the
+   * 03-dynamic-facts.js example for how to pull in data asynchronously during runtime
+   */
+  const facts = { displayMessage: true }
 
-/**
- * Define a 'displayMessage' as a constant value
- * Fact values do NOT need to be known at engine runtime; see the
- * 03-dynamic-facts.js example for how to pull in data asynchronously during runtime
- */
-const facts = { displayMessage: true }
+  // engine.run() evaluates the rule using the facts provided
+  const { events } = await engine.run(facts)
 
-// run the engine
-engine
-  .run(facts)
-  .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)
+  events.map(event => console.log(event.params.data.green))
+}
 
+start()
 /*
  * OUTPUT:
  *