rules-engine-ts

Strongly typed rules engine for evaluating deep and complex rules.

About
Terminology
Basic Usage
UI Implementation Example
Installation
Usage
Rules Specification
TypeScript Usage
Authors

About

Rules Engine TS is a strongly typed rules engine for evaluating deep and complex rules. With the power of Typescript you can create type safe rules that are easy to read and maintain.

Terminology

Rule

A rule is a single condition that can be evaluated. A rule can be of the following types:

string
number
boolean
array_value
array_length
object_key
object_value
object_key_value
generic_comparison
generic_type

Depending on the type, certain operators are available. For example, the string type has the following operators:

equals_to
does_not_equal_to
contains
not_contains
starts_with
ends_with

Refer to the Rules Specification section for more information on the available properties.

Union

A union is a collection of rules and/or other unions. A union can have a connector of and or or. If the connector is and then all rules and unions must evaluate to true. If the connector is or then only one rule or union must evaluate to true.

Root Union

The root union is the top level union. It contains the same properties of a regular union but does not have a parent_id property.

Parent

The parent of a rule or union is the union that contains it. Any rule or union can be linked back to its parent with its parent_id property. The parent union should contain the rule or union in its rules array.

Basic Usage

The recommended way to consume rules-engine-ts is in a TypeScript environment. TypeScript will warn you when your rules are missing properties or if the types of your properties are incorrect. That isn't to say that rules-engine-ts can't be run with JavaScript. You will still get autocomplete on the available properties, but you will not get any warnings if you are missing properties or if the types of your properties are incorrect.

A rules engine can be configured and run like so:

import { addRuleToUnion, addRulesToUnion, addUnionToUnion, createRoot, run } from 'rules-engine-ts';

// Create root union
const root = createRoot({ connector: 'and' });

// Add a rule to the root union
addRuleToUnion(root, { type: 'number', field: 'age', operator: 'greater_than', value: 18 });

// Add a union to the root union (creates a nested ruleset)
const union = addUnionToUnion(root, { connector: 'or' });

// Add nested rules to the nested union
addRulesToUnion(union, [
  { type: 'string', field: 'name', value: 'bob', operator: 'equals_to', ignore_case: true },
  { type: 'string', field: 'name', value: 'alice', operator: 'equals_to', ignore_case: true },
]);

// Run the rules engine
const pass = run(root, { age: 19, name: 'Bob' });
const fail = run(root, { age: 19, name: 'Carol' });

console.log(pass); // true
console.log(fail); // false

This is what the state of the Rule Engine looks like:

{
  "entity": "root_union",
  "id": "0d7428af-10e4-481b-84a7-056946bd4f12",
  "connector": "and",
  "rules": [
    {
      "entity": "rule",
      "id": "82e96b0d-886e-4a2e-bf8c-f81b02ef11ce",
      "parent_id": "0d7428af-10e4-481b-84a7-056946bd4f12",
      "type": "number",
      "field": "age",
      "operator": "greater_than",
      "value": 18
    },
    {
      "entity": "union",
      "id": "7c493486-409b-48df-bd66-7f4a16500c5e",
      "parent_id": "0d7428af-10e4-481b-84a7-056946bd4f12",
      "connector": "or",
      "rules": [
        {
          "entity": "rule",
          "id": "3abc4e64-d6c8-4303-9d07-b573a571f19a",
          "parent_id": "7c493486-409b-48df-bd66-7f4a16500c5e",
          "type": "string",
          "field": "name",
          "operator": "equals_to",
          "value": "bob",
          "ignore_case": true
        },
        {
          "entity": "rule",
          "id": "a3995445-55ca-49b2-8381-3d6758750413",
          "parent_id": "7c493486-409b-48df-bd66-7f4a16500c5e",
          "type": "string",
          "field": "name",
          "operator": "equals_to",
          "value": "alice",
          "ignore_case": true
        }
      ]
    }
  ]
}

UI Implementation Example

The rules can then be persisted into a database in JSON format:

