Scriba Rule Engine

A flexible rule engine (zero dependencies) for evaluating dynamic conditions and executing actions on records. Ideal for validation, automation, and configurable workflows in TypeScript/Node.js projects.

---

🚀 Features

Feature	Description
Simple & Composite Conditions	Supports and, or, not logical operators.
Dynamic Expressions	Use placeholders like {{field}} in conditions and actions.
Built-in Actions	throw, log, setField, callFunction, callWebhook.
Extensibility	Register custom conditions and actions.
Async Support	Handle asynchronous API calls or external tasks.
Zero Dependencies	Works out-of-the-box without extra packages.

---

📦 Installation

# Using npm
npm install scriba-rule-engine

# Using yarn
yarn add scriba-rule-engine

---

⚙️ Core Types

type Condition = {
  type?: string;
  field?: string;
  value?: any;
  valueFrom?: string;
  expression?: string;
  and?: Condition[];
  or?: Condition[];
  not?: Condition;
};

type ActionPayload = Record<string, any>;
type ActionFn = (params: { record: any; payload: ActionPayload }) => Promise<void> | void;

type Rule = {
  conditions: Condition | Condition[];
  actions: Array<{ type: string } & ActionPayload>;
  priority?: number;
};

---

💡 Usage Example

import { RuleEngine, defaultConditions, defaultActions } from "scriba-rule-engine";

const engine = new RuleEngine({
  conditions: defaultConditions,
  actions: defaultActions,
});

const record = { name: "Alice", age: 25, status: "active" };

const rules = [
  {
    conditions: { type: "greaterThan", field: "age", value: 18 },
    actions: [
      { type: "log", message: "User {{name}} is an adult" },
      { type: "setField", field: "verified", value: true }
    ]
  },
  {
    conditions: { type: "fieldExists", field: "status" },
    actions: [
      { type: "callFunction", fn: async (r) => console.log("Processing", r.name) }
    ]
  }
];

await engine.applyRules(record, rules);
console.log(record);
// Output: { name: "Alice", age: 25, status: "active", verified: true }

---

🛠️ Adding Custom Conditions or Actions

// Custom Condition
engine.registerCondition("isEven", (record, cond) => record[cond.field!] % 2 === 0);

// Custom Action
engine.registerAction("customAction", async ({ record }) => {
  console.log("Custom action executed for:", record);
});

---

🔗 Built-in Conditions

Condition	Description
greaterThan	Checks if a field is greater than a value.
lessThan	Checks if a field is less than a value.
equals	Checks equality with a value.
notEquals	Checks inequality with a value.
fieldExists	Checks if a field exists.
fieldNull	Checks if a field is null or undefined.
inList	Checks if the field value exists in an array.
notInList	Checks if the field value does NOT exist in an array.
matchesRegex	Checks if a field matches a regex.
expression	Evaluates a dynamic JavaScript expression with placeholders.
beforeDate	Checks if a date is before a given date.
afterDate	Checks if a date is after a given date.
startsWith	Checks if a string starts with a value.
endsWith	Checks if a string ends with a value.
contains	Checks if a string contains a value.
allInList	Checks if all values in condition array exist in record field array.
anyInList	Checks if any value in condition array exists in record field array.

---

🔗 Built-in Actions

Action	Description
throw	Throws an error with a dynamic message.
log	Logs a message to the console.
setField	Sets a record field to a value or expression result.
callFunction	Calls a custom function with the record and arguments.
callWebhook	Sends a POST request to a webhook with dynamic payload.

---

📖 Advanced Examples

Conditional AND / OR

const rec = { age: 30, status: 'inactive' };
const rules = [
  {
    conditions: {
      and: [
        { type: 'greaterThan', field: 'age', value: 18 },
        { not: { type: 'equals', field: 'status', value: 'active' } }
      ]
    },
    actions: [{ type: 'setField', field: 'canAccess', value: true }]
  }
];
await engine.applyRules(rec, rules);
console.log(rec.canAccess); // true

Multiple Actions

const rec = { age: 70, profile: {} };
const rules = [
  {
    conditions: { type: 'greaterThan', field: 'age', value: 65 },
    actions: [
      { type: 'setField', field: 'status', value: 'blocked' },
      { type: 'setField', field: 'profile.category', value: 'senior' }
    ]
  }
];
await engine.applyRules(rec, rules);
console.log(rec.status, rec.profile.category); // blocked senior

Expression Example

const rec = { score: 5 };
const rules = [
  { conditions: { expression: '{{score}} > 0' }, actions: [{ type: 'setField', field: 'bonus', expression: '{{score}} * 10' }] }
];
await engine.applyRules(rec, rules);
console.log(rec.bonus); // 50

---

📚 Notes

• Expressions use double curly braces {{field}} to dynamically evaluate record values.
• Rules can have optional priority for execution order.
• Actions can be asynchronous, supporting external API calls.
• Fully extensible and lightweight, with zero dependencies.