json-rules-engine-to-json-logic

:warning: This package is under active development: Compatibility and APIs may change.

A minimal Typescript library for converting a json-rules-engine condition to a JsonLogic rule specification.

Why? • Key Features • Installation • API • Example • Compatibility • See Also • License

Why?

From the json-rules-engine README:

json-rules-engine is a powerful, lightweight rules engine. Rules are composed of simple json structures, making them human readable and easy to persist.

Rule engines often come in handy because they allow you to:

• Express complex rules in JSON, and
• Can be evaluated securely (no use of eval)

Because of this, user defined rules can be persisted and securely evaluated on both your frontend and backend, making them ideal for scenarios when you need to allow configurable rules to be securely evaluated during runtime (e.g. an automation engine).

There are many 3rd party libraries that depend on rules engines, json-logic being one of the more popular options. As such, these libraries often expect as input, or they output a json-logic rule. This can sometimes be an issue as it might force you to adopt json-logic throughout your entire application, or it might mean you're unable to use those libraries if you choose to roll a different engine.

By providing the means to convert a json-rules-engine condition to a json-logic rule, json-rules-engine-to-json-logic allows you to take advantage of libraries that integrate with json-logic without having to adopt it across your entire application should you want to use json-rules-engine.

Key Features

• written in typescript
• zero dependencies
• minimal size: less than 1kb minified + zipped
• works with plain JavaScript too - you don't need to use TypeScript.
• small api: only two functions you need to learn
• isomorphic: works in Node.js and all modern browsers

Installation

1$ npm install json-rules-engine-to-json-logic

API

toJsonRule(condition: JsonRulesEngineCondition): JsonLogicRule

Converts a json-rules-engine condition to a json-logic rule.

1import { toJsonRule } from "json-rules-engine-to-json-logic";
2
3const jsonLogicRule = toJsonRule({
4  all: [
5    {
6      fact: "name",
7      operator: "equal",
8      value: "Harry Potter",
9    },
10  ],
11});
12
13// => { and: [{ "===": [{ var: "name" }, "Harry Potter"] }] };

CompatibilityError(message: string)

Thrown on failed conversions when the json-rules-engine condition uses functionality that can't be converted. Contains the following properties:

• name: "CompatibilityError"
• message: a string, indicating what was incompatible.

Example

1import { toJsonRule } from "json-rules-engine-to-json-logic";
2import { Engine } from "json-rules-engine";
3import jsonLogic from "json-logic-js";
4
5const facts = {
6  name: "Harry Potter",
7};
8
9const conditions = {
10  all: [
11    {
12      fact: "name",
13      operator: "equal",
14      value: "Harry Potter",
15    },
16  ],
17};
18
19// evaluate using json-rules-engine
20const engine = new Engine();
21engine.addRule({
22  conditions,
23  event: { type: "isHarry" },
24});
25const result = await engine.run(facts);
26const jsonRulesResult = result.results.length > 0;
27
28// evaluate using json-logic
29const jsonLogicRule = toJsonRule(conditions);
30const jsonLogicResult = jsonLogic.apply(jsonLogicRule, facts);
31
32// assert both return the same result
33console.assert(jsonLogicResult === jsonRulesResult);

This is available in the examples

Compatibility

Given both libraries offer different functionality, it is impossible to 100% convert between one and the other. In the case where a conversion isn't possible, a Compatibility error will be thrown, or a feature will be ignored. Current incompatibilities include:

• json-rules-engine uses json-path whereas json-logic uses dot notation. json-path is the more powerful of the two, and a lot of functionality doesn't port over. A Compatibility error will be thrown if a condition uses json-path functionality that can't be ported over to dot notation.
• json-rules-engine provides a params property that allows you to create function handlers to provide dynamic facts during run-time. This isn't possible with json-logic and is therefore ignored.

See Also

• json-rules-engine
• json-logic

License

MIT