{
  "entity": "root_union",
  "id": "598444ae-032c-4ae5-85da-644cf90ab920",
  "connector": "or",
  "rules": [
    {
      "entity": "rule",
      "id": "03fcb9b5-a3fe-4d63-97f3-dfce431c331d",
      "parent_id": "598444ae-032c-4ae5-85da-644cf90ab920",
      "type": "string",
      "field": "user_display_name",
      "operator": "equals_to",
      "value": "Alice",
      "ignore_case": true
    },
    {
      "id": "d60639aa-8239-40c7-9cc3-ec89f8f8c58d",
      "entity": "union",
      "connector": "and",
      "parent_id": "598444ae-032c-4ae5-85da-644cf90ab920",
      "rules": [
        {
          "entity": "rule",
          "id": "1821d9da-9f37-4689-a118-bf436ca37e89",
          "parent_id": "d60639aa-8239-40c7-9cc3-ec89f8f8c58d",
          "type": "string",
          "field": "user_display_name",
          "operator": "equals_to",
          "value": "Bob",
          "ignore_case": true
        },
        {
          "entity": "rule",
          "id": "c2a058ab-6005-44a4-94ae-b75736dce536",
          "parent_id": "d60639aa-8239-40c7-9cc3-ec89f8f8c58d",
          "type": "number",
          "field": "total_challenges",
          "operator": "greater_than_or_equal_to",
          "value": 5
        }
      ]
    }
  ]
}

At a later date, the rules can retrieved from the database and can be run by the rules engine like this:

import { run } from 'rules-engine-ts';

const rules = getRulesFromDatabase();

const pass = run(rules, { user_display_name: 'alice', total_challenges: 0 });
const fail = run(rules, { user_display_name: 'bob', total_challenges: 0 });

if (pass) {
  // do something
}

if (fail) {
  //do somehting else
}

Installation

Install the package using your favorite package manager:

npm install rules-engine-ts
yarn add rules-engine-ts
pnpm add rules-engine-ts

Usage

`createRoot(connector: 'and' | 'or'): RootUnion`

Creates a root union. This is the entry point for creating a rules engine.

import { createRoot } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });

State of the Rules Engine:

{
  "entity": "root_union",
  "id": "0d7428af-10e4-481b-84a7-056946bd4f12",
  "connector": "and",
  "rules": []
}

`addRuleToUnion(parent: RootUnion | Union, newRule: NewRule): Rule`

Adds a rule to a union or root union. The rules engine assigns a unique ID and automatically tags it with a parent_id. Returns the rule that was added.

import { addRuleToUnion, createRoot } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });

addRuleToUnion(root, { type: 'number', field: 'age', operator: 'greater_than', value: 18 });

State of the Rules Engine:

{
  "entity": "root_union",
  "id": "0d7428af-10e4-481b-84a7-056946bd4f12",
  "connector": "and",
  "rules": [
    {
      "entity": "rule",
      "id": "82e96b0d-886e-4a2e-bf8c-f81b02ef11ce",
      "parent_id": "0d7428af-10e4-481b-84a7-056946bd4f12",
      "type": "number",
      "field": "age",
      "operator": "greater_than",
      "value": 18
    }
  ]
}

`addRulesToUnion(parent: RootUnion | Union, newRules: NewRule[]): Rule[]`

Adds many rules to a union or root union. The rules engine assigns a unique ID and automatically tags it with a parent_id. Returns the list of rules that were added.

import { addRulesToUnion, createRoot } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });

addRulesToUnion(root, [
  { type: 'string', field: 'name', value: 'bob', operator: 'equals_to', ignore_case: true },
  { type: 'string', field: 'name', value: 'alice', operator: 'equals_to', ignore_case: true },
]);

State of the Rules Engine:

{
  "entity": "root_union",
  "id": "61dadd25-22a0-4e84-abe5-92fcfd6cac9e",
  "connector": "and",
  "rules": [
    {
      "entity": "rule",
      "id": "50158f7e-1d87-4ca8-aaca-ef1bbb41c9c2",
      "parent_id": "61dadd25-22a0-4e84-abe5-92fcfd6cac9e",
      "type": "string",
      "field": "name",
      "operator": "equals_to",
      "value": "bob",
      "ignore_case": true
    },
    {
      "entity": "rule",
      "id": "5f6ac1d1-7ce7-40a5-a94c-5e4a47a45e28",
      "parent_id": "61dadd25-22a0-4e84-abe5-92fcfd6cac9e",
      "type": "string",
      "field": "name",
      "operator": "equals_to",
      "value": "alice",
      "ignore_case": true
    }
  ]
}

