query-string

query-string is a small, dependency-light JavaScript library for parsing and stringifying URL query strings. It turns a ?foo=bar&baz=1 string into a plain object and back again, handling the messy edge cases that the raw URLSearchParams API leaves to you: multiple array-encoding conventions, optional number and boolean coercion, custom per-key type schemas, sorted output, and helpers that operate on full URLs including the hash fragment.

Widely used across the front-end ecosystem with tens of millions of weekly downloads, it works identically in modern browsers and Node.js, ships first-class TypeScript types, and exposes a tiny, predictable API surface centered on parse and stringify.

What You Get

• parse and stringify functions that convert between query strings and plain objects
• Six array-encoding formats (bracket, index, comma, separator, bracket-separator, colon-list-separator) plus the default duplicate-key style
• Optional coercion of values to numbers and booleans, or explicit per-key type schemas including custom transform functions
• URL-aware helpers parseUrl and stringifyUrl that preserve the path and hash fragment
• pick and exclude helpers for filtering parameters, and bundled TypeScript type definitions

Common Use Cases

• Reading and updating filter, sort, and pagination state stored in the URL of a single-page app
• Serializing request parameters into query strings for HTTP calls
• Normalizing array parameters between a frontend and an API that uses a specific bracket or comma convention
• Parsing OAuth or token data passed back in a URL hash fragment

Under The Hood

Architecture The entire library lives in base.js (~600 lines), re-exported through a tiny index.js that presents a default namespace object. Seven public functions — extract, parse, stringify, parseUrl, stringifyUrl, pick, and exclude — are built around internal encoderForArrayFormat and parserForArrayFormat factories that return the right encode/decode reducer for the chosen arrayFormat. parse splits pairs on &, uses split-on-first to divide each on its first =, decodes with decode-uri-component, folds results through the array reducer, and returns a prototype-less object via Object.create(null); stringify runs the inverse, and the URL helpers wrap these while carrying the path and hash fragment.

Tech Stack Written in modern ESM JavaScript targeting Node.js >=18 ("type": "module"), with three tiny single-purpose runtime dependencies: decode-uri-component, filter-obj, and split-on-first. Types ship as hand-written .d.ts files (base.d.ts, index.d.ts). Tooling is xo for linting, ava for tests, tsd for type tests, and a benchmark script.

Code Quality The code is clean and consistent, favoring small pure helpers and switch-based strategy selection over branching sprawl. Test coverage is thorough: a dedicated test/ directory holds separate suites for parse, stringify, parse-url, stringify-url, extract, pick, exclude, and property-based tests via fast-check, alongside index.test-d.ts type assertions. Edge cases around null, undefined, empty strings, and encoding are handled explicitly throughout.

API Design The developer experience is a strong point: the surface is minimal and memorable (parse/stringify mirror JSON), options are plain objects with sensible defaults, and the README documents every array format and type option with runnable examples. Full TypeScript definitions and isomorphic browser/Node behavior mean almost no boilerplate to get started, though the many arrayFormat variants require reading the docs to pick the right convention.