json-logic-js

What is json-logic-js?

The json-logic-js package allows you to apply logical operations and rules to JSON data. It is useful for creating complex conditional logic in a declarative way, making it easier to manage and understand.

What are json-logic-js's main functionalities?

Basic Logic Operations

This feature allows you to perform basic logical operations such as 'if', 'and', 'or', and comparison operators. The code sample checks if 3 is greater than 1 and returns 'yes' if true, otherwise 'no'.

{"if": [{">": [3, 1]}, "yes", "no"]}

Data Manipulation

This feature allows you to manipulate data using operations like 'map', 'reduce', and 'filter'. The code sample increments each element in the array [1, 2, 3] by 1.

{"map": [[1, 2, 3], {"+": [1, {"var": ""}]}]}

Variable Handling

This feature allows you to handle variables within your JSON logic. The code sample retrieves the value of 'user.name' from the data context.

{"var": "user.name"}

Custom Operations

This feature allows you to define custom operations. The code sample demonstrates a custom 'log' operation that logs the value of 'message'.

{"log": [{"var": "message"}]}

Other packages similar to json-logic-js

json-rules-engine

The json-rules-engine package is a rules engine that allows you to define and evaluate complex business rules in JSON format. It is more feature-rich compared to json-logic-js, offering advanced features like rule prioritization and fact validation.

json-rules-engine-simplified

The json-rules-engine-simplified package is a lightweight alternative to json-rules-engine, offering a more straightforward API for defining and evaluating rules. It is less powerful than json-rules-engine but easier to use for basic rule evaluations.

README

json-logic-js

This parser accepts JsonLogic rules and executes them in JavaScript.

The JsonLogic format is designed to allow you to share rules (logic) between front-end and back-end code (regardless of language difference), even to store logic along with a record in a database. JsonLogic is documented extensively at JsonLogic.com, including examples of every supported operation and a place to try out rules in your browser.

The same format can also be executed in PHP by the library json-logic-php

Installation

To parse JsonLogic rules in a JavaScript frontend, install this library is via Bower:

bower install --save json-logic-js

To parse JsonLogic rules in a JavaScript backend (like Node.js), install this library via NPM:

npm install json-logic-js

Note that this project uses a module loader that also makes it suitable for RequireJS projects.

If that doesn't suit you, and you want to manage updates yourself, the entire library is self-contained in logic.js and you can download it straight into your project as you see fit.

curl -O https://raw.githubusercontent.com/jwadhams/json-logic-js/master/logic.js

Examples

Simple

jsonLogic.apply( { "==" : [1, 1] } );
// true

This is a simple test, equivalent to 1 == 1. A few things about the format:

1. The operator is always in the "key" position. There is only one key per JsonLogic rule.
2. The values are typically an array.
3. Each value can be a string, number, boolean, array (non-associative), or null

Compound

Here we're beginning to nest rules.

jsonLogic.apply(
  {"and" : [
    { ">" : [3,1] },
    { "<" : [1,3] }
  ] }
);
// true

In an infix language (like JavaScript) this could be written as:

( (3 > 1) && (1 < 3) )

Data-Driven

Obviously these rules aren't very interesting if they can only take static literal data. Typically jsonLogic will be called with a rule object and a data object. You can use the var operator to get attributes of the data object:

jsonLogic.apply(
  { "var" : ["a"] }, // Rule
  { a : 1, b : 2 }   // Data
);
// 1

If you like, we support syntactic sugar on unary operators to skip the array around values:

jsonLogic.apply(
  { "var" : "a" },
  { a : 1, b : 2 }
);
// 1

You can also use the var operator to access an array by numeric index:

jsonLogic.apply(
  {"var" : 1 },
  [ "apple", "banana", "carrot" ]
);
// "banana"

Here's a complex rule that mixes literals and data. The pie isn't ready to eat unless it's cooler than 110 degrees, and filled with apples.

var rules = { "and" : [
  {"<" : [ { "var" : "temp" }, 110 ]},
  {"==" : [ { "var" : "pie.filling" }, "apple" ] }
] };

var data = { "temp" : 100, "pie" : { "filling" : "apple" } };

jsonLogic.apply(rules, data);
// true

Always and Never

Sometimes the rule you want to process is "Always" or "Never." If the first parameter passed to jsonLogic is a non-object, non-associative-array, it is returned immediately.

//Always
jsonLogic.apply(true, data_will_be_ignored);
// true

//Never
jsonLogic.apply(false, i_wasnt_even_supposed_to_be_here);
// false

Compatibility

This library makes use of Array.map and Array.reduce, so it's not exactly Internet Explorer 8 friendly.

If you want to use JsonLogic and support deprecated browsers, you could easily use BabelJS's polyfill or directly incorporate the polyfills documented on MDN for map and reduce.

Customization

It's not possible to include everyone's excellent ideas without the core library bloating, bringing in a ton of outside dependencies, or occasionally causing use case conflicts (some people need to safely execute untrusted rules, some people need to change outside state).

Check out the documentation for adding custom operations and be sure to stop by the Wiki page of custom operations to see if someone has already solved your problem or to share your solution.

Changelog

2.0.1

The operations object could be exploited to run arbitrary code. Resolves SNYK-JS-JSONLOGICJS-674308, thanks Arel Cordero for reporting.