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