build-url-ts is intentionally small: pass a base URL and an object, get a URL with encoded query parameters. It exists because string-built URLs are one of those tiny bugs that survive code review until a space, array, or undefined value lands in production.
Why it exists#
I do not want every codebase to grow a custom query-string helper. I also do not want a heavy dependency for a job the platform already mostly knows how to do. This repo keeps the contract narrow: take structured input, normalize it once, and let the caller stop thinking about escaping rules.
Small helpers are worth building when they remove a repeated source of defensive programming. URL construction shows up in API clients, dashboards, webhooks, redirects, and internal tools. The mistakes are rarely dramatic in review. They look like "works for this one example" and then fail when the value is empty, repeated, encoded already, or passed through another system.
The useful thing here is not clever URL logic. It is reducing the number of places a team has to remember the same edge case.
What's inside#
- Object-to-query handling with predictable encoding.
- TypeScript types around the input shape.
- Existing query parameters are merged instead of accidentally discarded.
- Array parameters, empty values, and already-encoded input get one shared rule.
- ESM, CommonJS, and browser/CDN builds exist because tiny utilities often travel farther than the app they started in.
- A small surface area that is easy to test and delete if the platform covers it later.
Where it earns its place#
The repo is not trying to replace URL or URLSearchParams. It wraps the part where teams usually
get inconsistent: how object values become query parameters, what gets skipped, what gets repeated,
and how a base URL with existing parameters should behave.
That matters in generated SDKs, webhook calls, analytics links, signed redirects, and internal tools. A single wrong separator or double-encoded value can turn into a support issue that looks larger than the bug really is. I would rather put that boring edge in a tiny package with tests than debug it again in every caller.
The engineering habit#
When a bug class repeats, I prefer a tiny boring primitive over scattered comments. The primitive should be easy to read, easy to test, and small enough that nobody feels trapped by it. If the standard platform later covers the same behavior cleanly, delete the helper and move on.
That is the whole point of this repo: make the common path safer without creating a framework around a URL.