Rules Engine Quickric

High-performance business rules engine for JavaScript/TypeScript applications.

Native Rust engine compiled to WebAssembly delivering superior speed and optimization, specifically designed for efficient evaluation of complex predefined rules. Ideal for systems requiring real-time rule-based validation, filtering, and decision-making.

📦 Installation

npm install rules-engine-qui

🚀 Quick Start

import init, { RulesEngineWasm } from 'rules-engine-qui';

async function example() {
  // Initialize WASM module
  await init();
  
  // Create engine instance
  const engine = new RulesEngineWasm();
  
  // Add a rule
  engine.add_rule_from_json(`{
    "id": "vip_discount",
    "priority": 1,
    "expression": {
      "op": "EQ",
      "left": { "var": "customer_type" },
      "right": { "value": "VIP" }
    }
  }`);
  
  // Evaluate with context
  const result = engine.evaluate({ customer_type: "VIP" });
  console.log(result); // { "vip_discount": true }
}

📖 Usage Guide

Rule Structure

A rule consists of:

{
  "id": "unique_identifier",        // Unique rule ID
  "priority": 1,                     // Evaluation priority (higher = first)
  "expression": {                    // Logical expression
    "op": "OPERATOR",
    "left": { ... },
    "right": { ... }
  }
}

Available Operators

| Operator | Description | Example | |----------|-------------|---------| | EQ | Equal to | age == 18 | | NEQ | Not equal to | status != "active" | | GT | Greater than | price > 100 | | GTE | Greater than or equal | age >= 18 | | LT | Less than | stock < 10 | | LTE | Less than or equal | discount <= 50 | | AND | Logical AND | age >= 18 AND vip == true | | OR | Logical OR | category == "A" OR category == "B" | | NOT | Logical NOT | NOT blocked |

Expression Types

1. Variable

Reads a value from context:

{ "var": "variable_name" }

2. Literal Value

Defines a constant value:

{ "value": 18 }           // Number
{ "value": "VIP" }        // String
{ "value": true }         // Boolean

3. Operation

Combines expressions with operators:

{
  "op": "GTE",
  "left": { "var": "age" },
  "right": { "value": 18 }
}

💡 Practical Examples

Example 1: Age Validation

import init, { RulesEngineWasm } from 'rules-engine-qui';

await init();
const engine = new RulesEngineWasm();

engine.add_rule_from_json(`{
  "id": "is_adult",
  "priority": 1,
  "expression": {
    "op": "GTE",
    "left": { "var": "age" },
    "right": { "value": 18 }
  }
}`);

const user = { age: 25 };
const result = engine.evaluate(user);
console.log(result.is_adult); // true

Example 2: Multiple Rules

const rules = [
  {
    id: "vip_customer",
    priority: 1,
    expression: {
      op: "EQ",
      left: { var: "type" },
      right: { value: "VIP" }
    }
  },
  {
    id: "large_purchase",
    priority: 2,
    expression: {
      op: "GT",
      left: { var: "amount" },
      right: { value: 1000 }
    }
  },
  {
    id: "discount_applicable",
    priority: 3,
    expression: {
      op: "OR",
      left: {
        op: "EQ",
        left: { var: "type" },
        right: { value: "VIP" }
      },
      right: {
        op: "GT",
        left: { var: "amount" },
        right: { value: 1000 }
      }
    }
  }
];

await init();
const engine = new RulesEngineWasm();

// Add all rules
rules.forEach(rule => {
  engine.add_rule_from_json(JSON.stringify(rule));
});

// Evaluate
const context = { type: "NORMAL", amount: 1500 };
const result = engine.evaluate(context);

console.log(result);
// {
//   "vip_customer": false,
//   "large_purchase": true,
//   "discount_applicable": true
// }

Example 3: Complex Logic (AND + OR + NOT)

const accessRule = {
  id: "access_granted",
  priority: 1,
  expression: {
    op: "AND",
    left: {
      op: "GTE",
      left: { var: "age" },
      right: { value: 18 }
    },
    right: {
      op: "AND",
      left: {
        op: "NOT",
        operand: {
          op: "EQ",
          left: { var: "blocked" },
          right: { value: true }
        }
      },
      right: {
        op: "OR",
        left: {
          op: "EQ",
          left: { var: "type" },
          right: { value: "PREMIUM" }
        },
        right: {
          op: "EQ",
          left: { var: "type" },
          right: { value: "VIP" }
        }
      }
    }
  }
};

await init();
const engine = new RulesEngineWasm();
engine.add_rule_from_json(JSON.stringify(accessRule));

const user = {
  age: 30,
  blocked: false,
  type: "PREMIUM"
};

const result = engine.evaluate(user);
console.log(result.access_granted); // true

🔧 API

RulesEngineWasm

Constructor

const engine = new RulesEngineWasm();

Methods

add_rule_from_json(json: string): void

Adds a rule to the engine from a JSON string.

engine.add_rule_from_json(`{
  "id": "my_rule",
  "priority": 1,
  "expression": { ... }
}`);

evaluate(context: object): object

Evaluates all rules with the provided context and returns an object with the results.

const result = engine.evaluate({ age: 25, type: "VIP" });
// { "rule1": true, "rule2": false, ... }

🌐 Framework Integration

Angular

// app.component.ts
import { Component, OnInit } from '@angular/core';
import init, { RulesEngineWasm } from 'rules-engine-qui';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html'
})
export class AppComponent implements OnInit {
  private engine?: RulesEngineWasm;

  async ngOnInit() {
    await init();
    this.engine = new RulesEngineWasm();
    
    // Configure rules...
    this.engine.add_rule_from_json(`{...}`);
  }
  
  evaluateRules(data: any) {
    return this.engine?.evaluate(data);
  }
}

React

import { useEffect, useState } from 'react';
import init, { RulesEngineWasm } from 'rules-engine-qui';

function App() {
  const [engine, setEngine] = useState<RulesEngineWasm | null>(null);

  useEffect(() => {
    init().then(() => {
      const newEngine = new RulesEngineWasm();
      // Configure rules...
      setEngine(newEngine);
    });
  }, []);

  const evaluate = (data: any) => {
    return engine?.evaluate(data);
  };

  return <div>...</div>;
}

Vue

// composable
import { ref, onMounted } from 'vue';
import init, { RulesEngineWasm } from 'rules-engine-qui';

export function useRulesEngine() {
  const engine = ref<RulesEngineWasm | null>(null);

  onMounted(async () => {
    await init();
    engine.value = new RulesEngineWasm();
  });

  const evaluate = (data: any) => {
    return engine.value?.evaluate(data);
  };

  return { engine, evaluate };
}

📄 Author

© Enrique Ruiz | Technical Lead