Repository files navigation

A querystring parsing and stringifying library with some added security.

Lead Maintainer:Jordan Harband

Theqs module was originally created and maintained byTJ Holowaychuk.

varqs=require('qs');varassert=require('assert');varobj=qs.parse('a=c');assert.deepEqual(obj,{a:'c'});varstr=qs.stringify(obj);assert.equal(str,'a=c');

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:

assert.deepEqual(qs.parse('foo[bar]=baz'),{foo:{bar:'baz'}});

When using theplainObjects 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:

varnullObject=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 useplainObjects as mentioned above, or setallowPrototypes totrue 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.

varprotoObject=qs.parse('a[hasOwnProperty]=b',{allowPrototypes:true});assert.deepEqual(protoObject,{a:{hasOwnProperty:'b'}});

URI encoded strings work too:

assert.deepEqual(qs.parse('a%5Bb%5D=c'),{a:{b:'c'}});

You can also nest your objects, like'foo[bar][baz]=foobarbaz':

assert.deepEqual(qs.parse('foo[bar][baz]=foobarbaz'),{foo:{bar:{baz:'foobarbaz'}}});

By default, when nesting objectsqs will only parse up to 5 children deep.This means if you attempt to parse a string like'a[b][c][d][e][f][g][h][i]=j' your resulting object will be:

varexpected={a:{b:{c:{d:{e:{f:{'[g][h][i]':'j'}}}}}}};varstring='a[b][c][d][e][f][g][h][i]=j';assert.deepEqual(qs.parse(string),expected);

This depth can be overridden by passing adepth option toqs.parse(string, [options]):

vardeep=qs.parse('a[b][c][d][e][f][g][h][i]=j',{depth:1});assert.deepEqual(deep,{a:{b:{'[c][d][e][f][g][h][i]':'j'}}});

You can configureqs to throw an error when parsing nested input beyond this depth using thestrictDepth option (defaulted to false):

try{qs.parse('a[b][c][d][e][f][g][h][i]=j',{depth:1,strictDepth:true});}catch(err){assert(errinstanceofRangeError);assert.strictEqual(err.message,'Input depth exceeded depth option of 1 and strictDepth is true');}

The depth limit helps mitigate abuse whenqs is used to parse user input, and it is recommended to keep it a reasonably small number. The strictDepth option adds a layer of protection by throwing an error when the limit is exceeded, allowing you to catch and handle such cases.

For similar reasons, by defaultqs will only parse up to 1000 parameters. This can be overridden by passing aparameterLimit option:

varlimited=qs.parse('a=b&c=d',{parameterLimit:1});assert.deepEqual(limited,{a:'b'});

If you want an error to be thrown whenever the a limit is exceeded (eg,parameterLimit,arrayLimit), set thethrowOnLimitExceeded option totrue. This option will generate a descriptive error if the query string exceeds a configured limit.

try{qs.parse('a=1&b=2&c=3&d=4',{parameterLimit:3,throwOnLimitExceeded:true});}catch(err){assert(errinstanceofError);assert.strictEqual(err.message,'Parameter limit exceeded. Only 3 parameters allowed.');}

WhenthrowOnLimitExceeded is set tofalse (default),qs will parse up to the specifiedparameterLimit and ignore the rest without throwing an error.

To bypass the leading question mark, useignoreQueryPrefix:

varprefixed=qs.parse('?a=b&c=d',{ignoreQueryPrefix:true});assert.deepEqual(prefixed,{a:'b',c:'d'});

An optional delimiter can also be passed:

vardelimited=qs.parse('a=b;c=d',{delimiter:';'});assert.deepEqual(delimited,{a:'b',c:'d'});

Delimiters can be a regular expression too:

varregexed=qs.parse('a=b;c=d,e=f',{delimiter:/[;,]/});assert.deepEqual(regexed,{a:'b',c:'d',e:'f'});

OptionallowDots can be used to enable dot notation:

varwithDots=qs.parse('a.b=c',{allowDots:true});assert.deepEqual(withDots,{a:{b:'c'}});

OptiondecodeDotInKeys can be used to decode dots in keysNote: it impliesallowDots, soparse will error if you setdecodeDotInKeys totrue, andallowDots tofalse.