`addUnionToUnion(parent: RootUnion | Union, newUnion: NewUnion): Union`

Adds a union to an existing union or root union. Returns the rule that was added.

import { addRuleToUnion, addRulesToUnion, addUnionToUnion, createRoot } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });

const union = addUnionToUnion(root, { connector: 'or' });
addRuleToUnion(union, { type: 'string', field: 'name', value: 'bob', operator: 'equals_to', ignore_case: true });
addRuleToUnion(union, { type: 'string', field: 'name', value: 'alice', operator: 'equals_to', ignore_case: true });

State of the Rules Engine:

{
  "entity": "root_union",
  "id": "0d7428af-10e4-481b-84a7-056946bd4f12",
  "connector": "and",
  "rules": [
    {
      "entity": "union",
      "id": "7c493486-409b-48df-bd66-7f4a16500c5e",
      "parent_id": "0d7428af-10e4-481b-84a7-056946bd4f12",
      "connector": "or",
      "rules": [
        {
          "entity": "rule",
          "id": "3abc4e64-d6c8-4303-9d07-b573a571f19a",
          "parent_id": "7c493486-409b-48df-bd66-7f4a16500c5e",
          "type": "string",
          "field": "name",
          "operator": "equals_to",
          "value": "bob",
          "ignore_case": true
        },
        {
          "entity": "rule",
          "id": "a3995445-55ca-49b2-8381-3d6758750413",
          "parent_id": "7c493486-409b-48df-bd66-7f4a16500c5e",
          "type": "string",
          "field": "name",
          "operator": "equals_to",
          "value": "alice",
          "ignore_case": true
        }
      ]
    }
  ]
}

`addUnionsToUnion(parent: RootUnion | Union, newUnions: NewUnion[]): Union[]`

Adds many unions to an existing union or root union. Returns the list of unions that were added.

import { addRulesToUnion, addUnionsToUnion, createRoot } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });

const unions = addUnionsToUnion(root, [{ connector: 'or' }, { connector: 'or' }]);
addRulesToUnion(unions[0], [
  { type: 'string', field: 'name', value: 'bob', operator: 'equals_to', ignore_case: true },
  { type: 'string', field: 'name', value: 'alice', operator: 'equals_to', ignore_case: true },
]);
addRulesToUnion(unions[1], [
  { type: 'number', field: 'age', value: 18, operator: 'equals_to' },
  { type: 'number', field: 'age', value: 21, operator: 'equals_to' },
]);

State of the Rules Engine:

{
  "entity": "root_union",
  "id": "28a9ae06-594a-4520-8d73-2fd871804634",
  "connector": "and",
  "rules": [
    {
      "entity": "union",
      "id": "8e5e66dd-e86c-4f9e-acc7-7baa852fdfe8",
      "parent_id": "28a9ae06-594a-4520-8d73-2fd871804634",
      "connector": "or",
      "rules": [
        {
          "entity": "rule",
          "id": "a8ecbafd-0a1a-4e9e-bb70-8bd11a62f274",
          "parent_id": "8e5e66dd-e86c-4f9e-acc7-7baa852fdfe8",
          "type": "string",
          "field": "name",
          "operator": "equals_to",
          "value": "bob",
          "ignore_case": true
        },
        {
          "entity": "rule",
          "id": "d4fd56bf-af82-4382-a1cb-93d80cb87ef4",
          "parent_id": "8e5e66dd-e86c-4f9e-acc7-7baa852fdfe8",
          "type": "string",
          "field": "name",
          "operator": "equals_to",
          "value": "alice",
          "ignore_case": true
        }
      ]
    },
    {
      "entity": "union",
      "id": "5e5d7f00-d0f6-40d9-84b3-39600241a92f",
      "parent_id": "28a9ae06-594a-4520-8d73-2fd871804634",
      "connector": "or",
      "rules": [
        {
          "entity": "rule",
          "id": "7ea03690-d9c4-4a3e-97eb-d927cf6845e8",
          "parent_id": "5e5d7f00-d0f6-40d9-84b3-39600241a92f",
          "type": "number",
          "field": "age",
          "operator": "equals_to",
          "value": 18
        },
        {
          "entity": "rule",
          "id": "bb63d7da-b0dc-4d00-824c-4de09151c609",
          "parent_id": "5e5d7f00-d0f6-40d9-84b3-39600241a92f",
          "type": "number",
          "field": "age",
          "operator": "equals_to",
          "value": 21
        }
      ]
    }
  ]
}

