qs

The qs module was originally created and maintained by TJ Holowaychuk.

Usage

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

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 the plainObjects option the parsed value is returned as a null object, created via Object.create(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:

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.

By default, when nesting objects qs 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:

var expected ={

a:{

b:{

c:{

d:{

e:{

f:{

'[g][h][i]':'j'

}

}

}

}

}

}

};

var string ='a[b][c][d][e][f][g][h][i]=j';

assert.deepEqual(qs.parse(string), expected);

This depth can be overridden by passing a depth option to qs.parse(string, [options]):

var deep =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'}}});

The depth limit helps mitigate abuse when qs is used to parse user input, and it is recommended to keep it a reasonably small number.

For similar reasons, by default qs will only parse up to 1000 parameters. This can be overridden by passing a parameterLimit option:

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

assert.deepEqual(limited,{ a:'b'});

To bypass the leading question mark, use ignoreQueryPrefix:

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

assert.deepEqual(prefixed,{ a:'b', c:'d'});

An optional delimiter can also be passed:

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

assert.deepEqual(delimited,{ a:'b', c:'d'});

Delimiters can be a regular expression too:

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

assert.deepEqual(regexed,{ a:'b', c:'d', e:'f'});

Option allowDots can be used to enable dot notation:

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

assert.deepEqual(withDots,{ a:{ b:'c'}});

Parsing Arrays

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

var withArray =qs.parse('a[]=b&a[]=c');

assert.deepEqual(withArray,{ a:['b','c']});

You may specify an index as well:

var withIndexes =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:

var noSparse =qs.parse('a[1]=b&a[15]=c');

assert.deepEqual(noSparse,{ a:['b','c']});

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

var withEmptyString =qs.parse('a[]=&a[]=b');

assert.deepEqual(withEmptyString,{ a:['','b']});

var withIndexedEmptyString =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 of 20. Any array members with an index of greater than 20 will
instead be converted to an object with the index as the key:

var withMaxIndex =qs.parse('a[100]=b');

assert.deepEqual(withMaxIndex,{ a:{'100':'b'}});

This limit can be overridden by passing an arrayLimit option:

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

assert.deepEqual(withArrayLimit,{ a:{'1':'b'}});

To disable array parsing entirely, set parseArrays to false.

var noParsingArrays =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:

var mixedNotation =qs.parse('a[0]=b&a[b]=c');

assert.deepEqual(mixedNotation,{ a:{'0':'b', b:'c'}});

You can also create arrays of objects:

var arraysOfObjects =qs.parse('a[][b]=c');

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

Stringifying

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 the encode option to false:

var unencoded =qs.stringify({ a:{ b:'c'}},{ encode:false});

assert.equal(unencoded,'a[b]=c');

Encoding can be disabled for keys by setting the encodeValuesOnly option to true:

Finally, you can use the filter 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: