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

npm i grule

Using Yarn

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.

// 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<IUser>(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 <T> 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.

// ... Previous code

// Create Rules
const rules: IRules<IUser> = ({ 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)

// Import Engine
import { Grule } from 'grule'

// Create an type
type IUser = {
  id: number
  name: string
}

// Create instance
new Grule<IUser>({
  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

// Type: less(value: ILess): boolean
// Acceptable: ['number', 'bigint']

• lessOrEqual

// Type: lessOrEqual(value: ILess): boolean
// Acceptable: ['number', 'bigint']

• greater

// Type: greater(value: IGreater): boolean
// Acceptable: ['number', 'bigint']

• greaterOrEqual

// Type: greaterOrEqual(value: IGreater): boolean
// Acceptable: ['number', 'bigint']

• equal

// Type: equal(value: IEqual): boolean
// Acceptable: ['bigint', 'boolean', 'number', 'string', 'date']

• diff

// Type: diff(value: IEqual): boolean
// Acceptable: ['bigint', 'boolean', 'number', 'string', 'date']

• in

// Type: in(value: In): boolean
// Acceptable: ['bigint', 'boolean', 'number', 'string', 'array']

• notIn

// Type: notIn(value: In): boolean
// Acceptable: ['bigint', 'boolean', 'number', 'string', 'array']

• eval

// 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

// Type: when(test: boolean): Promise<boolean>
// 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.