![\"rapiq\"](\"https://raw.githubusercontent.com/tada5hi/rapiq/master/.github/assets/logo.svg\"){kind=logo}
\n \n\n \n \n \n
\n Move a rapiq Query across a URL boundary, and back, losslessly.
\n Writes self-described expression filters; reads expression and legacy
\n JSON:API bracket filters, so applications migrate without a flag day.\n
\n ![\"npm](\"https://img.shields.io/npm/v/@rapiq/codec-url?color=%23a21caf&label=npm\")
![\"types\"](\"https://img.shields.io/npm/types/@rapiq/codec-url?color=%23db2777\")
![\"License:](\"https://img.shields.io/npm/l/@rapiq/codec-url?color=blue\")
\n Documentation\n ·\n Monorepo\n ·\n npm\n
\n\n---\n\nPart of [**rapiq**](https://github.com/tada5hi/rapiq). Typed REST queries: *build, transport, validate, execute.*\nThis 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.\n\n- 🔁 **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.\n- 🏷️ **In-band codec identity**: encoded payloads carry a reserved `codec` stamp, so decoding dispatches deterministically; unstamped input is probed via registered `detect` hooks.\n- 🧭 **Read-both, write-expression**: new payloads use expression filters; the decoder still accepts legacy `filter[name]=…` bracket filters for a gradual v2 migration.\n- 🔌 **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.\n\n## Installation\n\n```sh\nnpm install @rapiq/core @rapiq/parser-simple @rapiq/parser-expression @rapiq/codec-url\n```\n\n## Usage\n\n```typescript\nimport { createURLCodec } from '@rapiq/codec-url';\n\nconst codec = createURLCodec(schemaRegistry);\n\ncodec.encode(query);\n// codec=url-expression&filter=or(eq(name,'John'),gte(age,'18'))\n\ncodec.decode('codec=url-expression&filter=or(...)', { schema: 'user' });\ncodec.decode('filter[name]=John', { schema: 'user' }); // legacy simple input\n```\n\nEncoding uses `url-expression` by default. During the v2 migration, callers can explicitly request the deprecated simple writer:\n\n```typescript\nimport { URL_SIMPLE_CODEC } from '@rapiq/codec-url';\n\ncodec.encode(query, { codec: URL_SIMPLE_CODEC });\n// codec=url-simple&filter[name]=John\n```\n\nDecoding 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`.\n\nUse `encodeAsync()` and `decodeAsync()` when schema filter validators are asynchronous. Advanced callers can register a custom `URLCodecDefinition` on a `URLCodec` instance.\n\n## The rapiq family\n\n| Package | Purpose |\n|---|---|\n| [@rapiq/core](https://github.com/tada5hi/rapiq/tree/master/packages/core) | Query AST, typed build layer & schema system (the shared foundation) |\n| [@rapiq/parser-simple](https://github.com/tada5hi/rapiq/tree/master/packages/parser-simple) | Parse plain object/array input (the \"simple\" dialect) |\n| [@rapiq/parser-expression](https://github.com/tada5hi/rapiq/tree/master/packages/parser-expression) | Parse filter expressions like `and(eq(name,'John'), gte(age,'18'))` |\n| [@rapiq/parser-mongo](https://github.com/tada5hi/rapiq/tree/master/packages/parser-mongo) | Parse MongoDB-style filter documents like `{ age: { $gte: 18 } }` |\n| **[@rapiq/codec-url](https://github.com/tada5hi/rapiq/tree/master/packages/codec-url)** | URL query-string transport codec |\n| [@rapiq/adapter-sql](https://github.com/tada5hi/rapiq/tree/master/packages/adapter-sql) | Dialect-agnostic SQL fragment adapter (pg, mysql, sqlite, mssql, oracle) |\n| [@rapiq/adapter-typeorm](https://github.com/tada5hi/rapiq/tree/master/packages/adapter-typeorm) | Apply a query to a TypeORM `SelectQueryBuilder` |\n| [@rapiq/adapter-prisma](https://github.com/tada5hi/rapiq/tree/master/packages/adapter-prisma) | Serialize a query into a Prisma argument object |\n| [@rapiq/adapter-drizzle](https://github.com/tada5hi/rapiq/tree/master/packages/adapter-drizzle) | Serialize a query into a Drizzle relational query config |\n| [@rapiq/adapter-memory](https://github.com/tada5hi/rapiq/tree/master/packages/adapter-memory) | Evaluate a query against in-memory objects & arrays |\n\n## Documentation\n\nFull guide: [rapiq.tada5hi.net/packages/codec-url](https://rapiq.tada5hi.net/packages/codec-url)\n\n## License\n\nPublished under the [MIT License](https://github.com/tada5hi/rapiq/blob/master/LICENSE).\n","readmeFilename":"README.md"}