UNPKG

5.54 kBMarkdownView Raw
1[![Build Status](https://api.travis-ci.org/mithunsatheesh/node-rules.svg?branch=master)](https://travis-ci.org/mithunsatheesh/node-rules)
2[![npm](https://img.shields.io/npm/l/express.svg?style=flat-square)]()
3[![npm version](https://badge.fury.io/js/node-rules.svg)](http://badge.fury.io/js/node-rules)
4[![Coverage Status](https://coveralls.io/repos/github/mithunsatheesh/node-rules/badge.svg?branch=master)](https://coveralls.io/github/mithunsatheesh/node-rules?branch=master)
5[![npm downloads](https://img.shields.io/npm/dm/node-rules.svg)](https://img.shields.io/npm/dm/node-rules.svg)
6[![install size](https://packagephobia.now.sh/badge?p=node-rules)](https://packagephobia.now.sh/result?p=node-rules)
7[![Known Vulnerabilities](https://snyk.io/test/npm/node-rules/badge.svg)](https://snyk.io/test/npm/node-rules)
8
9
10Node Rules
11=====
12
13Node-rules is a light weight forward chaining Rule Engine, written in JavaScript.
14
15
16#### Installation
17
18 npm install node-rules
19
20![Sample Screencast](https://raw.githubusercontent.com/mithunsatheesh/node-rules/gh-pages/images/screencast.gif "See it in action")
21
22#### Try This Out!
23
24You can see it in action in [this RunKit example](https://runkit.com/mithunsatheesh/runkit-npm-node-rules).
25
26#### Overview
27
28Node-rules takes rules written in JSON friendly format as input. Once the rule engine is running with rules registered on it, you can feed it facts and the rules will be applied one by one to generate an outcome.
29
30###### 1. Defining a Rule
31
32A rule will consist of a condition and its corresponding consequence. You can find the explanation for various mandatory and optional parameters of a rule in [this wiki](https://github.com/mithunsatheesh/node-rules/wiki/Rules).
33
34``` js
35{
36 "condition" : function(R) {
37 R.when(this.transactionTotal < 500);
38 },
39 "consequence" : function(R) {
40 this.result = false;
41 R.stop();
42 }
43}
44```
45
46Here priority is an optional parameter which will be used to specify priority of a rule over other rules when there are multiple rules running. In the above rule `R.when` evaluates the condition expression and `R.stop` used to stop further processing of the fact as we have arrived at a result.
47
48The functions `R.stop`, `R.when`, `R.next`, `R.restart` are part of the Flow Control API which allows user to control the Engine Flow. Read more about [Flow Controls](https://github.com/mithunsatheesh/node-rules/wiki/Flow-Control-API) in [wiki](https://github.com/mithunsatheesh/node-rules/wiki).
49
50
51###### 2. Defining a Fact
52Facts are those input json values on which the rule engine applies its rule to obtain results. A fact can have multiple attributes as you decide.
53
54A sample Fact may look like
55
56 {
57 "name":"user4",
58 "application":"MOB2",
59 "transactionTotal":400,
60 "cardType":"Credit Card",
61 }
62
63###### 3. Using the Rule Engine
64
65The example below shows how to use the rule engine to apply a sample rule on a specific fact. Rules can be fed into the rule engine as Array of rules or as an individual rule object.
66
67``` js
68var RuleEngine = require("node-rules");
69
70/* Creating Rule Engine instance */
71var R = new RuleEngine();
72
73/* Add a rule */
74var rule = {
75 "condition": function(R) {
76 console.log(this);
77 R.when(this.transactionTotal < 500);
78 },
79 "consequence": function(R) {
80 this.result = false;
81 this.reason = "The transaction was blocked as it was less than 500";
82 R.stop();
83 }
84};
85
86/* Register Rule */
87R.register(rule);
88
89/* Add a Fact with less than 500 as transaction, and this should be blocked */
90var fact = {
91 "name": "user4",
92 "application": "MOB2",
93 "transactionTotal": 400,
94 "cardType": "Credit Card"
95};
96
97/* Check if the engine blocks it! */
98R.execute(fact, function (data) {
99 if (data.result) {
100 console.log("Valid transaction");
101 } else {
102 console.log("Blocked Reason:" + data.reason);
103 }
104});
105```
106
107###### 4. Controlling Rules running on the Rule Engine
108If you are looking for ways to specify the order in which the rules get applied on a fact, it can be done via using the `priority` parameter. Read more about it in the [Rule wiki](https://github.com/mithunsatheesh/node-rules/wiki/Rules). If you need to know about how to change priority of rules or remove add new rules to a Running Rule Engine, you may read more about it in [Dynamic Control Wiki](https://github.com/mithunsatheesh/node-rules/wiki/Dynamic-Control).
109
110###### 5. Exporting Rules to an external storage
111To read more about storing rules running on the engine to an external DB, refer this [wiki article](https://github.com/mithunsatheesh/node-rules/wiki/Exporting-and-Importing-Rules).
112
113
114#### Wiki
115To read more about the Rule engine functions, please read [the wiki here](https://github.com/mithunsatheesh/node-rules/wiki)!. To find more examples of implementation please look in the [examples](https://github.com/mithunsatheesh/node-rules/tree/master/examples) folder.
116
117#### Issues
118Got issues with the implementation?. Feel free to open an issue [here](https://github.com/mithunsatheesh/node-rules/issues/new).
119
120#### Licence
121Node rules is distributed under the MIT License.
122
123#### External References
124* https://ieeexplore.ieee.org/document/7968566
125
126#### Credits
127The JSON friendly rule formats used in version 2.x.x of this module were initially based on the node module [jools](https://github.com/tdegrunt/jools).
128The screencast image shown in this page is taken from [nmotv.in](http://nmotw.in/node-rules/) which has a pretty nice article on how to use this module!