1# qs
  2
  3A querystring parsing and stringifying library with some added security.
  4
  5[![Build Status](https://secure.travis-ci.org/hapijs/qs.svg)](http://travis-ci.org/hapijs/qs)
  6
  7Lead Maintainer: [Nathan LaFreniere](https://github.com/nlf)
  8
  9The **qs** module was originally created and maintained by [TJ Holowaychuk](https://github.com/visionmedia/node-querystring).
 10
 11## Usage
 12
 13```javascript
 14var Qs = require('qs');
 15
 16var obj = Qs.parse('a=c');    // { a: 'c' }
 17var str = Qs.stringify(obj);  // 'a=c'
 18```
 19
 20### Parsing Objects
 21
 22```javascript
 23Qs.parse(string, [options]);
 24```
 25
 26**qs** allows you to create nested objects within your query strings, by surrounding the name of sub-keys with square brackets `[]`.
 27For example, the string `'foo[bar]=baz'` converts to:
 28
 29```javascript
 30{
 31  foo: {
 32    bar: 'baz'
 33  }
 34}
 35```
 36
 37URI encoded strings work too:
 38
 39```javascript
 40Qs.parse('a%5Bb%5D=c');
 41// { a: { b: 'c' } }
 42```
 43
 44You can also nest your objects, like `'foo[bar][baz]=foobarbaz'`:
 45
 46```javascript
 47{
 48  foo: {
 49    bar: {
 50      baz: 'foobarbaz'
 51    }
 52  }
 53}
 54```
 55
 56By default, when nesting objects **qs** will only parse up to 5 children deep. This means if you attempt to parse a string like
 57`'a[b][c][d][e][f][g][h][i]=j'` your resulting object will be:
 58
 59```javascript
 60{
 61  a: {
 62    b: {
 63      c: {
 64        d: {
 65          e: {
 66            f: {
 67              '[g][h][i]': 'j'
 68            }
 69          }
 70        }
 71      }
 72    }
 73  }
 74}
 75```
 76
 77This depth can be overridden by passing a `depth` option to `Qs.parse(string, [options])`:
 78
 79```javascript
 80Qs.parse('a[b][c][d][e][f][g][h][i]=j', { depth: 1 });
 81// { a: { b: { '[c][d][e][f][g][h][i]': 'j' } } }
 82```
 83
 84The depth limit helps mitigate abuse when **qs** is used to parse user input, and it is recommended to keep it a reasonably small number.
 85
 86For similar reasons, by default **qs** will only parse up to 1000 parameters. This can be overridden by passing a `parameterLimit` option:
 87
 88```javascript
 89Qs.parse('a=b&c=d', { parameterLimit: 1 });
 90// { a: 'b' }
 91```
 92
 93An optional delimiter can also be passed:
 94
 95```javascript
 96Qs.parse('a=b;c=d', { delimiter: ';' });
 97// { a: 'b', c: 'd' }
 98```
 99
100Delimiters can be a regular expression too:
101
102```javascript
103Qs.parse('a=b;c=d,e=f', { delimiter: /[;,]/ });
104// { a: 'b', c: 'd', e: 'f' }
105```
106
107### Parsing Arrays
108
109**qs** can also parse arrays using a similar `[]` notation:
110
111```javascript
112Qs.parse('a[]=b&a[]=c');
113// { a: ['b', 'c'] }
114```
115
116You may specify an index as well:
117
118```javascript
119Qs.parse('a[1]=c&a[0]=b');
120// { a: ['b', 'c'] }
121```
122
123Note 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
124to create an array. When creating arrays with specific indices, **qs** will compact a sparse array to only the existing values preserving
125their order:
126
127```javascript
128Qs.parse('a[1]=b&a[15]=c');
129// { a: ['b', 'c'] }
130```
131
132Note that an empty string is also a value, and will be preserved:
133
134```javascript
135Qs.parse('a[]=&a[]=b');
136// { a: ['', 'b'] }
137Qs.parse('a[0]=b&a[1]=&a[2]=c');
138// { a: ['b', '', 'c'] }
139```
140
141**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
142instead be converted to an object with the index as the key:
143
144```javascript
145Qs.parse('a[100]=b');
146// { a: { '100': 'b' } }
147```
148
149This limit can be overridden by passing an `arrayLimit` option:
150
151```javascript
152Qs.parse('a[1]=b', { arrayLimit: 0 });
153// { a: { '1': 'b' } }
154```
155
156To disable array parsing entirely, set `arrayLimit` to `-1`.
157
158If you mix notations, **qs** will merge the two items into an object:
159
160```javascript
161Qs.parse('a[0]=b&a[b]=c');
162// { a: { '0': 'b', b: 'c' } }
163```
164
165You can also create arrays of objects:
166
167```javascript
168Qs.parse('a[][b]=c');
169// { a: [{ b: 'c' }] }
170```
171
172### Stringifying
173
174```javascript
175Qs.stringify(object, [options]);
176```
177
178When stringifying, **qs** always URI encodes output. Objects are stringified as you would expect:
179
180```javascript
181Qs.stringify({ a: 'b' });
182// 'a=b'
183Qs.stringify({ a: { b: 'c' } });
184// 'a%5Bb%5D=c'
185```
186
187Examples 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.
188
189When arrays are stringified, by default they are given explicit indices:
190
191```javascript
192Qs.stringify({ a: ['b', 'c', 'd'] });
193// 'a[0]=b&a[1]=c&a[2]=d'
194```
195
196You may override this by setting the `indices` option to `false`:
197
198```javascript
199Qs.stringify({ a: ['b', 'c', 'd'] }, { indices: false });
200// 'a=b&a=c&a=d'
201```
202
203Empty strings and null values will omit the value, but the equals sign (=) remains in place:
204
205```javascript
206Qs.stringify({ a: '' });
207// 'a='
208```
209
210Properties that are set to `undefined` will be omitted entirely:
211
212```javascript
213Qs.stringify({ a: null, b: undefined });
214// 'a='
215```
216
217The delimiter may be overridden with stringify as well:
218
219```javascript
220Qs.stringify({ a: 'b', c: 'd' }, { delimiter: ';' });
221// 'a=b;c=d'
222```