`addAnyToUnion(parent: RootUnion | Union, newRuleOrUnion: NewRule | NewUnion): Rule | Union`

Adds a rule or a union to an existing union or root union. Returns the rule or union that was added.

import { addAnyToUnion, createRoot } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });

const any = addAnyToUnion(root, { connector: 'or' });
if (any.entity === 'union') {
  addAnyToUnion(any, { type: 'string', field: 'name', value: 'bob', operator: 'equals_to', ignore_case: true });
  addAnyToUnion(any, { type: 'string', field: 'name', value: 'alice', operator: 'equals_to', ignore_case: true });
}

State of the Rules Engine:

{
  "entity": "root_union",
  "id": "825ef3d8-3151-4367-b751-1deae8b308c1",
  "connector": "and",
  "rules": [
    {
      "entity": "union",
      "id": "71b5296a-5358-4399-878d-f535c9f21faf",
      "parent_id": "825ef3d8-3151-4367-b751-1deae8b308c1",
      "connector": "or",
      "rules": [
        {
          "entity": "rule",
          "id": "3cd0463f-c5e7-4dd9-98b8-9e7cf79417b5",
          "parent_id": "71b5296a-5358-4399-878d-f535c9f21faf",
          "type": "string",
          "field": "name",
          "operator": "equals_to",
          "value": "bob",
          "ignore_case": true
        },
        {
          "entity": "rule",
          "id": "f10e7cec-c737-4c2c-b137-d7ab0e26e045",
          "parent_id": "71b5296a-5358-4399-878d-f535c9f21faf",
          "type": "string",
          "field": "name",
          "operator": "equals_to",
          "value": "alice",
          "ignore_case": true
        }
      ]
    }
  ]
}

`addManyToUnion(parent: RootUnion | Union, newRulesOrUnions: (NewRule | NewUnion)[]): (Rule | Union)[]`

Adds many rules or unions to an existing union or root union. Returns the list of rules or unions that were added.

import { addManyToUnion, createRoot } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });

addManyToUnion(root, [
  { type: 'string', field: 'name', value: 'bob', operator: 'equals_to', ignore_case: true },
  { type: 'string', field: 'name', value: 'alice', operator: 'equals_to', ignore_case: true },
  { connector: 'or' },
]);

State of the Rules Engine:

{
  "entity": "root_union",
  "id": "26252c95-37da-47d4-b361-7ad82ae13a9b",
  "connector": "and",
  "rules": [
    {
      "entity": "rule",
      "id": "edbf5239-e931-480a-b231-119af2c1a1d1",
      "parent_id": "26252c95-37da-47d4-b361-7ad82ae13a9b",
      "type": "string",
      "field": "name",
      "operator": "equals_to",
      "value": "bob",
      "ignore_case": true
    },
    {
      "entity": "rule",
      "id": "1e9109fa-30cf-41a9-9e78-e8395a423d6d",
      "parent_id": "26252c95-37da-47d4-b361-7ad82ae13a9b",
      "type": "string",
      "field": "name",
      "operator": "equals_to",
      "value": "alice",
      "ignore_case": true
    },
    {
      "entity": "union",
      "id": "0bb57d03-ac07-41af-941a-6a2625bac130",
      "parent_id": "26252c95-37da-47d4-b361-7ad82ae13a9b",
      "connector": "or",
      "rules": []
    }
  ]
}

`run(union: RootUnion | Union, value: any): boolean`

Evaluates a set of rules against a value. The value can be of any type (object, array, string, number, boolean, etc). Returns a boolean indicating whether the value passes the rules.

import { addRuleToUnion, addRulesToUnion, addUnionToUnion, createRoot, run } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });
addRuleToUnion(root, { type: 'number', field: 'age', operator: 'greater_than', value: 18 });

const union = addUnionToUnion(root, { connector: 'or' });
addRulesToUnion(union, [
  { type: 'string', field: 'name', value: 'bob', operator: 'equals_to', ignore_case: true },
  { type: 'string', field: 'name', value: 'alice', operator: 'equals_to', ignore_case: true },
]);

const pass = run(root, { age: 19, name: 'Bob' });
const fail = run(root, { age: 19, name: 'Carol' });

