• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Query string
2
3<!--introduced_in=v0.1.25-->
4
5> Stability: 2 - Stable
6
7<!--name=querystring-->
8
9<!-- source_link=lib/querystring.js -->
10
11The `querystring` module provides utilities for parsing and formatting URL
12query strings. It can be accessed using:
13
14```js
15const querystring = require('querystring');
16```
17
18## `querystring.decode()`
19<!-- YAML
20added: v0.1.99
21-->
22
23The `querystring.decode()` function is an alias for `querystring.parse()`.
24
25## `querystring.encode()`
26<!-- YAML
27added: v0.1.99
28-->
29
30The `querystring.encode()` function is an alias for `querystring.stringify()`.
31
32## `querystring.escape(str)`
33<!-- YAML
34added: v0.1.25
35-->
36
37* `str` {string}
38
39The `querystring.escape()` method performs URL percent-encoding on the given
40`str` in a manner that is optimized for the specific requirements of URL
41query strings.
42
43The `querystring.escape()` method is used by `querystring.stringify()` and is
44generally not expected to be used directly. It is exported primarily to allow
45application code to provide a replacement percent-encoding implementation if
46necessary by assigning `querystring.escape` to an alternative function.
47
48## `querystring.parse(str[, sep[, eq[, options]]])`
49<!-- YAML
50added: v0.1.25
51changes:
52  - version: v8.0.0
53    pr-url: https://github.com/nodejs/node/pull/10967
54    description: Multiple empty entries are now parsed correctly (e.g. `&=&=`).
55  - version: v6.0.0
56    pr-url: https://github.com/nodejs/node/pull/6055
57    description: The returned object no longer inherits from `Object.prototype`.
58  - version: v6.0.0, v4.2.4
59    pr-url: https://github.com/nodejs/node/pull/3807
60    description: The `eq` parameter may now have a length of more than `1`.
61-->
62
63* `str` {string} The URL query string to parse
64* `sep` {string} The substring used to delimit key and value pairs in the
65  query string. **Default:** `'&'`.
66* `eq` {string}. The substring used to delimit keys and values in the
67  query string. **Default:** `'='`.
68* `options` {Object}
69  * `decodeURIComponent` {Function} The function to use when decoding
70    percent-encoded characters in the query string. **Default:**
71    `querystring.unescape()`.
72  * `maxKeys` {number} Specifies the maximum number of keys to parse.
73    Specify `0` to remove key counting limitations. **Default:** `1000`.
74
75The `querystring.parse()` method parses a URL query string (`str`) into a
76collection of key and value pairs.
77
78For example, the query string `'foo=bar&abc=xyz&abc=123'` is parsed into:
79
80<!-- eslint-skip -->
81```js
82{
83  foo: 'bar',
84  abc: ['xyz', '123']
85}
86```
87
88The object returned by the `querystring.parse()` method _does not_
89prototypically inherit from the JavaScript `Object`. This means that typical
90`Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`, and others
91are not defined and *will not work*.
92
93By default, percent-encoded characters within the query string will be assumed
94to use UTF-8 encoding. If an alternative character encoding is used, then an
95alternative `decodeURIComponent` option will need to be specified:
96
97```js
98// Assuming gbkDecodeURIComponent function already exists...
99
100querystring.parse('w=%D6%D0%CE%C4&foo=bar', null, null,
101                  { decodeURIComponent: gbkDecodeURIComponent });
102```
103
104## `querystring.stringify(obj[, sep[, eq[, options]]])`
105<!-- YAML
106added: v0.1.25
107-->
108
109* `obj` {Object} The object to serialize into a URL query string
110* `sep` {string} The substring used to delimit key and value pairs in the
111  query string. **Default:** `'&'`.
112* `eq` {string}. The substring used to delimit keys and values in the
113  query string. **Default:** `'='`.
114* `options`
115  * `encodeURIComponent` {Function} The function to use when converting
116    URL-unsafe characters to percent-encoding in the query string. **Default:**
117    `querystring.escape()`.
118
119The `querystring.stringify()` method produces a URL query string from a
120given `obj` by iterating through the object's "own properties".
121
122It serializes the following types of values passed in `obj`:
123{string|number|boolean|string[]|number[]|boolean[]}
124Any other input values will be coerced to empty strings.
125
126```js
127querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' });
128// Returns 'foo=bar&baz=qux&baz=quux&corge='
129
130querystring.stringify({ foo: 'bar', baz: 'qux' }, ';', ':');
131// Returns 'foo:bar;baz:qux'
132```
133
134By default, characters requiring percent-encoding within the query string will
135be encoded as UTF-8. If an alternative encoding is required, then an alternative
136`encodeURIComponent` option will need to be specified:
137
138```js
139// Assuming gbkEncodeURIComponent function already exists,
140
141querystring.stringify({ w: '中文', foo: 'bar' }, null, null,
142                      { encodeURIComponent: gbkEncodeURIComponent });
143```
144
145## `querystring.unescape(str)`
146<!-- YAML
147added: v0.1.25
148-->
149
150* `str` {string}
151
152The `querystring.unescape()` method performs decoding of URL percent-encoded
153characters on the given `str`.
154
155The `querystring.unescape()` method is used by `querystring.parse()` and is
156generally not expected to be used directly. It is exported primarily to allow
157application code to provide a replacement decoding implementation if
158necessary by assigning `querystring.unescape` to an alternative function.
159
160By default, the `querystring.unescape()` method will attempt to use the
161JavaScript built-in `decodeURIComponent()` method to decode. If that fails,
162a safer equivalent that does not throw on malformed URLs will be used.
163