Add documentation around conditions

Add documentation covering the use and advantages of condition sharing.
Specifically on the ability to re-use the same condition across multiple
rules.

Author: Christopher Pardy

docs/engine.md

@@ -12,6 +12,8 @@ The Engine stores and executes rules, emits events, and maintains state.
     * [engine.removeRule(Rule instance | String ruleId)](#engineremoverulerule-instance)
     * [engine.addOperator(String operatorName, Function evaluateFunc(factValue, jsonValue))](#engineaddoperatorstring-operatorname-function-evaluatefuncfactvalue-jsonvalue)
     * [engine.removeOperator(String operatorName)](#engineremoveoperatorstring-operatorname)
+    * [engine.setCondition(String name, Object conditions)](#enginesetconditionstring-name-object-conditions)
+    * [engine.removeCondition(String name)](#engineremovecondtionstring-name)
     * [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)
@@ -43,6 +45,11 @@ let engine = new Engine([Array rules], options)
 an exception is thrown.  Turning this option on will cause the engine to treat
 undefined facts as `undefined`.  (default: false)
 
+`allowUndefinedConditions` - By default, when a running engine encounters a
+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)
+
 `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])
@@ -172,6 +179,71 @@ engine.addOperator('startsWithLetter', (factValue, jsonValue) => {
 engine.removeOperator('startsWithLetter');
 ```
 
+### engine.setCondition(String name, Object conditions)
+
+Adds or updates a condition to the engine. Rules may include references to this condition. Conditions must start with `all`, `any`, `not`, or reference a condition.
+
+```javascript
+engine.setCondition('validLogin', {
+  all: [
+    {
+      operator: 'notEqual',
+      fact: 'loginToken',
+      value: null
+    },
+    {
+      operator: 'greaterThan',
+      fact: 'loginToken',
+      path: '$.expirationTime',
+      value: { fact: 'now' }
+    }
+  ]
+});
+
+engine.addRule({
+  condtions: {
+    all: [
+      {
+        condition: 'validLogin'
+      },
+      {
+        operator: 'contains',
+        fact: 'loginToken',
+        path: '$.role',
+        value: 'admin'
+      }
+    ]
+  },
+  event: {
+    type: 'AdminAccessAllowed'
+  }
+})
+
+```
+
+### engine.removeCondition(String name)
+
+Removes the condition that was previously added.
+
+```javascript
+engine.setCondition('validLogin', {
+  all: [
+    {
+      operator: 'notEqual',
+      fact: 'loginToken',
+      value: null
+    },
+    {
+      operator: 'greaterThan',
+      fact: 'loginToken',
+      path: '$.expirationTime',
+      value: { fact: 'now' }
+    }
+  ]
+});
+
+engine.removeCondition('validLogin');
+```
 
 
 ### engine.run([Object facts], [Object options]) -> Promise ({ events: [], failureEvents: [], almanac: Almanac, results: [], failureResults: []})

docs/rules.md

@@ -15,6 +15,7 @@ Rules contain a set of _conditions_ and a single _event_.  When the engine is ru
 * [Conditions](#conditions)
     * [Basic conditions](#basic-conditions)
     * [Boolean expressions: all, any, and not](#boolean-expressions-all-any-and-not)
+    * [Condition Reference](#condition-reference)
     * [Condition helpers: params](#condition-helpers-params)
     * [Condition helpers: path](#condition-helpers-path)
     * [Condition helpers: custom path resolver](#condition-helpers-custom-path-resolver)
@@ -136,7 +137,7 @@ See the [hello-world](../examples/01-hello-world.js) example.
 
 ### Boolean expressions: `all`, `any`, and `not`
 
-Each rule's conditions *must* have an `all` or `any` operator containing an array of conditions at its root or a `not` operator containing a single condition.  The `all` operator specifies that all conditions contained within must be truthy for the rule to be considered a `success`.  The `any` operator only requires one condition to be truthy for the rule to succeed. The `not` operator will negate whatever condition it contains.
+Each rule's conditions *must* have an `all` or `any` operator containing an array of conditions at its root, a `not` operator containing a single condition, or a condition reference. The `all` operator specifies that all conditions contained within must be truthy for the rule to be considered a `success`.  The `any` operator only requires one condition to be truthy for the rule to succeed. The `not` operator will negate whatever condition it contains.
 
 ```js
 // all:
@@ -174,7 +175,30 @@ let rule = new Rule({
 })
 ```
 
-Notice in the second example how `all`, `any`, and 'not' can be nested within one another to produce complex boolean expressions.  See the [nested-boolean-logic](../examples/02-nested-boolean-logic.js) example.
+Notice in the second example how `all`, `any`, and `not` can be nested within one another to produce complex boolean expressions.  See the [nested-boolean-logic](../examples/02-nested-boolean-logic.js) example.
+
+### Condition Reference
+
+Rules may reference conditions based on their name.
+
+```js
+let rule = new Rule({
+  conditions: {
+    all: [
+      { condition: 'conditionName' },
+      { /* additional condition */ }
+    ]
+  }
+})
+```
+
+Before running the rule the condition should be added to the engine.
+
+```js
+engine.setCondition('conditionName', { /* conditions */ });
+```
+
+Conditions must start with `all`, `any`, `not`, or reference a condition.
 
 ### Condition helpers: `params`
 

examples/10-condition-sharing.js

@@ -0,0 +1,139 @@
+'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 } = require('json-rules-engine')
+
+async function start () {
+  /**
+   * Setup a new engine
+   */
+  const engine = new Engine()
+
+  /**
+   * Condition that will be used to determine if a user likes screwdrivers
+   */
+  engine.setCondition('screwdriverAficionado', {
+    all: [
+      {
+        fact: 'drinksOrangeJuice',
+        operator: 'equal',
+        value: true
+      },
+      {
+        fact: 'enjoysVodka',
+        operator: 'equal',
+        value: true
+      }
+    ]
+  })
+
+  /**
+   * Rule for identifying people who should be invited to a screwdriver social
+   * - Only invite people who enjoy screw drivers
+   * - Only invite people who are sociable
+   */
+  const inviteRule = {
+    conditions: {
+      all: [
+        {
+          condition: 'screwdriverAficionado'
+        },
+        {
+          fact: 'isSociable',
+          operator: 'equal',
+          value: true
+        }
+      ]
+    },
+    event: { type: 'invite-to-screwdriver-social' }
+  }
+  engine.addRule(inviteRule)
+
+  /**
+   * Rule for identifying people who should be invited to the other social
+   * - Only invite people who don't enjoy screw drivers
+   * - Only invite people who are sociable
+   */
+  const otherInviteRule = {
+    conditions: {
+      all: [
+        {
+          not: {
+            condition: 'screwdriverAficionado'
+          }
+        },
+        {
+          fact: 'isSociable',
+          operator: 'equal',
+          value: true
+        }
+      ]
+    },
+    event: { type: 'invite-to-other-social' }
+  }
+  engine.addRule(otherInviteRule)
+
+  /**
+   * Register listeners with the engine for rule success and failure
+   */
+  engine
+    .on('success', async (event, almanac) => {
+      const accountId = await almanac.factValue('accountId')
+      console.log(
+        `${accountId}` +
+          'DID'.green +
+          ` meet conditions for the ${event.type.underline} rule.`
+      )
+    })
+    .on('failure', async (event, almanac) => {
+      const accountId = await almanac.factValue('accountId')
+      console.log(
+        `${accountId} did ` +
+          'NOT'.red +
+          ` meet conditions for the ${event.type.underline} rule.`
+      )
+    })
+
+  // define fact(s) known at runtime
+  let facts = {
+    accountId: 'washington',
+    drinksOrangeJuice: true,
+    enjoysVodka: true,
+    isSociable: true
+  }
+
+  // first run, using washington's facts
+  await engine.run(facts)
+
+  facts = {
+    accountId: 'jefferson',
+    drinksOrangeJuice: true,
+    enjoysVodka: false,
+    isSociable: true,
+    accountInfo: {}
+  }
+
+  // second run, using jefferson's facts; facts & evaluation are independent of the first run
+  await engine.run(facts)
+}
+
+start()
+
+/*
+ * OUTPUT:
+ *
+ * washington DID meet conditions for the invite-to-screwdriver-social rule.
+ * washington did NOT meet conditions for the invite-to-other-social rule.
+ * jefferson did NOT meet conditions for the invite-to-screwdriver-social rule.
+ * jefferson DID meet conditions for the invite-to-other-social rule.
+ */