console.log(pass); // true
console.log(fail); // false

`findAnyById(union: RootUnion | Union, id: string): RootUnion | Union | Rule | undefined`

Finds any rule or union by id. Returns the rule or union if found, otherwise returns undefined.

import { addRuleToUnion, addUnionToUnion, createRoot, findAnyById } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });
const rule = addRuleToUnion(root, { type: 'number', field: 'age', operator: 'greater_than', value: 18 });
const union = addUnionToUnion(root, { connector: 'or' });

const foundRule = findAnyById(root, rule.id);
console.log(foundRule === rule); // true

const foundUnion = findAnyById(root, union.id);
console.log(foundUnion === union); // true

`findRuleById(union: RootUnion | Union, id: string): Rule | undefined`

Finds a rule by id. Returns the rule if found, otherwise returns undefined.

import { addRuleToUnion, addUnionToUnion, createRoot, findRuleById } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });
const rule = addRuleToUnion(root, { type: 'number', field: 'age', operator: 'greater_than', value: 18 });
const union = addUnionToUnion(root, { connector: 'or' });

const foundRule = findRuleById(root, rule.id);
console.log(foundRule === rule); // true

const foundUnion = findRuleById(root, union.id);
console.log(foundUnion); // undefined

`findUnionById(union: RootUnion | Union, id: string): RootUnion | Union | undefined`

Finds a union by id. Returns the union if found, otherwise returns undefined.

import { addRuleToUnion, addUnionToUnion, createRoot, findUnionById } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });
const rule = addRuleToUnion(root, { type: 'number', field: 'age', operator: 'greater_than', value: 18 });
const union = addUnionToUnion(root, { connector: 'or' });

const foundUnion = findUnionById(root, union.id);
console.log(foundUnion === union); // true;

const foundRule = findUnionById(root, rule.id);
console.log(foundRule); // undefined;

`validate(root: RootUnion): { isValid: true } | { isValid: false; reason: string }`

Validates the structure of a ruleset. Returns an object with a boolean indicating whether the ruleset is valid, and a reason if the ruleset is invalid.

import { addRuleToUnion, createRoot, validate } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });
const rule = addRuleToUnion(root, { type: 'number', field: 'age', operator: 'greater_than', value: 18 });

console.log(validate(root));
// { isValid: true }

rule.type = 'string';

console.log(validate(root));
// {
//   isValid: false,
//   reason: 'Code: invalid_union ~ Path: rules[0] ~ Message: Invalid input'
// }

`normalize<T extends Union | RootUnion>(union: T, options?: Options): T`

Normalization is a process that ensures that the ruleset is in a consistent state. It performs the following updates recursively in the following order:

Removes any rules or unions that do not conform to the type system. options.remove_failed_validations
Removes any unions without any rules. options.remove_empty_unions
Converts any union with a single rule to a rule. options.promote_single_rule_unions
Updates all parent ids to match the parent union options.update_parent_ids

All these updates are turned on by default. You can disable them by passing in an options object as the second argument with the corresponding properties set to false.

import { addRuleToUnion, addUnionToUnion, createRoot, normalize } from 'rules-engine-ts';

import { v4 as uuidv4 } from 'uuid';

const root = createRoot({ connector: 'or' });

const rule1 = addRuleToUnion(root, { field: 'name', operator: 'contains', type: 'string', value: 'bob' });
const union = addUnionToUnion(root, { connector: 'and' });
const rule2 = addRuleToUnion(union, { field: 'name', operator: 'contains', type: 'string', value: 'alice' });

rule1.parent_id = uuidv4();
rule2.type = 'number';
// @ts-expect-error
union.connector = 'invalid';

console.log(root); // Before normalization
normalize(root, {
  // Normalization options (optional)
  promote_single_rule_unions: true,
  remove_empty_unions: true,
  remove_failed_validations: true,
  update_parent_ids: true,
});
console.log(root); // After normalization

Before normalization:

