Add Shared Condition Support

Add Support for Shared Conditions which are added to the engine and
then referenced in various rules.

Author: Christopher Pardy

src/condition.js

@@ -21,7 +21,7 @@ export default class Condition {
       } else {
         this[booleanOperator] = new Condition(subConditions)
       }
-    } else {
+    } else if (!Object.prototype.hasOwnProperty.call(properties, 'uses')) {
       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')
@@ -54,6 +54,8 @@ export default class Condition {
       } else {
         props[oper] = this[oper].toJSON(false)
       }
+    } else if (this.isSharedCondition()) {
+      props.uses = this.uses
     } else {
       props.operator = this.operator
       props.value = this.value
@@ -147,4 +149,12 @@ export default class Condition {
   isBooleanOperator () {
     return Condition.booleanOperator(this) !== undefined
   }
+
+  /**
+   * Whether the condition represents a reference to a shared condition
+   * @returns {Boolean}
+   */
+  isSharedCondition () {
+    return Object.prototype.hasOwnProperty.call(this, 'uses')
+  }
 }

src/engine.js

@@ -7,6 +7,7 @@ import Almanac from './almanac'
 import EventEmitter from 'eventemitter2'
 import defaultOperators from './engine-default-operators'
 import debug from './debug'
+import Condition from './condition'
 
 export const READY = 'READY'
 export const RUNNING = 'RUNNING'
@@ -24,6 +25,7 @@ class Engine extends EventEmitter {
     this.pathResolver = options.pathResolver
     this.operators = new Map()
     this.facts = new Map()
+    this.sharedConditions = new Map()
     this.status = READY
     rules.map(r => this.addRule(r))
     defaultOperators.map(o => this.addOperator(o))
@@ -92,6 +94,27 @@ class Engine extends EventEmitter {
     return ruleRemoved
   }
 
+  /**
+   * Adds or updates a shared condition
+   * @param {string} name - the name of the shared condition to be referenced by rules.
+   * @param {object} conditions - the conditions to use when the shared condition is referenced.
+   */
+  addSharedCondition (name, conditions) {
+    if (!name) throw new Error('Engine: addSharedCondition() requires name')
+    if (!conditions) throw new Error('Engine: addSharedCondition() requires conditions')
+    this.sharedConditions.set(name, new Condition(conditions))
+    return this
+  }
+
+  /**
+   * Removes a shared condition that has previously been added to this engine
+   * @param {string} name - the name of the shared condition to remove.
+   * @returns true if the shared condition existed, otherwise false
+   */
+  removeSharedCondition (name) {
+    return this.sharedConditions.delete(name)
+  }
+
   /**
    * Add a custom operator definition
    * @param {string}   operatorOrName - operator identifier within the condition; i.e. instead of 'equals', 'greaterThan', etc

src/rule.js

@@ -3,6 +3,7 @@
 import Condition from './condition'
 import RuleResult from './rule-result'
 import debug from './debug'
+import deepClone from 'clone'
 import EventEmitter from 'eventemitter2'
 
 class Rule extends EventEmitter {
@@ -70,8 +71,8 @@ class Rule extends EventEmitter {
    * @param {object} conditions - conditions, root element must be a boolean operator
    */
   setConditions (conditions) {
-    if (!Object.prototype.hasOwnProperty.call(conditions, 'all') && !Object.prototype.hasOwnProperty.call(conditions, 'any') && !Object.prototype.hasOwnProperty.call(conditions, 'not')) {
-      throw new Error('"conditions" root must contain a single instance of "all", "any", or "not"')
+    if (!Object.prototype.hasOwnProperty.call(conditions, 'all') && !Object.prototype.hasOwnProperty.call(conditions, 'any') && !Object.prototype.hasOwnProperty.call(conditions, 'not') && !Object.prototype.hasOwnProperty.call(conditions, 'uses')) {
+      throw new Error('"conditions" root must contain a single instance of "all", "any", "not", or "uses"')
     }
     this.conditions = new Condition(conditions)
     return this
@@ -188,6 +189,10 @@ class Rule extends EventEmitter {
      * @return {Promise(true|false)} - resolves with the result of the condition evaluation
      */
     const evaluateCondition = (condition) => {
+      if (condition.isSharedCondition()) {
+        realize(this.engine.sharedConditions.get(condition.uses), condition)
+      }
+
       if (condition.isBooleanOperator()) {
         const subConditions = condition[condition.operator]
         let comparisonPromise
@@ -309,6 +314,12 @@ class Rule extends EventEmitter {
       return prioritizeAndRun([condition], 'not').then(result => !result)
     }
 
+    const realize = (sharedCondition, targetCondition) => {
+      if (!sharedCondition) throw new Error(`No shared condition ${targetCondition.uses} exists`)
+      delete targetCondition.uses
+      Object.assign(targetCondition, deepClone(sharedCondition))
+    }
+
     /**
      * Emits based on rule evaluation result, and decorates ruleResult with 'result' property
      * @param {RuleResult} ruleResult

test/engine-shared-conditions.test.js

@@ -0,0 +1,106 @@
+'use strict'
+
+import sinon from 'sinon'
+import engineFactory from '../src/index'
+
+describe('Engine: shared conditions', () => {
+  let engine
+  let sandbox
+  before(() => {
+    sandbox = sinon.createSandbox()
+  })
+  afterEach(() => {
+    sandbox.restore()
+  })
+
+  describe('supports shared conditions across multiple rules', () => {
+    const name = 'over60'
+    const sharedCondition = {
+      all: [{
+        fact: 'age',
+        operator: 'greaterThanInclusive',
+        value: 60
+      }]
+    }
+
+    const sendEvent = {
+      type: 'checkSending',
+      params: {
+        sendRetirementPayment: true
+      }
+    }
+
+    const sendConditions = {
+      all: [
+        { uses: name },
+        {
+          fact: 'isRetired',
+          operator: 'equal',
+          value: true
+        }
+      ]
+    }
+
+    const outreachEvent = {
+      type: 'triggerOutreach'
+    }
+
+    const outreachConditions = {
+      all: [
+        { uses: name },
+        {
+          fact: 'requestedOutreach',
+          operator: 'equal',
+          value: true
+        }
+      ]
+    }
+
+    let eventSpy
+    let ageSpy
+    let isRetiredSpy
+    let requestedOutreachSpy
+    beforeEach(() => {
+      eventSpy = sandbox.spy()
+      ageSpy = sandbox.stub()
+      isRetiredSpy = sandbox.stub()
+      requestedOutreachSpy = sandbox.stub()
+      engine = engineFactory()
+
+      const sendRule = factories.rule({ conditions: sendConditions, event: sendEvent })
+      engine.addRule(sendRule)
+
+      const outreachRule = factories.rule({ conditions: outreachConditions, event: outreachEvent })
+      engine.addRule(outreachRule)
+
+      engine.addSharedCondition(name, sharedCondition)
+
+      engine.addFact('age', ageSpy)
+      engine.addFact('isRetired', isRetiredSpy)
+      engine.addFact('requestedOutreach', requestedOutreachSpy)
+      engine.on('success', eventSpy)
+    })
+
+    it('emits all events when all conditions are met', async () => {
+      ageSpy.returns(65)
+      isRetiredSpy.returns(true)
+      requestedOutreachSpy.returns(true)
+      await engine.run()
+      expect(eventSpy).to.have.been.calledWith(sendEvent).and.to.have.been.calledWith(outreachEvent)
+    })
+
+    it('expands shared conditions in rule results', async () => {
+      ageSpy.returns(65)
+      isRetiredSpy.returns(true)
+      requestedOutreachSpy.returns(true)
+      const { results } = await engine.run()
+      const nestedSharedCondition = {
+        'conditions.all[0].all[0].fact': 'age',
+        'conditions.all[0].all[0].operator': 'greaterThanInclusive',
+        'conditions.all[0].all[0].value': 60
+      }
+      expect(results[0]).to.nested.include(nestedSharedCondition)
+      expect(results[1]).to.nested.include(nestedSharedCondition)
+    })
+  })
+})

test/rule.test.js

@@ -109,7 +109,7 @@ describe('Rule', () => {
   describe('setConditions()', () => {
     describe('validations', () => {
       it('throws an exception for invalid root conditions', () => {
-        expect(rule.setConditions.bind(rule, { foo: true })).to.throw(/"conditions" root must contain a single instance of "all", "any", or "not"/)
+        expect(rule.setConditions.bind(rule, { foo: true })).to.throw(/"conditions" root must contain a single instance of "all", "any", "not", or "uses"/)
       })
     })
   })

types/index.d.ts

@@ -23,6 +23,9 @@ export class Engine {
   removeRule(ruleOrName: Rule | string): boolean;
   updateRule(rule: Rule): void;
 
+  addSharedCondition(name: string, conditions: TopLevelCondition): this;
+  removeSharedCondition(name: string): boolean;
+
   addOperator(operator: Operator): Map<string, Operator>;
   addOperator<A, B>(
     operatorName: string,
@@ -98,10 +101,7 @@ export interface Event {
   params?: Record<string, any>;
 }
 
-export type PathResolver = (
-  value: object,
-  path: string,
-) => any;
+export type PathResolver = (value: object, path: string) => any;
 
 export type EventHandler = (
   event: Event,
@@ -156,7 +156,24 @@ interface ConditionProperties {
 }
 
 type NestedCondition = ConditionProperties | TopLevelCondition;
-type AllConditions = { all: NestedCondition[]; name?: string; priority?: number; };
-type AnyConditions = { any: NestedCondition[]; name?: string; priority?: number; };
-type NotConditions = { not: NestedCondition; name?: string; priority?: number; };
-export type TopLevelCondition = AllConditions | AnyConditions | NotConditions;
+type AllConditions = {
+  all: NestedCondition[];
+  name?: string;
+  priority?: number;
+};
+type AnyConditions = {
+  any: NestedCondition[];
+  name?: string;
+  priority?: number;
+};
+type NotConditions = { not: NestedCondition; name?: string; priority?: number };
+type SharedConditionReference = {
+  uses: string;
+  priority?: number;
+  name?: string;
+};
+export type TopLevelCondition =
+  | AllConditions
+  | AnyConditions
+  | NotConditions
+  | SharedConditionReference;