ts-rule-engine

Lightweight rule engine, written in typescript

Supports and tested with

{
  "node": "18.x || 20.x || 22.x",
}

Features

• [x] Structure for rule definition
• [x] Rerun rules after fact is updated
• [x] Stop rule engine on any rule from executing further
• [x] Infinite loop prevention with max iterations limit
• [x] One time rule execution in sequence
• [x] Rule weight for priority
• [x] Supports ESM and CommonJS
• [x] Logger interface for custom logging

Installation

npm install ts-rule-engine
pnpm add ts-rule-engine
yarn add ts-rule-engine
bun add ts-rule-engine

1. Defining a Rule

A rule will consist of a condition and action, id, name and weight. The condition is a function that returns a boolean value. The action is a function that will be executed if the condition is true. The action function will be passed the fact, { rule, stop }. The stop function will stop the rule engine from executing further rules. This way you can control the flow of the rule engine.

import type { Rule } from 'ts-rule-engine'

/* Define fact interface */
interface Fact {
  balance: number
  broke?: boolean
}

/* Define rule */
const rule: Rule<Fact> = {
  id: 1,
  name: 'Rule 1',
  weight: 1,
  condition: (fact) => {
    return fact.balance < 5
  },
  action: (fact, { stop }) => {
    fact.broke = true
    /* stop() will stop the rule engine from executing further rules */
    stop()
  }
}

Higher the weight of the rule, higher the priority of the rule. If the weight is not provided, it will be set to 0 by default and will be executed after all the rules with weight > 0 are executed. If all weights are same, rules will be executed in the order they are added to the rule engine.

2. Defining a Fact

Facts are those input json values on which the rule engine applies its rule to obtain results. A fact can have multiple attributes as you decide.

A sample Fact may look like

/* Define fact interface */
interface Fact {
  application: string
  cost: number
  license?: string
  description?: string
}

/* Define fact */
const fact: Fact = {
  application: 'ts-rule-engine',
  cost: 0
}

3. Using the Rule Engine

The example below shows how to use the rule engine to apply a sample rule on a specific fact. Rules can be fed into the rule engine as Array of rules or as an individual rule object.

import { RuleEngine } from 'ts-rule-engine'

/* Define fact */
const fact: Fact = {
  application: 'ts-rule-engine',
  cost: 0,
  license: '',
  description: ''
}

/* Define rule */
const rule: Rule<Fact> = {
  condition: (fact) => {
    return fact.cost === 0
  },
  consequence: (fact) => {
    fact.license = 'MIT'
    fact.description = 'License originating at the Massachusetts Institute of Technology (MIT) in the late 1980s'
    fact.stop()
  },
};

/* Creating Rule Engine instance */
const engine = new RuleEngine(fact)
engine.addRule(rule)
/* For multiple rules, use engine.addRules(rules) */
await engine.run()

console.log(fact)
/*
{
  application: 'ts-rule-engine',
  cost: 0,
  license: 'MIT',
  reason: 'License originating at the Massachusetts Institute of Technology (MIT) in the late 1980s'
}
*/

4. Using the Rule Engine with Logger

The example below shows how to use the rule engine with a custom logger. The logger should implement the Logger interface. If a logger is not provided, logs are written using the global console object.

import { RuleEngine, Logger } from 'ts-rule-engine'

/* Define fact */
const fact: Fact = {
  application: 'ts-rule-engine',
  cost: 0,
  license: '',
  description: ''
}

/* Define rule */
const rule: Rule<Fact> = {
  condition: (fact) => {
    return fact.cost === 0
  },
  action: (fact, { logger }) => {
    logger.info('All Good')
    fact.license = 'MIT'
    fact.description = 'License originating at the Massachusetts Institute of Technology (MIT) in the late 1980s'
    fact.stop()
  },
};

/* Custom Logger */
class CustomLogger implements Logger {
  messages: string[] = []

  info(message?: string, ...optionalParams: string[]): void {
    this.messages.push(message)
  }

  warn(message?: string, ...optionalParams: string[]): void {
    this.messages.push(message)
  }

  error(message?: string, ...optionalParams: string[]): void {
    this.messages.push(message)
  }
}

/* Creating Rule Engine instance */
const logger = new CustomLogger()
const engine = new RuleEngine(fact, {logger})
engine.addRule(rule)
/* For multiple rules, use engine.addRules(rules) */
await engine.run()

// Check logger messages
console.log(logger.messages)
/*
[
  'Rule 1: Executing',
  'Rule 1: Executed',
  'Rule 1: Stopped'
]
*/