ES6 examples; README examples; remove Overview

- Converted all examples to ES6
- Added fuller, more realistic examples to the README
- Replaced the basic example with nested-boolean-logic
- Ordered examples in order of complexity
- Removed the Overview

Author: Cache Hamm

Diff for: README.md

@@ -24,17 +24,9 @@ A rules engine expressed in JSON
 $ npm install json-rules-engine
 ```
 
-## Documentation
+## Basic Example
 
-It's best to start with the [overview](./docs/overview.md) to understand the terminology.  Next, see the [walkthrough](./docs/overview.md) and try out some [examples](./examples).
-
-To dive right in, start with the [basic example](./examples/basic.js).
-
-## Example
-
-In basketball, a player who commits five personal fouls over the course of a 40-minute game, or six in a 48-minute game, fouls out.
-
-This example demonstrates an engine for detecting whether an individual player has fouled out.
+This example demonstrates an engine for detecting whether a basketball player has fouled out (a player who commits five personal fouls over the course of a 40-minute game, or six in a 48-minute game, fouls out).
 
 ```js
 import { Engine } from 'json-rules-engine'
@@ -79,28 +71,120 @@ engine.addRule({
 })
 
 /**
- * define the facts
- * note: facts may be loaded asynchronously at runtime; see the advanced example below
+ * Define facts the engine will use to evaluate the conditions above.
+ * Facts may also be loaded asynchronously at runtime; see the advanced example below
  */
 let facts = {
   personalFoulCount: 6,
   gameDuration: 40
 }
 
-// run the engine
+// Run the engine to evaluate
 engine
   .run(facts)
