json-rules-engine-simplified

A simple rules engine expressed in JSON - Updated for NodeJS 20.

The primary goal of this project is to be an alternative of json-rules-engine for react-jsonschema-form-conditionals, as such it has similar interface and configuration, but simplified predicate language, similar to SQL.

Features

• Optional schema and rules validation
• Basic boolean operations (and or and not) that allow to have any arbitrary complexity
• Rules expressed in simple, easy to read JSON
• Declarative conditional logic with predicates
• Relevant conditional logic support
• Support of nested structures with selectn including composite arrays
• Secure - no use of eval()

Installation

Install json-rules-engine-simplified by running:

npm install --s json-rules-engine-simplified

Usage

The simplest example of using json-rules-engine-simplified

import Engine from 'json-rules-engine-simplified'

let rules = [{
    conditions: {
      firstName: "empty"
    },
    event: {
        type: "remove",
        params: { 
            field: "password"
        },
    }
}];

/**
 * Setup a new engine
 */
let engine = new Engine(rules);

let formData = {
  lastName: "Smit"
}

// Run the engine to evaluate
engine
  .run(formData)
  .then(events => { // run() returns remove event
    events.map(event => console.log(event.type));
  })

Rules engine expects to know all the rules in advance, it effectively drops builder pattern, but keeps the interface.

Appending rule to existing engine

You don't have to specify all rules at the construction time, you can add rules in different time in process. In order to add new rules to the Engine use addRule function.

For example, following declarations are the same

import Engine from 'json-rules-engine-simplified';

let engineA = new Engine();

let rule = {
    conditions: {
      firstName: "empty"
    },
    event: {
        type: "remove",
        params: { 
            field: "password"
        },
    }
};

engineA.addRule(rule);

let engineB = new Engine(rule);

In this case engineA and engineB will give the same results.

Validation

In order to prevent most common errors, Engine does initial validation on the schema, during construction. Validation is done automatically if you specify schema during construction.

let rules = [{
    conditions: {
      firstName: "empty"
    },
    event: {
        type: "remove",
        params: { field: "password" },
    }
}];

let schema = {
    properties: {
        firstName: { type: "string" },
        lastName: { type: "string" }
    }
}

let engine = new Engine(rules, schema);

Types of errors

• Conditions field validation (conditions use fields that are not part of the schema)
• Predicate validation (used predicates are not part of the predicates library and most likely wrong)

Validation is done only during development, validation is disabled by default in production.

WARNING!!! Currently validation does not support nested structures, so be extra careful, when using those.

Conditional logic

Conditional logic is based on public predicate library with boolean logic extension.

Predicate library has a lot of predicates that we found more, than sufficient for our use cases.

To showcase conditional logic, we'll be using simple registration schema

let schema = {
  definitions: {
    hobby: {
      type: "object",
      properties: {
        name: { type: "string" },
        durationInMonth: { type: "integer" },
      }
    }
  },
  title: "A registration form",
  description: "A simple form example.",
  type: "object",
  required: [
    "firstName",
    "lastName"
  ],
  properties: {
    firstName: {
      type: "string",
      title: "First name"
    },
    lastName: {
      type: "string",
      title: "Last name"
    },
    age: {
      type: "integer",
      title: "Age",
    },
    bio: {
      type: "string",
      title: "Bio",
    },
    country: {
      type: "string",
      title: "Country" 
    },
    state: {
      type: "string",
      title: "State" 
    },
    zip: {
      type: "string",
      title: "ZIP" 
    },
    password: {
      type: "string",
      title: "Password",
      minLength: 3
    },
    telephone: {
      type: "string",
      title: "Telephone",
      minLength: 10
    },
    work: { "$ref": "#/definitions/hobby" },
    hobbies: {
        type: "array",
        items: { "$ref": "#/definitions/hobby" }
    }
  }
}

Assuming action part is taken from react-jsonschema-form-conditionals

Single line conditionals

Let's say we want to remove password , when firstName is missing, we can expressed it like this:

let rules = [{
    conditions: {
      firstName: "empty"
    },
    event: {
      type: "remove",
      params: {
        field: "password"
      }
    }
}]

This translates into - when firstName is empty, trigger remove event.

Empty keyword is equal in predicate library and required event will be performed only when predicate.empty(registration.firstName) is true.

Conditionals with arguments

Let's say we need to require zip, when age is less than 16, because the service we are using is legal only after 16 in some countries

let rules = [{
    conditions: {
      age: { less : 16 }
    },
    event: {
      type: "require",
      params: {
        field: "zip"
      }
    }
}]

This translates into - when age is less than 16, require zip.

Less keyword is less in predicate and required event will be returned only when predicate.empty(registration.age, 5) is true.

Boolean operations on a single field

AND

For the field AND is a default behavior.

Looking at previous rule, we decide that we want to change the rule and require zip, when age is between 16 and 70, so it would be available only to people older, than 16 and younger than 70.

let rules = [{
    conditions: {
        age: {
          greater: 16,
          less : 70,
        }
    },
    event: {
      type: "require",
      params: {
        field: "zip"
      }
    }
}]

By default action will be applied only when both field conditions are true. In this case, when age is greater than 16 and less than 70.

NOT

