logicguru-engine

Logic Rule Engine

A powerful, async-ready JSON-based logic rule engine for evaluating nested conditions, variable bindings, dynamic file loading, and custom actions.

✅ Features

• Nested condition support (AND/OR/==/!=/...)

• $ variables resolved from provided context

• Template string resolution (${variable} in log messages)

• $file.variable for dynamic external data resolution

• Preload data from files via useFiles config

Support for multiple action types:

• log (with template string support ${})

• assign (new object return with result)

• update (nested path support)

• excludeVal (array value removal)

• deleteKey (property deletion)

• Fully async-compatible and optimized

• Easily configurable for different contexts and sources

---

📦 Installation

npm install logicguru-engine

🚀 Usage

import { configureRuleEngine } from "logic-rule-engine";
import rules from "./examples/rules.json";

const context = {
  source: "evensect",
  productId: "123344",
  baseProductId: "123344",
  addons: ["1234", "5678"],
};

const engine = await configureRuleEngine(rules, {
  basePath: "./data",
  defaultContext: context,
});

const result = await engine();
console.log(result);

📘 Rules Structure

{
  "id": "section-rule",
  "useFiles": {
    "productFile": {
      "path": "${get.baseProductId}.json",
      "variable": ["ageOld"]
    }
  },
  "condition": {
    "and": [{ "==": ["$get.source", "evectus"] }],
    "and": [{ "includeIn": ["$get.agentList", "20001111"] }],
    "and": [{ "includeKey": ["$get.AdditionalDetails", "noUpsell"] }],
    "and": [{ "includeVal": ["$get.memberList", "234046574"] }]
  },
  "actions": [
    {
      "type": "log",
      "message": "Processing agent ${get.agentId}"
    },
    {
      "type": "update",
      "key": "$res.productId",
      "value": "$get.agentId",
      "returnKey": "res"
    },
    {
      "type": "excludeVal",
      "key": "$res.addons",
      "exclude": "1234",
      "returnKey": "res.addons"
    },
    {
      "type": "deleteKey",
      "key": "$temp.oldValue"
    }
  ]
}

---

🔧 Actions

• log:

{
  "type": "log",
  "message": "Processing ${variable.path}"
}

• assign:

{
  "type": "assign",
  "key": "targetKey",
  "value": "$someKey"
}

• update

{
  "type": "update",
  "key": "$object.nested.path",
  "value": "$newValue",
  "returnKey": "resultKey"
}

• excludeVal //array removal

{
  "type": "excludeVal",
  "key": "$target.array",
  "exclude": "valueToRemove",
  "returnKey": "modifiedArray"
}

• deleteKey //work on object

{
  "type": "deleteKey",
  "key": "$object.keyToRemove",
  "returnKey": "modifiedobject"
}

includeFromArr

Filters an array to include only objects matching specified values, with optional key selection.

Enhanced Syntax

{
  "type": "includeFromArr",
  "target": "<output-path>",
  "source": "<source-array>",
  "matchProperty": "<property-name>",
  "includeValue": "<value-or-array>",
  "includeKeys": ["<key1>", "<key2>"], // Optional
  "returnKey": "<optional-return-key>"
}

excludeFromArr:

{
  "type": "excludeFromArr",
  "target": "$res.addon",
  "source": "$get.data.addon",
  "matchProperty": "addonId",
  "excludeValue": ["0654", "1234"],
  "returnKey": "res"
}

📁 Dynamic File Loading

Supports useFiles to load data from external JSON dynamically using variable interpolation like $productFile. Supports useFiles to load data from external JSON dynamically using variable interpolation:

"useFiles": {
  "productFile": {
    "path": "${get.baseProductId}.json",
    "variable": ["dataset"]
  }
}

🆕 Recent Updates

• Added template string resolution (${}) in log messages

• New excludeVal action for array value removal

• New deleteKey action for property deletion

• New includeIn action for array value condition check to find specific value

• New includeKey action for object property check to find specific key

• New includeVal action for object property check to find specific value

• Enhanced update action with nested path support

• Improved object handling in variable resolution

ensure your action types follow the new syntax, particularly:

• Use exclude instead of value in excludeVal actions

• Template strings ${}, now work in log messages

• Nested paths are fully supported in all actions

---

Overview

Two specialized actions for filtering arrays of objects:

Action	Description
excludeFromArr	Removes objects matching specified values
includeFromArr	Keeps only objects matching specified values

excludeFromArr

Removes objects that match specified values from an array.

Parameters

Parameter	Type	Required	Description
target	string	Yes	Context path to store results (supports $ notation)
source	string	Yes	Source array path (supports $ notation)
matchProperty	string	Yes	Property name to check in objects
excludeValue	string/array	Yes	Value(s) to exclude
returnKey	string	No	Key to return in result object

**for any feedback/issue you can directly mail me on [e-mail] or share issue on github by raising a issue on https://github.com/Sachinsharmawebdev/logicguru-engine/issues

💖 Support Our Open-Source Work

If you find this project valuable and would like to support its continued development, please consider:

🌟 Sponsoring via GitHub

Your sponsorship helps us:

• Maintain and improve this project full-time

• Add new features and fix bugs faster

• Create more high-quality open-source tools

Every contribution makes a difference, no matter the size. Together we can build better tools for the developer community.

---