RSQL / FIQL

RSQL emitter and parser for Node.js and Browsers

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. FIQL is great for use in URI; there are no unsafe characters, so URL encoding is not required. On the other side, FIQL’s syntax is not very intuitive and URL encoding isn’t always that big deal, so RSQL also provides a friendlier syntax for logical operators and some of the comparison operators.

For example, you can query your resource like this: /movies?query=name=="Kill Bill";year=gt=2003 or /movies?query=director.lastName==Nolan and year>=2000. See examples below.

Source: https://github.com/jirutka/rsql-parser

Packages

This repository is a monorepo which means that it contains several packages. All packages are published on the npm registry under the @rsql/ scope.

Package	Version	Size	Description
@rsql/builder			Simple API for building RSQL
@rsql/parser			RSQL parser string => AST
@rsql/emitter			RSQL emitter AST => string
@rsql/ast			RSQL AST definitions and functions

Each package contains more detailed documentation. To learn more, click on the links above.

Installation

# with npm
npm install --save @rsql/builder

# with yarn
yarn add @rsql/builder

Features

• Fast LALR(1) implementation 🏎
• Small package size and 0 dependencies (because it was written by hand, not generated) 🚀
• Works both in Node.js and Browser environment 👌
• First class TypeScript support ✨
• Highly modular code - use what you really need 📦

Grammar

Based on the following specification: https://github.com/jirutka/rsql-parser#grammar-and-semantic

Custom operators

By default RSQL defines 8 built-in comparison operators: ==, !=, <, >, <=, >=, =in=, and =out=. You can define your custom operators - the only requirement is that they have to satisfy following regular expression: /=[a-z]+=/ (FIQL operator). The parser will accept any comparison that contains a valid operator. Because of that, you don't have to register it. Instead, we suggest defining your grammar as a module. Here is an example how you can define =all= and =empty= operator:

// src/rsql/ast.ts
const ALL = "=all=";
const EMPTY = "=empty=";

export * from "@rsql/ast";
export { ALL, EMPTY };

// src/rsql/builder.ts
import builder from "@rsql/builder";
import { ALL, EMPTY } from "./ast";

export default {
  ...builder,
  all(selector: string, values: string[]) {
    return builder.comparison(selector, ALL, values);
  },
  empty(selector: string, empty: boolean) {
    return builder.comparison(selector, EMPTY, empty ? "yes" : "no");
  },
};

Example

// parsing
import { parse } from "@rsql/parser";
const expression = parse("year>=2003");

// exploring
import { isComparisonNode, getSelector, getValue } from "@rsql/ast";
if (isComparisonNode(expression)) {
  console.log(`Selector: ${getSelector(expression)}`);
  // > Selector: year
  console.log(`Operator: ${expression.operator}`);
  // > Operator: >=
  console.log(`Value: ${getValue(expression)}`);
  // > Value: 2003
}

// building
import builder from "@rsql/builder";
const newExpression = builder.and(expression, builder.le("year", "2020"));

// emitting
import { emit } from "@rsql/emitter";
const rsql = emit(newExpression);
console.log(`Emitted: ${rsql}`);
// > Emitted: year>=2003;year<=2020

License

MIT