json-rules-engine

What is json-rules-engine?

The json-rules-engine npm package is a powerful tool for creating and executing business rules in JavaScript. It allows you to define rules in JSON format and evaluate them against a set of facts. This can be useful for a variety of applications, including decision-making systems, workflow automation, and more.

What are json-rules-engine's main functionalities?

Defining Rules

You can define rules using JSON format. Each rule consists of conditions and an event. The conditions specify the criteria that need to be met, and the event specifies what happens when the conditions are met.

{"rules":[{"conditions":{"all":[{"fact":"temperature","operator":"greaterThanInclusive","value":100}]},"event":{"type":"highTemperature","params":{"message":"Temperature is too high!"}}}]}

Evaluating Rules

You can evaluate rules against a set of facts. If the facts meet the conditions specified in the rules, the corresponding event will be triggered.

{"facts":{"temperature":101},"engine":{"addRule":"rule","run":"facts"}}

Combining Multiple Conditions

You can combine multiple conditions using logical operators like 'all' and 'any'. This allows you to create complex rules that evaluate multiple criteria.

{"rules":[{"conditions":{"all":[{"fact":"temperature","operator":"greaterThanInclusive","value":100},{"fact":"humidity","operator":"lessThan","value":30}]},"event":{"type":"alert","params":{"message":"High temperature and low humidity!"}}}]}

Other packages similar to json-rules-engine

nools

nools is a rules engine for JavaScript that uses a domain-specific language (DSL) for defining rules. It is more powerful and flexible than json-rules-engine but has a steeper learning curve. It is suitable for complex rule-based systems.

README

A rules engine expressed in JSON

Synopsis

json-rules-engine is a powerful, lightweight rules engine. Rules are composed of simple json structures, making them human readable and easy to persist.

Features

• Rules expressed in simple, easy to read JSON
• Full support for ALL and ANY boolean operators, including recursive nesting
• Fast by default, faster with configuration; priority levels and cache settings for fine tuning performance
• Secure; no use of eval()
• Lightweight & extendable; less than 500 lines of javascript w/few dependencies

Installation

$ npm install json-rules-engine

Documentation

It's best to start with the overview to understand the terminology. Next, see the walkthrough and try out some examples.

To dive right in, start with the basic example.

Hello World

import { Engine } from 'json-rules-engine'
import { Rule } from 'json-rules-engine'

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

/**
 * Create a rule
 */
let rule = new Rule()

// define the 'conditions' for when "hello world" should display
rule.setConditions({
  all: [{
    fact: 'displayMessage',
    operator: 'equal',
    value: true
  }]
})
// define the 'event' that will fire when the condition evaluates truthy
rule.setEvent({
  type: 'message',
  params: {
    data: 'hello-world!'
  }
})
// add rule to engine
engine.addRule(rule)

/**
 * Pass initial values into the engine.
 * Fact values do NOT need to be known at engine runtime; see the
 * examples for how to pull in data asynchronously throughout a run()
 */
let facts = { displayMessage: true }

// run the engine
engine
  .run(facts)
  .then(triggeredEvents => { // run() return events with truthy conditions
    triggeredEvents.map(event => console.log(event.params.data))
  })
  .catch(console.log)

/*
 * hello-world!
 */

Try it out!

Persisting Rules

Rules may be easily converted to JSON and persisted to a database, file system, or elsewhere. To convert a rule to JSON, simply call the rule.toJSON() method. Later, a rule may be restored by feeding the json into the Rule constructor.

// save somewhere...
let jsonString = rule.toJSON()

// ...later:
let rule = new Rule(jsonString)

Why aren't "fact" methods persistable? This is by design, for several reasons. Firstly, facts are by definition business logic bespoke to your application, and therefore lie outside the scope of this library. Secondly, many times this request indicates a design smell; try thinking of other ways to compose the rules and facts to accomplish the same objective. Finally, persisting fact methods would involve serializing javascript code, and restoring it later via eval(). If you have a strong desire for this feature, the node-rules project supports this (though be aware the capability is enabled via eval().

Debugging

To see what the engine is doing under the hood, debug output can be turned on via:

DEBUG=json-rules-engine

Changelog

1.0.4 / 2016-06-18

• fix issue #6; runtime facts unique to each run()