npm package: @rule-kit/core
Description: modern async rules engine
Author: clinejm
Latest version: 0.2.1

# @rule-kit/core

modern async rules engine.

---
**Very experimental. A side project to explore the building blocks of composable software systems. The goal is to create something useful but who knows if this is the right path. Please check it out. Constructive thoughts are welcome.**

---

## When to use

- Use were hand-coding javascript logic isn't practical or safe. 
    - No code tools where users don't want to or can't be trusted to write javascript
    - Large and complex or dynamic forms where hand-coded validation is unreliable. 
    - Workflows
    - Data processing

## Features

- No runtime dependencies in core engine, or transpiling (just needs `async/await`)
- Small core, easy to read and if needed copypasta and hack up. 
- Specify rules in `JSON` which allows for 
    - dynamic rules
    - fetch rules from server
    - run the same rules on client and server
- `compile` a rule once at runtime and execute the rule multiple times
    - the `compile` function converts the rules to executeable 
    code with out the use of `eval` or any other shady hacks. 
- Mix and match `sync` and `async` rules.
- Rule Groups
    - `and` all rules must be true for group to be true (this is the default)
    - `or` if any rule returns true then the group is true
- Groups can be nested.
- The rule or rule group that causes the rule to be `false` is returned as `errorRule`
- Add custom operators (these are just simple `sync` or `async` functions)
- Operators can compare a field to a literal value or another field in the data object 


## Built-in Operators

- `is`  
- `is_empty`
- `not_empty`


See roadmap for more operators to come. 

## Installation 

```bash
npm install @rule-kit/core
```

## Basic Usage

```javascript

import {compile, defaultOperators} from '@rule-kit/core';

const rules = [
    { field: 'first', operator: 'is', value: 'foo' },
    { field: 'last', not: true, operator: 'is', value: 'A' },
    { field: 'last', not: true, operator: 'is', value: 'C' },
];

const rule = compile({ rules: rules, operators:baseOperators })

let {result, errorRule} = await rule({
    first: 'foo',
    last: 'B'
});

console.log('Results (True)', result, errorRule);
// true, null

let {result, errorRule} = await rule({
    first: 'foo',
    last: 'A'
});

console.log('Results (False)', result, errorRule);
// false,  {  field: 'first', operator: 'is', value: 'foo' }


```

### Nested Rules

```javascript

const rule = { 
    operator: 'or', 
    rules:[
        { field: 'first', operator: 'is', value: 'foo' },
        {
            operator: 'or', 
            rules: [
                { field: 'last', operator: 'is', value: 'foo' },
                { field: 'last', operator: 'is', value: 'blort' }
            ]
        }
    ]
}

const rule = compile({ rules: rule })

let {result, errorRule} = await rule({
    first: 'foo',
    last: 'A'
});
// result === false (because last isn't foo or blort)

let {result, errorRule} = await rule({
    first: 'foo',
    last: 'foo'
});
// result === true (because first and last are foo )

```

In the above example the the field `first` must have a value or `foo`
and the field `last` must have a value of either `foo` or `blort` 


### Compare one field to another

```javascript

//value can be an object not just a literal. 
// in this case provide the field to compare
const rules = [{ field: 'password', operator: 'is', value: { field: 'confirmpass' } }];

const rule = compile({ rules });

let {result, errorRule} = await rule({
    password: 'foo',
    confirmpass: 'foo'
});
// result === true (because they match)


let {result, errorRule} = await rule({{
    password: 'foo',
    confirmpass: 'dddd'
});
// result === false (because they don't match)


```

### Custom Operators

An operator is just a function it will receive to arguments 
- `data` the object that contains the data the function is to evaulate
- `config` the configuration of the rule. this will contain at least the key `field` or the location of the data being evaulated by this rule. 

```javascript

const getValue = (data, config) => (config.value.field ? data[config.value.field] : config.value)

const sleep = ms => {
    return new Promise(resolve => setTimeout(resolve, ms))
}

function is_empty(data, config) {
    const test = data[config.field];
    return !test || (test.trim && test.trim().length === 0)
}

const defaultInputs = (config) => (config?.value?.field ? [config.field, config?.value?.field] : [config.field]);
const fieldOnlyInput = (config) => ([config.field]);

const defaultOperators = {
    is: {
        type: 'sync',
        inputs: defaultInputs,
        fn: (data, config) => (data[config.field] === getValue(data, config)),
    },
    async_is: {
        type: 'async',
        inputs: defaultInputs,
        fn: async (data, config) => {
            return sleep(config.time || 1000).then(() => data[config.field] === getValue(data, config))
        }
    },
    is_empty: {
        type: 'sync',
        inputs: fieldOnlyInput,
        fn: is_empty
    },
    not_empty: {
        type: 'sync',
        inputs: fieldOnlyInput,
        fn: (data, config) => !is_empty(data, config)
    }
}

```

## Road Map

- Real docs
- More tests
- Sync only comple (if you don't need async functions)
- More Operators
    - Strings 
    - Math/Numbers
    - Dates
    - Arrays
- Extensions
    - `react` `useRule` hook
    - utlity to display user friendly localized error messages (eg form validation)
    - GUI builder