JSON:API-style
Fields, filters, relations, pagination & sort — one consistent query scheme based on the JSON:API specification.
Skip to content
rapiq
One query language between client & server. Build JSON:API-style queries on the client, parse them into a typed AST against schema allow-lists on the server — and turn them into SQL or TypeORM queries with composable adapters.
SQL dialect
/users?fields=id,name,age&filter[name]=~to~&filter[age]=%3E%3D21&page[limit]=25&sort=-ageSELECT "id", "name", "age"
FROM "users"
WHERE ("name" ~* $1 and "age" >= $2)
ORDER BY "age" DESC
LIMIT 25 -- params: ["to",21]
Live — @rapiq/parser-simple, @rapiq/codec-url-simple and @rapiq/sql are running in your browser.
A pipeline, not a parser
Typed query AST
Input parses into Query nodes that backends consume via the visitor pattern — new targets never touch core.
Schema allow-lists
Declare what clients may request — allowed keys, defaults, mappings. Disallowed input is dropped or throws.
Pluggable parsers
Parse plain objects or an expression language — both dialects produce the exact same Query AST.
SQL & TypeORM
Render parameterized SQL for five dialects, or apply a Query straight to a TypeORM SelectQueryBuilder.
TypeScript-first
Typed key paths via recursive NestedKeys<T> — allow-lists and defaults autocomplete against your records.
One AST, six packages
rapiq is a family of focused, composable packages. Install only what each side of your application needs — everything meets in the core query AST.
@rapiq/core
The foundation — query AST, visitor interfaces and the schema system everything else builds on.
- Fields, Filters, Pagination, Relations & Sorts nodes
- defineSchema() + SchemaRegistry allow-lists
- Parser base classes & typed errors
@rapiq/parser-simple
Parses plain object/array input — the URL-query-like "simple" dialect.
- Filters like { age: '>=18', name: '~jo~' }
- Schema validation while parsing
- Powers the URL decoder
@rapiq/parser-expression
Parses an expression language into the same Query AST.
- and(eq(name, 'John'), gte(age, '18'))
- Tokenizer + recursive-descent parser
- Compound and/or conditions with negation
@rapiq/codec-url-simple
URL query-string codec — the transport between client and server.
- URLEncoder: Query AST → query string
- URLDecoder: query string → Query AST
- JSON:API-style parameter names
@rapiq/sql
Dialect-agnostic SQL adapter turning the AST into parameterized fragments.
- Presets: Postgres, MySQL, SQLite, MSSQL, Oracle
- Dialects are option objects, not subclasses
- Visitor-driven — fragments accumulate per parameter
@rapiq/typeorm
Applies a parsed Query directly to a TypeORM SelectQueryBuilder.
- Mutates the query builder in place
- Relations become joins automatically
- Builds on the @rapiq/sql visitors
From client to query in three steps
Build on the client, transport as a query string, parse & validate on the server.
# client side — build & encode queries
npm install @rapiq/core @rapiq/codec-url-simple
# server side — parse, validate & translate
npm install @rapiq/core @rapiq/parser-simple @rapiq/sql@rapiq/typeorm
Straight into TypeORM
Apply a parsed Query directly to a SelectQueryBuilder — the adapter walks the AST and mutates the builder, nothing is stringified twice.
- TypeormAdapter — wraps any SelectQueryBuilder
- Visitor-driven — reuses the @rapiq/sql visitors
- Relations → joins — allowed relations join automatically
- Parameterized — filter values bind as parameters, never interpolated
import { FiltersVisitor } from '@rapiq/sql';
import { TypeormAdapter } from '@rapiq/typeorm';
const queryBuilder = repository.createQueryBuilder('user');
const adapter = new TypeormAdapter();
adapter.withQuery(queryBuilder);
query.filters.accept(new FiltersVisitor(adapter.filters));
adapter.execute();
const [entities, total] = await queryBuilder.getManyAndCount();