Support Facts In Events

Support event parameters to include facts
this allows the events to reference values that are being stored
in a persistent storage mechanism or otherwise unknown when the rules
are written.

Author: Christopher Pardy

docs/engine.md

@@ -50,6 +50,8 @@ condition reference that cannot be resolved an exception is thrown. Turning
 this option on will cause the engine to treat unresolvable condition references
 as failed conditions. (default: false)
 
+`allowFactsInEventParams` - By default when rules succeed or fail the events emitted are clones of the event in the rule declaration. When setting this option to true the parameters on the events will be have any fact references resolved. (default: false)
+
 `pathResolver` - Allows a custom object path resolution library to be used. (default: `json-path` syntax). See [custom path resolver](./rules.md#condition-helpers-custom-path-resolver) docs.
 
 ### engine.addFact(String id, Function [definitionFunc], Object [options])

docs/rules.md

@@ -349,6 +349,12 @@ engine.on('failure', function(event, almanac, ruleResult) {
 })
 ```
 
+### Referencing Facts In Events
+
+With the engine option [`allowFactsInEventParams`](./engine.md#options) the parameters of the event may include references to facts in the same form as [Comparing Facts](#comparing-facts).
+
+See [11-using-facts-in-events.js](../examples/11-using-facts-in-events.js) for an example.
+
 ## Operators
 
 Each rule condition must begin with a boolean operator(```all```, ```any```, or ```not```) at its root.

examples/11-using-facts-in-events.js

@@ -0,0 +1,143 @@
+"use strict";
+/*
+ * This is an advanced example demonstrating rules that re-use a condition defined
+ * in the engine.
+ *
+ * Usage:
+ *   node ./examples/10-condition-sharing.js
+ *
+ * For detailed output:
+ *   DEBUG=json-rules-engine node ./examples/10-condition-sharing.js
+ */
+
+require("colors");
+const { Engine, Fact } = require("json-rules-engine");
+
+async function start() {
+  /**
+   * Setup a new engine
+   */
+  const engine = new Engine([], { allowFactsInEventParams: true });
+
+  // in-memory "database"
+  let currentHighScore = null;
+  const currentHighScoreFact = new Fact('currentHighScore', () => currentHighScore)
+
+  /**
+   * Rule for when you've gotten the high score
+   * - Event will include the previous high score
+   */
+  const highScoreRule = {
+    conditions: {
+      any: [
+        {
+          fact: "currentHighScore",
+          operator: "equal",
+          value: null
+        },
+        {
+          fact: "score",
+          operator: "greaterThan",
+          value: {
+            fact: "currentHighScore",
+            path: "$.score",
+          },
+        }
+      ],
+    },
+    event: {
+      type: "highscore",
+      params: {
+        initials: { fact: 'initials' },
+        score: { fact: "score" }
+      },
+    },
+  };
+  const gameOverRule = {
+    conditions: {
+      all: [
+        {
+          fact: "score",
+          operator: "lessThanInclusive",
+          value: {
+            fact: "currentHighScore",
+            path: "$.score"
+          }
+        }
+      ]
+    },
+    event: {
+      type: "gameover",
+      params: {
+        initials: {
+          fact: "currentHighScore",
+          path: "$.initials"
+        },
+        score: {
+          fact: "currentHighScore",
+          path: "$.score"
+        }
+      }
+    }
+  }
+  engine.addRule(highScoreRule);
+  engine.addRule(gameOverRule);
+  engine.addFact(currentHighScoreFact);
+
+  /**
+   * Register listeners with the engine for rule success and failure
+   */
+  engine
+    .on("success", async ({ params: { initials, score }}) => {
+      console.log(`HIGH SCORE\n${initials} - ${score}`);
+    })
+    .on("success", ({ type, params }) => {
+      if(type === 'highscore') {
+        currentHighScore = params;
+      }
+    });
+
+  let facts = {
+    initials: 'DOG',
+    score: 968
+  }
+
+  // first run, without a high score
+  await engine.run(facts);
+
+  console.log('\n');
+
+  // new player
+  facts = {
+    initials: 'AAA',
+    score: 500
+  };
+
+  // new player hasn't gotten the high score yet
+  await engine.run(facts);
+
+  console.log('\n');
+
+  facts = {
+    initials: 'AAA',
+    score: 1000
+  };
+
+  // second run, with a high score
+  await engine.run(facts);
+}
+
+start();
+
+/*
+ * OUTPUT:
+ * 
+ * NEW SCORE:
+ * DOG - 968
+ *
+ * HIGH SCORE:
+ * DOG - 968
+ * 
+ * HIGH SCORE:
+ * AAA - 1000
+ */

src/almanac.js

@@ -162,4 +162,14 @@ export default class Almanac {
 
     return factValuePromise
   }
+
+  /**
+   * Interprets .value as either a primitive, or if a fact, retrieves the fact value
+   */
+  getValue (value) {
+    if (isObjectLike(value) && Object.prototype.hasOwnProperty.call(value, 'fact')) { // value: { fact: 'xyz' }
+      return this.factValue(value.fact, value.params, value.path)
+    }
+    return Promise.resolve(value)
+  }
 }

src/condition.js

@@ -11,8 +11,8 @@ export default class Condition {
     if (booleanOperator) {
       const subConditions = properties[booleanOperator]
       const subConditionsIsArray = Array.isArray(subConditions)
-      if (booleanOperator !== 'not' && !subConditionsIsArray) throw new Error(`"${booleanOperator}" must be an array`)
-      if (booleanOperator === 'not' && subConditionsIsArray) throw new Error(`"${booleanOperator}" cannot be an array`)
+      if (booleanOperator !== 'not' && !subConditionsIsArray) { throw new Error(`"${booleanOperator}" must be an array`) }
+      if (booleanOperator === 'not' && subConditionsIsArray) { throw new Error(`"${booleanOperator}" cannot be an array`) }
       this.operator = booleanOperator
       // boolean conditions always have a priority; default 1
       this.priority = parseInt(properties.priority, 10) || 1
@@ -22,9 +22,9 @@ export default class Condition {
         this[booleanOperator] = new Condition(subConditions)
       }
     } else if (!Object.prototype.hasOwnProperty.call(properties, 'condition')) {
-      if (!Object.prototype.hasOwnProperty.call(properties, 'fact')) throw new Error('Condition: constructor "fact" property required')
-      if (!Object.prototype.hasOwnProperty.call(properties, 'operator')) throw new Error('Condition: constructor "operator" property required')
-      if (!Object.prototype.hasOwnProperty.call(properties, 'value')) throw new Error('Condition: constructor "value" property required')
+      if (!Object.prototype.hasOwnProperty.call(properties, 'fact')) { throw new Error('Condition: constructor "fact" property required') }
+      if (!Object.prototype.hasOwnProperty.call(properties, 'operator')) { throw new Error('Condition: constructor "operator" property required') }
+      if (!Object.prototype.hasOwnProperty.call(properties, 'value')) { throw new Error('Condition: constructor "value" property required') }
 
       // a non-boolean condition does not have a priority by default. this allows
       // priority to be dictated by the fact definition
@@ -84,7 +84,11 @@ export default class Condition {
    */
   _getValue (almanac) {
     const value = this.value
-    if (isObjectLike(value) && Object.prototype.hasOwnProperty.call(value, 'fact')) { // value: { fact: 'xyz' }
+    if (
+      isObjectLike(value) &&
+      Object.prototype.hasOwnProperty.call(value, 'fact')
+    ) {
+      // value: { fact: 'xyz' }
       return almanac.factValue(value.fact, value.params, value.path)
     }
     return Promise.resolve(value)
@@ -102,20 +106,28 @@ export default class Condition {
   evaluate (almanac, operatorMap) {
     if (!almanac) return Promise.reject(new Error('almanac required'))
     if (!operatorMap) return Promise.reject(new Error('operatorMap required'))
-    if (this.isBooleanOperator()) return Promise.reject(new Error('Cannot evaluate() a boolean condition'))
+    if (this.isBooleanOperator()) { return Promise.reject(new Error('Cannot evaluate() a boolean condition')) }
 
     const op = operatorMap.get(this.operator)
-    if (!op) return Promise.reject(new Error(`Unknown operator: ${this.operator}`))
+    if (!op) { return Promise.reject(new Error(`Unknown operator: ${this.operator}`)) }
 
-    return this._getValue(almanac) // todo - parallelize
-      .then(rightHandSideValue => {
-        return almanac.factValue(this.fact, this.params, this.path)
-          .then(leftHandSideValue => {
-            const result = op.evaluate(leftHandSideValue, rightHandSideValue)
-            debug(`condition::evaluate <${JSON.stringify(leftHandSideValue)} ${this.operator} ${JSON.stringify(rightHandSideValue)}?> (${result})`)
-            return { result, leftHandSideValue, rightHandSideValue, operator: this.operator }
-          })
-      })
+    return Promise.all([
+      almanac.getValue(this.value),
+      almanac.factValue(this.fact, this.params, this.path)
+    ]).then(([rightHandSideValue, leftHandSideValue]) => {
+      const result = op.evaluate(leftHandSideValue, rightHandSideValue)
+      debug(
+        `condition::evaluate <${JSON.stringify(leftHandSideValue)} ${
+          this.operator
+        } ${JSON.stringify(rightHandSideValue)}?> (${result})`
+      )
+      return {
+        result,
+        leftHandSideValue,
+        rightHandSideValue,
+        operator: this.operator
+      }
+    })
   }
 
   /**

src/engine.js

@@ -23,6 +23,7 @@ class Engine extends EventEmitter {
     this.rules = []
     this.allowUndefinedFacts = options.allowUndefinedFacts || false
     this.allowUndefinedConditions = options.allowUndefinedConditions || false
+    this.allowFactsInEventParams = options.allowFactsInEventParams || false
     this.pathResolver = options.pathResolver
     this.operators = new Map()
     this.facts = new Map()

src/rule-result.js

@@ -1,6 +1,7 @@
 'use strict'
 
 import deepClone from 'clone'
+import { isObject } from 'lodash'
 
 export default class RuleResult {
   constructor (conditions, event, priority, name) {
@@ -15,6 +16,23 @@ export default class RuleResult {
     this.result = result
   }
 
+  resolveEventParams (almanac) {
+    if (isObject(this.event.params)) {
+      const updates = []
+      for (const key in this.event.params) {
+        if (Object.prototype.hasOwnProperty.call(this.event.params, key)) {
+          updates.push(
+            almanac
+              .getValue(this.event.params[key])
+              .then((val) => (this.event.params[key] = val))
+          )
+        }
+      }
+      return Promise.all(updates)
+    }
+    return Promise.resolve()
+  }
+
   toJSON (stringify = true) {
     const props = {
       conditions: this.conditions.toJSON(false),

src/rule.js

@@ -367,8 +367,12 @@ class Rule extends EventEmitter {
      */
     const processResult = (result) => {
       ruleResult.setResult(result)
+      let processEvent = Promise.resolve()
+      if (this.engine.allowFactsInEventParams) {
+        processEvent = ruleResult.resolveEventParams(almanac)
+      }
       const event = result ? 'success' : 'failure'
-      return this.emitAsync(event, ruleResult.event, almanac, ruleResult).then(
+      return processEvent.then(() => this.emitAsync(event, ruleResult.event, almanac, ruleResult)).then(
         () => ruleResult
       )
     }