Part of rapiq. Typed REST queries: build, transport, validate, execute. @rapiq/core owns the intermediate representation the whole pipeline revolves around: a typed Query AST (fields, filters, pagination, relations, sorts), the defineQuery build layer, the Schema allow-list system, and the visitor interfaces parsers, codecs and backend adapters implement.

• 🧭 Typed end to end: every field path in defineQuery<User> is checked against the record type; condition helpers (eq, gte, and, or, …) replace magic value strings.
• 🌳 One AST, many consumers: the same Query node graph is walked into SQL, a TypeORM builder or in-memory predicates through the visitor pattern; core never changes when a backend is added.
• 🛡️ Schema = the receiving side's allow-list: declare per-parameter allowed / default / mapping; parsers and codecs validate against it and drop or throw per policy.
• 🧩 Composable & immutable: mergeQueries uses keyed left priority for fields, relations and sorts, per-property left priority for pagination, and ordered logical AND for filters. The Filters combinators (merge, and, or) let a gateway add scope without losing predicates.

Installation

npm install @rapiq/core

Usage

Build a query

defineQuery builds the AST directly from typed input; every field path is checked against the record generic:

import { defineQuery, gte, or, eq } from '@rapiq/core';

const query = defineQuery<User>({
    fields: ['id', 'name'],
    filters: or(gte('age', 18), eq('deleted_at', null)),
    relations: ['realm'],
    sorts: '-created_at',
    pagination: { limit: 10 },
});

Filters accept scalars ({ name: 'John' }), bare arrays (in, null is a legal element), $-operator objects ({ age: { $gte: 18 } }) and condition helpers (eq, gte, inArray, and, or, …). Queries compose immutably with mergeQueries: filters are ordered logical AND, while keyed parameters use left priority. Use or(...) inside a filter tree for alternatives.

Declare what a caller may request

A Schema is the receiving side's allow-list: parsers and decoders validate incoming input against it:

import { SchemaRegistry, defineSchema } from '@rapiq/core';

const registry = new SchemaRegistry();

registry.add(defineSchema<User>({
    name: 'user',
    fields: { allowed: ['id', 'name', 'age'] },
    filters: { allowed: ['id', 'name', 'age'] },
    relations: { allowed: ['realm'] },
    sorts: { allowed: ['id', 'age'] },
    pagination: { maxLimit: 50 },
    schemaMapping: { realm: 'realm' },
}));

Consume the AST

Every node implements accept(visitor). Backends implement the visitor interfaces (IQueryVisitor, IFiltersVisitor, …) to walk a query into whatever they target. Ready-made adapters exist for SQL, TypeORM and in-memory data; parsers and URL codecs live in their own packages as well.

The rapiq family

| Package | Purpose | |---|---| | @rapiq/core | Query AST, typed build layer & schema system (the shared foundation) | | @rapiq/parser-simple | Parse plain object/array input (the "simple" dialect) | | @rapiq/parser-expression | Parse filter expressions like and(eq(name,'John'), gte(age,'18')) | | @rapiq/parser-mongo | Parse MongoDB-style filter documents like { age: { $gte: 18 } } | | @rapiq/codec-url | URL query-string transport codec | | @rapiq/adapter-sql | Dialect-agnostic SQL fragment adapter (pg, mysql, sqlite, mssql, oracle) | | @rapiq/adapter-typeorm | Apply a query to a TypeORM SelectQueryBuilder | | @rapiq/adapter-prisma | Serialize a query into a Prisma argument object | | @rapiq/adapter-drizzle | Serialize a query into a Drizzle relational query config | | @rapiq/adapter-memory | Evaluate a query against in-memory objects & arrays |

Documentation

Full guide: rapiq.tada5hi.net. See Building Queries, Schemas and Merging Queries.

License

Published under the MIT License.