Document path resolver option; add table of contents to docs

Author: Cache Hamm

CHANGELOG.md

@@ -2,8 +2,8 @@
   * BREAKING CHANGES
     * `path` support using `selectn` should use the `pathResolver` feature. Read more [here](). To continue using selectn, add the following to the engine constructor:
       ```js
-      const pathResolver = (value, path) => {
-        return selectn(path)(value)
+      const pathResolver = (object, path) => {
+        return selectn(path)(object)
       }
       const engine = new Engine(rules, { pathResolver })
       ```

docs/almanac.md

@@ -1,5 +1,14 @@
 # Almanac
 
+* [Overview](#overview)
+* [Methods](#methods)
+    * [almanac.factValue(Fact fact, Object params, String path) -> Promise](#almanacfactvaluefact-fact-object-params-string-path---promise)
+    * [almanac.addRuntimeFact(String factId, Mixed value)](#almanacaddruntimefactstring-factid-mixed-value)
+* [Common Use Cases](#common-use-cases)
+    * [Fact dependencies](#fact-dependencies)
+    * [Retrieve fact values when handling events](#retrieve-fact-values-when-handling-events)
+    * [Rule Chaining](#rule-chaining)
+
 ## Overview
 
 An almanac collects facts through an engine run cycle.  As the engine computes fact values,

docs/engine.md

@@ -2,6 +2,20 @@
 
 The Engine stores and executes rules, emits events, and maintains state.
 
+* [Methods](#methods)
+  * [constructor([Array rules], Object [options])](#constructorarray-rules-object-options)
+    * [Options](#options)
+  * [engine.addFact(String id, Function [definitionFunc], Object [options])](#engineaddfactstring-id-function-definitionfunc-object-options)
+  * [engine.removeFact(String id)](#engineremovefactstring-id)
+  * [engine.addRule(Rule instance|Object options)](#engineaddrulerule-instanceobject-options)
+  * [engine.removeRule(Rule instance)](#engineremoverulerule-instance)
+  * [engine.addOperator(String operatorName, Function evaluateFunc(factValue, jsonValue))](#engineaddoperatorstring-operatorname-function-evaluatefuncfactvalue-jsonvalue)
+  * [engine.removeOperator(String operatorName)](#engineremoveoperatorstring-operatorname)
+  * [engine.run([Object facts], [Object options]) -> Promise ({ events: Events, almanac: Almanac})](#enginerunobject-facts-object-options---promise--events-events-almanac-almanac)
+  * [engine.stop() -> Engine](#enginestop---engine)
+    * [engine.on('success', Function(Object event, Almanac almanac, RuleResult ruleResult))](#engineonsuccess-functionobject-event-almanac-almanac-ruleresult-ruleresult)
+    * [engine.on('failure', Function(Object event, Almanac almanac, RuleResult ruleResult))](#engineonfailure-functionobject-event-almanac-almanac-ruleresult-ruleresult)
+
 ## Methods
 
 ### constructor([Array rules], Object [options])
@@ -16,7 +30,8 @@ let engine = new Engine([Array rules])
 
 // initialize with options
 let options = {
-  allowUndefinedFacts: false
+  allowUndefinedFacts: false,
+  pathResolver: (object, path) => _.get(object, path)
 };
 let engine = new Engine([Array rules], options)
 ```
@@ -27,6 +42,8 @@ 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)
 
+`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])
 
 ```js

docs/facts.md

@@ -3,6 +3,9 @@
 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 either computed value, or promise that resolves to a computed value.
 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](#methods)
+  * [constructor(String id, Constant|Function(Object params, Almanac almanac), [Object options]) -> instance](#constructorstring-id-constantfunctionobject-params-almanac-almanac-object-options---instance)
+
 ## Methods
 
 ### constructor(String id, Constant|Function(Object params, Almanac almanac), [Object options]) -> instance

docs/rules.md

@@ -3,15 +3,30 @@
 
 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](#methods)
-
-[Conditions](#conditions)
-
-[Events](#events)
-
-[Operators](#operators)
-
-[Rule Results](#rule-results)
+* [Methods](#methods)
+  * [constructor([Object options|String json])](#constructorobject-optionsstring-json)
+  * [setConditions(Array conditions)](#setconditionsarray-conditions)
+  * [getConditions() -> Object](#getconditions---object)
+  * [setEvent(Object event)](#seteventobject-event)
+  * [getEvent() -> Object](#getevent---object)
+  * [setPriority(Integer priority = 1)](#setpriorityinteger-priority--1)
+  * [getPriority() -> Integer](#getpriority---integer)
+  * [toJSON(Boolean stringify = true)](#tojsonboolean-stringify--true)
+* [Conditions](#conditions)
+  * [Basic conditions](#basic-conditions)
+  * [Boolean expressions: all and any](#boolean-expressions-all-and-any)
+  * [Condition helpers: params](#condition-helpers-params)
+  * [Condition helpers: path](#condition-helpers-path)
+  * [Condition helpers: custom path resolver](#condition-helpers-custom-path-resolver)
+  * [Comparing facts](#comparing-facts)
+* [Events](#events)
+    * [rule.on('success', Function(Object event, Almanac almanac, RuleResult ruleResult))](#ruleonsuccess-functionobject-event-almanac-almanac-ruleresult-ruleresult)
+    * [rule.on('failure', Function(Object event, Almanac almanac, RuleResult ruleResult))](#ruleonfailure-functionobject-event-almanac-almanac-ruleresult-ruleresult)
+* [Operators](#operators)
+  * [String and Numeric operators:](#string-and-numeric-operators)
+  * [Numeric operators:](#numeric-operators)
+  * [Array operators:](#array-operators)
+* [Rule Results](#rule-results)
 
 ## Methods
 
@@ -217,6 +232,34 @@ json-path support is provided by [jsonpath-plus](https://github.com/s3u/JSONPath
 
 For an example, see [fact-dependency](../examples/04-fact-dependency.js)
 
+### Condition helpers: custom `path` resolver
+
+To use a custom path resolver instead of the `json-path` default, a `pathResolver` callback option may be passed to the engine. The callback will be invoked during execution when a `path` property is encountered.
+
+```js
+const { get } = require('lodash') // to use the lodash path resolver, for example
+
+function pathResolver (object, path) {
+  // when the rule below is evaluated:
+  //   "object" will be the 'fact1' value
+  //   "path" will be '.price[0]'
+  return get(object, path)
+}
+const engine = new Engine(rules, { pathResolver })
+engine.addRule(new Rule({
+  conditions: {
+    all: [
+      {
+        fact: 'fact1',
+        path: '.price[0]', // uses lodash path syntax
+        operator: 'equal',
+        value: 1
+      }
+    ]
+  })
+)
+```
+
 ### Comparing facts
 
 Sometimes it is necessary to compare facts against other facts.  This can be accomplished by nesting the second fact within the `value` property.  This second fact has access to the same `params` and `path` helpers as the primary fact.

docs/walkthrough.md

@@ -1,5 +1,11 @@
 # Walkthrough
 
+* [Step 1: Create an Engine](#step-1-create-an-engine)
+* [Step 2: Add Rules](#step-2-add-rules)
+    * [Step 3: Define Facts](#step-3-define-facts)
+* [Step 4: Handing Events](#step-4-handing-events)
+* [Step 5: Run the engine](#step-5-run-the-engine)
+
 ## Step 1: Create an Engine
 
 ```js