+0
Daily
8,951
stars
983
forks
66
watchers
262
prs
372
issues
0
releases
README
qs [![Version Badge][npm-version-svg]][package-url]
[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]
[![npm badge][npm-badge-png]][package-url]
A querystring parsing and stringifying library with some added security.
Lead Maintainer: Jordan Harband
The qs module was originally created and maintained by TJ Holowaychuk.
Usage
javascript
var qs = require('qs');
var assert = require('assert');
var obj = qs.parse('a=c');
assert.deepEqual(obj, { a: 'c' });
var str = qs.stringify(obj);
assert.equal(str, 'a=c');
Parsing Objects
javascript
qs.parse(string, [options]);
qs allows you to create nested objects within your query strings, by surrounding the name of sub-keys with square brackets [].
For example, the string 'foo[bar]=baz' converts to:
javascript
assert.deepEqual(qs.parse('foo[bar]=baz'), {
foo: {
bar: 'baz'
}
});
When using the plainObjects option the parsed value is returned as a null object, created via { __proto__: null } and as such you should be aware that prototype methods will not exist on it and a user may set those names to whatever value they like:
javascript
var nullObject = qs.parse('a[hasOwnProperty]=b', { plainObjects: true });
assert.deepEqual(nullObject, { a: { hasOwnProperty: 'b' } });
By default parameters that would overwrite properties on the object prototype are ignored, if you wish to keep the data from those fields either use plainObjects as mentioned above, or set allowPrototypes to true which will allow user input to overwrite those properties.
WARNING It is generally a bad idea to enable this option as it can cause problems when attempting to use the properties that have been overwritten.
Always be careful with this option.
javascript
var protoObject = qs.parse('a[hasOwnProperty]=b', { allowPrototypes: true });
assert.deepEqual(protoObject, { a: { hasOwnProperty: 'b' } });
URI encoded strings work too:
javascript
assert.deepEqual(qs.parse('a%5Bb%5D=c'), {
a: { b: 'c' }
});
You can also nest your objects, like 'foo[bar][baz]=foobarbaz':
javascript
assert.deepEqual(qs.parse('foo[bar][baz]=foobarbaz'), {
foo: {
bar: {
baz: 'foobarbaz'
}
}
});
Since v6.14.1 and v6.15.2, parse interprets nested bracket groups more consistently.
Query strings with unbalanced [/] can produce different results than in 6.15.1;
see 558.
Because of that bracket grammar,
qs does not agree with URLSearchParams,
node:querystring, or any other flat parser about what the "name" of a parameter is,
and it never has.
URLSearchParams reads 'foo[bar]=baz' as one flat name foo[bar];
qs reads it as the path foo.bar.
Text that qs's grammar cannot place,
such as the extra in 'foo[bar]extra=baz',
is currently dropped, so several distinct flat names can resolve to the same qs path
(see 619).
So validating, authorizing, filtering,
or signing a queryTop issues
#378Stringify with "arrayFormat: comma" encodes objects inside arrays as "[object Object]"30 comments · 2020-08-11#264Add support for sets19 comments · 2018-05-30#107Change `arrayLimit` default to 018 comments · 2015-08-07#345Stringifying using different arrayFormats, then parsed, create different things16 comments · 2019-11-15#306Request to offer qs under an unmodified MIT licence16 comments · 2019-03-28#215Cannot parse array of objects using arrayFormat = 'brackets'13 comments · 2017-06-13#491Exclude the value of a certain key, from getting encoded 11 comments · 2024-02-05#513square brackets confuse the parser6 comments · 2024-10-10