Add engine pathResolver option; remove selectn automatic fallback

Author: Cache Hamm

CHANGELOG.md

@@ -1,7 +1,14 @@
 #### 6.0. / 2020-12-XX
   * BREAKING CHANGES
-    * Private `rule.event` property renamed. Use `rule.getEvent()` to avoid breaking changes in the future.
+    * `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 engine = new Engine(rules, { pathResolver })
+      ```
     * Engine and Rule events `on('success')`, `on('failure')`, and Rule callbacks `onSuccess` and `onFailure` now honor returned promises; any event handler that returns a promise will be waited upon to resolve before engine execution continues. (fixes #235)
+    * Private `rule.event` property renamed. Use `rule.getEvent()` to avoid breaking changes in the future.
     * The 'success-events' fact used to store successful events has been converted to an internal data structure and will no longer appear in the almanac's facts. (fixes #187)
 
 #### 5.3.0 / 2020-12-02

package.json

@@ -73,6 +73,7 @@
     "chai-as-promised": "^7.1.1",
     "colors": "~1.4.0",
     "dirty-chai": "2.0.1",
+    "lodash": "4.17.20",
     "mocha": "^8.1.3",
     "perfy": "^1.1.5",
     "sinon": "^9.0.3",

src/almanac.js

@@ -7,6 +7,10 @@ import debug from './debug'
 import { JSONPath } from 'jsonpath-plus'
 import isObjectLike from 'lodash.isobjectlike'
 
+function defaultPathResolver (value, path) {
+  return JSONPath({ path, json: value, wrap: false })
+}
+
 /**
  * Fact results lookup
  * Triggers fact computations and saves the results
@@ -17,6 +21,7 @@ export default class Almanac {
     this.factMap = new Map(factMap)
     this.factResultsCache = new Map() // { cacheKey:  Promise<factValu> }
     this.allowUndefinedFacts = Boolean(options.allowUndefinedFacts)
+    this.pathResolver = options.pathResolver || defaultPathResolver
     this.successEvents = []
 
     for (const factId in runtimeFacts) {
@@ -122,44 +127,19 @@ export default class Almanac {
         factValuePromise = this._setFactValue(fact, params, fact.calculate(params, this))
       }
     }
-    if (path) { // selectn supports arrays and strings as a 'path'
-      // strings starting with '$' denotes json path. otherwise fall back to deprecated 'selectn' syntax
-      if (typeof path === 'string' && path.startsWith('$')) {
-        debug(`condition::evaluate extracting object property ${path}`)
-        return factValuePromise
-          .then(factValue => {
-            if (isObjectLike(factValue)) {
-              const pathValue = JSONPath({ path, json: factValue, wrap: false })
-              debug(`condition::evaluate extracting object property ${path}, received: ${JSON.stringify(pathValue)}`)
-              return pathValue
-            } else {
-              debug(`condition::evaluate could not compute object path(${path}) of non-object: ${factValue} <${typeof factValue}>; continuing with ${factValue}`)
-              return factValue
-            }
-          })
-      } else {
-        let selectn
-        try {
-          selectn = require('selectn')
-        } catch (err) {
-          console.error('Oops! Looks like you\'re trying to use the deprecated syntax for the ".path" property.')
-          console.error('Please convert your "path" properties to JsonPath syntax (ensure your path starts with "$")')
-          console.error('Alternatively, if you wish to continue using old syntax (provided by selectn), you may "npm install selectn" as a direct dependency.')
-          console.error('See https://github.com/CacheControl/json-rules-engine/blob/master/CHANGELOG.md#500--2019-10-27 for more information.')
-          throw new Error('json-rules-engine: Unmet peer dependency "selectn" required for use of deprecated ".path" syntax. please "npm install selectn" or convert to json-path syntax')
-        }
-        return factValuePromise
-          .then(factValue => {
-            if (isObjectLike(factValue)) {
-              const pathValue = selectn(path)(factValue)
-              debug(`condition::evaluate extracting object property ${path}, received: ${pathValue}`)
-              return pathValue
-            } else {
-              debug(`condition::evaluate could not compute object path(${path}) of non-object: ${factValue} <${typeof factValue}>; continuing with ${factValue}`)
-              return factValue
-            }
-          })
-      }
+    if (path) {
+      debug(`condition::evaluate extracting object property ${path}`)
+      return factValuePromise
+        .then(factValue => {
+          if (isObjectLike(factValue)) {
+            const pathValue = this.pathResolver(factValue, path)
+            debug(`condition::evaluate extracting object property ${path}, received: ${JSON.stringify(pathValue)}`)
+            return pathValue
+          } else {
+            debug(`condition::evaluate could not compute object path(${path}) of non-object: ${factValue} <${typeof factValue}>; continuing with ${factValue}`)
+            return factValue
+          }
+        })
     }
 
     return factValuePromise

src/engine.js

@@ -21,6 +21,7 @@ class Engine extends EventEmitter {
     super()
     this.rules = []
     this.allowUndefinedFacts = options.allowUndefinedFacts || false
+    this.pathResolver = options.pathResolver
     this.operators = new Map()
     this.facts = new Map()
     this.status = READY
@@ -210,7 +211,11 @@ class Engine extends EventEmitter {
   run (runtimeFacts = {}) {
     debug('engine::run started')
     this.status = RUNNING
-    const almanac = new Almanac(this.facts, runtimeFacts, { allowUndefinedFacts: this.allowUndefinedFacts })
+    const almanacOptions = {
+      allowUndefinedFacts: this.allowUndefinedFacts,
+      pathResolver: this.pathResolver
+    }
+    const almanac = new Almanac(this.facts, runtimeFacts, almanacOptions)
     const orderedSets = this.prioritizeRules()
     let cursor = Promise.resolve()
     // for each rule set, evaluate in parallel,

test/engine-fact.test.js

@@ -1,6 +1,7 @@
 'use strict'
 
 import sinon from 'sinon'
+import { get } from 'lodash'
 import engineFactory from '../src/index'
 
 const CHILD = 14
@@ -224,9 +225,6 @@ describe('Engine: fact evaluation', () => {
             value: 1
           }]
         }
-        const event = {
-          type: 'runtimeEvent'
-        }
 
         engine = engineFactory([])
         const rule = factories.rule({ conditions, event })
@@ -268,6 +266,33 @@ describe('Engine: fact evaluation', () => {
       await engine.run()
       expect(successSpy).to.have.been.calledWith(event)
     })
+
+    describe('pathResolver', () => {
+      it('allows a custom path resolver to be registered which interprets the path property', async () => {
+        const fact = { x: { y: [99] }, a: 2 }
+        const conditions = {
+          all: [{
+            fact: 'x',
+            path: 'y[0]',
+            operator: 'equal',
+            value: 99
+          }]
+        }
+        const pathResolver = (value, path) => {
+          return get(value, path)
+        }
+
+        engine = engineFactory([], { pathResolver })
+        const rule = factories.rule({ conditions, event })
+        await engine.run()
+        engine.addRule(rule)
+        engine.on('success', successSpy)
+        engine.on('failure', failureSpy)
+        await engine.run(fact)
+        expect(successSpy).to.have.been.calledWith(event)
+        expect(failureSpy).to.not.have.been.calledWith(event)
+      })
+    })
   })
 
   describe('promises', () => {

types/index.d.ts

@@ -1,5 +1,6 @@
 export interface EngineOptions {
   allowUndefinedFacts: boolean;
+  pathResolver: string;
 }
 
 export interface EngineResult {