@comodinx/query-filters/README.md

@comodinx/query-filters is a module for parsing filters in string to object.

# Query Filters

@comodinx/query-filters is a module for parsing filters in string to object.

## Index

* [Download & Install][install].
* [How is it used?][how_is_it_used].
* [Tests][tests].

## Download & Install

### NPM
```bash
$ npm install @comodinx/query-filters
```

### Source code
```bash
$ git clone https://github.com/comodinx/query-filters.git
$ cd query-filters
$ npm install
```

## How is it used?

### Simple usage
```js
const { Parser } = require('@comodinx/query-filters');
const parser = new Parser();

parser.parse('active eq 1,description li %casa');
// { "active": { "eq": "1" }, "description": { "li": "%casa" } }

parser.parse('active eq 1,description li %casa,description eq depto');
// { "active": { "eq": "1" }, "description": { "li": "%casa", "eq": "depto" } }
```

## Logical operators and groups

### AND
- Default operator
- Represented by `,`

```txt
active eq 1,description li %casa
```

### OR
- Represented by `|`

```txt
active eq 1|description li %casa
```

### Groups
- Represented by `(` and `)`

```txt
active eq 1,(description li %casa|description eq depto)
```

### Precedence
- `AND` has higher precedence than `OR`
- Use groups to control evaluation order

```txt
active eq 1,description li %casa|age ge 18
active eq 1,(description li %casa|age ge 18)
```

### Parsed result example
```js
parser.parse('active eq 1,(deleted_at is null|age ge 18)');
/*
{
  active: { eq: 1 },
  or: [
    { deleted_at: { is: 'null' } },
    { age: { ge: 18 } }
  ]
}
*/
```

## Operators
| Name | Example                | Description                                                   |
|:-----|:-----------------------|:--------------------------------------------------------------|
| eq   | id eq 1                | Check equality. id = 1                                        |
| ne   | name ne nico           | Check inequality. name != 'nico'                              |
| gt   | id gt 1                | Check greater than. id > 1                                    |
| ge   | id ge 10               | Check greater than or equal. id >= 10                         |
| lt   | id lt 1                | Check less than. id < 1                                       |
| le   | id le 10               | Check less than or equal. id <= 10                            |
| li   | name li nico%          | Check matches with nico*. name like nico%                     |
| nl   | name nl nico%          | Check not matches with nico*. name not like nico%             |
| in   | id in [1;2;3]          | Check if included on [1,2,3]. id in (1,2,3)                   |
| ni   | id ni [1;2;3]          | Check if not included on [1,2,3]. id not in (1,2,3)           |
| be   | id be [1;10]           | Check if it is between a and b. id between (1 and 10)         |
| nb   | id nb [1;10]           | Check if it is not between a and b. id not between (1 and 10) |
| is   | deleted_at is null     | Check if it is null.                                          |
| no   | deleted_at is not null | Check if it is not null.                                      |

## Configurations
| Name            | Type   | Default                                           | Description                                      |
|:----------------|:-------|:--------------------------------------------------|:-------------------------------------------------|
| logicals        | object | `{ or: '|', and: ',' }`                           | Logical operators configuration.                 |
| key             | string | `"[A-Za-z0-9_]+"`                                 | RegExp string for matching keys.                 |
| value           | string | `".+"`                                            | RegExp string for matching values.               |
| operators       | array  | `['eq','ne','gt','ge','lt','le','li','nl','in','ni','be','nb','is','no']` |
| operatorPrefix  | string | `" "`                                             | Operator prefix.                                 |
| operatorSuffix  | string | `" "`                                             | Operator suffix.                                 |
| operatorFlags   | string | `"i"`                                             | Operator regexp flag.                            |
| separatorGroups | string | `";"`                                             | List values separator.                           |
| groups          | object | `{ start: '(', end: ')' }`                        | Conditions group delimiters.                     |

## Format

```js
const parser = new Parser();

parser.format({
  active: { eq: 1 },
  description: { li: '%casa' },
  or: [
    { deleted_at: { is: 'null' } },
    { age: { ge: 18 } }
  ]
});
// "active eq 1,description li %casa,(deleted_at is null|age ge 18)"
```

## Tests

In order to see more concrete examples, **I INVITE YOU TO LOOK AT THE TESTS :)**

### Run the unit tests
```bash
npm install
npm test
```

<!-- deep links -->
[install]: #download--install
[how_is_it_used]: #how-is-it-used
[tests]: #tests