qs

qs is the querystring parsing and stringifying library that powers Express’s built-in query parser and countless other Node.js HTTP stacks. It goes beyond the built-in querystring module by supporting nested objects and arrays through bracket notation (foo[bar][baz]=x), configurable array formats, and dot notation, while still round-tripping cleanly between parse and stringify.

Because qs sits directly in the path of untrusted user input, the maintainers have hardened it against parameter-pollution and prototype-pollution attacks with tunable limits — depth, parameterLimit, arrayLimit — and a strictDepth/throwOnLimitExceeded mode that turns silent truncation into explicit errors. It has minimal runtime dependencies and remains one of the most widely depended-upon packages in the npm ecosystem.

What You Get

• parse() and stringify() functions for converting between query strings and JavaScript objects
• Nested object and array support via bracket notation (a[b][c]=d) and optional dot notation
• Configurable limits (depth, parameterLimit, arrayLimit) with a throwOnLimitExceeded mode for defending against malicious input
• Multiple array serialization formats (indices, brackets, repeat, comma) for compatibility with different backend expectations
• iso-8859-1 and utf-8 charset handling, including sentinel-based auto-detection for legacy form submissions

Common Use Cases

• Parsing incoming query strings in Express, Connect, or other Node.js HTTP servers
• Serializing complex filter/sort/pagination state into a URL for client-side routing
• Round-tripping nested API request parameters without a full JSON body
• Sanitizing and bounding untrusted query input to prevent prototype-pollution or resource-exhaustion attacks

Under The Hood

Architecture qs is split into four small, single-purpose modules under lib/: parse.js walks a raw query string into a flat key-list via parseValues, then parseKeys/parseObject recursively expand bracket-notation keys (e.g. a[b][c]) into a nested object up to the configured depth, falling back to a flattened remainder key once that depth is exceeded. stringify.js performs the inverse walk, recursing over an arbitrary JS value and joining key/value pairs with a configurable delimiter, while utils.js provides the shared encode/decode, compact (sparse-array cleanup), and merge (safe object-merging that explicitly special-cases prototype pollution) primitives that both directions depend on. formats.js is a two-entry lookup for RFC1738 vs RFC3986 percent-encoding. There is no class hierarchy or plugin system — the whole library is a handful of composed functions gated by an options object, and index.js simply re-exports parse, stringify, and formats.

Tech Stack Written in plain ES5-style JavaScript ('use strict', var throughout, no build-time transpilation of the published code) targeting Node >=0.6 per package.json engines. Runtime dependencies are minimal and defensive: es-define-property (a Object.defineProperty cross-engine shim) and side-channel (an out-of-band WeakMap-style store used to track array-overflow state without mutating user objects). The dev toolchain uses browserify plus common-shakeify/bundle-collapser to produce a standalone browser bundle in dist/, tape with nyc for tests and coverage, and eslint with @ljharb/eslint-config for linting; CI (.github/workflows/) runs the test matrix down to Node versions below 10, reflecting the maintainer’s (ljharb) broader ecosystem commitment to very wide Node-version compatibility.

Code Quality Test coverage is extensive relative to the library’s size: test/parse.js (1933 lines), test/stringify.js (1678 lines), and test/utils.js (626 lines) exercise edge cases exhaustively — sparse arrays, prototype-pollution attempts, charset sentinels, depth/parameter/array-limit boundaries, and round-trip parse/stringify symmetry. npm test chains a README doctest runner (evalmd) with lint and coverage-gated tape runs, and posttest runs npm audit against production dependencies. Naming is consistent and functions are kept short and single-purpose; there is no TypeScript, but the small, stable public surface (parse, stringify, formats) limits the practical cost of that.

API Design The public API is deliberately tiny — two functions (parse, stringify) each taking a value and an options object — which keeps the zero-config path (qs.parse('a=c')) trivial while still exposing dozens of well-documented options (allowDots, arrayLimit, charsetSentinel, duplicates, etc.) for advanced tuning. The README is unusually thorough for an npm package, walking through every option with runnable, asserted code examples, which both documents behavior and doubles as the test suite via evalmd. The main friction point for newcomers is the sheer number of options and the security-relevant defaults (e.g. arrayLimit: 20, depth: 5) that silently reshape output unless understood upfront — a deliberate trade-off favoring safety over surprise-free flexibility.