@mw-experts/rsql

RSQL / FIQL tools

Complete and thoroughly tested parser for RSQL/FIQL written in Typescript(Javascript). Tools to work with RSQL: matcher, filter, converter to SQL. Built with zero dependencies.

Installing

npm install @mw-experts/rsql

or

yarn add @mw-experts/rsql

Usage

Import library

Import library as CommonJS module:

const rsql = require('@mw-experts/rsql');

Import library as ES6 module:

import { RsqlMatcher } from '@mw-experts/rsql';
import { RsqlFilter } from '@mw-experts/rsql';
import { RsqlToSqlConverter } from '@mw-experts/rsql';

or

import * as rsql from '@mw-experts/rsql';

Import library as standalone script in a browser:

<script src="../node_modules/@mw-experts/rsql/dist/rsql-browser.js"></script>

About RSQL / FIQL

RSQL is a query language for parametrized filtering of entries in RESTful APIs.

It’s based on FIQL (Feed Item Query Language) an URI-friendly syntax for expressing filters across the entries in an Atom Feed.

The simplicity of RSQL and its capability to express complex queries in a compact and HTTP URI-friendly way makes it a good candidate for becoming a generic query language for searching REST endpoints.

For example, you can query your resource like this:

/movies?search=name=="Kill Bill";year=gt=2003

or

/movies?search=director.lastName==Nolan and year>=2000.

RSQL introduces simple and composite operators which can be used to build basic and complex queries.

Basic operators:

Basic Operator	Description
==	Equal To
!=	Not Equal To
=gt=	Greater Than
>	Greater Than
=ge=	Greater Or Equal To
>=	Greater Or Equal To
=lt=	Less Than
<	Less Than
=le=	Less Or Equal To
<=	Less Or Equal To
=in=	In
=out=	Not in
=includes-all=	Includes all
=includes-one=	Includes one

These operators can be used to do all sort of simple queries, for example:

• name==Fero: find all people whose name is Fero
• street!=Darna: find all people who do not live at Darna
• age=gt=10: find all people older than 10 (exclusive)
• age>10: find all people older than 10 (exclusive)
• age=ge=10: find all people older than 10 (inclusive)
• age>=10: find all people older than 10 (inclusive)
• house=lt=3: find all people who have less than 3 houses
• house<3: find all people who have less than 3 houses
• house=le=3: find all people who have less than or 3 houses
• house<=3: find all people who have less than or 3 houses
• name=in=(Fero,Jane) find all people whose name is Fero or Jane
• name=out=(Alex,Mike) find all people whose name is not Alex or Mike
• list=includes-all=(item1,item2) find all records where list is array and includes item1 and item2
• list=includes-one=(item1,item2) find all records where list is array and includes item1 or item2

Composite operators:

Composite Operator	Description
;	Logical AND
and	Logical AND
,	Logical OR
or	Logical OR

These operators can be used to join the simple queries and build more involved queries which can be as complex as required. Here are some examples:

• age=gt=10;age=lt=20: find all people older than 10 and younger than 20
• age=gt=10 and age=lt=20: find all people older than 10 and younger than 20
• age=lt=5,age=gt=30: find all people younger than 5 or older than 30
• age<5 or age>30: find all people younger than 5 or older than 30
• age=gt=10;age=lt=20;name=in=(Fero,Jane): find all people older than 10 and younger than 20 with names either Fero or Jane.

Fields and Values

Fields can only consist of next regexp symbols: [\w-.] (A-Za-z0-9_-.)

• field.name==value
• field-name==value
• field_name==value
• FieldName==value
• FIELD_NAME_777==value

Values can only consist of next regexp symbols:

• in double quotes - space, any unicode letter, any unicode number, _, -, ., ', (, )
• in single quotes - space, any unicode letter, any unicode number, _, -, ., ", (, )
• without quotes - any unicode letter, any unicode number, _, -, .
• with == or != operators you can also use asterisk * as a wildcard

Ordering

By default, operators evaluated from left to right. However, a parenthesized expression can be used to change the precedence.

• age=lt=20;(name==Fero,name==Jane): find all people younger than 20 with names either Fero or Jane.

Convert RSQL to SQL

const rsqlStr = 'name=="Kill Bill",year=ge=2000';
let result;

try {
  result = rsql.RsqlToSqlConverter.getInstance().convert(rsqlStr);
} catch (e) {
  console.warn(e);
}

console.log(result);

// will output:
// ("name" = 'Kill Bill' OR "year" >= '2000')

You can have different field names wrapper, for example if you use Mysql. Just pass a second argument to convert method like this:

const rsqlStr = 'name=="Kill Bill",year=ge=2000';
let result;

try {
  result = rsql.RsqlToSqlConverter.getInstance().convert(rsqlStr, '`');
} catch (e) {
  console.warn(e);
}

console.log(result);

// will output:
// (`name` = 'Kill Bill' OR `year` >= '2000')

• "=includes-all=", "=includes-one=" operators are not supported in RsqlToSqlConverter
• Not included in browser bundle

Filter array of objects

const data = [
  { name: 'Kill Bill', year: 2006 },
  { name: 'Terminator', year: 1998 },
  { name: 'Matrix', year: 2000 },
];

const rsqlStr = 'name=="Kill Bill",year=ge=2000';
let result = [];

try {
  result = rsql.RsqlFilter.getInstance().filter(rsqlStr, data);
} catch (e) {
  console.warn(e);
}

console.log(result);

// will output:
// [
//  { name: 'Kill Bill', year: 2006 },
//  { name: 'Matrix', year: 2000 },
// ]

You can ask for deep nested properties using dot separator - someObj.prop, or array notation - someList[0].prop:

const data = [
    {
        deep: {
            nested: {
                field: 777
            }
        },
        list: [1, 2, 3]
    }
]

const rsql = 'deep.nested.field==777';
const rsql = 'list[1]==2';

Match item

const data = { name: 'Matrix', year: 2000 };

const rsqlStr = 'name=="Kill Bill";year=ge=2000';

try {
  result = rsql.RsqlMatcher.getInstance().match(rsqlStr, data);
} catch (e) {
  console.warn(e);
}

console.log(result);

// will output: false

Value part of matching expression also can be used as path to value, example:

const data = [
    {
        deep: {
            nested: {
                field: 2
            }
        },
        list: [1, 2, 3]
    }
]

const rsqlStr = 'deep.nested.field==list[1]';

try {
  result = rsql.RsqlMatcher.getInstance().match(rsqlStr, data);
} catch (e) {
  console.warn(e);
}

console.log(result);

// will output: true

Match many items

typescript version:

const rsqlStr = 'name=="Kill Bill";year=ge=2000';

const tokens: Token<RsqlTokenType>[] = RsqlTokenizer.getInstance().tokenize(rsqlStr);
const ast: RsqlAstRootNode = RsqlParser.getInstance().parse(tokens);
const matcher: RsqlMatcher = RsqlMatcher.getInstance();

try {
  result1 = matcher.matchWithPreparedAst(ast, { name: 'Matrix', year: 2000 });
  result2 = matcher.matchWithPreparedAst(ast, { name: 'Kill Bill', year: 2021 });
} catch (e) {
  console.warn(e);
}

console.log(result1);
// will output: false

console.log(result2);
// will output: true

javascript version:

const rsqlStr = 'name=="Kill Bill";year=ge=2000';

const tokens = rsql.RsqlTokenizer.getInstance().tokenize(rsqlStr);
const ast = rsql.RsqlParser.getInstance().parse(tokens);
const matcher = rsql.RsqlMatcher.getInstance();

try {
  result1 = matcher.matchWithPreparedAst(ast, { name: 'Matrix', year: 2000 });
  result2 = matcher.matchWithPreparedAst(ast, { name: 'Kill Bill', year: 2021 });
} catch (e) {
  console.warn(e);
}

console.log(result1);
// will output: false

console.log(result2);
// will output: true

Filter and Matcher is case-insensitive

• name==Marina and name==marina will give the same results - Marina, marina

Usage of wildcard

You can use wildcard * in == and != operators. Example:

• name==Ma* find all items where name starts from Ma - Marina, Maxim, Maria
• value==*de* find all items where value starts and ends with any symbols - Made, abcdefg

Comparison rules:

• "==", "!=" before comparison data converts to string
• "=gt=", ">", "=ge=", ">=", "=lt=", "<", "=le=", "<=" before comparison data converts to number
• "=in=", "=out=" before comparison data converts to string
• "=includes-all=", "=includes-one=" before comparison data converts to array of strings

Authors

• Andrey Korovin - misticwonder

License

This project is licensed under the MIT License - see the LICENSE.md file for details