Part of rapiq. Typed REST queries: build, transport, validate, execute. This is the transport layer: one façade encodes a Query into a query string on the calling side and decodes it back into the same AST on the receiving side.

• 🔁 Lossless within a dialect: decode(encode(query)) restores the same query (modulo scalar type normalization); outside a dialect's subset, encode throws a typed error instead of silently changing semantics.
• 🏷️ In-band codec identity: encoded payloads carry a reserved codec stamp, so decoding dispatches deterministically; unstamped input is probed via registered detect hooks.
• 🧭 Read-both, write-expression: new payloads use expression filters; the decoder still accepts legacy filter[name]=… bracket filters for a gradual v2 migration.
• 🔌 Express-ready: feed it a raw query string or a pre-parsed req.query; it maps the JSON:API wire names (filter, page, include, …) and validates against your schema.

Installation

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

Usage

import { createURLCodec } from '@rapiq/codec-url';

const codec = createURLCodec(schemaRegistry);

codec.encode(query);
// codec=url-expression&filter=or(eq(name,'John'),gte(age,'18'))

codec.decode('codec=url-expression&filter=or(...)', { schema: 'user' });
codec.decode('filter[name]=John', { schema: 'user' }); // legacy simple input

Encoding uses url-expression by default. During the v2 migration, callers can explicitly request the deprecated simple writer:

import { URL_SIMPLE_CODEC } from '@rapiq/codec-url';

codec.encode(query, { codec: URL_SIMPLE_CODEC });
// codec=url-simple&filter[name]=John

Decoding dispatches on a stamped codec identifier first. For unstamped input, a string filter is treated as an expression and a bracket/object filter as the legacy simple dialect. Unknown stamped identifiers throw a typed CodecError.

Use encodeAsync() and decodeAsync() when schema filter validators are asynchronous. Advanced callers can register a custom URLCodecDefinition on a URLCodec instance.

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/codec-url

License

Published under the MIT License.