Node.js Reference ยท path, os and url
The Node.js querystring module
Reference for the legacy Node.js querystring module: parse(), stringify(), escape() and unescape(), repeated keys, options, null-prototype results and URLSearchParams.
The node:querystring module converts between a query string like a=1&b=two and a plain object. It predates URLSearchParams and is now marked legacy: it is kept for compatibility and will not change, but new code should use URLSearchParams, which behaves like browsers.
There are four functions: parse() (string to object), stringify() (object to string), and the escaping helpers escape() and unescape(). The module's best-known quirk is that a key which appears several times becomes an array, and that the object parse() returns has no prototype.
import qs from 'node:querystring'; qs.parse('a=1&b=2&b=3'); // [Object: null prototype] { a: '1', b: ['2', '3'] } qs.stringify({ q: 'node js' }); // 'q=node%20js'
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
querystring.parse(str[, sep[, eq[, options]]]) querystring.stringify(obj[, sep[, eq[, options]]]) querystring.escape(str) querystring.unescape(str)
| Name | Description |
|---|---|
str |
The query string (without a leading ?) or the string to escape. |
obj |
An object whose values are strings, numbers, bigints, booleans or arrays of those. |
sep |
Pair separator. Default '&'. |
eq |
Key/value separator. Default '='. |
options.maxKeys |
parse() only. Maximum number of keys to read. Default 1000; 0 means no limit. |
options.decodeURIComponent |
parse() only. Function used to decode. Default querystring.unescape(). |
options.encodeURIComponent |
stringify() only. Function used to encode. Default querystring.escape(). |
Returns: parse() gives an object with a null prototype; the others return strings.
Errors: escape() throws URIError for a lone surrogate. unescape() falls back to a lenient decoder instead of throwing when the input has a bad percent sequence.
Usage notes
- Repeated keys become arrays and single keys stay strings, so the type of a value depends on the input. Normalize with
[].concat(value)when you need a list. - All values are strings after
parse();page=2gives'2', not2. - A key without
=gets an empty string. Because the result has a null prototype,hasOwnPropertyis missing; useObject.hasOwn(obj, key)or theinoperator. maxKeysguards against attackers sending thousands of parameters. Keep it unless you have a reason.stringify()silently turns unsupported values (null,undefined, objects) into empty strings and does not nest objects; it will not producea[b]=c.- It does not encode spaces as
+; it uses%20.URLSearchParams.toString()uses+. - Choose
URLSearchParamsfor new code. Keepquerystringwhere you must preserve its exact output, such as signing or compatibility with an older service.