URLSearchParams encoder / decoder

The snippets below parse and serialize application/x-www-form-urlencoded query pairs. Node's new URLSearchParams() is the same WHATWG class this page uses. CPython urllib.parse.parse_qsl plus urlencode is the stdlib pair that keeps duplicate keys in order. For when form encoding differs from RFC 3986 percent-encoding, see URLSearchParams vs encodeURIComponent: Form vs Percent-Encoding.

const encoded = new URLSearchParams('q=hello world&category=news').toString();
// "q=hello+world&category=news"

const pairs = [...new URLSearchParams('q=hello+world&category=news').entries()];
// [["q", "hello world"], ["category", "news"]]

new URLSearchParams('?q=hello world').toString();
// "q=hello+world"

new URLSearchParams('a=1&a=2').toString();
// "a=1&a=2"

from urllib.parse import parse_qsl, urlencode

raw = 'q=hello world&category=news'.lstrip('?')
pairs = parse_qsl(raw, keep_blank_values=True)
# [('q', 'hello world'), ('category', 'news')]

urlencode(pairs)
# 'q=hello+world&category=news'

parse_qsl('a=1&a=2', keep_blank_values=True)
# [('a', '1'), ('a', '2')]

urlencode writes * as %2A and leaves ~; this page and Node leave * and write ~ as %7E. quote_plus / unquote_plus encode one value, not a query. This page rejects a full URL; paste only the query. curl --url-query samples are in URLSearchParams in the shell below. Percent-encode a string on the URL encoder; split an absolute URL on the URL parser.

There is no POSIX form-urlencoded encoder. jq 1.7 @uri percent-encodes UTF-8 and writes %20 for spaces — RFC 3986, not this page. curl 8.5 --url-query (and --data-urlencode with -G) is application/x-www-form-urlencoded: spaces become +. Each flag is one name=value pair, not a whole query. On the documented pairs ( q=hello world and category=news), two --url-query flags write the same q=hello+world&category=news Encode writes. -w '%{url_effective}' prints the encoded URL; the host is only a placeholder. curl is not POSIX. For the Node and CPython snippets, see URLSearchParams in Python and Node above.

# Two pairs (same query Encode writes)
curl -s --url-query 'q=hello world' --url-query 'category=news' \
  -o /dev/null -w '%{url_effective}\n' \
  https://example.invalid/
# https://example.invalid/?q=hello+world&category=news

# Named stdin
printf '%s' 'hello world' | curl -s --url-query 'q@-' \
  -o /dev/null -w '%{url_effective}\n' \
  https://example.invalid/
# https://example.invalid/?q=hello+world

# Same encoder via -G --data-urlencode
curl -s -G --data-urlencode 'q=hello world' \
  --data-urlencode 'category=news' \
  -o /dev/null -w '%{url_effective}\n' \
  https://example.invalid/
# https://example.invalid/?q=hello+world&category=news

Passing the whole query as one flag encodes & and = in the value (q=hello+world%26category%3dnews); this page parses pairs. A leading ? becomes a literal question mark in the name (??q=hello+world); Encode strips one leading ?. curl leaves ~ and encodes * as %2a; this page writes %7E and leaves *. A literal + becomes %2b; Encode of q=hello+world stays q=hello+world (Decode treats that plus as a space). Hex digits are lowercase (%2b / %c3%a9); this page writes uppercase %2B / %C3%A9. Already-encoded %20 becomes %2520 in curl; Encode here writes hello+world. A space in a field name stays a space (hello world=news); this page writes hello+world=news. Empty stdin with @- adds no query. A full URL is encoded as a field; this page throws. curl has no form-urlencoded decoder — use Decode here or the Node / CPython snippets above. Without -G, --data-urlencode is a POST body, so %{url_effective} has no query. @uri and Encode component live on the URL encoder. curl %{url.host} is not a WHATWG parser — split an absolute URL on the URL parser. For form encoding vs percent-encoding, see URLSearchParams vs encodeURIComponent: Form vs Percent-Encoding.