url-search-params

url-search-params is a small, dependency-free polyfill for the WHATWG URLSearchParams interface, letting code parse and build query strings the same way on platforms that predate native support. It implements the full surface of the spec — append, delete, get, getAll, has, set, sort, and iteration via keys/values/entries — using plain ES5 so it can run anywhere, including older browsers and legacy Node.js versions.

Beyond the standalone constructor, it also patches HTMLAnchorElement.prototype.searchParams and URL.prototype.searchParams when the host environment defines search/href accessors but not the searchParams getter itself, so anchor and URL objects gain a working searchParams property that stays in sync with href and search. The project is explicitly marked deprecated by its author in favor of the actively maintained @ungap/url-search-params, but the original package remains published and widely downloaded as a drop-in shim for projects still targeting it.

What You Get

• A full URLSearchParams constructor implementing append, delete, get, getAll, has, set, sort, and toString
• Iterable keys(), values(), and entries() methods with Symbol.iterator support where available
• Automatic patching of HTMLAnchorElement.prototype.searchParams and URL.prototype.searchParams so anchor/URL objects expose a live, synced searchParams property
• Multiple prebuilt distributions (CommonJS/Node, AMD, plain browser global, and minified variants) so it can be dropped into virtually any module system
• Zero runtime dependencies, keeping the footprint small for legacy or size-constrained environments

Common Use Cases

• Shimming URLSearchParams in older browsers (e.g. pre-Chrome 49 or iOS 10 with its known buggy native implementation) before falling back to native support checks
• Providing query-string parsing/building in legacy Node.js codebases that predate native URLSearchParams availability
• Giving anchor elements a working searchParams accessor in environments where only href/search setters exist
• Server-rendered or isomorphic apps needing consistent URLSearchParams behavior across both server and older client runtimes

Under The Hood

Architecture The polyfill is split into a handful of small, single-purpose files that are concatenated by a Makefile into several distributable bundles (build/url-search-params.js, .node.js, .amd.js, and minified “max” variants). src/url-search-params.js implements the core prototype methods (forEach, keys, values, entries, Symbol.iterator) by feature-detecting existing native support and only patching what’s missing; src/url-search-params-sort.js adds a spec-compliant sort() the same way; src/utilities.js contains upgradeClass, which conditionally redefines href/search/searchParams accessors on HTMLAnchorElement and URL prototypes so they stay synchronized with an internal _searchParams instance; and src/upgrades.js is the thin entry point that invokes upgradeClass against those two globals when present. There’s no dependency injection or layered architecture — it’s a flat, prototype-patching shim, and its main risk surface is that any consumer relying on exact native URLSearchParams/URL prototype shape could be affected since the polyfill mutates those prototypes directly rather than providing an isolated implementation.

Tech Stack Written in plain ES5 JavaScript with zero runtime dependencies, targeting maximum compatibility with legacy browsers and Node.js. The build pipeline uses a hand-written Makefile plus uglify-js for minification and jshint for linting; wru serves as the lightweight test-assertion framework, and tiny-cdn provides a local dev server for the browser demo page. There is no TypeScript, no modern bundler (webpack/rollup/esbuild), and no type declarations — distribution relies entirely on prebuilt static files referenced from package.json’s main/unpkg fields.

Code Quality A single test file (test/url-search-params.js) exercises the public API using the wru micro-framework, run via npm test; there is no CI configuration currently active in the repository (the README’s Travis badge points at a build that predates the repo’s archival) and no type system to catch misuse at compile time. Error handling is minimal by design — a single explicit TypeError guard exists for calling searchParams on the wrong instance type, and there’s no structured logging or validation elsewhere. Naming is consistent camelCase throughout, and the codebase’s small size keeps it readable despite the lack of modern tooling.

API Design The public API mirrors the native URLSearchParams interface method-for-method, so there’s effectively zero learning curve for anyone who already knows the Web API it polyfills — you require('url-search-params') (or include the browser build) and call the same append/get/set/delete/sort methods you’d use natively. The only extra concept to learn is the documented HTMLAnchorElement.prototype.searchParams feature-detection pattern the README calls out, which requires an explicit 'searchParams' in HTMLAnchorElement.prototype check rather than a truthy check to avoid a spec-compliant TypeError. Getting started requires no configuration or boilerplate beyond the import.