varwithDots=qs.parse('name%252Eobj.first=John&name%252Eobj.last=Doe',{decodeDotInKeys:true});assert.deepEqual(withDots,{'name.obj':{first:'John',last:'Doe'}});

OptionallowEmptyArrays can be used to allowing empty array values in object

varwithEmptyArrays=qs.parse('foo[]&bar=baz',{allowEmptyArrays:true});assert.deepEqual(withEmptyArrays,{foo:[],bar:'baz'});

Optionduplicates can be used to change the behavior when duplicate keys are encountered

assert.deepEqual(qs.parse('foo=bar&foo=baz'),{foo:['bar','baz']});assert.deepEqual(qs.parse('foo=bar&foo=baz',{duplicates:'combine'}),{foo:['bar','baz']});assert.deepEqual(qs.parse('foo=bar&foo=baz',{duplicates:'first'}),{foo:'bar'});assert.deepEqual(qs.parse('foo=bar&foo=baz',{duplicates:'last'}),{foo:'baz'});

If you have to deal with legacy browsers or services, there's also support for decoding percent-encoded octets as iso-8859-1:

varoldCharset=qs.parse('a=%A7',{charset:'iso-8859-1'});assert.deepEqual(oldCharset,{a:'§'});

Some services add an initialutf8=✓ value to forms so that old Internet Explorer versions are more likely to submit the form as utf-8.Additionally, the server can check the value against wrong encodings of the checkmark character and detect that a query string orapplication/x-www-form-urlencoded body wasnot sent as utf-8, eg. if the form had anaccept-charset parameter or the containing page had a different character set.

qs supports this mechanism via thecharsetSentinel option.If specified, theutf8 parameter will be omitted from the returned object.It will be used to switch toiso-8859-1/utf-8 mode depending on how the checkmark is encoded.

Important: When you specify both thecharset option and thecharsetSentinel option, thecharset will be overridden when the request contains autf8 parameter from which the actual charset can be deduced.In that sense thecharset will behave as the default charset rather than the authoritative charset.

vardetectedAsUtf8=qs.parse('utf8=%E2%9C%93&a=%C3%B8',{charset:'iso-8859-1',charsetSentinel:true});assert.deepEqual(detectedAsUtf8,{a:'ø'});// Browsers encode the checkmark as ✓ when submitting as iso-8859-1:vardetectedAsIso8859_1=qs.parse('utf8=%26%2310003%3B&a=%F8',{charset:'utf-8',charsetSentinel:true});assert.deepEqual(detectedAsIso8859_1,{a:'ø'});

If you want to decode the&#...; syntax to the actual character, you can specify theinterpretNumericEntities option as well:

vardetectedAsIso8859_1=qs.parse('a=%26%239786%3B',{charset:'iso-8859-1',interpretNumericEntities:true});assert.deepEqual(detectedAsIso8859_1,{a:'☺'});

It also works when the charset has been detected incharsetSentinel mode.

qs can also parse arrays using a similar[] notation:

varwithArray=qs.parse('a[]=b&a[]=c');assert.deepEqual(withArray,{a:['b','c']});

You may specify an index as well:

varwithIndexes=qs.parse('a[1]=c&a[0]=b');assert.deepEqual(withIndexes,{a:['b','c']});

Note that the only difference between an index in an array and a key in an object is that the value between the brackets must be a number to create an array.When creating arrays with specific indices,qs will compact a sparse array to only the existing values preserving their order:

varnoSparse=qs.parse('a[1]=b&a[15]=c');assert.deepEqual(noSparse,{a:['b','c']});

You may also useallowSparse option to parse sparse arrays:

varsparseArray=qs.parse('a[1]=2&a[3]=5',{allowSparse:true});assert.deepEqual(sparseArray,{a:[,'2',,'5']});

Note that an empty string is also a value, and will be preserved:

varwithEmptyString=qs.parse('a[]=&a[]=b');assert.deepEqual(withEmptyString,{a:['','b']});varwithIndexedEmptyString=qs.parse('a[0]=b&a[1]=&a[2]=c');assert.deepEqual(withIndexedEmptyString,{a:['b','','c']});

qs will also limit specifying indices in an array to a maximum index of20.Any array members with an index of greater than20 will instead be converted to an object with the index as the key.This is needed to handle cases when someone sent, for example,a[999999999] and it will take significant time to iterate over this huge array.

