https://github.com/stein197/js-qs
Simple bundle of JavaScript functions to make work with query string easer
https://github.com/stein197/js-qs
parser query-string querystring
Last synced: about 1 month ago
JSON representation
Simple bundle of JavaScript functions to make work with query string easer
- Host: GitHub
- URL: https://github.com/stein197/js-qs
- Owner: stein197
- License: mit
- Created: 2019-12-02T11:01:27.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2023-07-18T08:34:34.000Z (over 2 years ago)
- Last Synced: 2025-11-23T15:05:43.870Z (4 months ago)
- Topics: parser, query-string, querystring
- Language: TypeScript
- Homepage:
- Size: 144 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# JavaScript query string params parser and reader
[](https://www.npmjs.com/package/@stein197/qs)
[](LICENSE)
URL Query string parser and stringifier. The package allows to customize parsing and stringifying process.
## Installation
```
npm install @stein197/qs
```
## Usage
Here is the example of simple usage:
```ts
import * as qs from "@stein197/qs";
qs.stringify({a: 1, b: 2}); // "a=1&b=2"
qs.parse("a=1&b=2"); // {a: 1, b: 2}
```
## Key features
- [Nesting structures support](#nesting-structures-support)
- [Omitting redundant indices](#omitting-redundant-indices)
- [Inferring arrays where possible](#inferring-arrays-where-possible)
- [Inferring primitive types where possible](#inferring-primitive-types-where-possible)
- [Inferring flags](#inferring-flags)
- [Encoding and decoding](#encoding-and-decoding)
- [Sparse arrays support](#sparse-arrays-support)
- [Custom encoders and decoders](#custom-encoders-and-decoders)
### Nesting structures support
You can pass to both functions complex structures, which includes objects and arrays:
```ts
qs.parse("a[b]=2"); // {a: {b: 2}}
qs.stringify({a: {b: 2}}); // "a[b]=2"
```
The complexity of structures is unlimited - you can parse/stringify structures of any depth and type (object or array)
### Omitting redundant indices
The indices of arrays of stringified result could be omitted where possible. You can disable this option by providing `indices` option with `true` value. You cannot do this properly with [qs](https://github.com/ljharb/qs), especially when it deals with deeply nested arrays.
```ts
qs.stringify({a: [1, 2, 3]}); // "a[]=1&a[]=2&a[]=3"
```
Indices could be ommited for more deep structures.
### Inferring arrays where possible
The arrays could be inferred from query string where possible:
```ts
qs.parse("a[]=1"); // {a: [1]}
qs.parse("a[0]=1"); // {a: [1]}
```
Arrays could be inferred from more deep structures.
### Inferring primitive types where possible
By default, `parse()` function will try to cast string values to corresponding types where possible (undefined, null, boolean or number).
```ts
qs.parse("a=undefined&b=null&c=false&d=-1"); // {a: undefined, b: null, c: false, d: -1}
```
### Inferring flags
When an item doesn't have both value and separator, then `true` is returned for this specific key:
```ts
qs.parse("a=1&b"); // {a: 1, b: true}
qs.stringify({a: 1, b: true}); "a=1&b"
```
### Encoding and decoding
When parsing and stringifying, special characters will be percent-encoded/decoded:
```ts
qs.parse("a=%20"); // {a: " "}
qs.stringify({a: "&"}); // "a=%26"
```
### Sparse arrays support
Since the package supports arrays, it supports sparse ones:
```ts
qs.parse("a[1]=1"); // {a: [, 1]}
qs.stringify({a: [, 1]}); // "a[1]=1"
```
### Custom encoders and decoders
If it's not enough, then you can provide an encoder and a decoder down to both functions like as follows:
```ts
qs.parse("a.b=1&a.c=2", {
decode: (rawKey: string, rawValue: string, index: number) => {
return [
rawKey.toUpperCase().split("."),
rawValue * index
]
}
}); // {A: {B: 0, C: 2}}
qs.stringify({a: {b: 1, c: 2}}, {
encode: (keyPath: string[], value: any, index: number) => {
return [
keyPath.join(".").toUpperCase(),
String(value * index)
]
}
}); // "A.B=0&A.C=2"
```
To get more information on how this works, please refer to the documentation in the source code.
## API
> For more information, please refer to the documentation in source code.
## NPM scripts
- `browserify`. Create `qs.min.js` file to include directly via `` tags
- `build`. Run `clean`, `test`, `ts` and `browserify` scripts
- `clean`. Remove compiled files
- `test`. Run unit tests
- `ts`. Compile the project
- `ts:check`. Validate source code for compilation