@tringle/tri-rule

Getting started with Rule Manager

Rule manager is a utility tool for you to evaluate your javascript objects with predefined rule sets

This library is written to be used in Typescript projects

How to use

To start using this library you need to have two simple elements

1- The object which you want to evaluate

2- The rule set which you want to use

Limitations for object evaluation

There is not much of a limitation for the object structure, your object can extend in any dimension. However, currently this library only supports comparison between Numbers, Strings and Dates. You can also use IN operator to test against Arrays and Strings but you cannot compare two Arrays.

Limitations for rule set

The only limitation for the rule set is that the rules can only extend as binary trees with two nodes. It is planned to be changed in future updates to improve ease of use

How to create a rule set

To be able to create a rule set, you need to understand two things: logical rules and comparison rules.

Logical Rules

Logical rules are operations where you compare two boolean values against each other with the use of operators below:

• AND
• OR
• XOR

Logical rules can take two values where the values can be

• Logical Rule
• Comparison Rule
• Boolean

Then outputs a boolean value.

//Boolean vs Boolean
const logicalRule = {
  values: [true, false],
  operator: "AND",
}; //Outputs false

//LogicalRule vs ComparisonRule
const logicalRule = {
  values: [
    {
      values: [true, false],
      operator: "AND",
    },
    {
      values: [1, 2],
      operator: "<",
    },
  ],
  operator: "OR",
}; //Outputs true

//ComparisonRule vs ComparisonRule
const logicalRule = {
  values: [
    {
      values: [1, 2],
      operator: ">",
    },
    {
      values: [3, 4],
      operator: "<",
    },
  ],
  operator: "XOR",
}; //Outputs true

Comparison Rules

Comparison rules are operations where you compare two values agains each other with the operators below

• >
• >=
• ==
• ===
• !=
• !==
• <
• <=
• IN

Comparison rules can take two values where the values can be

• String
• Number
• Array
• Date
• Key Accessor

Note: Currently you cannot compare two array or objects with each other but you can check if array includes some other value with IN operator.

const comparisonRule = {
  values: [1, 2],
  operator: ">",
}; //Outputs false

//Searches 7 inside the Array
const comparisonRule = {
  values: [7, [1, 2, 3, 4, 5, 6, 7]],
  operator: "IN",
}; //Outputs true

//Searches "test" inside the "tstring"
const comparisonRule = {
  values: ["test", "tstring"],
  operator: "IN",
}; //Outputs false

const comparisonRule = {
  values: ["test", "test"],
  operator: "===",
}; //Outputs true

//$.abc is an example of Key Accessor
//You can learn more about them in the next part
const comparisonRule = {
  values: ["$.abc", 2],
  operator: "<",
}; //Output is dependent on abc key

//Checks if the second date is later than the first date
// You can only check two dates against each other
const date1 = new Date("2000-09-19T03:24:00");
const date2 = new Date("2000-05-25T03:24:00");

const comparisonRule = {
  values: [date1, date2],
  operator: "<",
}; //Outputs true

What is a Key Accessor?

Key accessor is a special string that is used to get a value from your object.

You can access any value from your object with key accessor. Key Accessor also supports nested objects, so you can chain as much keys as you want :D

The structure of Key Accessor goes like:

$ + .key + .key ...

Example:

const comparisonRule = {
  values: ["$.my_first_key.my_nested_key", 2],
  operator: "<",
};

When Rule Manager encounters with a Key Accessor, it replaces accessor with it's value.

It throws an error if it cannot finds the key

Available Methods

---

evaluate(object, rule)

Parameters:

• object: Any valid javascript object
• rule: Logical rule or comparison rule

Explanation: This is the core method of the library, you can evaluate one object against one rule set

Example:

const myObject = {
    foo:123,
    bar:{
        abc:[1,2,3,4,5]
    }
}

const myRule = {
    operator: "AND"
    values: [
        {
            operator:">",
            values:[
                "$.foo",100
            ]
        },
        {
            operator: "IN",
            values: [5, "$.bar.abc"]
        }
    ]
}

//This should return true
new RuleManager().evaluate(myObject,myRule)

---

evaluateArray(object, ruleArray, mode)

Parameters:

• object: Any valid javascript object
• ruleArray: Array of rules
• mode: "every" or "any"

If "every" is given then it will return false if any one of the given rules returns false

If "any" is given then it will return true if any one of the given rules returns true

Explanation: This is an utility method of the library, you can evaluate one object against multiple rule sets

Example:

const myObject = {
    foo:123,
    bar:{
        abc:[1,2,3,4,5]
    }
}

const myRule = {
    operator: "AND"
    values: [
        {
            operator:">",
            values:[
                "$.foo",100
            ]
        },
        {
            operator: "IN",
            values: [5, "$.bar.abc"]
        }
    ]
} //Returns true

const myRule2 = {
    operator: "XOR"
    values: [
        {
            operator:">",
            values:[
                "$.foo",100
            ]
        },
        {
            operator: "IN",
            values: [5, "$.bar.abc"]
        }
    ]
} //Returns false

//This should return false because the "every" mode expects all rules to be true
new RuleManager().evaluateArray(myObject,[myRule,myRule2], "every")

//This should return true because the "any" mode returns true any of the given rules is true
new RuleManager().evaluateArray(myObject,[myRule,myRule2], "any")