Logic Guru 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

  • Logical: and, or
  • Comparison: ==, !=, >, <, >=, <=
  • Array/Object: includeIn, includeKey, includeVal

• Date Functions

  • year(date): Calculate years from date
  • month(date): Calculate months from date
  • day(date): Calculate days from date

• Context Variables

  • $ variables resolved from provided context
  • Template string resolution (${variable})
  • Date function support (${year($context.date)})

• Dynamic File Loading

  • useFiles for external data resolution
  • Template path support (${variable}_slug.json)
  • Preload data from files

• Action Types

  • log: Logging with template support
  • assign: Create new object with result
  • update: Update nested paths
  • excludeVal: Remove array values
  • deleteKey: Delete properties
  • excludeFromArr: Filter array by property
  • includeFromArr: Include array items by property
  • deleteKeyFromArray: Delete specific keys from array objects
  • updateKeyInArray: Update specific keys in array objects
  • addKeyToArray: Add new keys to array objects
  • filterArray: Filter arrays based on conditions
  • filterObject: Filter object key-value pairs based on conditions

• Fully async-compatible and optimized

• TypeScript support

• Comprehensive error handling

📦 Installation

npm install logicguru-engine

🚀 Basic Usage

import { configureRuleEngine } from "logicguru-engine";

const rules = [
  {
    "id": "age-verification",
    "condition": {
      "and": [
        { ">=": ["${year($context.birthDate)}", 18] }
      ]
    },
    "actions": [
      {
        "type": "assign",
        "key": "result.isAdult",
        "value": true
      }
    ]
  }
];

const context = {
  birthDate: "2000-01-01"
};

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

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

📘 Rules Structure

{
  "id": "user-verification",
  "useFiles": {
    "configFile": {
      "path": "/config/${$context.type}_config.json"
    }
  },
  "condition": {
    "and": [
      { ">=": ["${year($context.birthDate)}", 18] },
      { "!=": ["$context.status", "suspended"] },
      { "includeIn": ["$context.id", "$configFile.validIds"] }
    ]
  },
  "actions": [
    {
      "type": "log",
      "message": "Processing user: ${$context.userId}"
    },
    {
      "type": "assign",
      "key": "result.isEligible",
      "value": true
    }
  ]
}

🔧 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

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

deleteKey

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

excludeFromArr

{
  "type": "excludeFromArr",
  "target": "$result.items",
  "source": "$context.items",
  "matchProperty": "id",
  "excludeValue": ["item1", "item2"],
  "returnKey": "$result.filteredItems"
}

includeFromArr

{
  "type": "includeFromArr",
  "target": "$result.items",
  "source": "$context.items",
  "matchProperty": "id",
  "includeValue": ["item1", "item2"],
  "includeKeys": ["id", "name"],
  "returnKey": "$result.filteredItems"
}

deleteKeyFromArray

{
  "type": "deleteKeyFromArray",
  "source": "$context.fruits",
  "target": "fruitsWithoutPrice",
  "matchProperty": "location",
  "matchValue": ["India", "Mexico"],
  "deleteKeys": ["price", "supplier"]
}

updateKeyInArray

{
  "type": "updateKeyInArray",
  "source": "$context.fruits",
  "target": "updatedFruits",
  "matchProperty": "location",
  "matchValue": "USA",
  "updates": {
    "price": "$newPrice",
    "status": "premium"
  }
}

addKeyToArray

{
  "type": "addKeyToArray",
  "source": "$context.fruits",
  "target": "fruitsWithDiscount",
  "matchProperty": "location",
  "matchValue": ["India", "Brazil"],
  "additions": {
    "discount": "20%",
    "discountPrice": "$discountedPrice"
  }
}

filterArray

{
  "type": "filterArray",
  "source": "$context.items",
  "target": "activeItems",
  "matchProperty": "status",
  "matchValue": ["active", "pending"]
}

With comparison operators:

{
  "type": "filterArray",
  "source": "$context.products",
  "target": "expensiveProducts",
  "matchProperty": "price",
  "operator": ">=",
  "matchValue": 1000
}

filterObject

{
  "type": "filterObject",
  "source": "$sumInsure",
  "target": "highTierSumInsure",
  "filterBy": "key",
  "operator": ">",
  "compareValue": 6
}

Filter by value:

{
  "type": "filterObject",
  "source": "$prices",
  "target": "expensiveItems",
  "filterBy": "value",
  "operator": ">=",
  "compareValue": 100000
}

📅 Date Functions

year

{
  "condition": {
    ">=": ["${year($context.birthDate)}", 18]
  }
}

month

{
  "condition": {
    "<": ["${month($context.joinDate)}", 6]
  }
}

day

{
  "condition": {
    "<=": ["${day($context.trialStartDate)}", 30]
  }
}

🆕 Recent Updates

• Added new comparison operators (!=, >, <, >=, <=)
• Added date functions (year, month, day)
• Enhanced error handling and logging
• Improved TypeScript support
• Added comprehensive documentation

📚 Documentation

For detailed documentation, including best practices and examples, see DOCUMENTATION.md

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

MIT License - see the LICENSE file for details.

💬 Support

For support, please:

• Open an issue on GitHub
• Contact: [email protected]
• Visit: https://github.com/Sachinsharmawebdev/logicguru-engine

**for any feedback/issue you can directly mail me on [email protected] 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.