Nools
Nools is a rules engine for node based on the rete network.
Installation
npm install nools
Usage
To get started with nools the examples and tests are a great place to get started.
Defining a flow
When using nools you define a flow which acts as a container for rules that can later be used to get an engine session
Pragmatically
var nools = ; var { thismessage = message;}; var flow = nools;
In the above flow definition 2 rules were defined
- Hello
- Requires a Message
- The messages's message must match the regular expression "/^hello(\s*world)?$/"
- When matched the message's message is modified and then we let the engine know that we modified the message.
- Goodbye
- Requires a Message
- The messages's message must match the regular expression "/.*goodbye$/"(anything that ends in goodbye)
- When matched the resulting message is logged.
Nools DSL
You may also use the nools
rules language to define your rules
define Message {
message : '',
constructor : function(message){
this.message = message;
}
}
rule Hello {
when {
m : Message m.message =~ /^hello(\\s*world)?$/;
}
then {
modify(m, function(){this.message += " goodbye";});
}
}
rule Goodbye {
when {
m : Message m.message =~ /.*goodbye$/;
}
then {
console.log(m.message);
}
}
To use the flow
var flow = nools Message = flow;
Working with a session
A session is an instance of the flow that contains a working memory and handles the assertion, modification, and retraction of facts from the engine.
To obtain an engine session from the flow invoke the getSession method.
var session = flow;
Working with facts
Facts are items that the rules should try to match.
To add facts to the session use assert method.
session;session;session;
As a convenience any object passed into getSession will also be asserted.
flow;
To retract facts from the session use the retract method.
var m = "hello"; //assert the fact into the enginesession; //remove the fact from the enginesession;
To modify a fact use the modify method.
Note modify will not work with immutable objects (i.e. strings).
var m = "hello"; session; mmessage = "hello goodbye"; session;
assert is typically used pre engine execution and during the execution of the rules.
modify and retract are typically used during the execution of the rules.
Firing the rules
When you get a session from a flow no rules will be fired until the match method is called.
var session = flow;//assert your different messagessession;session;session; //now fire the rulessession
The match method returns a promise that is invoked once there are no more rules to activate.
Example of the promise api
session;
Disposing of the session
When working with a lot of facts it is wise to call the dispose method which will purge the current session of all facts, this will help prevent the process growing a large memory footprint.
session;
Defining rules
Rule structure
Lets look at the "Calculate" rule in the Fibonacci example
//flow.rule(type[String|Function], constraints[Array|Array[[]]], action[Function]); flow;
Or using the nools DSL
rule Calculate{
when {
f1 : Fibonacci f1.value != -1 {sequence:s1};
f2 : Fibonacci f2.value != -1 && f2.sequence == s1 + 1 {sequence:s2};
f3 : Fibonacci f3.value == -1 && f3.sequence == s2 + 1;
}
then {
modify(f3, function(){
this.value = f1.value + f2.value;
});
retract(f1);
}
}
Constraints
Constraints define what facts the rule should match. The constraint is a array of either a single constraint (i.e. Bootstrap rule) or an array of constraints(i.e. Calculate).
Prgamatically
//Type alias pattern store sequence to s1 Fibonacci "f1" "f1.value != -1" sequence:"s1" Fibonacci "f2" "f2.value != -1 && f2.sequence == s1 + 1" sequence:"s2" Fibonacci "f3" "f3.value == -1 && f3.sequence == s2 + 1" Result "r"
Using nools DSL
when {
f1 : Fibonacci f1.value != -1 {sequence:s1};
f2 : Fibonacci f2.value != -1 && f2.sequence == s1 + 1 {sequence:s2};
f3 : Fibonacci f3.value == -1 && f3.sequence == s2 + 1;
}
-
Type - is the Object type the rule should match. The available types are
String
- "string", "String", StringNumber
- "number", "Number", NumberBoolean
- "boolean", "Boolean", BooleanDate
- "date", "Date", DateRegExp
- "regexp", "RegExp", RegExpArray
- "array", "Array", [], ArrayObject
- "object", "Object", "hash", Object- Custom - any custom type that you define
-
Alias - the name the object should be represented as.
-
Pattern(optional) - The pattern that should evaluate to a boolean, the alias that was used should be used to reference the object in the pattern. Strings should be in single quotes, regular expressions are allowed. Any previously define alias/reference can be used within the pattern. Available operators are.
&&
,AND
,and
||
,OR
,or
>
,<
,>=
,<=
,gt
,lt
,gte
,lte
==
,!=
,=~
,eq
,neq
,like
+
,-
,*
,/
-
(unary minus).
(member operator)in
(check inclusion in an array)- Defined helper functions
now
- the current dateDate(year?, month?, day?, hour?, minute?, second?, ms?)
- creates a newDate
objectlengthOf(arr, length)
- checks the length of an arrayisTrue(something)
- check if something === trueisFalse(something)
- check if something === falseisRegExp(something)
- check if something is aRegExp
isArray(something)
- check if something is anArray
isNumber(something)
- check if something is anNumber
isHash(something)
- check if something is strictly anObject
isObject(something)
- check if something is any type ofObject
isDate(something)
- check if something is aDate
isBoolean(something)
- check if something is aBoolean
isString(something)
- check if something is aString
isUndefined(something)
- check if something is aundefined
isDefined(something)
- check if something isDefined
isUndefinedOrNull(something)
- check if something is aundefined
ornull
isPromiseLike(something)
- check if something is a "promise" like (containingthen
,addCallback
,addErrback
)isFunction(something)
- check if something is aFunction
isNull(something)
- check if something isnull
isNotNull(something)
- check if something is not nulldateCmp(dt1, dt2)
- compares two dates return 1, -1, or 0years|months|days|hours|minutes|seconds``Ago
/FromNow``(interval)
- adds/subtracts the date unit from the current time
-
Reference(optional) - An object where the keys are properties on the current object, and values are aliases to use. The alias may be used in succeeding patterns.
Action
The action is a function that should be fired when all patterns in the rule match. The action is called in the scope of the engine so you can use this to assert, modify, or retract facts. An object containing all facts and references created by the alpha nodes is passed in as the first argument to the action.
So calculate's action modifies f3 by adding the value of f1 and f2 together and modifies f3 and retracts f1.
{ var f3 = factsf3 f1 = factsf1 f2 = factsf2; var v = f3value = f1value + factsf2value; factsrresult = v; this; this; }
The engine is also passed in as a second argument so alternatively you could do the following.
{ var f3 = factsf3 f1 = factsf1 f2 = factsf2; var v = f3value = f1value + factsf2value; factsrresult = v; engine; engine; }
If you have an async action that needs to take place an optional third argument can be passed in which is a function to be called when the action is completed.
{ //some async action process }
If any arguments are passed into next it is assumed there was an error and the session will error out.
To define the action with the nools DSL
then {
modify(f3, function(){
this.value = f1.value + f2.value;
});
retract(f1);
}
For rules defined using the rules language nools will automatically determine what parameters need to be passed in based on what is referenced in the action.
Examples
Fibonacci
"use strict"; var nools = ; var { thissequence = sequence; thisvalue = value || -1;}; var { thisresult = result || -1;}; var flow = nools; var r1 = session1 = flow s1 = ;session1; var r2 = session2 = flow s2 = ;session2; var r3 = session3 = flow s3 = ;session3;
Output
55 [43ms]
9.969216677189305e+30 [383ms]
4.346655768693743e+208 [3580ms]
Fiboncci with nools DSL
//Define our object classes, you can
//also declare these outside of the nools
//file by passing them into the compile method
define Fibonacci {
value:-1,
sequence:null
}
define Result {
value : -1
}
rule Recurse {
priority:1,
when {
//you can use not or or methods in here
not(f : Fibonacci f.sequence == 1);
//f1 is how you can reference the fact else where
f1 : Fibonacci f1.sequence != 1;
}
then {
assert(new Fibonacci({sequence : f1.sequence - 1}));
}
}
rule Bootstrap {
when {
f : Fibonacci f.value == -1 && (f.sequence == 1 || f.sequence == 2);
}
then{
modify(f, function(){
this.value = 1;
});
}
}
rule Calculate {
when {
f1 : Fibonacci f1.value != -1 {sequence : s1};
//here we define constraints along with a hash so you can reference sequence
//as s2 else where
f2 : Fibonacci f2.value != -1 && f2.sequence == s1 + 1 {sequence:s2};
f3 : Fibonacci f3.value == -1 && f3.sequence == s2 + 1;
r : Result
}
then {
modify(f3, function(){
this.value = r.result = f1.value + f2.value;
});
retract(f1);
}
}
And to run
var flow = nools; var Fibonacci = flow Result = flow;var r1 = session1 = flow s1 = +;session1; var r2 = session2 = flow s2 = +;session2; var r3 = session3 = flow s3 = +;session3;
License
MIT https://github.com/C2FO/nools/raw/master/LICENSE
Meta
- Code:
git clone git://github.com/C2FO/nools.git