https://github.com/nfroidure/strict-qs
A stricter query string parser
https://github.com/nfroidure/strict-qs
hacktoberfest javascript parser querystrings strict-types
Last synced: 7 months ago
JSON representation
A stricter query string parser
- Host: GitHub
- URL: https://github.com/nfroidure/strict-qs
- Owner: nfroidure
- License: mit
- Created: 2016-12-11T10:34:46.000Z (about 9 years ago)
- Default Branch: main
- Last Pushed: 2025-01-29T15:47:02.000Z (12 months ago)
- Last Synced: 2025-05-29T01:05:50.675Z (8 months ago)
- Topics: hacktoberfest, javascript, parser, querystrings, strict-types
- Language: TypeScript
- Homepage: http://insertafter.com/en/blog/toward_stricter_query_string_parser.html
- Size: 1.09 MB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
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)
## 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)