Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/piotr-oles/rsql
RSQL compiler and parser for Node.js and Browsers
https://github.com/piotr-oles/rsql
Last synced: 2 months ago
JSON representation
RSQL compiler and parser for Node.js and Browsers
- Host: GitHub
- URL: https://github.com/piotr-oles/rsql
- Owner: piotr-oles
- Created: 2019-10-25T14:30:15.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2023-07-18T21:39:46.000Z (over 1 year ago)
- Last Synced: 2024-10-13T10:20:58.459Z (3 months ago)
- Language: TypeScript
- Size: 1.24 MB
- Stars: 45
- Watchers: 3
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
RSQL / FIQL
RSQL emitter and parser for Node.js and Browsers
[](https://lerna.js.org/)
[](https://github.com/prettier/prettier)
[](http://commitizen.github.io/cz-cli/)
[](https://github.com/facebook/jest)
[](https://github.com/intuit/auto)
> 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](https://www.npmjs.com/) under the `@rsql/` scope.
| Package | Version | Size | Description |
| ------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------- |
| [`@rsql/builder`](./packages/builder) | [](https://www.npmjs.com/package/@rsql/builder) |  | Simple API for building RSQL |
| [`@rsql/parser`](./packages/parser) | [](https://www.npmjs.com/package/@rsql/parser) |  | RSQL parser `string => AST` |
| [`@rsql/emitter`](./packages/emitter) | [](https://www.npmjs.com/package/@rsql/emitter) |  | RSQL emitter `AST => string` |
| [`@rsql/ast`](./packages/ast) | [](https://www.npmjs.com/package/@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:
```typescript
// 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
```typescript
// 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