BlueGit

blue-star danique-bot

Files

danique-bot / node_modules / qs / README.md

README.md

Import template
timfa Tim · pushed by timfa · 4 years ago
c788ad20 History
README.md 14.3 KiB Download Raw

qs [![Version Badge][2]][1]

[![Build Status][3]][4] [![dependency status][5]][6] [![dev dependency status][7]][8] [![License][license-image]][license-url] [![Downloads][downloads-image]][downloads-url]

[![npm badge][11]][1]

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

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.

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

var encodedValues = 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 as encoder option:

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

_(Note: the encoder option does not apply if encode is false)_

Analogue to the encoder there is a decoder option for parse to override decoding of properties and values:

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

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 cases will be URI encoded during real usage.

When arrays are stringified, by default they are given explicit indices:

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

You may override this by setting the indices option to false:

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

You may use the arrayFormat 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'

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 the allowDots option to true:

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

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 to undefined 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 of Date objects, you can provide a serializeDate option:

var date = new Date(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) { return d.getTime(); } }),
    'a=7'
);

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

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

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:

function filterFunc(prefix, value) {
    if (prefix == 'b') {
        // Return an `undefined` value to omit a property.
        return;
    }
    if (prefix == 'e[f]') {
        return value.getTime();
    }
    if (prefix == 'e[g][0]') {
        return value * 2;
    }
    return value;
}
qs.stringify({ a: 'b', c: 'd', e: { f: new Date(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'

Handling of null values

By default, null values are treated like empty strings:

var withNull = 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.

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

To distinguish between null values and empty strings use the strictNullHandling flag. In the result string the null values have no = sign:

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

To parse values without = back to null use the strictNullHandling flag:

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

To completely skip rendering keys with null values, use the skipNulls flag:

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

Dealing with special character sets

By default the encoding and decoding of characters is done in utf-8. If you wish to encode querystrings to a different character set (i.e. Shift JIS) you can use the qs-iconv library:

var encoder = require('qs-iconv/encoder')('shift_jis');
var shiftJISEncoded = 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:

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

RFC 3986 and RFC 1738 space encoding

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');

[1]: https://npmjs.org/package/qs [2]: http://versionbadg.es/ljharb/qs.svg [3]: qs.svg [4]: https://travis-ci.org/ljharb/qs [5]: qs.svg [6]: https://david-dm.org/ljharb/qs [7]: dev-status.svg [8]: https://david-dm.org/ljharb/qs?type=dev [9]: qs.png [10]: https://ci.testling.com/ljharb/qs [11]: qs.png [license-image]: http://img.shields.io/npm/l/qs.svg [license-url]: LICENSE [downloads-image]: http://img.shields.io/npm/dm/qs.svg [downloads-url]: http://npm-stat.com/charts.html?package=qs

Source
1# qs <sup>[![Version Badge][2]][1]</sup>
2
3[![Build Status][3]][4]
4[![dependency status][5]][6]
5[![dev dependency status][7]][8]
6[![License][license-image]][license-url]
7[![Downloads][downloads-image]][downloads-url]
8
9[![npm badge][11]][1]
10
11A querystring parsing and stringifying library with some added security.
12
13Lead Maintainer: [Jordan Harband](https://github.com/ljharb)
14
15The **qs** module was originally created and maintained by [TJ Holowaychuk](https://github.com/visionmedia/node-querystring).
16
17## Usage
18
19```javascript
20var qs = require('qs');
21var assert = require('assert');
22
23var obj = qs.parse('a=c');
24assert.deepEqual(obj, { a: 'c' });
25
26var str = qs.stringify(obj);
27assert.equal(str, 'a=c');
28```
29
30### Parsing Objects
31
32[](#preventEval)
33```javascript
34qs.parse(string, [options]);
35```
36
37**qs** allows you to create nested objects within your query strings, by surrounding the name of sub-keys with square brackets `[]`.
38For example, the string `'foo[bar]=baz'` converts to:
39
40```javascript
41assert.deepEqual(qs.parse('foo[bar]=baz'), {
42 foo: {
43 bar: 'baz'
44 }
45});
46```
47
48When 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:
49
50```javascript
51var nullObject = qs.parse('a[hasOwnProperty]=b', { plainObjects: true });
52assert.deepEqual(nullObject, { a: { hasOwnProperty: 'b' } });
53```
54
55By 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.
56
57```javascript
58var protoObject = qs.parse('a[hasOwnProperty]=b', { allowPrototypes: true });
59assert.deepEqual(protoObject, { a: { hasOwnProperty: 'b' } });
60```
61
62URI encoded strings work too:
63
64```javascript
65assert.deepEqual(qs.parse('a%5Bb%5D=c'), {
66 a: { b: 'c' }
67});
68```
69
70You can also nest your objects, like `'foo[bar][baz]=foobarbaz'`:
71
72```javascript
73assert.deepEqual(qs.parse('foo[bar][baz]=foobarbaz'), {
74 foo: {
75 bar: {
76 baz: 'foobarbaz'
77 }
78 }
79});
80```
81
82By default, when nesting objects **qs** will only parse up to 5 children deep. This means if you attempt to parse a string like
83`'a[b][c][d][e][f][g][h][i]=j'` your resulting object will be:
84
85```javascript
86var expected = {
87 a: {
88 b: {
89 c: {
90 d: {
91 e: {
92 f: {
93 '[g][h][i]': 'j'
94 }
95 }
96 }
97 }
98 }
99 }
100};
101var string = 'a[b][c][d][e][f][g][h][i]=j';
102assert.deepEqual(qs.parse(string), expected);
103```
104
105This depth can be overridden by passing a `depth` option to `qs.parse(string, [options])`:
106
107```javascript
108var deep = qs.parse('a[b][c][d][e][f][g][h][i]=j', { depth: 1 });
109assert.deepEqual(deep, { a: { b: { '[c][d][e][f][g][h][i]': 'j' } } });
110```
111
112The depth limit helps mitigate abuse when **qs** is used to parse user input, and it is recommended to keep it a reasonably small number.
113
114For similar reasons, by default **qs** will only parse up to 1000 parameters. This can be overridden by passing a `parameterLimit` option:
115
116```javascript
117var limited = qs.parse('a=b&c=d', { parameterLimit: 1 });
118assert.deepEqual(limited, { a: 'b' });
119```
120
121To bypass the leading question mark, use `ignoreQueryPrefix`:
122
123```javascript
124var prefixed = qs.parse('?a=b&c=d', { ignoreQueryPrefix: true });
125assert.deepEqual(prefixed, { a: 'b', c: 'd' });
126```
127
128An optional delimiter can also be passed:
129
130```javascript
131var delimited = qs.parse('a=b;c=d', { delimiter: ';' });
132assert.deepEqual(delimited, { a: 'b', c: 'd' });
133```
134
135Delimiters can be a regular expression too:
136
137```javascript
138var regexed = qs.parse('a=b;c=d,e=f', { delimiter: /[;,]/ });
139assert.deepEqual(regexed, { a: 'b', c: 'd', e: 'f' });
140```
141
142Option `allowDots` can be used to enable dot notation:
143
144```javascript
145var withDots = qs.parse('a.b=c', { allowDots: true });
146assert.deepEqual(withDots, { a: { b: 'c' } });
147```
148
149### Parsing Arrays
150
151**qs** can also parse arrays using a similar `[]` notation:
152
153```javascript
154var withArray = qs.parse('a[]=b&a[]=c');
155assert.deepEqual(withArray, { a: ['b', 'c'] });
156```
157
158You may specify an index as well:
159
160```javascript
161var withIndexes = qs.parse('a[1]=c&a[0]=b');
162assert.deepEqual(withIndexes, { a: ['b', 'c'] });
163```
164
165Note 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
166to create an array. When creating arrays with specific indices, **qs** will compact a sparse array to only the existing values preserving
167their order:
168
169```javascript
170var noSparse = qs.parse('a[1]=b&a[15]=c');
171assert.deepEqual(noSparse, { a: ['b', 'c'] });
172```
173
174Note that an empty string is also a value, and will be preserved:
175
176```javascript
177var withEmptyString = qs.parse('a[]=&a[]=b');
178assert.deepEqual(withEmptyString, { a: ['', 'b'] });
179
180var withIndexedEmptyString = qs.parse('a[0]=b&a[1]=&a[2]=c');
181assert.deepEqual(withIndexedEmptyString, { a: ['b', '', 'c'] });
182```
183
184**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
185instead be converted to an object with the index as the key:
186
187```javascript
188var withMaxIndex = qs.parse('a[100]=b');
189assert.deepEqual(withMaxIndex, { a: { '100': 'b' } });
190```
191
192This limit can be overridden by passing an `arrayLimit` option:
193
194```javascript
195var withArrayLimit = qs.parse('a[1]=b', { arrayLimit: 0 });
196assert.deepEqual(withArrayLimit, { a: { '1': 'b' } });
197```
198
199To disable array parsing entirely, set `parseArrays` to `false`.
200
201```javascript
202var noParsingArrays = qs.parse('a[]=b', { parseArrays: false });
203assert.deepEqual(noParsingArrays, { a: { '0': 'b' } });
204```
205
206If you mix notations, **qs** will merge the two items into an object:
207
208```javascript
209var mixedNotation = qs.parse('a[0]=b&a[b]=c');
210assert.deepEqual(mixedNotation, { a: { '0': 'b', b: 'c' } });
211```
212
213You can also create arrays of objects:
214
215```javascript
216var arraysOfObjects = qs.parse('a[][b]=c');
217assert.deepEqual(arraysOfObjects, { a: [{ b: 'c' }] });
218```
219
220### Stringifying
221
222[](#preventEval)
223```javascript
224qs.stringify(object, [options]);
225```
226
227When stringifying, **qs** by default URI encodes output. Objects are stringified as you would expect:
228
229```javascript
230assert.equal(qs.stringify({ a: 'b' }), 'a=b');
231assert.equal(qs.stringify({ a: { b: 'c' } }), 'a%5Bb%5D=c');
232```
233
234This encoding can be disabled by setting the `encode` option to `false`:
235
236```javascript
237var unencoded = qs.stringify({ a: { b: 'c' } }, { encode: false });
238assert.equal(unencoded, 'a[b]=c');
239```
240
241Encoding can be disabled for keys by setting the `encodeValuesOnly` option to `true`:
242```javascript
243var encodedValues = qs.stringify(
244 { a: 'b', c: ['d', 'e=f'], f: [['g'], ['h']] },
245 { encodeValuesOnly: true }
246);
247assert.equal(encodedValues,'a=b&c[0]=d&c[1]=e%3Df&f[0][0]=g&f[1][0]=h');
248```
249
250This encoding can also be replaced by a custom encoding method set as `encoder` option:
251
252```javascript
253var encoded = qs.stringify({ a: { b: 'c' } }, { encoder: function (str) {
254 // Passed in values `a`, `b`, `c`
255 return // Return encoded string
256}})
257```
258
259_(Note: the `encoder` option does not apply if `encode` is `false`)_
260
261Analogue to the `encoder` there is a `decoder` option for `parse` to override decoding of properties and values:
262
263```javascript
264var decoded = qs.parse('x=z', { decoder: function (str) {
265 // Passed in values `x`, `z`
266 return // Return decoded string
267}})
268```
269
270Examples beyond this point will be shown as though the output is not URI encoded for clarity. Please note that the return values in these cases *will* be URI encoded during real usage.
271
272When arrays are stringified, by default they are given explicit indices:
273
274```javascript
275qs.stringify({ a: ['b', 'c', 'd'] });
276// 'a[0]=b&a[1]=c&a[2]=d'
277```
278
279You may override this by setting the `indices` option to `false`:
280
281```javascript
282qs.stringify({ a: ['b', 'c', 'd'] }, { indices: false });
283// 'a=b&a=c&a=d'
284```
285
286You may use the `arrayFormat` option to specify the format of the output array:
287
288```javascript
289qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'indices' })
290// 'a[0]=b&a[1]=c'
291qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'brackets' })
292// 'a[]=b&a[]=c'
293qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'repeat' })
294// 'a=b&a=c'
295```
296
297When objects are stringified, by default they use bracket notation:
298
299```javascript
300qs.stringify({ a: { b: { c: 'd', e: 'f' } } });
301// 'a[b][c]=d&a[b][e]=f'
302```
303
304You may override this to use dot notation by setting the `allowDots` option to `true`:
305
306```javascript
307qs.stringify({ a: { b: { c: 'd', e: 'f' } } }, { allowDots: true });
308// 'a.b.c=d&a.b.e=f'
309```
310
311Empty strings and null values will omit the value, but the equals sign (=) remains in place:
312
313```javascript
314assert.equal(qs.stringify({ a: '' }), 'a=');
315```
316
317Key with no values (such as an empty object or array) will return nothing:
318
319```javascript
320assert.equal(qs.stringify({ a: [] }), '');
321assert.equal(qs.stringify({ a: {} }), '');
322assert.equal(qs.stringify({ a: [{}] }), '');
323assert.equal(qs.stringify({ a: { b: []} }), '');
324assert.equal(qs.stringify({ a: { b: {}} }), '');
325```
326
327Properties that are set to `undefined` will be omitted entirely:
328
329```javascript
330assert.equal(qs.stringify({ a: null, b: undefined }), 'a=');
331```
332
333The query string may optionally be prepended with a question mark:
334
335```javascript
336assert.equal(qs.stringify({ a: 'b', c: 'd' }, { addQueryPrefix: true }), '?a=b&c=d');
337```
338
339The delimiter may be overridden with stringify as well:
340
341```javascript
342assert.equal(qs.stringify({ a: 'b', c: 'd' }, { delimiter: ';' }), 'a=b;c=d');
343```
344
345If you only want to override the serialization of `Date` objects, you can provide a `serializeDate` option:
346
347```javascript
348var date = new Date(7);
349assert.equal(qs.stringify({ a: date }), 'a=1970-01-01T00:00:00.007Z'.replace(/:/g, '%3A'));
350assert.equal(
351 qs.stringify({ a: date }, { serializeDate: function (d) { return d.getTime(); } }),
352 'a=7'
353);
354```
355
356You may use the `sort` option to affect the order of parameter keys:
357
358```javascript
359function alphabeticalSort(a, b) {
360 return a.localeCompare(b);
361}
362assert.equal(qs.stringify({ a: 'c', z: 'y', b : 'f' }, { sort: alphabeticalSort }), 'a=c&b=f&z=y');
363```
364
365Finally, you can use the `filter` option to restrict which keys will be included in the stringified output.
366If you pass a function, it will be called for each key to obtain the replacement value. Otherwise, if you
367pass an array, it will be used to select properties and array indices for stringification:
368
369```javascript
370function filterFunc(prefix, value) {
371 if (prefix == 'b') {
372 // Return an `undefined` value to omit a property.
373 return;
374 }
375 if (prefix == 'e[f]') {
376 return value.getTime();
377 }
378 if (prefix == 'e[g][0]') {
379 return value * 2;
380 }
381 return value;
382}
383qs.stringify({ a: 'b', c: 'd', e: { f: new Date(123), g: [2] } }, { filter: filterFunc });
384// 'a=b&c=d&e[f]=123&e[g][0]=4'
385qs.stringify({ a: 'b', c: 'd', e: 'f' }, { filter: ['a', 'e'] });
386// 'a=b&e=f'
387qs.stringify({ a: ['b', 'c', 'd'], e: 'f' }, { filter: ['a', 0, 2] });
388// 'a[0]=b&a[2]=d'
389```
390
391### Handling of `null` values
392
393By default, `null` values are treated like empty strings:
394
395```javascript
396var withNull = qs.stringify({ a: null, b: '' });
397assert.equal(withNull, 'a=&b=');
398```
399
400Parsing does not distinguish between parameters with and without equal signs. Both are converted to empty strings.
401
402```javascript
403var equalsInsensitive = qs.parse('a&b=');
404assert.deepEqual(equalsInsensitive, { a: '', b: '' });
405```
406
407To distinguish between `null` values and empty strings use the `strictNullHandling` flag. In the result string the `null`
408values have no `=` sign:
409
410```javascript
411var strictNull = qs.stringify({ a: null, b: '' }, { strictNullHandling: true });
412assert.equal(strictNull, 'a&b=');
413```
414
415To parse values without `=` back to `null` use the `strictNullHandling` flag:
416
417```javascript
418var parsedStrictNull = qs.parse('a&b=', { strictNullHandling: true });
419assert.deepEqual(parsedStrictNull, { a: null, b: '' });
420```
421
422To completely skip rendering keys with `null` values, use the `skipNulls` flag:
423
424```javascript
425var nullsSkipped = qs.stringify({ a: 'b', c: null}, { skipNulls: true });
426assert.equal(nullsSkipped, 'a=b');
427```
428
429### Dealing with special character sets
430
431By default the encoding and decoding of characters is done in `utf-8`. If you
432wish to encode querystrings to a different character set (i.e.
433[Shift JIS](https://en.wikipedia.org/wiki/Shift_JIS)) you can use the
434[`qs-iconv`](https://github.com/martinheidegger/qs-iconv) library:
435
436```javascript
437var encoder = require('qs-iconv/encoder')('shift_jis');
438var shiftJISEncoded = qs.stringify({ a: 'こんにちは!' }, { encoder: encoder });
439assert.equal(shiftJISEncoded, 'a=%82%B1%82%F1%82%C9%82%BF%82%CD%81I');
440```
441
442This also works for decoding of query strings:
443
444```javascript
445var decoder = require('qs-iconv/decoder')('shift_jis');
446var obj = qs.parse('a=%82%B1%82%F1%82%C9%82%BF%82%CD%81I', { decoder: decoder });
447assert.deepEqual(obj, { a: 'こんにちは!' });
448```
449
450### RFC 3986 and RFC 1738 space encoding
451
452RFC3986 used as default option and encodes ' ' to *%20* which is backward compatible.
453In the same time, output can be stringified as per RFC1738 with ' ' equal to '+'.
454
455```
456assert.equal(qs.stringify({ a: 'b c' }), 'a=b%20c');
457assert.equal(qs.stringify({ a: 'b c' }, { format : 'RFC3986' }), 'a=b%20c');
458assert.equal(qs.stringify({ a: 'b c' }, { format : 'RFC1738' }), 'a=b+c');
459```
460
461[1]: https://npmjs.org/package/qs
462[2]: http://versionbadg.es/ljharb/qs.svg
463[3]: https://api.travis-ci.org/ljharb/qs.svg
464[4]: https://travis-ci.org/ljharb/qs
465[5]: https://david-dm.org/ljharb/qs.svg
466[6]: https://david-dm.org/ljharb/qs
467[7]: https://david-dm.org/ljharb/qs/dev-status.svg
468[8]: https://david-dm.org/ljharb/qs?type=dev
469[9]: https://ci.testling.com/ljharb/qs.png
470[10]: https://ci.testling.com/ljharb/qs
471[11]: https://nodei.co/npm/qs.png?downloads=true&stars=true
472[license-image]: http://img.shields.io/npm/l/qs.svg
473[license-url]: LICENSE
474[downloads-image]: http://img.shields.io/npm/dm/qs.svg
475[downloads-url]: http://npm-stat.com/charts.html?package=qs