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