Merge pull request CacheControl#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:
  *