# strict-qs
> A stricter Query String parser
Latest version **10.0.0** (published 2026-04-07) · MIT license · 0 weekly downloads
## Install
```sh
npm install strict-qs
pnpm add strict-qs
yarn add strict-qs
bun add strict-qs
```
## Health
**Score 60/100 (C)** — status: active.
Positive: has types; esm support; no vulnerabilities; high quality score.
Warnings: low downloads.
## Facts
| | |
|---|---|
| Version | 10.0.0 |
| Published | 2026-04-07 |
| First published | 2016-12-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=24.14.0 |
| Dependencies | 2 |
| Unpacked size | 77.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | Nicolas Froidure |
| Maintainers | nfroidure |
| Keywords | qs, query, string, parser |
## Links
- npm: https://www.npmjs.com/package/strict-qs
- Repository: https://github.com/nfroidure/strict-qs
- Homepage: https://github.com/nfroidure/strict-qs#readme
- Issues: https://github.com/nfroidure/strict-qs/issues
- Funding: https://github.com/sponsors/nfroidure
- npm.io page: https://npm.io/package/strict-qs
## Dependencies (2)
- [debug](https://npm.io/package/debug.md) ^4.4.0
- [yerror](https://npm.io/package/yerror.md) ^11.0.0
## Alternatives
- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads
## Recent versions
- 10.0.0 (latest) — 2026-04-07
- 9.0.0 — 2026-03-27
- 8.0.3 — 2024-07-15
- 8.0.2 — 2024-02-24
- 8.0.1 — 2023-08-16
- 8.0.0 — 2023-08-12
- 7.0.2 — 2023-01-05
- 7.0.1 — 2022-09-01
- 7.0.0 — 2022-06-06
- 6.1.5 — 2022-05-25
- 6.1.4 — 2021-04-09
- 6.1.3 — 2020-09-14
- 6.1.2 — 2020-05-17
- 6.1.1 — 2020-04-01
- 6.1.0 — 2020-04-01
- … 20 more at https://npm.io/package/strict-qs/versions
## README
[//]: # ( )
[//]: # (This file is automatically generated by a `metapak`)
[//]: # (module. Do not change it except between the)
[//]: # (`content:start/end` flags, your changes would)
[//]: # (be overridden.)
[//]: # ( )
# strict-qs
> A stricter Query String parser
[](https://github.com/nfroidure/strict-qs/blob/main/LICENSE)
[](https://coveralls.io/github/nfroidure/strict-qs?branch=main)
[//]: # (::contents:start)
A stricter query string parser allows to ensure URIs uniqueness and better
caching through your own cache but also public HTTP proxies for public
endpoints.
To ensure URIs uniqueness, `strict-qs` checks:
- the order in which query strings are set,
- query parameters values aren't set to their default values,
- values set are reentrant (ie: `1.10` will be refused, its
canonical form `1.1` will be required),
- query parameters used are existing and effective,
- items collections are sorted (by value for number, alpha-numeric for strings).
As a side effect, it also cast values from strings to
their target types.
You may wonder if it is not overkill to be that strict.
On every projects I worked on, I never been sad to have
built too strict systems. The inverse is not true ;).
Also, it may be less pain to handle such strictness if
you generate client APIs that handle that strictness for
you, which is recommended. You can see an example of such
client [here](https://github.com/sencrop/sencrop-js-api-client).
## Usage
```js
import qs from 'strict-qs';
// The definition formatting is swagger compatible
// but only for the subset I use. PRs are welcome
// for broader support
const qsDefinition = [{
name: 'lang',
in: 'query',
type: 'string',
required: true,
description: 'The language for the search'
}, {
name: 'types',
in: 'query',
type: 'array',
items: {
type: 'string',
enum: ['open', 'closed', 'pending', 'idle', 'invalid'],
},
description: 'The types of the search'
}, {
name: 'code',
in: 'query',
type: 'integer',
description: 'The code id'
}];
qs(
qsDefinition,
'?lang=fr&types=open&types=closed&types=pending&code=3'
);
// Returns
{
lang: 'fr',
types: ['open', 'closed', 'pending'],
code: 3
}
qs(
qsDefinition,
'?code=3&lang=fr&types=open&types=closed&types=pending'
);
// throws an error since the order is bad
new Error('E_BAD_QUERY_PARAM', 'types')
```
The returned query parameters should still be validated with
any JSON Schema validator. You can see how it is done in
[swagger-http-router](https://github.com/nfroidure/swagger-http-router)
for instance.
[//]: # (::contents:end)
# API
## qsStrict(options, definitions, search) ⇒ Object
Parse a queryString according to the provided definitions
**Kind**: global function
**Returns**: Object - The parsed properties
| Param | Type | Description |
| --- | --- | --- |
| options | Object | Parser options |
| options.allowEmptySearch | Boolean | Avoid throwing when the search is empty |
| options.allowUnknownParams | Boolean | Avoid throwing when some params are unknown |
| options.allowDefault | Boolean | Avoid throwing when some params is set to its default value |
| options.allowUnorderedParams | Boolean | Avoid throwing when params are not set in the same order than declarations |
| definitions | Array | Swagger compatible list of defitions |
| search | string | The actual query string to parse |
**Example**
```js
import qs from 'strict-qs';
const qsOptions = { allowEmptySearch: true };
const qsDefinition = [{
name: 'pages',
in: 'query',
type: 'array',
items: {
type: 'number',
},
ordered: true,
description: 'The pages to print',
}];
qs(qsOptions, qsDefinition, '?pages=0&pages=1&pages=2');
// Returns:
// {
// pages: [0, 1, 2], // eslint-disable-line
// }
```
# Authors
- [Nicolas Froidure](http://insertafter.com/en/index.html)
# License
[MIT](https://github.com/nfroidure/strict-qs/blob/main/LICENSE)
---
_Source: https://npm.io/package/strict-qs · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._