-  .then(events => { // run() return events with truthy conditions
+  .then(events => { // run() returns events with truthy conditions
     events.map(event => console.log(event.params.message))
   })
 
 /*
+ * Output:
+ *
  * Player has fouled out!
  */
 ```
 
 Run this example [here](./examples/nested-boolean-logic.js)
 
+## Advanced Example
+
+This example demonstates an engine for identifying employees who work for Microsoft and are taking Christmas day off.
+
+This  demonstrates an engine which uses asynchronous fact data.
+Fact information is loaded via API call during runtime, and the results are cached and recycled for all 3 conditions.
+It also demonstates use of the condition _path_ feature to reference properties of objects returned by facts.
+
+```js
+import { Engine } from 'json-rules-engine'
+
+// example client for making asynchronous requests to an api, database, etc
+import apiClient from './account-api-client'
+
+/**
+ * Setup a new engine
+ */
+let engine = new Engine()
+
+/**
+ * Rule for identifying microsoft employees taking pto on christmas
+ *
+ * the account-information fact returns:
+ *  { company: 'XYZ', status: 'ABC', ptoDaysTaken: ['YYYY-MM-DD', 'YYYY-MM-DD'] }
+ */
+let microsoftRule = {
+  conditions: {
+    all: [{
+      fact: 'account-information',
+      operator: 'equal',
+      value: 'microsoft',
+      path: '.company' // access the 'company' property of "account-information"
+    }, {
+      fact: 'account-information',
+      operator: 'in',
+      value: ['active', 'paid-leave'], // 'status' can be active or paid-leave
+      path: '.status' // access the 'status' property of "account-information"
+    }, {
+      fact: 'account-information',
+      operator: 'contains', // the 'ptoDaysTaken' property (an array) must contain '2016-12-25'
+      value: '2016-12-25',
+      path: '.ptoDaysTaken' // access the 'ptoDaysTaken' property of "account-information"
+    }]
+  },
+  event: {
+    type: 'microsoft-christmas-pto',
+    params: {
+      message: 'current microsoft employee taking christmas day off'
+    }
+  }
+}
+engine.addRule(microsoftRule)
+
+/**
+ * 'account-information' fact executes an api call and retrieves account data, feeding the results
+ * into the engine.  The major advantage of this technique is that although there are THREE conditions
+ * requiring this data, only ONE api call is made.  This results in much more efficient runtime performance
+ * and fewer network requests.
+ */
+engine.addFact('account-information', function (params, almanac) {
+  console.log('loading account information...')
+  return almanac.factValue('accountId')
+    .then((accountId) => {
+      return apiClient.getAccountInformation(accountId)
+    })
+})
+
+// define fact(s) known at runtime
+let facts = { accountId: 'lincoln' }
+engine
+  .run(facts)
+  .then(function (events) {
+    console.log(facts.accountId + ' is a ' + events.map(event => event.params.message))
+  })
+  .catch(err => console.log(err.stack))
+
+/*
+ * OUTPUT:
+ *
+ * loading account information... // <-- API call is made ONCE and results recycled for all 3 conditions
+ * lincoln is a current microsoft employee taking christmas day off
+ */
+```
+
+Run this example [here](./examples/nested-boolean-logic.js)
+
+## Docs
+
+The examples above provide a simple demonstrations of what `json-rules-engine` can do.  To learn more about the advanced features and techniques,
+see the [docs](./docs) and read through the [examples](./examples).  There is also a [walkthrough](./docs/walkthrough.md) available.
 
 ## Persisting Rules
 

Diff for: docs/engine.md

@@ -1,5 +1,7 @@
 # Engine
 
+The Engine stores and executes rules, emits events, and maintains state.
+
 ## Methods
 
 ### constructor([Array rules])

Diff for: docs/facts.md

@@ -1,5 +1,8 @@
 # Facts
 
+Facts are methods or constants registered with the engine prior to runtime and referenced within rule conditions.  Each fact method should be a pure function that may return a computed value or promise.
+As rule conditions are evaluated during runtime, they retrieve fact values dynamically and use the condition _operator_ to compare the fact result with the condition _value_.
+
 ## Methods
 
 ### constructor(String id, Constant|Function, [Object options]) -> instance

Diff for: docs/overview.md

@@ -1,5 +1,7 @@
 # Rules
 
+Rules contain a set of _conditions_ and a single _event_.  When the engine is run, each rule condition is evaluated.  If the results are truthy, the rule's _event_ is triggered.
+
 ## Methods
 
 ### constructor([Object options|String json])

Diff for: docs/rules.md

@@ -11,18 +11,18 @@
  */
 
 require('colors')
-var Engine = require('../dist').Engine
-var Rule = require('../dist').Rule
+let Engine = require('../dist').Engine
+let Rule = require('../dist').Rule
 
 /**
  * Setup a new engine
  */
-var engine = new Engine()
+let engine = new Engine()
 
 /**
  * Create a rule
  */
-var rule = new Rule()
+let rule = new Rule()
 
 // define the 'conditions' for when "hello world" should display
 rule.setConditions({
@@ -47,13 +47,13 @@ engine.addRule(rule)
  * Fact values do NOT need to be known at engine runtime; see the
  * examples for how to pull in data asynchronously as the engine runs
  */
-var facts = { displayMessage: true }
+let facts = { displayMessage: true }
 
 // run the engine
 engine
   .run(facts)
-  .then(function (triggeredEvents) { // engine returns a list of events with truthy conditions
-    triggeredEvents.map(function (event) { console.log(event.params.data.green) })
+  .then(triggeredEvents => { // engine returns a list of events with truthy conditions
+    triggeredEvents.map(event => console.log(event.params.data.green))
   })
   .catch(console.log)
 

Diff for: examples/hello-world.js renamed to examples/01-hello-world.js

@@ -11,7 +11,7 @@
  */
 
 require('colors')
-var Engine = require('../dist').Engine
+let Engine = require('../dist').Engine
 
 /**
  * Setup a new engine

Diff for: examples/nested-boolean-logic.js renamed to examples/02-nested-boolean-logic.js

@@ -0,0 +1,93 @@
+'use strict'
+
+/*
+ * This example demonstrates computing fact values at runtime, and leveraging the 'path' feature
+ * to select object properties returned by facts
+ *
+ * Usage:
+ *   node ./examples/dynamic-facts.js
+ *
+ * For detailed output:
+ *   DEBUG=json-rules-engine node ./examples/dynamic-facts.js
+ */
+
+require('colors')
+let Engine = require('../dist').Engine
+// example client for making asynchronous requests to an api, database, etc
+let apiClient = require('./support/account-api-client')
+
+/**
+ * Setup a new engine
+ */
+let engine = new Engine()
+
+/**
+ * Rule for identifying microsoft employees taking pto on christmas
+ *
+ * the account-information fact returns:
+ *  { company: 'XYZ', status: 'ABC', ptoDaysTaken: ['YYYY-MM-DD', 'YYYY-MM-DD'] }
+ */
+let microsoftRule = {
+  conditions: {
+    all: [{
+      fact: 'account-information',
+      operator: 'equal',
+      value: 'microsoft',
+      path: '.company' // access the 'company' property of "account-information"
+    }, {
+      fact: 'account-information',
+      operator: 'in',
+      value: ['active', 'paid-leave'], // 'status'' can be active or paid-leave
+      path: '.status' // access the 'status' property of "account-information"
+    }, {
+      fact: 'account-information',
+      operator: 'contains',
+      value: '2016-12-25',
+      path: '.ptoDaysTaken' // access the 'ptoDaysTaken' property of "account-information"
+    }]
+  },
+  event: {
+    type: 'microsoft-christmas-pto',
+    params: {
+      message: 'current microsoft employee taking christmas day off'
+    }
+  }
+}
+engine.addRule(microsoftRule)
+
+/**
+ * 'account-information' fact executes an api call and retrieves account data, feeding the results
+ * into the engine.  The major advantage of this technique is that although there are THREE conditions
+ * requiring this data, only ONE api call is made.  This results in much more efficient runtime performance.
+ */
+engine.addFact('account-information', function (params, almanac) {
+  return almanac.factValue('accountId')
+    .then(accountId => {
+      return apiClient.getAccountInformation(accountId)
+    })
+})
+
+// define fact(s) known at runtime
+let facts = { accountId: 'lincoln' }
+engine
+  .run(facts)
+  .then(events => {
+    if (!events.length) return
+    console.log(facts.accountId + ' is a ' + events.map(event => event.params.message))
+  })
+  .catch(err => console.log(err.stack))
+
+/*
+ * OUTPUT:
+ *
+ * loading account information for "lincoln"
+ * lincoln is a current microsoft employee taking christmas day off
+ *
+ * NOTES:
+ *
+ * - Notice that although all 3 conditions required data from the "account-information" fact,
+ *   the account-information api call is executed only ONCE.  This is because fact results are
+ *   cached by default, increasing performance and lowering network requests.
+ *
+ * - See the 'fact' docs on how to disable fact caching
+ */