Request query parsing
Decode query parameters received by a Node.js backend.
Node.js · Module
node:querystring
The node:querystring module parses URL query strings into key-value collections and formats objects back into query-string text. It also exposes encoding and decoding helpers.
How it works
The module parses URL query strings into collections of key-value pairs and formats objects into URL query strings. Repeated keys become arrays when parsed, while stringify iterates over an object's own properties and encodes values.
Syntax
const querystring = require('node:querystring');
querystring.parse(str[, sep[, eq[, options]]]);
querystring.stringify(obj[, sep[, eq[, options]]]);
querystring.escape(str);
querystring.unescape(str);Parameters
| Name | Type | Description |
|---|---|---|
str | string | Query-string text to decode. |
obj | object | Object whose own properties are serialized. |
sep | string | Optional field separator used during parsing or formatting. |
eq | string | Optional key/value assignment character used during parsing or formatting. |
options | object | Optional parsing or formatting options, including custom encoding functions. |
Returns
parse() returns a collection of key-value pairs; stringify() returns a URL query string; escape() returns a percent-encoded string; unescape() returns a decoded string.
Key points
- Use the module when backend code needs to decode or generate URL query-string data.
- Load the built-in module through the
node:querystringspecifier rather than installing a package. - Use escape when a single string needs query-string percent-encoding.
- Use stringify to serialize an object's own properties into query-string syntax.
- Use parse to convert query-string text into an object-like collection for application code.
Common mistakes
- This module is Node-specific rather than a standardized web API; use URLSearchParams when browser compatibility matters or performance is not critical.
- Parsing is not a general URL parser: provide the query-string portion rather than a complete URL.
Example: Parse and format a query string
const querystring = require('node:querystring');
const parsed = querystring.parse('term=node&tag=api&tag=backend');
const encoded = querystring.stringify({ term: 'node', tag: ['api', 'backend'] });
console.log(parsed.term); // 'node'
console.log(parsed.tag); // [ 'api', 'backend' ]
console.log(encoded); // term=node&tag=api&tag=backendParse an incoming query string into key-value data, then serialize an object back into query-string form.
When to use it
URL query construction
Generate query strings for redirects, links, or outbound requests.
Component encoding
Apply Node-optimized percent encoding to an individual query value.
Interview questions
QWhat does the node:querystring module provide?
Import the module with require('node:querystring'). Use parse() to turn a query string into key-value data and stringify() to encode an object as a query string.
Follow-up: When would you choose URLSearchParams instead? Choose it when standardized behavior or browser-code compatibility is more valuable than this module's performance advantage.
QHow does parse handle repeated keys?
querystring.parse(str) converts a query string into a collection of key-value pairs. A key occurring multiple times is represented as an array in the parsed result.
Follow-up: How should a consumer handle a field that may be either a string or an array? Normalize the value at the boundary before applying application logic.
QHow does stringify construct its output?
querystring.stringify(obj) creates a query string by iterating over the object's own properties. Arrays produce repeated key-value pairs, and values are percent-encoded for the query-string format.
Follow-up: What should be checked when serializing unusual values? Verify the resulting string for the intended representation and use a custom encoding function only when the documented defaults are unsuitable.
Related
querystring.parse()querystring.stringify()querystring.escape()querystring.unescape()URLSearchParams