{
  "entity": "root_union",
  "id": "70cf2539-b960-4831-b0f2-3b201aea550a",
  "connector": "or",
  "rules": [
    {
      "entity": "rule",
      "id": "4b644371-6bc2-46b1-b855-c2098df80fb3",
      "parent_id": "8ca677c2-b01c-4cf2-91ec-9c95b6ff7dff",
      "type": "string",
      "field": "name",
      "operator": "contains",
      "value": "bob"
    },
    {
      "entity": "union",
      "id": "c43e8705-6b4b-42b5-941c-3295c17cf5db",
      "parent_id": "70cf2539-b960-4831-b0f2-3b201aea550a",
      "connector": "invalid",
      "rules": [
        {
          "entity": "rule",
          "id": "8589e28c-a1d5-4a0b-b930-24c5931eaadb",
          "parent_id": "c43e8705-6b4b-42b5-941c-3295c17cf5db",
          "type": "number",
          "field": "name",
          "operator": "contains",
          "value": "alice"
        }
      ]
    }
  ]
}

After normalization:

{
  "entity": "root_union",
  "id": "70cf2539-b960-4831-b0f2-3b201aea550a",
  "connector": "or",
  "rules": [
    {
      "entity": "rule",
      "id": "4b644371-6bc2-46b1-b855-c2098df80fb3",
      "parent_id": "70cf2539-b960-4831-b0f2-3b201aea550a",
      "type": "string",
      "field": "name",
      "operator": "contains",
      "value": "bob"
    }
  ]
}

`updateRuleById(root: RootUnion, id: string, values: NewRule): Rule | undefined`

Updates a rule by id. Returns the updated rule if found, otherwise returns undefined.

import { addRuleToUnion, createRoot, updateRuleById } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });
const rule = addRuleToUnion(root, { type: 'number', field: 'age', operator: 'greater_than', value: 18 });

console.log(root.rules[0]); // Before update
updateRuleById(root, rule.id, { type: 'number', field: 'age', operator: 'less_than', value: 30 });
console.log(root.rules[0]); // After update

Before update:

{
  "entity": "rule",
  "id": "cc3d4bab-783a-4683-a223-8dee979b0bf0",
  "parent_id": "e0da0708-1fbf-4e64-887c-d7684b17dd00",
  "type": "number",
  "field": "age",
  "operator": "greater_than",
  "value": 18
}

After update:

{
  "entity": "rule",
  "id": "cc3d4bab-783a-4683-a223-8dee979b0bf0",
  "parent_id": "e0da0708-1fbf-4e64-887c-d7684b17dd00",
  "type": "number",
  "field": "age",
  "operator": "less_than",
  "value": 30
}

`updateUnionById(root: RootUnion, id: string, values: NewUnion): Union | RootUnion | undefined`

Updates a union by id. Returns the updated union if found, otherwise returns undefined.

import { addUnionToUnion, createRoot, updateUnionById } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });
const union = addUnionToUnion(root, { connector: 'and' });

console.log(root.rules[0]); // Before update
updateUnionById(root, union.id, { connector: 'or' });
console.log(root.rules[0]); // After update

Before update:

{
  "entity": "union",
  "id": "b0a289a5-f02e-4bb4-bbbf-d148d1fc570f",
  "parent_id": "1ac8dad7-46c0-430b-9ad1-fdb8f1fd721a",
  "connector": "and",
  "rules": []
}

After update:

{
  "entity": "union",
  "id": "b0a289a5-f02e-4bb4-bbbf-d148d1fc570f",
  "parent_id": "1ac8dad7-46c0-430b-9ad1-fdb8f1fd721a",
  "connector": "or",
  "rules": []
}

`removeAllById<T extends RootUnion | Union>(union: T, id: string): T`

Removes all rules and unions of a given id from a ruleset. Returns the updated ruleset.

import { addRuleToUnion, addUnionToUnion, createRoot, removeAllById } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });
const union = addUnionToUnion(root, { connector: 'or' });
const rule = addRuleToUnion(union, { type: 'number', field: 'age', operator: 'greater_than', value: 18 });

console.log(union.rules.length); // 1
removeAllById(root, rule.id);
console.log(union.rules.length); // 0

Rules Specification

The properties of a rule change depending on the type field. The type field acts as a discriminator to determine which properties are valid for a given rule.

type = 'string'

Property	Value	Description
type	'string'	The type of the value to be evaluated.
field	string	The field to check. Supports nested properties, e.g. `users.admins[0].name`.
operator	'equals_to' 'does_not_equal_to' 'contains' 'does_not_contain' 'starts_with' 'ends_with'	The operator to use.
value	string	The value to compare against.
ignore_case	boolean	Whether to ignore case when comparing strings.

