ljharb /qs

A querystring parser and serializer with nesting support

★ 8,951⑂ 983👁 66⑃ 262● 372▤ 0
JavaScriptBSD-3-ClauseCreated 2014-07-25
+0
日增长
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 query

Top issues

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON