qs
A querystring parser and serializer with nesting support
qs parses and serializes URL query strings in JavaScript, with support for nested objects, arrays, and built-in safety limits that prevent abuse from oversized or deeply-nested inputs.
qs is a small JavaScript library for reading and writing query strings, which are the key-value pairs that appear after the question mark in a URL. For example, in the address example.com/search?name=alice&age=30, the part after the question mark is a query string. qs gives you a clean way to convert that text into a JavaScript object and, in the other direction, to turn an object back into a query string.
What sets qs apart from the basic query string tools built into browsers and Node.js is support for nesting. You can represent structured data like { user: { name: 'alice' } } in a URL using bracket notation (user[name]=alice), and qs will correctly parse it back into that nested shape. It also handles arrays, optional dot notation, and several edge cases around duplicate keys and special characters.
The library includes a number of safety features designed for situations where the query string comes from untrusted input. By default it limits parsing to 1,000 parameters and five levels of nesting, which prevents certain kinds of abuse that can occur when an attacker sends an abnormally large or deeply nested input. These limits are configurable, and you can also set the library to throw an error rather than silently truncate when a limit is exceeded.
The README is detailed and covers many options: ignoring the leading question mark, using custom delimiters, handling different character encodings (including older ISO-8859-1 encoding used by some legacy systems), controlling how arrays are formatted in the output, and more. Both parsing and stringifying have their own set of options.
qs works in both Node.js and browsers, and is widely used as a dependency inside larger frameworks and tools. It is maintained under the BSD-3-Clause license.
Where it fits
- Parse a URL query string from user input into a nested JavaScript object, safely handling unexpected or malformed values.
- Serialize a nested JavaScript object into a URL query string with bracket notation for use in an API request.
- Handle arrays and nested structures in query strings that the built-in browser URLSearchParams cannot represent.
- Enforce parsing limits in a server-side app to prevent abuse from oversized or deeply-nested query string inputs.