Allow Named Conditions

Allow Conditions to include names that are emitted as part of events
and can be serialized to / from JSON
Names are useful to provide human readable tags on the different
conditions, especially complex ones made up of
nested boolean conditions.

Author: Christopher Pardy

examples/02-nested-boolean-logic.js

@@ -31,7 +31,8 @@ async function start () {
           fact: 'personalFoulCount',
           operator: 'greaterThanInclusive',
           value: 5
-        }]
+        }],
+        name: "short foul limit"
       }, {
         all: [{
           fact: 'gameDuration',
@@ -43,7 +44,8 @@ async function start () {
             operator: 'lessThan',
             value: 6
           }
-        }]
+        }],
+        name: "long foul limit"
       }]
     },
     event: { // define the event to fire when the conditions evaluate truthy

src/condition.js

@@ -44,6 +44,9 @@ export default class Condition {
     if (this.priority) {
       props.priority = this.priority
     }
+    if (this.name) {
+      props.name = this.name
+    }
     const oper = Condition.booleanOperator(this)
     if (oper) {
       if (Array.isArray(this[oper])) {

test/condition.test.js

@@ -12,6 +12,7 @@ function condition () {
   return {
     all: [{
       id: '6ed20017-375f-40c9-a1d2-6d7e0f4733c5',
+      name: "team participation in form",
       fact: 'team_participation',
       operator: 'equal',
       value: 50,
@@ -29,6 +30,7 @@ describe('Condition', () => {
       expect(subject).to.have.property('operator')
       expect(subject).to.have.property('value')
       expect(subject).to.have.property('path')
+      expect(subject).to.have.property('name');
     })
 
     it('boolean conditions have properties', () => {

test/engine-event.test.js

@@ -25,15 +25,19 @@ describe('Engine: event', () => {
    */
   function simpleSetup () {
     const conditions = {
-      any: [{
-        fact: 'age',
-        operator: 'greaterThanInclusive',
-        value: 21
-      }, {
-        fact: 'qualified',
-        operator: 'equal',
-        value: true
-      }]
+      any: [
+        {
+          name: 'over 21',
+          fact: 'age',
+          operator: 'greaterThanInclusive',
+          value: 21
+        },
+        {
+          fact: 'qualified',
+          operator: 'equal',
+          value: true
+        }
+      ]
     }
     engine = engineFactory()
     const ruleOptions = { conditions, event, priority: 100 }
@@ -50,25 +54,32 @@ describe('Engine: event', () => {
    */
   function advancedSetup () {
     const conditions = {
-      any: [{
-        fact: 'age',
-        operator: 'greaterThanInclusive',
-        value: 21
-      }, {
-        fact: 'qualified',
-        operator: 'equal',
-        value: true
-      }, {
-        all: [{
-          fact: 'zipCode',
-          operator: 'in',
-          value: [80211, 80403]
-        }, {
-          fact: 'gender',
-          operator: 'notEqual',
-          value: 'female'
-        }]
-      }]
+      any: [
+        {
+          fact: 'age',
+          operator: 'greaterThanInclusive',
+          value: 21
+        },
+        {
+          fact: 'qualified',
+          operator: 'equal',
+          value: true
+        },
+        {
+          all: [
+            {
+              fact: 'zipCode',
+              operator: 'in',
+              value: [80211, 80403]
+            },
+            {
+              fact: 'gender',
+              operator: 'notEqual',
+              value: 'female'
+            }
+          ]
+        }
+      ]
     }
     engine = engineFactory()
     const ruleOptions = { conditions, event, priority: 100 }
@@ -91,6 +102,7 @@ describe('Engine: event', () => {
         expect(ruleResult.result).to.be.true()
         expect(ruleResult.conditions.any[0].result).to.be.true()
         expect(ruleResult.conditions.any[0].factResult).to.equal(21)
+        expect(ruleResult.conditions.any[0].name).to.equal('over 21')
         expect(ruleResult.conditions.any[1].result).to.be.false()
         expect(ruleResult.conditions.any[1].factResult).to.equal(false)
       }
@@ -177,11 +189,13 @@ describe('Engine: event', () => {
         params: drinkOrderParams
       }
       const drinkOrderConditions = {
-        any: [{
-          fact: 'canOrderDrinks',
-          operator: 'equal',
-          value: true
-        }]
+        any: [
+          {
+            fact: 'canOrderDrinks',
+            operator: 'equal',
+            value: true
+          }
+        ]
       }
       const drinkOrderRule = factories.rule({
         conditions: drinkOrderConditions,
@@ -193,7 +207,10 @@ describe('Engine: event', () => {
         engine.on('success', function (event, almanac, ruleResult) {
           switch (event.type) {
             case 'setDrinkingFlag':
-              almanac.addRuntimeFact('canOrderDrinks', event.params.canOrderDrinks)
+              almanac.addRuntimeFact(
+                'canOrderDrinks',
+                event.params.canOrderDrinks
+              )
               break
             case 'offerDrink':
               expect(event.params).to.eql(drinkOrderParams)
@@ -257,7 +274,9 @@ describe('Engine: event', () => {
         expect(ruleResult.conditions.any[1].factResult).to.equal(false)
         expect(ruleResult.conditions.any[2].result).to.be.false()
         expect(ruleResult.conditions.any[2].all[0].result).to.be.false()
-        expect(ruleResult.conditions.any[2].all[0].factResult).to.equal(ZIP_CODE)
+        expect(ruleResult.conditions.any[2].all[0].factResult).to.equal(
+          ZIP_CODE
+        )
         expect(ruleResult.conditions.any[2].all[1].result).to.be.false()
         expect(ruleResult.conditions.any[2].all[1].factResult).to.equal(GENDER)
       }
@@ -375,7 +394,8 @@ describe('Engine: event', () => {
       rule.on('success', successSpy)
       await engine.run()
       const ruleResult = successSpy.getCall(0).args[2]
-      const expected = '{"conditions":{"priority":1,"any":[{"operator":"greaterThanInclusive","value":21,"fact":"age","factResult":21,"result":true},{"operator":"equal","value":true,"fact":"qualified","factResult":false,"result":false}]},"event":{"type":"setDrinkingFlag","params":{"canOrderDrinks":true}},"priority":100,"result":true}'
+      const expected =
+        '{"conditions":{"priority":1,"any":[{"name":"over 21","operator":"greaterThanInclusive","value":21,"fact":"age","factResult":21,"result":true},{"operator":"equal","value":true,"fact":"qualified","factResult":false,"result":false}]},"event":{"type":"setDrinkingFlag","params":{"canOrderDrinks":true}},"priority":100,"result":true}'
       expect(JSON.stringify(ruleResult)).to.equal(expected)
     })
   })

types/index.d.ts

@@ -152,10 +152,11 @@ interface ConditionProperties {
   path?: string;
   priority?: number;
   params?: Record<string, any>;
+  name?: string;
 }
 
 type NestedCondition = ConditionProperties | TopLevelCondition;
-type AllConditions = { all: NestedCondition[] };
-type AnyConditions = { any: NestedCondition[] };
-type NotConditions = { not: NestedCondition };
+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;