Crate restqs 

REST Query Syntax parser for REST API filtering plans.

RestQS parses RQS query strings into typed plans. The core parser does not emit SQL. Database and ORM translation lives in adapters, so application code can keep parsing, authorization, and persistence concerns separate.

A service starts with a FieldCatalog. The catalog maps public query fields to trusted database columns and value kinds. The parser checks every requested field against that catalog and returns RqsQuery.

Basic Parsing

use restqs::{FieldCatalog, parse};

let catalog = FieldCatalog::new()
    .allow_integer("age", "users.age")?
    .allow_text("status", "users.status")?;

let query = parse("age>=18&status=in(active,pending)", &catalog)?;

assert_eq!(query.filters().len(), 2);

Safe Defaults

RestQS treats query strings as untrusted input. User field names never become database identifiers. Adapters receive trusted catalog columns and typed RqsValue values.

The default ParserLimits cap raw query length at 8 KiB, parameter count at 128, single value length at 2 KiB, list item count at 100, and limit= at 100.

Adapter Boundary

The sqlx feature exposes SQLx-oriented fragment generation through [adapters::sqlx]. The adapter returns SQL fragments and bind values. The host repository still owns the final SQL statement, connection, transaction, and result mapping.

Modules

adapters

Adapter modules that translate RQS plans.

Structs

Field

One public field mapped to one database column.

FieldCatalog

Explicit allowlist for fields that can appear in RQS input.

FieldRef

Resolved field data stored in an RQS plan.

Filter

One filter in an RQS plan.

Pagination

Pagination selected by limit= and skip=.

Parser

RQS parser bound to one allowlist catalog.

ParserConfig

Parser configuration.

ParserLimits

Defensive parser limits used by the default parser.

Projection

Projection selected by fields=.

RegexLiteral

Regex literal parsed from slash form.

RqsQuery

Parsed RQS query plan.

SortTerm

One sort term.

Enums

FilterOp

Supported filter operators.

RqsError

RQS parser and adapter errors.

RqsValue

Value owned by an RQS plan.

SortDirection

Sort direction.

ValueKind

Value type expected by an allowlisted field.

Functions

parse

Parse an RQS string with default config.

Type Aliases

RqsResult

Result type used by RestQS.