A simple and powerful mechanism for validating rules in JSON.
Built with ❤︎ by Hiukky
# About
Grule is a minimal mechanism for testing conditions against values using a JSON scheme. Its main objective is to work as a Rete mechanism and to solve all operations in a performatic and simple way.
# Installation
### Using NPM
```sh
npm i grule
```
### Using Yarn
```sh
yarn add grule
```
# Use
To set up your rules scheme, just follow the steps below.
### Create an instance
To create a test instance, you will need a load of facts to power the engine.
```ts
// Import Engine
import { Grule } from 'grule'
// Create an type
type IUser = {
id: number
name: string
}
// Create metadata
const metadata: IUser = {
id: 3,
name: 'test',
}
// Create instance
const grule = new Grule(metadata)
```
### Subscribe rules
After creating an instance of the engine, pre-loading with facts, the next step is to register the rules. To register the rules, you must import the `IRules ` interface and create a set of rules for the attributes declared in the facts.
The rules follow the structure of the data declared in the facts. For each attribute a rule will be executed.
The rule creation function offers 2 arguments, the first being the `attributes` and the second the `events`.
You can use a logical expression for each test and perform an action you want, or you can use the `when` and `then` event to test and perform an action based on the result. This is a good option for dynamic testing.
After creating an instance and registering the rules, you can simply execute the run method by passing the rules defined as a parameter. At the end of the tests, if there is no error that interrupts the flow of the tests, a Boolean value will be returned.
- `true` all conditions have passed.
- `false` one or all of the conditions failed.
```ts
// ... Previous code
// Create Rules
const rules: IRules = ({ id, name }, { when }) => ({
id: when(id.diff(1)).then(() => {
throw new Error('User not allowed.')
}),
name: name.in(['foo', 'test']),
})
// Enroll rules
grule.run(rules)
```
You can also simplify the previous flow in a cleaner way. (Example of final code)
```ts
// Import Engine
import { Grule } from 'grule'
// Create an type
type IUser = {
id: number
name: string
}
// Create instance
new Grule({
id: 3,
name: 'test',
}).run(({ id, name }, { when }) => ({
id: when(id.diff(1)).then(() => {
throw new Error('User not allowed.')
}),
name: name.in(['foo', 'test']),
}))
```
## Available methods
### For Attributes
Each attribute has 9 methods available for the tests that are.
- **less**
```ts
// Type: less(value: ILess): boolean
// Acceptable: ['number', 'bigint']
```
- **lessOrEqual**
```ts
// Type: lessOrEqual(value: ILess): boolean
// Acceptable: ['number', 'bigint']
```
- **greater**
```ts
// Type: greater(value: IGreater): boolean
// Acceptable: ['number', 'bigint']
```
- **greaterOrEqual**
```ts
// Type: greaterOrEqual(value: IGreater): boolean
// Acceptable: ['number', 'bigint']
```
- **equal**
```ts
// Type: equal(value: IEqual): boolean
// Acceptable: ['bigint', 'boolean', 'number', 'string', 'date']
```
- **diff**
```ts
// Type: diff(value: IEqual): boolean
// Acceptable: ['bigint', 'boolean', 'number', 'string', 'date']
```
- **in**
```ts
// Type: in(value: In): boolean
// Acceptable: ['bigint', 'boolean', 'number', 'string', 'array']
```
- **notIn**
```ts
// Type: notIn(value: In): boolean
// Acceptable: ['bigint', 'boolean', 'number', 'string', 'array']
```
- **eval**
```ts
// Type: eval(operator: IOperatorsList, arg1: A): boolean
// Acceptable: [Idle]
```
### For Events
Grule currently has only one event than `when`. It returns a promise with a boolean result from the test performed.
- **when**
```ts
// Type: when(test: boolean): Promise
// Acceptable: ['boolean']
```
# Contributing
Grule is in an initial version without many features yet, but you can feel free to send your suggestion or open a PR.
