urlcat

urlcat is a small JavaScript and TypeScript library for building URLs without the usual string-concatenation pitfalls. It interpolates named path parameters, appends the rest as a query string, and handles slashes and escaping for you, so you no longer accidentally produce double slashes, missing separators, or unencoded values.

Its single friendly function reads almost like a template: give it a base URL, a path template with :params, and an object of values, and it fills in the path and query string correctly. Written in TypeScript with full type definitions and only qs as a dependency, urlcat keeps a tiny footprint while making API request URLs safe and readable.

What You Get

• A single urlcat() function for building complete URLs from a template and params
• Automatic path-parameter interpolation with :name placeholders
• Leftover params serialized into a properly escaped query string
• Correct slash handling so you never get double or missing slashes
• Full TypeScript types plus helpers like query() and subst() for partial building

Common Use Cases

• Constructing REST API request URLs from a base and path template
• Safely appending query parameters without manual encoding
• Interpolating dynamic path segments like /users/:id
• Replacing error-prone template-literal URL concatenation

Under The Hood

Architecture - The whole library is a single src/index.ts module. The overloaded urlcat function branches on its arguments: base + params, or base + path template + params. Internally it splits work between subst (replacing :name tokens in the path from the params object, consuming those keys) and query (serializing the remaining keys with qs). Helper routines join the base URL and path with a single slash and validate that every declared path parameter is provided, throwing on missing values.

Tech Stack - Authored in TypeScript with a single runtime dependency, qs, for query-string serialization. It builds with tsup into CommonJS, ESM, and type-definition outputs, and documentation is served with docsify. The package targets both browser and Node usage.

Code Quality - The test directory contains a comprehensive Jest suite with coverage reporting to Coveralls, exercising path interpolation, query serialization, slash edge cases, and error conditions. The code is strictly typed with function overloads that give precise signatures for each call form, and ESLint enforces style.

API Design - The API is the library’s standout feature: a single, template-like call that reads naturally and eliminates boilerplate. Overloads support building just a query string or just interpolating a path, and helper exports (query, subst, join) cover partial cases. Extensive documentation on urlcat.org and clear TypeScript signatures make it approachable within minutes.