Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ilovepixelart/ts-rule-engine
Lightweight rule engine, written in typescript
https://github.com/ilovepixelart/ts-rule-engine
backend engine forward-chaining node rule swc typescript
Last synced: 11 days ago
JSON representation
Lightweight rule engine, written in typescript
- Host: GitHub
- URL: https://github.com/ilovepixelart/ts-rule-engine
- Owner: ilovepixelart
- License: mit
- Created: 2023-08-07T18:26:14.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-28T13:35:51.000Z (23 days ago)
- Last Synced: 2024-11-02T00:32:28.999Z (18 days ago)
- Topics: backend, engine, forward-chaining, node, rule, swc, typescript
- Language: TypeScript
- Homepage:
- Size: 472 KB
- Stars: 5
- Watchers: 1
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# ts-rule-engine
Lightweight rule engine, written in typescript
[](https://www.npmjs.com/package/ts-rule-engine)
[](https://www.npmjs.com/package/ts-rule-engine)
[](https://github.com/ilovepixelart/ts-rule-engine/blob/main/LICENSE)
\
[](https://sonarcloud.io/summary/new_code?id=ilovepixelart_ts-rule-engine)
[](https://sonarcloud.io/summary/new_code?id=ilovepixelart_ts-rule-engine)
\
[](https://sonarcloud.io/summary/new_code?id=ilovepixelart_ts-rule-engine)
[](https://sonarcloud.io/summary/new_code?id=ilovepixelart_ts-rule-engine)
[](https://sonarcloud.io/summary/new_code?id=ilovepixelart_ts-rule-engine)
[](https://www.npmjs.com/package/ts-rule-engine)
## Supports and tested with
```json
{
"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
```bash
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.
```typescript
import type { Rule } from 'ts-rule-engine'
/* Define fact interface */
interface Fact {
balance: number
broke?: boolean
}
/* Define rule */
const rule: Rule = {
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
```typescript
/* 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.
```typescript
import { RuleEngine } from 'ts-rule-engine'
/* Define fact */
const fact: Fact = {
application: 'ts-rule-engine',
cost: 0,
license: '',
description: ''
}
/* Define rule */
const rule: Rule = {
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.
```typescript
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 = {
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'
]
*/
```