decision-engine

Install

npm install decision-engine --save

Description

A decision engine which based on fact and rules provided can deduce what decisions should be made. For example in an Ecommerce system, when users place orders there are multiple decisions to be made, whether the order qualifies for discount, what kind of shipping is applicable and so on. This calls for a business rule engine which decision-engine exactly is.

Rule

A rule is basically a JSON with 4 properties

name - name of decision, which is returned by the engine.
group - group identifier to which the rule belongs, a group can have multiple rules.
comment - description about rule just for readable purposes
conditions - actual rules are represented here

Where to keep rules ?

Rules can be stored externally in a .json file or in a document db like MongoDB. Storage can be in any format until engine is provided a json format.

Conditions

Conditions is a json object which can have either of and or or key, these corresponds to boolean && and || respectively. This and/or key then could be a json array or json object depending upon the rule complexity. The unit of the condition is a json object which has three properties :

key - key in the fact which is to be considered
value - value to be compared with can be anything string, int, boolean.
comparator - this is the comparing function to be used.

This unit looks like this :

{
  "key": "order.items.length",
  "value": 2,
  "comparator": "gte"
}

Now a condition can have multiple units paired under and or or key as elements of json array. This is shown below:

"and": [
  {
    "key": "order.items.length",
    "value": 5,
    "comparator": "lte"
  },
  {
    "key": "order.price",
    "value": 5000,
    "comparator": "gte"
  }
]

Let's call this as a composite unit. The boolean evaluation of individual unit will be reduced to single boolean value by applying either and or or function as defined by the parent key which is and in above shown example. Now this composite unit can be directly referenced under conditions attribute or can be nested under and/or keys as json objects. Lets see an example.

Composite unit directly referenced by conditions

"conditions": {
        "and": [{
            "key": "order.items.length",
            "value": 5,
            "comparator": "lte"
        }, {
            "key": "order.price",
            "value": 5000,
            "comparator": "gte"
        }]
}

Composite unit as an nested json object

"conditions": {
  "and": {
    "5ItemsPrice5000": {
      "and": [
        {
          "key": "order.items.length",
          "value": 5,
          "comparator": "lte"
        },
        {
          "key": "order.price",
          "value": 5000,
          "comparator": "gte"
        }
      ]
    }
  }
}

Note that 5ItemsPrice5000 is a custom name and does not affect the rule syntax. It could be any string. Perhaps it would be more clear if you will see how two composite units can be combined.

"conditions": {
  "or": {
    "5ItemsPrice5000": {
      "and": [
        {
          "key": "order.items.length",
          "value": 5,
          "comparator": "gte"
        },
        {
          "key": "order.price",
          "value": 5000,
          "comparator": "gte"
        }
      ]
    },
    "priceGreaterThan20000": {
      "and": [
        {
          "key": "order.price",
          "value": 20000,
          "comparator": "gte"
        },
        {
          "key": "order.items.length",
          "value": 1,
          "comparator": "is"
        }
      ]
    }
  }
}

In the above example there are two composite units 5ItemsPrice5000 and priceGreaterThan20000 combined by an or. This means either 5ItemsPrice5000 or priceGreaterThan20000 has to evaluate to true for decision to be applicable. This nesting of composite conditions with and and or can be done to a very deep level for supporting complex rules. Now its time to reveal how a rule looks like.

{
  "name": "10",
  "group": "discount",
  "comment": "10% discount applicable to order of more than 10 items with minimum total price of 500 or total order amount of 2000",
  "conditions": {
    "or": {
      "5ItemsPrice5000": {
        "and": [
          {
            "key": "order.items.length",
            "value": 5,
            "comparator": "gte"
          },
          {
            "key": "order.price",
            "value": 5000,
            "comparator": "gte"
          }
        ]
      },
      "priceGreaterThan20000": {
        "and": [
          {
            "key": "order.price",
            "value": 20000,
            "comparator": "gte"
          },
          {
            "key": "order.items.length",
            "value": 1,
            "comparator": "is"
          }
        ]
      }
    }
  }
}

Comparators available

is (a, that)

  returns true if a === that

gte (a, that)

  returns true if a >= that

gt (a, that)

  returns true if a > that

lte (a, that)

   returns true if a <= that

lt (a, that)

  returns true if a < that

not (a, that)

  returns true if a!===that

divisible (a, that)

  returns true if a % that === 0

regex (a, that)

  returns true if new RegExp(that).test(a) === true

API Usage

const decisionEngine = require('decision-engine')

Methods

addRule (rule)

rule is the json object having single rule. This will register the rule with decision engine.

decisionEngine.addRule(require('./orderSystem/discount.json'))

importRules (rules)

rules is the json array having multiple rule. This will register the rule with decision engine.

decisionEngine.importRules(require('./orderSystemRules.json'))

deleteRule (name, group)

This will delete the rule identified by name and belonging to group from decision engine.

decisionEngine.deleteRule('10', 'discount')

run (fact, group, callback)

Runs the rules from a group on the fact and generates an array of applicable decisions' names. callback is of standard format i.e. two parameters first being err and second being result. result will be the array of applicable decisions' names.

let fact = {
  "user": {
    "name" :"sikorski",
    "address" : {
      "state":{
        "name":"Earth"
      },
      "express":{
        "duration":1,
        "available":true
      }
    },
    "subs":{
      "prime":true
    }
  },
  "order": {
    "items": [],
    "price": 0,
    "express": false,
    "cashOnDelivery": true
  }
}

fact.order.items.push({name: 'coffee mug', id: 'skuid1'})
fact.order.items.push({name: 'nodejs book', id: 'skuid2'})
fact.order.items.push({name: 'java book', id: 'skuid3'})
fact.order.price = 600

decisionEngine.addRule(require('./orderSystem/discount.json'))

decisionEngine.run(fact, 'discount', function (err, result) {
  if (err) done(err)
  else {
    //result wil be ['10']
    done(null, result)
  }
})

Examples & Issues

Please refer test for example usage and feel free to log issues if any.

anandrajneesh / decision-engine

readme