json-policy

Evaluates expressions/policies that are based on the JSON format. It allows mathematical expressions, conditional operators, and custom operators of your own doing.

Installing

Install using npm

npm i --save json-policy 

Usage

evaluate({expression}, {attributes}, {custom operator definitions}) Substitutes attributes (when specified) to the given expression and returns the result. The result is not bound to a pure boolean value but a truthy or falsey. It could return a string.

{expression} has the following format:

{
	"<operator>" : [ ...<args> ],
	...
}

{attributes} is simply a regular json object that is used to substitute variables in the expression

{custom operator definitions } is an optional parameter for you to define your own set of operators. It has the following format:

{
	"not" : function(arg) {
		return !arg;	
	}
}

Default operators

| Operator | Description | | |-----------|:------------:|:---:| | not(value) | Logical not. | NOT value | | and(arg1, arg2) | Logical and. | arg1 AND arg2 | | or(arg1, arg2) | Logical not. | arg1 OR arg2 | | xor(arg1, arg2) | Logical exclusive or. | arg1 XOR arg2 | | or(arg1, arg2) | Logical not. | arg1 OR arg2 | | mand(arg1, arg2, ... argN) | Multiple logical and. | arg1 AND arg2 AND ... AND argN | | mor(arg1, arg2, ... argN) | Multiple logical or. | arg1 OR arg2 OR ... OR argN | | neq(arg1, arg2) | Not equal. | arg1 <> arg2 | | lt(arg1, arg2) | Less than. | arg1 < arg2 | | lte(arg1, arg2) | Less than or equal to. | arg1 <= arg2 | | eq(arg1, arg2) | Equal to. | arg1 == arg2| | gte(arg1, arg2) | Greater than or equal to. | arg1 >= arg2 | | gt(arg1, arg2) | Greater than. | arg1 > arg2 | | any(item, ...args) | Returns true if item matches with any of the values of the rest of the arguments. | | plus(arg1, arg2) | Mathematical addition or concatenate operator depending on the argument datatypes. arg1 + arg2 | | minus(arg1, arg2) | Mathematical subtraction. | arg1 - arg2 | | times(arg1, arg2) | Mathematical multiplication. | arg1 x arg2 | | divideby(arg1, arg2) | Mathematical division. | arg1 / arg2 | | modulo(arg1, arg2) | Mathematical modulo. | arg1 % arg2 | | power(arg1, arg2) | Mathematical power function. | arg1 ^ arg2 | | ifelse(condition, true_arg, false_arg) | If else conditional operator. | if (condition) then true_arg else false_arg | | print(string) | Prints a string to the console and also returns the printed string. | print("Hello, world!") | | echo(string) | Simply returns the inputted. | string.echo("Hello, world!") // Returns "Hello, world!" |

Examples

var JSONPolicy = require("json-policy");

var jsonPolicy = new JSONPolicy();

//
// Evaluate mathematical expressions
//
jsonPolicy.evaluate({ "plus" : [1, 2] });    // Equal to 3

//
// Evaluate boolean expressions
//
jsonPolicy.evaluate({ 
  "and" : [
    {"not" : {"eq" : [5, 1]}},
    {"neq" : [5, 1]},
    {"eq" : [1, 1]}
]});    // Equal to true

//
// Value substitution
//
jsonPolicy.evaluate({"gt" : [25, "$a"]}, { a : 18});    // Equal to true

//
// Property access
//
jsonPolicy.evaluate({"gt" : [25, "$user.age"]}, { user : { age : 18}});   // Equal to true

//
// Sample application for evaluating policies
//
jsonPolicy.evaluate({
  "and" : [ 
    {"eq" : ["$resource.sensitivity", "classified"]},
    {"or" : [
      {"eq" : ["$user.clearance", "topsecret"]},
      {"eq" : ["$user.clearance", "secret"]},
      {"eq" : ["$user.clearance", "classified"]},
    ]}
  ]}, { 
    resource : {
      sensitivity : "classified"
    },
    user : {
      clearance : "topsecret"
  }
});         // Equal to true

Custom operators

var operations = {
	"!" : function(arg) {
		return !arg;	
	},
	"&&" : function() {
		var result = true; 
		for (var i = 0; i < arguments.length; i++) {
			result = result && arguments[i];
		}

		return result;	
	},
	"||" : function() {
		var result = false; 
		for (var i = 0; i < arguments.length; i++) {
			result = result || arguments[i];
		}

		return result;	
};

jsonPolicy.evaluate({ 
  "and" : [
    {"!" : {"eq" : [5, 1]}},
    {"&&" : [5, 1]},
    {"||" : [1, 1]}
]}, {}, operators); 

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Building and Testing

Make use of grunt.

To build, perform the command below. The output will be in the build directory.

grunt build

To run the test fixtures:

grunt test

License

This project is licensed under the MIT License - see the LICENSE.md file for details