@arunkumar_h/rule-engine

---

Breaking Change: Please move to v3.1.0 or later.

---

A lightweight and extensible rule engine built with TypeScript and Node.js. Define complex business rules and evaluate conditions easily using a simple JSON structure.

📦 Installation

npm install @arunkumar_h/rule-engine

yarn add @arunkumar_h/rule-engine

🧠 Features

• ✅ Logical condition support (and, or, nested expressions)
• 🔧 Custom operators and named conditions
• 📜 Fully typed with TypeScript
• 🚀 Lightweight and dependency-aware
• 🔎 Native JMESPath support for data querying
• 🧰 Built-in caching using lru-cache for better performance

Feature / Capability	@arunkumar_h/rule-engine
✅ Written in TypeScript	✅ Native TypeScript with full type safety
⚙️ Custom Operators	✅ Built-in support, sync or async
🧠 Named Conditions	✅ Supports reusable named conditions
🧱 Nested Logical Trees	✅ Fully supported (and, or, deeply nested)
🔍 Data Query Language	✅ Built-in JMESPath support
🚀 Performance Optimizations	✅ Rule-level cache with lru-cache
🧰 Extensibility	✅ Add custom operators, conditions dynamically
⚖️ Lightweight	✅ Small and focused build
🧪 Testing Coverage Ready	✅ Easy to unit test each rule block
🔁 Dynamic Rule Loading	✅ Add/modify rules at runtime
🔄 Async Support	✅ Full async engine and operators
📦 Modern Packaging	✅ ESM + CJS + .d.ts types out of the box

⚙️ Default Operators

The following operators are available by default:

Operator	Description
===	Strict equality
!==	Strict inequality
==	Loose equality
!=	Loose inequality
>	Greater than
>=	Greater than or equal to
<	Less than
<=	Less than or equal to
%like	Starts with
like%	Ends with
%like%	Contains
in	Value is in the array
!in	Value is not in the array
includes	Array includes value
!includes	Array does not include value

🔨 Basic Usage

• condition This containes and and or as main block.
• onSuccess value that will be returned or function that will be invoked if the condition is satisfied.
• onFail value that will be returned or function that will be invoked if the condition fails.
• cache as default this will be set to true and can be disabled for rule wise false

import { Engine } from "@arunkumar_h/rule-engine";

const engineObj = new Engine();
const rule = {
  testRule: {
    condition: {
      and: [
        { path: "age", operator: "!==", value: 10 },
        {
          and: [
            { path: "age", operator: ">", value: 15 },
            {
              or: [
                { path: "age", operator: "!==", value: 30 },
                { path: "skills", operator: "includes", value: "ts" },
              ],
            },
          ],
        },
        { path: "language", operator: "in", value: ["tamil", "english"] },
      ],
    },
    onSuccess: (fact, ruleName) => "Success", // onSuccess: { id: 23 }
    onFail: (fact, ruleName) => "Fail", // onFail: "Error"
    cache: false, // default will be true
  }
};
engine.addRule(rule);

const fact = {age: 16, skills: ["ts", "php"], language: "tamil"}; // Your data to be validated 
const result = await engineObj.run(fact, "testRule");

🔧 Custom Operator Example

engine.addOperator({
  isEven: (factValue) => factValue % 2 === 0,
});

const rule = {
  evenCheck: {
    condition: {
      and: [
        { path: "number", operator: "isEven" },
      ],
    },
    onSuccess: "Number is even",
    onFail: "Number is odd",
  },
};

const result = await engine.run({ number: 8 }, "evenCheck");

🔍 API Overview

flowchart TB
    Rule --> onSuccess
    Rule --> onFail
    Rule --> Condition --> AND --> Operation
    Condition --> OR --> Operation

Engine API

let engine = new Engine() 

addRule({ rule1, rule2, ... })

• Add named rules dynamically.

addCondition({ condition1, condition2, ... })

• Add reusable named conditions.
• Conditions can reference other named conditions.

addOperator({ customOperator1, customOperator2, ... })

• Add custom (sync or async) operators.

run(fact, ruleName)

• Executes a given rule against the provided fact

⚡ Advanced Usage

• Adding named conditions.
• Adding named operators.
• Rule wise cache disabling.

import { Engine } from "@arunkumar_h/rule-engine";

const engineObj = new Engine();

const condition1 = {
  condition1: {
    and: [
      { path: "age", operator: "!==", value: 10 },
      {
        and: [
          { path: "age", operator: ">", value: 15 },
          {
            or: [
              { path: "age", operator: "!==", value: 30 },
              { path: "skills", operator: "includes", value: "ts" },
            ],
          },
        ],
      },
      { path: "language", operator: "in", value: ["tamil", "english"] },
    ],
  }
};
engine.addCondition(condition1);  // adding named condition

const rule = {
  testRule: {
    condition: "condition1",  // Using named condition
    onSuccess: "Success",  //  can be a function or a data
    onFail:  "Fail", //  can be a function or a data
    cache: false  // disable cache for this rule 
  }
};
engine.addRule(rule);

const fact = {age: 16, skills: ["ts", "php"], language: "tamil"}; // Your data to be validated 
const result = await engineObj.run(fact, "testRule");

🧪 Test Coverage

Badges above represent live coverage stats for:

• 
• 
• 
• 

Author

Arunkumar H

📄 License

• Code: Licensed under the MIT License
• Assets & Documentation: Licensed under the CC BY-SA 4.0 License

Some non-code content (e.g. diagrams, images, markdown docs) is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License.

See https://creativecommons.org/licenses/by-sa/4.0/ for more info.