type = 'number'

Property	Value	Description
type	'number'	The type of the value to be evaluated.
field	string	The field to check. Supports nested properties, e.g. `users.admins[0].age`.
operator	'equals_to' 'does_not_equal_to' 'greater_than' 'greater_than_or_equal_to' 'less_than' 'less_than_or_equal_to'	The operator to use.
value	number	The value to compare against.

type = 'boolean'

Property	Value	Description
type	'boolean'	The type of the value to be evaluated.
field	string	The field to check. Supports nested properties, e.g. `users.admins[0].is_active`.
operator	'is_true' 'is_false'	The operator to use.

type = 'array_value'

Property	Value	Description
type	'array_value'	The type of the value to be evaluated.
field	string	The field to check. Supports nested properties, e.g. `users.admins`.
operator	'contains' 'does_not_contain' 'contains_all'	The operator to use.
value	any	The value to compare against.

type = 'array_length'

Property	Value	Description
type	'array_length'	The type of the value to be evaluated.
field	string	The field to check. Supports nested properties, e.g. `users.admins`.
operator	'equals_to' 'does_not_equal_to' 'greater_than' 'greater_than_or_equal_to' 'less_than' 'less_than_or_equal_to'	The operator to use.
value	number	The value to compare against.

type = 'object_key'

Property	Value	Description
type	'object_key'	The type of the value to be evaluated.
field	string	The field to check. Supports nested properties, e.g. `users.admins[0]`.
operator	'contains' 'does_not_contain'	The operator to use.
value	string	The value to compare against.

type = 'object_value'

Property	Value	Description
type	'object_value'	The type of the value to be evaluated.
field	string	The field to check. Supports nested properties, e.g. `users.admins`.
operator	'contains' 'does_not_contain'	The operator to use.
value	any	The value to compare against.

type = 'object_key_value'

Property	Value	Description
type	'object_key_value'	The type of the value to be evaluated.
field	string	The field to check. Supports nested properties, e.g. `users.admins`.
operator	'contains' 'does_not_contain'	The operator to use.
value	{ key: 'string', value: 'any' }	The value to compare against.

type = 'generic_comparison'

Property	Value	Description
type	'generic_comparison'	The type of the value to be evaluated.
field	string	The field to check. Supports nested properties, e.g. `users.admins[0].unknown_property`.
operator	'equals_to' 'does_not_equal_to' 'greater_than' 'greater_than_or_equal_to' 'less_than' 'less_than_or_equal_to'	The operator to use.

type = 'generic_type'

Property	Value	Description
type	'generic_type'	The type of the value to be evaluated.
field	string	The field to check. Supports nested properties, e.g. `users.admins[0].unknown_property`.
operator	'is_truthy' 'is_falsey' 'is_null' 'is_not_null' 'is_undefined' 'is_not_undefined' 'is_string' 'is_not_string' 'is_number' 'is_not_number' 'is_boolean' 'is_not_boolean' 'is_array' 'is_not_array' 'is_object' 'is_not_object'	The operator to use.
value	any	The value to compare against.

TypeScript Usage

Rules can be pre-composed using type anotations before adding it to the rules engine:

import { NewNumberRule, NewRule, addRuleToUnion, createRoot } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });

const wideTypingRule: NewRule = { type: 'number', field: 'age', operator: 'greater_than', value: 18 };
const narrowTypingRule: NewNumberRule = { type: 'number', field: 'age', operator: 'less_than', value: 30 };

const wideAfterAdding = addRuleToUnion(root, wideTypingRule);
const narrowAfterAdding = addRuleToUnion(root, narrowTypingRule);

console.log(wideAfterAdding);
console.log(narrowAfterAdding);

{
  "entity": "rule",
  "id": "560f4e04-f786-4269-bbdd-704ad9793518",
  "parent_id": "6fa1aaa6-cfab-4647-a30c-a58af3e0a4d4",
  "type": "number",
  "field": "age",
  "operator": "greater_than",
  "value": 18
}

{
  "entity": "rule",
  "id": "46a36441-3f28-4dd7-8420-b1d584527a74",
  "parent_id": "6fa1aaa6-cfab-4647-a30c-a58af3e0a4d4",
  "type": "number",
  "field": "age",
  "operator": "less_than",
  "value": 30
}

