Part of rapiq. Typed REST queries: build, transport, validate, execute. A tokenizer + recursive-descent parser for a compact, human-readable filter language: the default filter format the URL codec writes.

and(eq(name, 'John'), gte(age, '18'))
or(in(status, 'active', 'pending'), gt(age, '65'))
not(contains(user.name, 'Bob'))

• 🧵 One string, whole tree: arbitrary and / or / not nesting fits in a single value; ideal for URLs, saved filters and CLI flags.
• 🎯 Explicit operators: eq, ne, lt(e), gt(e), in, nin, contains, startsWith, endsWith, and their negations, with no operator guessing.
• 🛡️ Fails loud: syntax errors and schema violations throw FiltersParseError immediately; there is no silent-drop mode for malformed expressions.
• 🔗 Same AST as every dialect: only filters is expression-flavoured; fields, relations, pagination and sorts reuse @rapiq/parser-simple.

Installation

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

Usage

import { ExpressionParser } from '@rapiq/parser-expression';

const parser = new ExpressionParser(registry);

const query = parser.parse({
    filters: "and(eq(name, 'John'), gte(age, '18'))",
    sorts: '-age',
    pagination: { limit: 25 },
}, { schema: 'user' });

Only the filters parameter uses the expression language; fields, relations, pagination and sorts accept the same input as @rapiq/parser-simple, and the whole thing returns the same Query AST. A standalone parseFilters(input, options) returns just the Filters node.

The grammar: eq, ne, lt, lte, gt, gte, in, nin, contains, startsWith, endsWith (and negations) as leaf conditions, composed with and(…) / or(…) / not(…). Values are always single-quoted (gte(age, '18')); quoted numerals coerce to numbers, 'true' / 'false' to booleans, 'null' to null.

Syntax errors and schema violations throw FiltersParseError immediately; the expression parser has no silent-drop mode for malformed expressions.

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 (grammar & operator table): rapiq.tada5hi.net/packages/parser-expression

License

Published under the MIT License.