varwithMaxIndex=qs.parse('a[100]=b');assert.deepEqual(withMaxIndex,{a:{'100':'b'}});

This limit can be overridden by passing anarrayLimit option:

varwithArrayLimit=qs.parse('a[1]=b',{arrayLimit:0});assert.deepEqual(withArrayLimit,{a:{'1':'b'}});

If you want to throw an error whenever the array limit is exceeded, set thethrowOnLimitExceeded option totrue. This option will generate a descriptive error if the query string exceeds a configured limit.

try{qs.parse('a[1]=b',{arrayLimit:0,throwOnLimitExceeded:true});}catch(err){assert(errinstanceofError);assert.strictEqual(err.message,'Array limit exceeded. Only 0 elements allowed in an array.');}

WhenthrowOnLimitExceeded is set tofalse (default),qs will parse up to the specifiedarrayLimit and if the limit is exceeded, the array will instead be converted to an object with the index as the key

To disable array parsing entirely, setparseArrays tofalse.

varnoParsingArrays=qs.parse('a[]=b',{parseArrays:false});assert.deepEqual(noParsingArrays,{a:{'0':'b'}});

If you mix notations,qs will merge the two items into an object:

varmixedNotation=qs.parse('a[0]=b&a[b]=c');assert.deepEqual(mixedNotation,{a:{'0':'b',b:'c'}});

You can also create arrays of objects:

vararraysOfObjects=qs.parse('a[][b]=c');assert.deepEqual(arraysOfObjects,{a:[{b:'c'}]});

Some people use comma to join array,qs can parse it:

vararraysOfObjects=qs.parse('a=b,c',{comma:true})assert.deepEqual(arraysOfObjects,{a:['b','c']})

(this cannot convert nested objects, such asa={b:1},{c:d})

By default, all values are parsed as strings.This behavior will not change and is explained inissue #91.

varprimitiveValues=qs.parse('a=15&b=true&c=null');assert.deepEqual(primitiveValues,{a:'15',b:'true',c:'null'});

If you wish to auto-convert values which look like numbers, booleans, and other values into their primitive counterparts, you can use thequery-types Express JS middleware which will auto-convert all request query parameters.

qs.stringify(object,[options]);

When stringifying,qs by default URI encodes output. Objects are stringified as you would expect:

assert.equal(qs.stringify({a:'b'}),'a=b');assert.equal(qs.stringify({a:{b:'c'}}),'a%5Bb%5D=c');

This encoding can be disabled by setting theencode option tofalse:

varunencoded=qs.stringify({a:{b:'c'}},{encode:false});assert.equal(unencoded,'a[b]=c');

Encoding can be disabled for keys by setting theencodeValuesOnly option totrue:

varencodedValues=qs.stringify({a:'b',c:['d','e=f'],f:[['g'],['h']]},{encodeValuesOnly:true});assert.equal(encodedValues,'a=b&c[0]=d&c[1]=e%3Df&f[0][0]=g&f[1][0]=h');

This encoding can also be replaced by a custom encoding method set asencoder option:

