@ts-awesome/rest-query

TypeScript friendly query parser extension for Rest

Key features:

minimalistic query language
support for logical operation and grouping
complementary with @ts-awesome/rest

ISimpleQuery language guide is here

Base use

import {parser} from "@ts-awesome/rest-query";

const input = {
  q: 'a > 5 && b = "test"',
  limit: 10,
  offset: 0,
  order: 'a+,b-,c',
  count: false,
};

const parsed = parser(input);

Outputs:

{
  "query": {
    "$and": [
      { "$gt": {"a": 5}},
      { "$eq": {"b": "test"}},
    ] 
  },
  "limit": 10,
  "offset": 0,
  "orderBy": [{"a": "ASC"},{"b": "DESC"},{"c": "ASC"}],
  "countOnly": false
}

Use with @ts-awesome/rest

import {Route, httpGet, queryParam} from "@ts-awesome/rest";
import {QueryParserMiddleware} from "@ts-awesome/rest-query";

@httpGet('/test', QueryParserMiddleware)
export class TestRoute extends Route {
  async handle(
    @queryParam('query', true) query: ISimpleQuery | null,
    @queryParam('orderBy', true) orderBy: IOrderBy[] | null,
    @queryParam('offset', Number, true) offset: number | null,
    @queryParam('limit', Number, true) limit: number | null,
    @queryParam('countOnly', Boolean) countOnly: boolean,
  ) {
    // something important happens here
  }
}

Query language

Literals

NULL
Identifiers - e.g. property names
Escaped identifiers - names wrapped into ` quotes
Strings - single- or double-quoted
Boolean - true or false
Numbers:
- Binary - 0b01010101
- Octal - 0o123456
- Hexadecimal - 0x1234567890abcdef
- Integers - -123456
- Floats - -123.456
- Scientific -0.5e-3
Arrays - e.g. [1,2,3]

Operators

= - equality e.g. a = 5
!= - non equal e.g. a != b
>
>=
<
<=
~ - like e.g. a ~ "%some%" - a should contain string some
^ - in e.g. a ^ [1,2,3] or "some" ^ b

Logic

! - not, e.g. !a
&& - and, e.g a = 5 && b != 2
|| - or, e.g a || !b

Expressions

You can use parenthesis to construct proper expressions

(a = 5) || ((b = 2) && (c ^ [1,2,3]))

Use in URI

Keep in mind that You should properly encode URI component before including it in URL

const query = `a = 5 && !c && b ~ "some%"`;
const url = `https://example.org?q=${encodeURIComponent(query)}&offset=0&limit=10`;

// https://example.org?q=a%20%3D%205%20%26%26%20!c%20%26%26%20b%20~%20%22some%25%22&offset=0&limit=10

License

May be freely distributed under the MIT license.