javascript-rql
Version:
Javascript RQL lib to transform js object to rql query string
308 lines (261 loc) • 6.8 kB
Markdown
# Javascript RQL
[](https://travis-ci.org/cloudblue/javascript-rql)
[](https://codecov.io/gh/cloudblue/javascript-rql)
[](https://img.shields.io/npm/v/javascript-rql)
[](https://sonarcloud.io/dashboard?id=javascript-rql)
The javascript-rql is a simple and powerful library to transform javascript object to valid rql query string. Supports queries of any complexity (any nesting).
## RQL
RQL (Resource query language) is designed for modern application development. It is built for the web, ready for NoSQL, and highly extensible with simple syntax.
This is a query language fast and convenient database interaction. RQL was designed for use in URLs to request object-style data structures.
[RQL Reference](https://connect.cloudblue.com/community/api/rql/)
[RQL for Web](https://www.sitepen.com/blog/resource-query-language-a-query-language-for-the-web-nosql/)
[Django RQL](https://github.com/cloudblue/django-rql)
## Install
To install the javascript-rql from a terminal window type:
```sh
$ npm install --save javascript-rql
```
## Interface
Javascript object with rql expressions should implement the following interface (typescript example):
```typescript
interface IRQLExpression {
$eq?: string|number,
$ne?: string|number,
$not?: IRQLExpression,
$gt?: number,
$ge?: number,
$lt?: number,
$le?: number,
$like?: string,
$ilike?: string,
$in?: Array<number|string>,
$out?: Array<number|string>,
$range?: {
min: number,
max: number,
},
}
interface IRQL {
$and? Array<IRQL>
$or?: Array<IRQL>;
$ordering?: Array<string>;
$select?: Array<string>;
limit?: number;
offset?: number;
[key: string]?: string|number|Array<string|number>|boolean|IRQLExpression;
}
```
## Usage
You can import rql function:
```js
import { rql } from 'javascript-rql';
```
or
```js
const { rql } = require('javascript-rql');
```
and use:
```js
rql(rqlObject);
```
## Examples
##### Simple filters
```js
const filter = {
name: 'eugene',
age: 13,
};
rql(filter); // 'name=eugene&age=13'
```
##### Filters with text matching
```js
const filter = {
name: {
$like: 'vasya*',
$ilike: '***New',
},
city: {
$like: {
start: 'M',
end: 'w',
},
$ilike: {
start: 'M',
},
},
country: {
$like: {
end: 'a',
},
$ilike: {
pattern: '*u*ss*',
start: 'R',
end: 'a',
},
},
area: {
$ilike: true,
$like: {
invalidKey: 'qwe',
},
},
};
rql(filter); //'like(name,*vasya\**)&ilike(name,*\*\*\*New*)&like(city,M*w)&ilike(city,M*)&like(country,*a)&ilike(country,R*a)&ilike(country,*u*ss*)like(name,*vasya\**)&ilike(name,*\*\*\*New*)&like(city,M*w)&ilike(city,M*)&like(country,*a)&ilike(country,R*a)&ilike(country,*u*ss*)'
```
##### Filter with list
```js
const filter = {
age: {
$out: [1, 2],
},
num: {
$in: [3, 4, 5],
},
};
rql(filter); //'out(age,(1,2))&in(num,(3,4,5))'
```
##### Filters with range
```js
const filter = {
age: {
$range: {
max: 5,
min: 9,
},
},
};
rql(filter); //'range(age,9,5)'
```
##### Filters with relationals
```js
const filter = {
name: {
$eq: 'vasya',
},
age: {
$gt: 1,
$lt: 8,
},
num: {
$lte: 9,
$gte: 4,
},
};
rql(filter); //'eq(name,vasya)>(age,1)<(age,8)<e(num,9)>e(num,4)'
```
##### Filters with logical NOT
```js
const filter = {
name: {
$not: [{
$eq: 'vasya',
}, {
$eq: 'petya',
}],
},
age: {
$not: {
$eq: 10,
$in: [1, 2, 3],
},
},
};
rql(filter); //'not(eq(name,vasya))¬(eq(name,petya))¬(eq(age,10))¬(in(age,(1,2,3)))'
```
##### Filters with logical OR
```js
const filter = {
// You can use $or inside field
color: {
$or: [
// Inside { } may be some conditions and for all them is used logical operator AND
{ $eq: 'red' },
{ $eq: 'blue' },
{ $eq: 'yellow' },
],
},
// Also you can use $or in root level, then inside must be objects array with fields name
$or: [
// Inside { } may be some fields with conditions and for all them is used logical operator AND
{ product: 'TV' },
{ product: 'Computer' },
],
};
rql(filter); //'(((eq(color,red))|(eq(color,blue)))|(eq(color,yellow)))&((product=TV)|(product=Computer))'
```
##### Combine AND and OR filters
```js
// When you need to use same keys in and conditions (for example with OR) you can use special logical AND:
const filter = {
$and: [
{
$or: [
{status: 'new'},
{type: 'program'},
],
},
{
$or: [
{status: 'done'},
{type: 'service'},
]
},
]
};
rql(filter); // "(((status=new)|(type=program)))&(((status=done)|(type=service)))"
```
##### Filters with control operators
We support 2 key for ordering: ordering and sort. Use the one which is implemented by the backend.
```js
const filter = {
$select: ['products', 'agreements'],
$ordering: '-created',
$sort: ['-name'],
$limit: { start: 10, count: 100 },
};
rql(filter); //Result: 'select(products,agreements)&ordering(-created)&sort(-name)&limit(10,100)'
```
##### Combine any filters in one query
```js
const combinationFilter = {
offset: 0,
limit: 10,
$select: ['products', 'agreements'],
$ordering: ['title', '-created'],
$or: [
{
type: 'distribution',
owner: { $eq: 'me' },
},
{
type: { $in: ['sourcing', 'service'] },
owner: { $not: { $eq: 'me' } },
},
],
name: {
$or: [
{ $like: 'my test' },
{ $like: 'my' },
{ $ilike: '***CONTRACT' },
],
},
};
rql(filter); //'offset=0&limit=10&select(products,agreements)&ordering(title,-created)&((type=distribution&eq(owner,me))|(in(type,(sourcing,service))¬(eq(owner,me))))&(((like(name,"*my test*"))|(like(name,*my*)))|(ilike(name,*\*\*\*CONTRACT*)))'
```
##### Filters with empty values
```js
// If values are empty, null, undefined then they will not be in the query.
const filter = {
$select: [],
$ordering: [],
name: '',
age: null,
$or: [{name: undefined}],
type: 'pending',
};
rql(filter); //'type=pending'
```
## Contribute
If you want to contribute to the javascript-rql development feel free to open issues or fork the github repository and submit your pull request.
## License
The javascript-rql is licensed under the [*Apache License 2.0*](http://www.apache.org/licenses/LICENSE-2.0).