varencoded=qs.stringify({a:{b:'c'}},{encoder:function(str){// Passed in values `a`, `b`, `c`return// Return encoded string}})

(Note: theencoder option does not apply ifencode isfalse)

Analogue to theencoder there is adecoder option forparse to override decoding of properties and values:

vardecoded=qs.parse('x=z',{decoder:function(str){// Passed in values `x`, `z`return// Return decoded string}})

You can encode keys and values using different logic by using the type argument provided to the encoder:

varencoded=qs.stringify({a:{b:'c'}},{encoder:function(str,defaultEncoder,charset,type){if(type==='key'){return// Encoded key}elseif(type==='value'){return// Encoded value}}})

The type argument is also provided to the decoder:

vardecoded=qs.parse('x=z',{decoder:function(str,defaultDecoder,charset,type){if(type==='key'){return// Decoded key}elseif(type==='value'){return// Decoded value}}})

Examples beyond this point will be shown as though the output is not URI encoded for clarity.Please note that the return values in these caseswill be URI encoded during real usage.

When arrays are stringified, they follow thearrayFormat option, which defaults toindices:

qs.stringify({a:['b','c','d']});// 'a[0]=b&a[1]=c&a[2]=d'

You may override this by setting theindices option tofalse, or to be more explicit, thearrayFormat option torepeat:

qs.stringify({a:['b','c','d']},{indices:false});// 'a=b&a=c&a=d'

You may use thearrayFormat option to specify the format of the output array:

qs.stringify({a:['b','c']},{arrayFormat:'indices'})// 'a[0]=b&a[1]=c'qs.stringify({a:['b','c']},{arrayFormat:'brackets'})// 'a[]=b&a[]=c'qs.stringify({a:['b','c']},{arrayFormat:'repeat'})// 'a=b&a=c'qs.stringify({a:['b','c']},{arrayFormat:'comma'})// 'a=b,c'

Note: when usingarrayFormat set to'comma', you can also pass thecommaRoundTrip option set totrue orfalse, to append[] on single-item arrays, so that they can round trip through a parse.

When objects are stringified, by default they use bracket notation:

qs.stringify({a:{b:{c:'d',e:'f'}}});// 'a[b][c]=d&a[b][e]=f'

You may override this to use dot notation by setting theallowDots option totrue:

qs.stringify({a:{b:{c:'d',e:'f'}}},{allowDots:true});// 'a.b.c=d&a.b.e=f'

You may encode the dot notation in the keys of object with optionencodeDotInKeys by setting it totrue:Note: it impliesallowDots, sostringify will error if you setdecodeDotInKeys totrue, andallowDots tofalse.Caveat: whenencodeValuesOnly istrue as well asencodeDotInKeys, only dots in keys and nothing else will be encoded.

qs.stringify({"name.obj":{"first":"John","last":"Doe"}},{allowDots:true,encodeDotInKeys:true})// 'name%252Eobj.first=John&name%252Eobj.last=Doe'

You may allow empty array values by setting theallowEmptyArrays option totrue:

qs.stringify({foo:[],bar:'baz'},{allowEmptyArrays:true});// 'foo[]&bar=baz'

Empty strings and null values will omit the value, but the equals sign (=) remains in place:

assert.equal(qs.stringify({a:''}),'a=');

Key with no values (such as an empty object or array) will return nothing:

assert.equal(qs.stringify({a:[]}),'');assert.equal(qs.stringify({a:{}}),'');assert.equal(qs.stringify({a:[{}]}),'');assert.equal(qs.stringify({a:{b:[]}}),'');assert.equal(qs.stringify({a:{b:{}}}),'');

Properties that are set toundefined will be omitted entirely:

assert.equal(qs.stringify({a:null,b:undefined}),'a=');

The query string may optionally be prepended with a question mark:

assert.equal(qs.stringify({a:'b',c:'d'},{addQueryPrefix:true}),'?a=b&c=d');

The delimiter may be overridden with stringify as well:

assert.equal(qs.stringify({a:'b',c:'d'},{delimiter:';'}),'a=b;c=d');

If you only want to override the serialization ofDate objects, you can provide aserializeDate option:

vardate=newDate(7);assert.equal(qs.stringify({a:date}),'a=1970-01-01T00:00:00.007Z'.replace(/:/g,'%3A'));assert.equal(qs.stringify({a:date},{serializeDate:function(d){returnd.getTime();}}),'a=7');

You may use thesort option to affect the order of parameter keys:

functionalphabeticalSort(a,b){returna.localeCompare(b);}assert.equal(qs.stringify({a:'c',z:'y',b :'f'},{sort:alphabeticalSort}),'a=c&b=f&z=y');

Finally, you can use thefilter option to restrict which keys will be included in the stringified output.If you pass a function, it will be called for each key to obtain the replacement value.Otherwise, if you pass an array, it will be used to select properties and array indices for stringification:

functionfilterFunc(prefix,value){if(prefix=='b'){// Return an `undefined` value to omit a property.return;}if(prefix=='e[f]'){returnvalue.getTime();}if(prefix=='e[g][0]'){returnvalue*2;}returnvalue;}qs.stringify({a:'b',c:'d',e:{f:newDate(123),g:[2]}},{filter:filterFunc});// 'a=b&c=d&e[f]=123&e[g][0]=4'qs.stringify({a:'b',c:'d',e:'f'},{filter:['a','e']});// 'a=b&e=f'qs.stringify({a:['b','c','d'],e:'f'},{filter:['a',0,2]});// 'a[0]=b&a[2]=d'

You could also usefilter to inject custom serialization for user defined types.Consider you're working with some api that expects query strings of the format for ranges:

https://domain.com/endpoint?range=30...70

For which you model as:

classRange{constructor(from,to){this.from=from;this.to=to;}}

You couldinject a custom serializer to handle values of this type:

qs.stringify({range:newRange(30,70),},{filter:(prefix,value)=>{if(valueinstanceofRange){return`${value.from}...${value.to}`;}// serialize the usual wayreturnvalue;},});// range=30...70

By default,null values are treated like empty strings:

varwithNull=qs.stringify({a:null,b:''});assert.equal(withNull,'a=&b=');

Parsing does not distinguish between parameters with and without equal signs.Both are converted to empty strings.

varequalsInsensitive=qs.parse('a&b=');assert.deepEqual(equalsInsensitive,{a:'',b:''});

To distinguish betweennull values and empty strings use thestrictNullHandling flag. In the result string thenullvalues have no= sign:

varstrictNull=qs.stringify({a:null,b:''},{strictNullHandling:true});assert.equal(strictNull,'a&b=');

To parse values without= back tonull use thestrictNullHandling flag:

varparsedStrictNull=qs.parse('a&b=',{strictNullHandling:true});assert.deepEqual(parsedStrictNull,{a:null,b:''});

To completely skip rendering keys withnull values, use theskipNulls flag:

varnullsSkipped=qs.stringify({a:'b',c:null},{skipNulls:true});assert.equal(nullsSkipped,'a=b');

If you're communicating with legacy systems, you can switch toiso-8859-1 using thecharset option:

variso=qs.stringify({æ:'æ'},{charset:'iso-8859-1'});assert.equal(iso,'%E6=%E6');

Characters that don't exist iniso-8859-1 will be converted to numeric entities, similar to what browsers do:

varnumeric=qs.stringify({a:'☺'},{charset:'iso-8859-1'});assert.equal(numeric,'a=%26%239786%3B');

You can use thecharsetSentinel option to announce the character by including anutf8=✓ parameter with the proper encoding if the checkmark, similar to what Ruby on Rails and others do when submitting forms.

varsentinel=qs.stringify({a:'☺'},{charsetSentinel:true});assert.equal(sentinel,'utf8=%E2%9C%93&a=%E2%98%BA');varisoSentinel=qs.stringify({a:'æ'},{charsetSentinel:true,charset:'iso-8859-1'});assert.equal(isoSentinel,'utf8=%26%2310003%3B&a=%E6');

By default the encoding and decoding of characters is done inutf-8, andiso-8859-1 support is also built in via thecharset parameter.

If you wish to encode querystrings to a different character set (i.e.Shift JIS) you can use theqs-iconv library:

varencoder=require('qs-iconv/encoder')('shift_jis');varshiftJISEncoded=qs.stringify({a:'こんにちは！'},{encoder:encoder});assert.equal(shiftJISEncoded,'a=%82%B1%82%F1%82%C9%82%BF%82%CD%81I');

This also works for decoding of query strings:

vardecoder=require('qs-iconv/decoder')('shift_jis');varobj=qs.parse('a=%82%B1%82%F1%82%C9%82%BF%82%CD%81I',{decoder:decoder});assert.deepEqual(obj,{a:'こんにちは！'});

RFC3986 used as default option and encodes ' ' to%20 which is backward compatible.In the same time, output can be stringified as per RFC1738 with ' ' equal to '+'.

assert.equal(qs.stringify({ a: 'b c' }), 'a=b%20c');assert.equal(qs.stringify({ a: 'b c' }, { format : 'RFC3986' }), 'a=b%20c');assert.equal(qs.stringify({ a: 'b c' }, { format : 'RFC1738' }), 'a=b+c');

Please email@ljharb or seehttps://tidelift.com/security if you have a potential security vulnerability to report.

Available as part of the Tidelift Subscription

The maintainers of qs and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications.Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use.Learn more.

qs logo byNUMI: