Add Support for Operator Decorators

Operator Decorators "decorate" an operator and return a new operator.
Create some defaults including:
- someFact -> for fact values that are arrays return if one of the values matches the decorated operator
- someValue -> same but for json values that are arrays
- everyFact
- everyValue
- not

Author: chris-pardy-newfire

examples/12-using-operator-decorators.js

@@ -0,0 +1,69 @@
+'use strict'
+/*
+ * This example demonstrates using operator decorators.
+ *
+ * In this example, a fact contains a list of strings and we want to check if any of these are valid.
+ *
+ * Usage:
+ *   node ./examples/12-using-operator-decorators.js
+ *
+ * For detailed output:
+ *   DEBUG=json-rules-engine node ./examples/12-using-operator-decorators.js
+ */
+
+require('colors')
+const { Engine } = require('json-rules-engine')
+
+async function start () {
+  /**
+   * Setup a new engine
+   */
+  const engine = new Engine()
+
+  /**
+   * Add a rule for validating a tag (fact)
+   * against a set of tags that are valid (also a fact)
+   */
+  const validTags = {
+    conditions: {
+      all: [{
+        fact: 'tags',
+        operator: 'everyFact:in',
+        value: { fact: 'validTags' }
+      }]
+    },
+    event: {
+      type: 'valid tags'
+    }
+  }
+
+  engine.addRule(validTags)
+
+  engine.addFact('validTags', ['dev', 'staging', 'load', 'prod'])
+
+  let facts
+
+  engine
+    .on('success', event => {
+      console.log(facts.tags.join(',') + ' WERE'.green + ' all ' + event.type)
+    })
+    .on('failure', event => {
+      console.log(facts.tags.join(',') + ' WERE NOT'.red + ' all ' + event.type)
+    })
+
+  // first run with valid tags
+  facts = { tags: ['dev', 'prod'] }
+  await engine.run(facts)
+
+  // second run with an invalid tag
+  facts = { tags: ['dev', 'deleted'] }
+  await engine.run(facts)
+}
+start()
+
+/*
+ * OUTPUT:
+ *
+ * dev, prod WERE all valid tags
+ * dev, deleted WERE NOT all valid tags
+ */

examples/package-lock.json

@@ -0,0 +1,13 @@
+'use strict'
+
+import OperatorDecorator from './operator-decorator'
+
+const OperatorDecorators = []
+
+OperatorDecorators.push(new OperatorDecorator('someFact', (factValue, jsonValue, next) => factValue.some(fv => next(fv, jsonValue)), Array.isArray))
+OperatorDecorators.push(new OperatorDecorator('someValue', (factValue, jsonValue, next) => jsonValue.some(jv => next(factValue, jv))))
+OperatorDecorators.push(new OperatorDecorator('everyFact', (factValue, jsonValue, next) => factValue.every(fv => next(fv, jsonValue)), Array.isArray))
+OperatorDecorators.push(new OperatorDecorator('everyValue', (factValue, jsonValue, next) => jsonValue.every(jv => next(factValue, jv))))
+OperatorDecorators.push(new OperatorDecorator('not', (factValue, jsonValue, next) => !next(factValue, jsonValue)))
+
+export default OperatorDecorators

src/engine-default-operator-decorators.js

@@ -2,12 +2,13 @@
 
 import Fact from './fact'
 import Rule from './rule'
-import Operator from './operator'
 import Almanac from './almanac'
 import EventEmitter from 'eventemitter2'
 import defaultOperators from './engine-default-operators'
+import defaultDecorators from './engine-default-operator-decorators'
 import debug from './debug'
 import Condition from './condition'
+import OperatorMap from './operator-map'
 
 export const READY = 'READY'
 export const RUNNING = 'RUNNING'
@@ -25,12 +26,13 @@ class Engine extends EventEmitter {
     this.allowUndefinedConditions = options.allowUndefinedConditions || false
     this.replaceFactsInEventParams = options.replaceFactsInEventParams || false
     this.pathResolver = options.pathResolver
-    this.operators = new Map()
+    this.operators = new OperatorMap()
     this.facts = new Map()
     this.conditions = new Map()
     this.status = READY
     rules.map(r => this.addRule(r))
     defaultOperators.map(o => this.addOperator(o))
+    defaultDecorators.map(d => this.addOperatorDecorator(d))
   }
 
   /**
@@ -127,30 +129,32 @@ class Engine extends EventEmitter {
    * @param {function(factValue, jsonValue)} callback - the method to execute when the operator is encountered.
    */
   addOperator (operatorOrName, cb) {
-    let operator
-    if (operatorOrName instanceof Operator) {
-      operator = operatorOrName
-    } else {
-      operator = new Operator(operatorOrName, cb)
-    }
-    debug(`engine::addOperator name:${operator.name}`)
-    this.operators.set(operator.name, operator)
+    this.operators.addOperator(operatorOrName, cb)
   }
 
   /**
    * Remove a custom operator definition
    * @param {string}   operatorOrName - operator identifier within the condition; i.e. instead of 'equals', 'greaterThan', etc
-   * @param {function(factValue, jsonValue)} callback - the method to execute when the operator is encountered.
    */
   removeOperator (operatorOrName) {
-    let operatorName
-    if (operatorOrName instanceof Operator) {
-      operatorName = operatorOrName.name
-    } else {
-      operatorName = operatorOrName
-    }
+    return this.operators.removeOperator(operatorOrName)
+  }
+
+  /**
+   * Add a custom operator definition
+   * @param {string}   decoratorOrName - operator identifier within the condition; i.e. instead of 'equals', 'greaterThan', etc
+   * @param {function(factValue, jsonValue, next)} callback - the method to execute when the decorator is encountered.
+   */
+  addOperatorDecorator (decoratorOrName, cb) {
+    this.operators.addOperatorDecorator(decoratorOrName, cb)
+  }
 
-    return this.operators.delete(operatorName)
+  /**
+   * Remove a custom operator definition
+   * @param {string}   decoratorOrName - operator identifier within the condition; i.e. instead of 'equals', 'greaterThan', etc
+   */
+  removeOperatorDecorator (decoratorOrName) {
+    return this.operators.removeOperatorDecorator(decoratorOrName)
   }
 
   /**

src/engine.js

@@ -2,8 +2,9 @@ import Engine from './engine'
 import Fact from './fact'
 import Rule from './rule'
 import Operator from './operator'
+import OperatorDecorator from './operator-decorator'
 
-export { Fact, Rule, Operator, Engine }
+export { Fact, Rule, Operator, OperatorDecorator, Engine }
 export default function (rules, options) {
   return new Engine(rules, options)
 }

src/json-rules-engine.js

@@ -0,0 +1,37 @@
+'use strict'
+
+import Operator from './operator'
+
+export default class OperatorDecorator {
+  /**
+   * Constructor
+   * @param {string}   name - decorator identifier
+   * @param {function(factValue, jsonValue, next)} callback - callback that takes the next operator as a parameter
+   * @param {function}  [factValueValidator] - optional validator for asserting the data type of the fact
+   * @returns {OperatorDecorator} - instance
+   */
+  constructor (name, cb, factValueValidator) {
+    this.name = String(name)
+    if (!name) throw new Error('Missing decorator name')
+    if (typeof cb !== 'function') throw new Error('Missing decorator callback')
+    this.cb = cb
+    this.factValueValidator = factValueValidator
+    if (!this.factValueValidator) this.factValueValidator = () => true
+  }
+
+  /**
+   * Takes the fact result and compares it to the condition 'value', using the callback
+   * @param   {Operator} operator - fact result
+   * @returns {Operator} - whether the values pass the operator test
+   */
+  decorate (operator) {
+    const next = operator.evaluate.bind(operator)
+    return new Operator(
+        `${this.name}:${operator.name}`,
+        (factValue, jsonValue) => {
+          return this.cb(factValue, jsonValue, next)
+        },
+        this.factValueValidator
+    )
+  }
+}