File an issue

node:querystring

Node.js legacy query-string module, resolvable via both ESM import and CommonJS require. Provides percent-encoding and key-value parsing/formatting utilities.

For new code the WHATWG URLSearchParams API is generally preferred, but querystring remains the canonical Node.js primitive and is frequently required by existing npm packages.

Available methods

MethodDescription
parse(str, sep?, eq?, options?)Parse a URL-encoded query string into a key→value object
stringify(obj, sep?, eq?, options?)Serialize an object into a URL-encoded query string
escape(str)Percent-encode a string (encodeURIComponent-compatible unreserved set)
unescape(str)Percent-decode a string (UTF-8-aware)
encode(...)Alias for stringify
decode(...)Alias for parse

Behaviour notes

  • Percent-encoding leaves the ECMAScript encodeURIComponent unreserved set untouched: A-Za-z0-9-._~!*'(). Every other byte is percent-encoded as %XX of its UTF-8 representation.
  • parse converts + to space in keys and values (Node.js legacy behaviour); unescape does not.
  • Duplicate keys in the input to parse produce an array value; single occurrences produce a scalar string.
  • Array values passed to stringify expand into repeated key=value segments separated by sep.
  • Custom delimiters — pass sep and/or eq to override the defaults (& and =).
  • Result shape — parse returns a plain object with enumerable, writable, configurable data properties, compatible with Object.keys, JSON.stringify, and spread syntax.

Example

javascript
const qs = require("node:querystring");

// parse
const parsed = qs.parse("name=Ada&role=engineer&role=manager");
// → { name: "Ada", role: ["engineer", "manager"] }

// stringify
const encoded = qs.stringify({ name: "Ada", role: ["engineer", "manager"] });
// → "name=Ada&role=engineer&role=manager"

// escape / unescape
qs.escape("a b&c");     // → "a%20b%26c"
qs.unescape("a%20b");   // → "a b"

// custom delimiters
qs.parse("a:1;b:2", ";", ":");  // → { a: "1", b: "2" }

See also

  • Node.js upstream:
  • WHATWG URLSearchParams (recommended for new code)