{"id":17268,"library":"http-url-builder","title":"HTTP URL Builder","description":"http-url-builder is a lightweight utility designed to simplify the construction of HTTP URLs, primarily for REST API interactions. It provides a fluent API to append path segments, add query parameters, and integrate path variables, streamlining the process of creating complex endpoints. The current stable version is 1.1.0, which notably introduced support for path variables. As a relatively new but actively maintained package, its release cadence is feature-driven, with updates focused on enhancing usability and functionality. Key differentiators include its explicit support for path variables, a clear and chainable API, and native TypeScript typings, which ensure a robust development experience compared to manual string concatenation or less specialized URL manipulation libraries.","status":"active","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/FlamingTuri/url-builder","tags":["javascript","url","rest-api","typescript"],"install":[{"cmd":"npm install http-url-builder","lang":"bash","label":"npm"},{"cmd":"yarn add http-url-builder","lang":"bash","label":"yarn"},{"cmd":"pnpm add http-url-builder","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily exports a named `URLBuilder` class. While CommonJS `require` might work for some bundlers, ESM import is the idiomatic and officially supported way for modern JavaScript/TypeScript projects.","wrong":"const URLBuilder = require('http-url-builder');","symbol":"URLBuilder","correct":"import { URLBuilder } from 'http-url-builder';"},{"note":"For type-checking purposes, the `URLBuilderOptions` interface can be imported to define the initial configuration for a URLBuilder instance, ensuring type safety when constructing URLs.","symbol":"URLBuilderOptions","correct":"import type { URLBuilderOptions } from 'http-url-builder';"},{"note":"While `URLBuilder` provides a class-based approach, some utilities might offer a standalone function for simpler, one-off URL construction. Check documentation for specific function names if a non-class utility is preferred.","symbol":"buildUrl","correct":"import { buildUrl } from 'http-url-builder';"}],"quickstart":{"code":"import { URLBuilder } from 'http-url-builder';\n\ninterface UserProfile { id: string; name: string; age: number; status: 'active' | 'inactive'; }\n\nconst API_BASE = 'https://api.example.com';\n\n// Build a URL for fetching a user profile by ID\nconst userProfileUrl = new URLBuilder(API_BASE)\n  .addPath('/users')\n  .addPath('/{userId}')\n  .withPathVariables({ userId: '123' })\n  .addQuery('fields', 'id,name,status')\n  .addQuery('expand', 'posts')\n  .build();\n\nconsole.log(`User Profile URL: ${userProfileUrl}`);\n// Expected: https://api.example.com/users/123?fields=id,name,status&expand=posts\n\n// Build a URL for searching users with specific criteria\nconst searchUsersUrl = new URLBuilder(API_BASE)\n  .addPath('/search')\n  .addQuery('query', 'john doe')\n  .addQuery('limit', 10)\n  .addQuery('page', 2)\n  .build();\n\nconsole.log(`Search Users URL: ${searchUsersUrl}`);\n// Expected: https://api.example.com/search?query=john+doe&limit=10&page=2\n\n// Example with optional parameters and encoding\nconst itemSearchUrl = new URLBuilder('https://store.example.com')\n  .addPath('/items')\n  .addQuery('category', 'electronics')\n  .addQuery('q', 'usb-c adapter & charger') // Spaces and special chars handled\n  .build();\n\nconsole.log(`Item Search URL: ${itemSearchUrl}`);\n// Expected: https://store.example.com/items?category=electronics&q=usb-c+adapter+%26+charger","lang":"typescript","description":"This quickstart demonstrates how to instantiate `URLBuilder`, add path segments, specify path variables, append query parameters, and finally build the complete URL string for various API endpoints, including proper URL encoding."},"warnings":[{"fix":"Upgrade to v1.1.0 or newer and refactor path-building logic to use the `addPath('/{variableName}')` followed by `withPathVariables({ variableName: 'value' })` pattern.","message":"Prior to version 1.1.0, explicit support for `path variables` (e.g., `/users/{id}`) was not available. While manual string concatenation might have been used, the `withPathVariables` method was introduced in v1.1.0, requiring adoption of the new API for dynamic path segments.","severity":"breaking","affected_versions":"<1.1.0"},{"fix":"Provide clean, unencoded strings for path segments and query parameter values. For path variables, verify exact case-sensitive matching between the placeholder in `addPath` and the key in `withPathVariables`.","message":"The `URLBuilder` automatically handles URL encoding for query parameters and path segments. However, ensure that any base URLs or manually added path segments do not contain already encoded parts that should not be re-encoded, as this can lead to double encoding issues. For path variables, ensure the variable name in `addPath` (e.g., `{userId}`) exactly matches the key in `withPathVariables({ userId: 'value' })`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consult your API documentation. If multiple parameters for the same key should be treated as a single, combined value, construct that combined string (e.g., `value1,value2`) before calling `addQuery`. Otherwise, chaining `addQuery('key', 'value1').addQuery('key', 'value2')` will produce separate parameters.","message":"When using `addQuery` with multiple values for the same key, the builder typically appends them, potentially creating `?key=value1&key=value2`. Understand the expected behavior for your API. If your API expects comma-separated values (e.g., `?key=value1,value2`), you may need to construct the value string manually before passing it to `addQuery`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure you are using `import { URLBuilder } from 'http-url-builder';` if the library exports it as a named export. If using CommonJS, check the library's documentation for the correct `require` syntax, which might involve `const { URLBuilder } = require('http-url-builder');` or `const URLBuilder = require('http-url-builder').URLBuilder;`.","cause":"Attempting to instantiate `URLBuilder` as a default export or incorrectly using `require` for a named export.","error":"TypeError: URLBuilder is not a constructor"},{"fix":"Ensure that every path variable placeholder defined within `addPath` (e.g., `{userId}`) has an exact matching key in the object passed to `withPathVariables({ userId: 'actualValue' })` before calling `build()`.","cause":"A placeholder like `/{variableName}` was included in an `addPath` call, but no corresponding key-value pair was supplied to the `withPathVariables` method.","error":"Error: Path variable '{variableName}' not provided in withPathVariables."}],"ecosystem":"npm","meta_description":null}