@@ -34,7 +34,6 @@ assert.equal(str, 'a=c');
3434### Parsing Objects
3535
3636[ ] ( #preventEval )
37-
3837``` javascript
3938qs .parse (string, [options]);
4039```
@@ -45,8 +44,8 @@ For example, the string `'foo[bar]=baz'` converts to:
4544``` javascript
4645assert .deepEqual (qs .parse (' foo[bar]=baz' ), {
4746 foo: {
48- bar: ' baz' ,
49- },
47+ bar: ' baz'
48+ }
5049});
5150```
5251
@@ -58,7 +57,7 @@ assert.deepEqual(nullObject, { a: { hasOwnProperty: 'b' } });
5857```
5958
6059By 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.
61- _ 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.
60+ * 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.
6261Always be careful with this option.
6362
6463``` javascript
@@ -70,7 +69,7 @@ URI encoded strings work too:
7069
7170``` javascript
7271assert .deepEqual (qs .parse (' a%5Bb%5D=c' ), {
73- a: { b: ' c' },
72+ a: { b: ' c' }
7473});
7574```
7675
@@ -80,9 +79,9 @@ You can also nest your objects, like `'foo[bar][baz]=foobarbaz'`:
8079assert .deepEqual (qs .parse (' foo[bar][baz]=foobarbaz' ), {
8180 foo: {
8281 bar: {
83- baz: ' foobarbaz' ,
84- },
85- },
82+ baz: ' foobarbaz'
83+ }
84+ }
8685});
8786```
8887
@@ -97,13 +96,13 @@ var expected = {
9796 d: {
9897 e: {
9998 f: {
100- ' [g][h][i]' : ' j' ,
101- },
102- },
103- },
104- },
105- },
106- },
99+ ' [g][h][i]' : ' j'
100+ }
101+ }
102+ }
103+ }
104+ }
105+ }
107106};
108107var string = ' a[b][c][d][e][f][g][h][i]=j' ;
109108assert .deepEqual (qs .parse (string), expected);
@@ -137,7 +136,6 @@ assert.deepEqual(limited, { a: 'b' });
137136```
138137
139138If you want an error to be thrown whenever the a limit is exceeded (eg, ` parameterLimit ` , ` arrayLimit ` ), set the ` throwOnLimitExceeded ` option to ` true ` . This option will generate a descriptive error if the query string exceeds a configured limit.
140-
141139``` javascript
142140try {
143141 qs .parse (' a=1&b=2&c=3&d=4' , { parameterLimit: 3 , throwOnLimitExceeded: true });
@@ -182,18 +180,16 @@ Note: it implies `allowDots`, so `parse` will error if you set `decodeDotInKeys`
182180
183181``` javascript
184182var withDots = qs .parse (' name%252Eobj.first=John&name%252Eobj.last=Doe' , { decodeDotInKeys: true });
185- assert .deepEqual (withDots, { ' name.obj' : { first: ' John' , last: ' Doe' } });
183+ assert .deepEqual (withDots, { ' name.obj' : { first: ' John' , last: ' Doe' }});
186184```
187185
188186Option ` allowEmptyArrays ` can be used to allowing empty array values in object
189-
190187``` javascript
191188var withEmptyArrays = qs .parse (' foo[]&bar=baz' , { allowEmptyArrays: true });
192189assert .deepEqual (withEmptyArrays, { foo: [], bar: ' baz' });
193190```
194191
195192Option ` duplicates ` can be used to change the behavior when duplicate keys are encountered
196-
197193``` javascript
198194assert .deepEqual (qs .parse (' foo=bar&foo=baz' ), { foo: [' bar' , ' baz' ] });
199195assert .deepEqual (qs .parse (' foo=bar&foo=baz' , { duplicates: ' combine' }), { foo: [' bar' , ' baz' ] });
@@ -209,7 +205,7 @@ assert.deepEqual(oldCharset, { a: '§' });
209205```
210206
211207Some services add an initial ` utf8=✓ ` value to forms so that old Internet Explorer versions are more likely to submit the form as utf-8.
212- Additionally, the server can check the value against wrong encodings of the checkmark character and detect that a query string or ` application/x-www-form-urlencoded ` body was _ not _ sent as utf-8, eg. if the form had an ` accept-charset ` parameter or the containing page had a different character set.
208+ Additionally, the server can check the value against wrong encodings of the checkmark character and detect that a query string or ` application/x-www-form-urlencoded ` body was * not * sent as utf-8, eg. if the form had an ` accept-charset ` parameter or the containing page had a different character set.
213209
214210** qs** supports this mechanism via the ` charsetSentinel ` option.
215211If specified, the ` utf8 ` parameter will be omitted from the returned object.
@@ -221,14 +217,14 @@ In that sense the `charset` will behave as the default charset rather than the a
221217``` javascript
222218var detectedAsUtf8 = qs .parse (' utf8=%E2%9C%93&a=%C3%B8' , {
223219 charset: ' iso-8859-1' ,
224- charsetSentinel: true ,
220+ charsetSentinel: true
225221});
226222assert .deepEqual (detectedAsUtf8, { a: ' ø' });
227223
228224// Browsers encode the checkmark as ✓ when submitting as iso-8859-1:
229225var detectedAsIso8859_1 = qs .parse (' utf8=%26%2310003%3B&a=%F8' , {
230226 charset: ' utf-8' ,
231- charsetSentinel: true ,
227+ charsetSentinel: true
232228});
233229assert .deepEqual (detectedAsIso8859_1, { a: ' ø' });
234230```
@@ -238,7 +234,7 @@ If you want to decode the `&#...;` syntax to the actual character, you can speci
238234``` javascript
239235var detectedAsIso8859_1 = qs .parse (' a=%26%239786%3B' , {
240236 charset: ' iso-8859-1' ,
241- interpretNumericEntities: true ,
237+ interpretNumericEntities: true
242238});
243239assert .deepEqual (detectedAsIso8859_1, { a: ' ☺' });
244240```
@@ -292,18 +288,17 @@ This is needed to handle cases when someone sent, for example, `a[999999999]` an
292288
293289``` javascript
294290var withMaxIndex = qs .parse (' a[100]=b' );
295- assert .deepEqual (withMaxIndex, { a: { 100 : ' b' } });
291+ assert .deepEqual (withMaxIndex, { a: { ' 100' : ' b' } });
296292```
297293
298294This limit can be overridden by passing an ` arrayLimit ` option:
299295
300296``` javascript
301297var withArrayLimit = qs .parse (' a[1]=b' , { arrayLimit: 0 });
302- assert .deepEqual (withArrayLimit, { a: { 1 : ' b' } });
298+ assert .deepEqual (withArrayLimit, { a: { ' 1 ' : ' b' } });
303299```
304300
305301If you want to throw an error whenever the array limit is exceeded, set the ` throwOnLimitExceeded ` option to ` true ` . This option will generate a descriptive error if the query string exceeds a configured limit.
306-
307302``` javascript
308303try {
309304 qs .parse (' a[1]=b' , { arrayLimit: 0 , throwOnLimitExceeded: true });
@@ -319,14 +314,14 @@ To disable array parsing entirely, set `parseArrays` to `false`.
319314
320315``` javascript
321316var noParsingArrays = qs .parse (' a[]=b' , { parseArrays: false });
322- assert .deepEqual (noParsingArrays, { a: { 0 : ' b' } });
317+ assert .deepEqual (noParsingArrays, { a: { ' 0 ' : ' b' } });
323318```
324319
325320If you mix notations, ** qs** will merge the two items into an object:
326321
327322``` javascript
328323var mixedNotation = qs .parse (' a[0]=b&a[b]=c' );
329- assert .deepEqual (mixedNotation, { a: { 0 : ' b' , b: ' c' } });
324+ assert .deepEqual (mixedNotation, { a: { ' 0 ' : ' b' , b: ' c' } });
330325```
331326
332327You can also create arrays of objects:
@@ -337,12 +332,10 @@ assert.deepEqual(arraysOfObjects, { a: [{ b: 'c' }] });
337332```
338333
339334Some people use comma to join array, ** qs** can parse it:
340-
341335``` javascript
342- var arraysOfObjects = qs .parse (' a=b,c' , { comma: true });
343- assert .deepEqual (arraysOfObjects, { a: [' b' , ' c' ] });
336+ var arraysOfObjects = qs .parse (' a=b,c' , { comma: true })
337+ assert .deepEqual (arraysOfObjects, { a: [' b' , ' c' ] })
344338```
345-
346339(_ this cannot convert nested objects, such as ` a={b:1},{c:d} ` _ )
347340
348341### Parsing primitive/scalar values (numbers, booleans, null, etc)
@@ -360,7 +353,6 @@ If you wish to auto-convert values which look like numbers, booleans, and other
360353### Stringifying
361354
362355[ ] ( #preventEval )
363-
364356``` javascript
365357qs .stringify (object, [options]);
366358```
@@ -380,72 +372,60 @@ assert.equal(unencoded, 'a[b]=c');
380372```
381373
382374Encoding can be disabled for keys by setting the ` encodeValuesOnly ` option to ` true ` :
383-
384375``` javascript
385- var encodedValues = qs .stringify ({ a: ' b' , c: [' d' , ' e=f' ], f: [[' g' ], [' h' ]] }, { encodeValuesOnly: true });
386- assert .equal (encodedValues, ' a=b&c[0]=d&c[1]=e%3Df&f[0][0]=g&f[1][0]=h' );
376+ var encodedValues = qs .stringify (
377+ { a: ' b' , c: [' d' , ' e=f' ], f: [[' g' ], [' h' ]] },
378+ { encodeValuesOnly: true }
379+ );
380+ assert .equal (encodedValues,' a=b&c[0]=d&c[1]=e%3Df&f[0][0]=g&f[1][0]=h' );
387381```
388382
389383This encoding can also be replaced by a custom encoding method set as ` encoder ` option:
390384
391385``` javascript
392- var encoded = qs .stringify (
393- { a: { b: ' c' } },
394- {
395- encoder : function (str ) {
396- // Passed in values `a`, `b`, `c`
397- return ; // Return encoded string
398- },
399- }
400- );
386+ var encoded = qs .stringify ({ a: { b: ' c' } }, { encoder : function (str ) {
387+ // Passed in values `a`, `b`, `c`
388+ return // Return encoded string
389+ }})
401390```
402391
403392_ (Note: the ` encoder ` option does not apply if ` encode ` is ` false ` )_
404393
405394Analogue to the ` encoder ` there is a ` decoder ` option for ` parse ` to override decoding of properties and values:
406395
407396``` javascript
408- var decoded = qs .parse (' x=z' , {
409- decoder : function (str ) {
410- // Passed in values `x`, `z`
411- return ; // Return decoded string
412- },
413- });
397+ var decoded = qs .parse (' x=z' , { decoder : function (str ) {
398+ // Passed in values `x`, `z`
399+ return // Return decoded string
400+ }})
414401```
415402
416403You can encode keys and values using different logic by using the type argument provided to the encoder:
417404
418405``` javascript
419- var encoded = qs .stringify (
420- { a: { b: ' c' } },
421- {
422- encoder : function (str , defaultEncoder , charset , type ) {
423- if (type === ' key' ) {
424- return ; // Encoded key
425- } else if (type === ' value' ) {
426- return ; // Encoded value
427- }
428- },
406+ var encoded = qs .stringify ({ a: { b: ' c' } }, { encoder : function (str , defaultEncoder , charset , type ) {
407+ if (type === ' key' ) {
408+ return // Encoded key
409+ } else if (type === ' value' ) {
410+ return // Encoded value
429411 }
430- );
412+ }})
431413```
432414
433415The type argument is also provided to the decoder:
434416
435417``` javascript
436- var decoded = qs .parse (' x=z' , {
437- decoder : function (str , defaultDecoder , charset , type ) {
438- if (type === ' key' ) {
439- return ; // Decoded key
440- } else if (type === ' value' ) {
441- return ; // Decoded value
442- }
443- },
444- });
418+ var decoded = qs .parse (' x=z' , { decoder : function (str , defaultDecoder , charset , type ) {
419+ if (type === ' key' ) {
420+ return // Decoded key
421+ } else if (type === ' value' ) {
422+ return // Decoded value
423+ }
424+ }})
445425```
446426
447427Examples beyond this point will be shown as though the output is not URI encoded for clarity.
448- Please note that the return values in these cases _ will _ be URI encoded during real usage.
428+ Please note that the return values in these cases * will * be URI encoded during real usage.
449429
450430When arrays are stringified, they follow the ` arrayFormat ` option, which defaults to ` indices ` :
451431
@@ -464,13 +444,13 @@ qs.stringify({ a: ['b', 'c', 'd'] }, { indices: false });
464444You may use the ` arrayFormat ` option to specify the format of the output array:
465445
466446``` javascript
467- qs .stringify ({ a: [' b' , ' c' ] }, { arrayFormat: ' indices' });
447+ qs .stringify ({ a: [' b' , ' c' ] }, { arrayFormat: ' indices' })
468448// 'a[0]=b&a[1]=c'
469- qs .stringify ({ a: [' b' , ' c' ] }, { arrayFormat: ' brackets' });
449+ qs .stringify ({ a: [' b' , ' c' ] }, { arrayFormat: ' brackets' })
470450// 'a[]=b&a[]=c'
471- qs .stringify ({ a: [' b' , ' c' ] }, { arrayFormat: ' repeat' });
451+ qs .stringify ({ a: [' b' , ' c' ] }, { arrayFormat: ' repeat' })
472452// 'a=b&a=c'
473- qs .stringify ({ a: [' b' , ' c' ] }, { arrayFormat: ' comma' });
453+ qs .stringify ({ a: [' b' , ' c' ] }, { arrayFormat: ' comma' })
474454// 'a=b,c'
475455```
476456
@@ -493,14 +473,12 @@ qs.stringify({ a: { b: { c: 'd', e: 'f' } } }, { allowDots: true });
493473You may encode the dot notation in the keys of object with option ` encodeDotInKeys ` by setting it to ` true ` :
494474Note: it implies ` allowDots ` , so ` stringify ` will error if you set ` decodeDotInKeys ` to ` true ` , and ` allowDots ` to ` false ` .
495475Caveat: when ` encodeValuesOnly ` is ` true ` as well as ` encodeDotInKeys ` , only dots in keys and nothing else will be encoded.
496-
497476``` javascript
498- qs .stringify ({ ' name.obj' : { first: ' John' , last: ' Doe' } }, { allowDots: true , encodeDotInKeys: true });
477+ qs .stringify ({ " name.obj" : { " first" : " John" , " last" : " Doe" } }, { allowDots: true , encodeDotInKeys: true })
499478// 'name%252Eobj.first=John&name%252Eobj.last=Doe'
500479```
501480
502481You may allow empty array values by setting the ` allowEmptyArrays ` option to ` true ` :
503-
504482``` javascript
505483qs .stringify ({ foo: [], bar: ' baz' }, { allowEmptyArrays: true });
506484// 'foo[]&bar=baz'
@@ -518,8 +496,8 @@ Key with no values (such as an empty object or array) will return nothing:
518496assert .equal (qs .stringify ({ a: [] }), ' ' );
519497assert .equal (qs .stringify ({ a: {} }), ' ' );
520498assert .equal (qs .stringify ({ a: [{}] }), ' ' );
521- assert .equal (qs .stringify ({ a: { b: [] } }), ' ' );
522- assert .equal (qs .stringify ({ a: { b: {} } }), ' ' );
499+ assert .equal (qs .stringify ({ a: { b: []} }), ' ' );
500+ assert .equal (qs .stringify ({ a: { b: {}} }), ' ' );
523501```
524502
525503Properties that are set to ` undefined ` will be omitted entirely:
@@ -546,14 +524,7 @@ If you only want to override the serialization of `Date` objects, you can provid
546524var date = new Date (7 );
547525assert .equal (qs .stringify ({ a: date }), ' a=1970-01-01T00:00:00.007Z' .replace (/ :/ g , ' %3A' ));
548526assert .equal (
549- qs .stringify (
550- { a: date },
551- {
552- serializeDate : function (d ) {
553- return d .getTime ();
554- },
555- }
556- ),
527+ qs .stringify ({ a: date }, { serializeDate : function (d ) { return d .getTime (); } }),
557528 ' a=7'
558529);
559530```
@@ -564,7 +535,7 @@ You may use the `sort` option to affect the order of parameter keys:
564535function alphabeticalSort (a , b ) {
565536 return a .localeCompare (b);
566537}
567- assert .equal (qs .stringify ({ a: ' c' , z: ' y' , b: ' f' }, { sort: alphabeticalSort }), ' a=c&b=f&z=y' );
538+ assert .equal (qs .stringify ({ a: ' c' , z: ' y' , b : ' f' }, { sort: alphabeticalSort }), ' a=c&b=f&z=y' );
568539```
569540
570541Finally, you can use the ` filter ` option to restrict which keys will be included in the stringified output.
@@ -666,7 +637,7 @@ assert.deepEqual(parsedStrictNull, { a: null, b: '' });
666637To completely skip rendering keys with ` null ` values, use the ` skipNulls ` flag:
667638
668639``` javascript
669- var nullsSkipped = qs .stringify ({ a: ' b' , c: null }, { skipNulls: true });
640+ var nullsSkipped = qs .stringify ({ a: ' b' , c: null }, { skipNulls: true });
670641assert .equal (nullsSkipped, ' a=b' );
671642```
672643
@@ -718,7 +689,7 @@ assert.deepEqual(obj, { a: 'こんにちは!' });
718689
719690### RFC 3986 and RFC 1738 space encoding
720691
721- RFC3986 used as default option and encodes ' ' to _ %20 _ which is backward compatible.
692+ RFC3986 used as default option and encodes ' ' to * %20 * which is backward compatible.
722693In the same time, output can be stringified as per RFC1738 with ' ' equal to '+'.
723694
724695```
0 commit comments