Skip to content

RSQL compiler and parser for Node.js and Browsers

Notifications You must be signed in to change notification settings

piotr-oles/rsql

Repository files navigation

RSQL / FIQL

RSQL emitter and parser for Node.js and Browsers

lerna code style: prettier commitizen friendly tested with jest auto release

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 npm size Simple API for building RSQL
@rsql/parser npm size RSQL parser string => AST
@rsql/emitter npm size RSQL emitter AST => string
@rsql/ast npm size 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

About

RSQL compiler and parser for Node.js and Browsers

Resources

Stars

Watchers

Forks

Sponsor this project

 

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •