@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.

Copyright (c) 2022 Volodymyr Iatsyshyn and other contributors