@toa.io/rsql

RSQL

A parser of RSQL expressions, with no dependencies.

$ npm i @toa.io/rsql

import { parse } from '@toa.io/rsql'

parse('rank>5;name==*tea*')

{
  type: 'LOGIC',
  left: {
    type: 'COMPARISON',
    left: { type: 'SELECTOR', selector: 'rank' },
    operator: '>',
    right: { type: 'VALUE', value: '5' }
  },
  operator: ';',
  right: {
    type: 'COMPARISON',
    left: { type: 'SELECTOR', selector: 'name' },
    operator: '==',
    right: { type: 'VALUE', value: '*tea*' }
  }
}

Expression

written	in the tree	holds
== !=	as written	one value
< <= > >=	as written	one value
=lt= =le= =gt= =ge=	< <= > >=	one value
=in= =out=	as written	a list
; or and	;	two expressions
, or or	,	two expressions

; binds tighter than ,, and parentheses group: a==1,b==2;c==3 is a==1,(b==2;c==3).

=in= and =out= hold a list whether they are given one in parentheses or a single value: state=in=(hot,cold), state=in=hot. No other operator takes a list.

A selector is unquoted. A value is unquoted, or quoted with " or ' when it has whitespace or any of "'();,=!~<> in it; inside the quotes a backslash stands for the character after it: name=="hot \"tea\"".

Whitespace between the parts of an expression means nothing. and and or are ordinary words where a selector or a value is expected: and==or and or==and.

Values

A value is a string, unless parse is given a function that reads it as something else:

import { parse, type Literal } from '@toa.io/rsql'

function read({ text, quoted, selector, operator }: Literal): string | number | null {
  if (quoted) return text
  if (text === 'null') return null

  return selector === 'rank' ? Number(text) : text
}

const tree = parse('rank>5;state=in=(hot,"null",null)', read) // Expression<string | number | null>

It is called once for each value, a list's values one by one, in the order they are written. What it throws, parse throws, so it is also where a selector or a value an application does not accept is refused.

Errors

An expression that cannot be parsed throws a SyntaxError. Positions count from one.

message	when
Unexpected '~' at position 6	something is where it may not be
Unexpected end	the expression ends where it may not
Unknown operator '=like=' at position 5	an operator of the =name= form is none of the above
Unclosed quote at position 4	a quote opened there is never closed
Unclosed parenthesis at position 1	a parenthesis opened there is never closed
Expression is empty	there is nothing but whitespace

Coming from @rsql/parser

The tree has the shape @rsql/parser gives it, as plain objects. What differs:

• Operators are in one spelling: =gt= arrives as >, and as ;, or as ,.
• =in= and =out= always hold a list, and a list given to any other operator is refused.
• An operator the table above does not name is refused, where any =name= was accepted.
• and and or need no space after them: (a==1)and(b==2).
• Messages do not repeat the expression, a parenthesis left open is named by its position in the expression, and of several things wrong the first is reported.