Skip to content
Tutorials Center
My learning

Topics

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.

NODE
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

Node.js parse() and stringify()

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.

Node.js Limits, escaping and URLSearchParams

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

NODE
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=2 gives '2', not 2.
  • A key without = gets an empty string. Because the result has a null prototype, hasOwnProperty is missing; use Object.hasOwn(obj, key) or the in operator.
  • maxKeys guards 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 produce a[b]=c.
  • It does not encode spaces as +; it uses %20. URLSearchParams.toString() uses +.
  • Choose URLSearchParams for new code. Keep querystring where you must preserve its exact output, such as signing or compatibility with an older service.