Let's say we want to change the logic to opposite, and trigger event only when age is lesser then 16 or greater than 70,

let rules = [{
  conditions: {
    age: {
      not: {
          greater: 16,
          less : 70,
      }
    }
  },
  event: {
    type: "require",
    params: {
      field: "zip"
    }
  }
}]

This does it, since the final result will be opposite of the previous condition.

OR

The previous example works, but it's a bit hard to understand, luckily we can express it differently with or conditional.

let rules = [{
  conditions: { age: { 
      or: [
        { lessEq : 5 },
        { greaterEq: 70 }
      ]
    }
  },
  event: {
    type: "require",
    params: {
      field: "zip"
    }
  }
}]

The result is the same as NOT, but easier to grasp.

Boolean operations on multi fields

To support cases, when action depends on more, than one field meeting criteria we introduced multi fields boolean operations.

Default AND operation

Let's say, when age is less than 70 and country is USA we want to require bio.

let rules = [{
  conditions: {
    age: { less : 70 },
    country: { is: "USA" }
  },
  event: { 
    type: "require",
    params: { fields: [ "bio" ]}
  }
}]

This is the way we can express this. By default each field is treated as a separate condition and all conditions must be meet.

OR

In addition to previous rule we need bio, if state is NY.

let rules = [{
  conditions: {
    or: [
      {
        age: { less : 70 },
        country: { is: "USA" }
      },
      {
        state: { is: "NY"}
      }
    ]
  },
  event: { 
    type: "require",
    params: { fields: [ "bio" ]}
  }
}]

NOT

When we don't require bio we need zip code.

let rules = [{
    conditions: {
      not: {
        or: [
          {
            age: { less : 70 },
            country: { is: "USA" }
          },
          {
            state: { is: "NY"}
          }
        ]
      }
    },
    event: { 
      type: "require",
      params: { fields: [ "zip" ]}
    }
}]

Nested object queries

Rules engine supports querying inside nested objects, with selectn, any data query that works in selectn, will work in here

Let's say we need to require state, when work has a name congressman, this is how we can do this:

let rules = [{
    conditions: {
      "work.name": { is: "congressman" }
    },
    event: { 
      type: "require",
      params: { fields: [ "state" ]}
    }
}]

Nested arrays object queries

Sometimes we need to make changes to the form if some nested condition is true.

For example if one of the hobbies is baseball, we need to make state required. This can be expressed like this:

let rules = [{
    conditions: {
      hobbies: {
        name: { is: "baseball" },
      }
    },
    event: { 
      type: "require",
      params: { fields: [ "state" ]}
    }
}]

Rules engine will go through all the elements in the array and trigger require if any of the elements meet the criteria.

Extending available predicates

If for some reason the list of predicates is insufficient for your needs, you can extend them pretty easy, by specifying additional predicates in global import object.

For example, if we want to add range predicate, that would verify, that integer value is in range, we can do it like this:

import predicate from "predicate";
import Engine from "json-rules-engine-simplified";

predicate.range = predicate.curry((val, range) => {
  return predicate.num(val) &&
    predicate.array(range) &&
    predicate.equal(range.length, 2) &&
    predicate.num(range[0]) &&
    predicate.num(range[1]) &&
    predicate.greaterEq(val, range[0]) &&
    predicate.lessEq(val, range[1]);
});

let engine = new Engine([{
  conditions: { age: { range: [ 20, 40 ] } },
  event: "hit"
}]);

Validation will automatically catch new extension and work as expected.

Logic on nested objects

Support of nested structures with selectn, so basically any query you can define in selectn you can use here.

For example if in previous example, age would be a part of person object, we could work with it like this:

    let rules = [ { conditions: { "person.age": { range: [ 20, 40 ] } } } ]; 

Also in order to support systems where keys with "." not allowed (for example if you would like to store data in mongo), you can use $ to separate references:

For example, this is the same condition, but instead of . it uses $:

    let rules = [ { conditions: { "person$age": { range: [ 20, 40 ] } } } ]; 

Relevant conditional logic

Sometimes you would want to validate formData fields one against the other. You can do this simply by appending $ to the beginning of reference.

For example, you want to trigger event only when a is less then b, when you don't know ahead a or b values

let schema = {
  type: "object",
  properties: {
    a: { type: "number" },
    b: { type: "number" }
  }
}

let rules = [{
  conditions: {
    a: { less: "$b" }
  },
  event: "some"
}]

let engine = new Engine(schema, rules);

This is how you do it, in run time $b will be replaces with field b value.

Relevant fields work on nested objects as well as on any field condition.

Events

Framework does not put any restrictions on event object, that will be triggered, in case conditions are meet

For example, event can be a string:

let rules = [{
    conditions: { ... },
    event: "require"
}]

Or number

let rules = [{
    conditions: { ... },
    event: 4
}]

Or an object

let rules = [{
    conditions: { ... },
    event: { 
      type: "require",
      params: { fields: [ "state" ]}
    }
}]

You can even return an array of events, each of which will be added to final array of results

let rules = [{
    conditions: { ... },
    event: [
      { 
        type: "require",
        params: { field: "state"}
      },
      { 
        type: "remove",
        params: { fields: "fake" }
      },
    ]
}]

License

The project is licensed under the Apache Licence 2.0.