Similarly, a union can also be pre-composed before adding it to the rules engine:

import { NewUnion, addUnionToUnion, createRoot } from 'rules-engine-ts';

const userSelectsAnd = false;

const root = createRoot({ connector: 'and' });
const union: NewUnion = { connector: userSelectsAnd ? 'and' : 'or' };

const unionAfterAdding = addUnionToUnion(root, union);
console.log(unionAfterAdding);

{
  "entity": "union",
  "id": "d2ce2a4e-ec53-4a64-9677-e9051c634bd1",
  "parent_id": "8b32fdc4-8e92-424f-9c00-1204838759e0",
  "connector": "or",
  "rules": []
}

To Do

[ ] Create recipe examples
[ ] Create function to detect conflicting or redundant rules
[ ] Create a UI builder tool

Authors

@andrewvo89 - Idea & Initial work.

See also the list of contributors who participated in this project.

rules-engine-ts

Table of Contents

About

Terminology

Rule

Union

Root Union

Parent

Basic Usage

UI Implementation Example

Installation

Usage

createRoot(connector: 'and' | 'or'): RootUnion

addRuleToUnion(parent: RootUnion | Union, newRule: NewRule): Rule

addRulesToUnion(parent: RootUnion | Union, newRules: NewRule[]): Rule[]

addUnionToUnion(parent: RootUnion | Union, newUnion: NewUnion): Union

addUnionsToUnion(parent: RootUnion | Union, newUnions: NewUnion[]): Union[]

addAnyToUnion(parent: RootUnion | Union, newRuleOrUnion: NewRule | NewUnion): Rule | Union

addManyToUnion(parent: RootUnion | Union, newRulesOrUnions: (NewRule | NewUnion)[]): (Rule | Union)[]

run(union: RootUnion | Union, value: any): boolean

findAnyById(union: RootUnion | Union, id: string): RootUnion | Union | Rule | undefined

findRuleById(union: RootUnion | Union, id: string): Rule | undefined

findUnionById(union: RootUnion | Union, id: string): RootUnion | Union | undefined

validate(root: RootUnion): { isValid: true } | { isValid: false; reason: string }

normalize<T extends Union | RootUnion>(union: T, options?: Options): T

updateRuleById(root: RootUnion, id: string, values: NewRule): Rule | undefined

updateUnionById(root: RootUnion, id: string, values: NewUnion): Union | RootUnion | undefined

removeAllById<T extends RootUnion | Union>(union: T, id: string): T

Rules Specification

type = 'string'

type = 'number'

type = 'boolean'

type = 'array_value'

type = 'array_length'

type = 'object_key'

type = 'object_value'

type = 'object_key_value'

type = 'generic_comparison'

type = 'generic_type'

TypeScript Usage

To Do

Authors

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

`createRoot(connector: 'and' | 'or'): RootUnion`

`addRuleToUnion(parent: RootUnion | Union, newRule: NewRule): Rule`

`addRulesToUnion(parent: RootUnion | Union, newRules: NewRule[]): Rule[]`

`addUnionToUnion(parent: RootUnion | Union, newUnion: NewUnion): Union`

`addUnionsToUnion(parent: RootUnion | Union, newUnions: NewUnion[]): Union[]`

`addAnyToUnion(parent: RootUnion | Union, newRuleOrUnion: NewRule | NewUnion): Rule | Union`

`addManyToUnion(parent: RootUnion | Union, newRulesOrUnions: (NewRule | NewUnion)[]): (Rule | Union)[]`

`run(union: RootUnion | Union, value: any): boolean`

`findAnyById(union: RootUnion | Union, id: string): RootUnion | Union | Rule | undefined`

`findRuleById(union: RootUnion | Union, id: string): Rule | undefined`

`findUnionById(union: RootUnion | Union, id: string): RootUnion | Union | undefined`

`validate(root: RootUnion): { isValid: true } | { isValid: false; reason: string }`

`normalize<T extends Union | RootUnion>(union: T, options?: Options): T`

`updateRuleById(root: RootUnion, id: string, values: NewRule): Rule | undefined`

`updateUnionById(root: RootUnion, id: string, values: NewUnion): Union | RootUnion | undefined`

`removeAllById<T extends RootUnion | Union>(union: T, id: string): T`

Weekly Downloads