Part of rapiq. Typed REST queries: build, transport, validate, execute. This is the validate end for URL-query-shaped input: plain objects and arrays go in, a schema-checked Query AST comes out.

• 📥 URL-query shaped: the value shapes a query string produces, under canonical parameter keys, e.g. { fields: [...], filters: {...}, sorts: '-age', … }.
• 🛡️ Schema-validated: anything outside the allow-list is dropped by default, or throws with throwOnFailure; absent parameters still receive schema defaults.
• 🔣 Compact operators: filter values carry inline operators like '>=18', '~jo~', '!5', null.
• 🧱 Per-parameter parsers: SimpleFieldsParser, SimpleFiltersParser, … are exported for parsing a single parameter.

Installation

npm install @rapiq/core @rapiq/parser-simple

Usage

import { SchemaRegistry, defineSchema } from '@rapiq/core';
import { SimpleParser } from '@rapiq/parser-simple';

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 },
}));

const parser = new SimpleParser(registry);

const query = parser.parse({
    fields: ['id', 'name'],
    filters: { name: '~jo~', age: '>=18' },
    relations: ['realm'],
    sorts: '-age',
    pagination: { limit: 25 },
}, { schema: 'user' });

Anything outside the schema's allow-lists is silently dropped; set throwOnFailure: true on the schema to get a ParseError instead. Parameters absent from the input still receive schema defaults.

The parser is transport-agnostic: it reads the canonical parameter keys (fields, filters, pagination, relations, sorts), and additionally accepts the deprecated sort spelling as an alias for sorts. It knows nothing about URL wire names: to consume a raw URL query string or an express-style req.query object (JSON:API wire names like filter, page, include), use the URL codec: its decoder maps the wire names and delegates to this parser.

Per-parameter parser classes (SimpleFieldsParser, SimpleFiltersParser, SimplePaginationParser, SimpleRelationsParser, SimpleSortsParser) are exported for parsing a single parameter.

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/packages/parser-simple. Per-parameter input shapes and operator syntax are on the parameter pages.

License

Published under the MIT License.