HTTP URL Builder

Common errors

• TypeError: URLBuilder is not a constructor

  cause Attempting to instantiate `URLBuilder` as a default export or incorrectly using `require` for a named export.
  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;`.

• Error: Path variable '{variableName}' not provided in withPathVariables.

  cause A placeholder like `/{variableName}` was included in an `addPath` call, but no corresponding key-value pair was supplied to the `withPathVariables` method.
  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()`.

Warnings

• breaking 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.
  Fix: Upgrade to v1.1.0 or newer and refactor path-building logic to use the `addPath('/{variableName}')` followed by `withPathVariables({ variableName: 'value' })` pattern.
• gotcha 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' })`.
  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`.
• gotcha 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`.
  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.

Install

• npm install http-url-builder npm
• yarn add http-url-builder yarn
• pnpm add http-url-builder pnpm

Imports

• URLBuilder
  wrong:

  const URLBuilder = require('http-url-builder');

  correct:

  import { URLBuilder } from 'http-url-builder';

  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.
• URLBuilderOptions

  import type { URLBuilderOptions } from 'http-url-builder';

  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.
• buildUrl

  import { buildUrl } from 'http-url-builder';

  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.

Quickstart

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.

import { URLBuilder } from 'http-url-builder';

interface UserProfile { id: string; name: string; age: number; status: 'active' | 'inactive'; }

const API_BASE = 'https://api.example.com';

// Build a URL for fetching a user profile by ID
const userProfileUrl = new URLBuilder(API_BASE)
  .addPath('/users')
  .addPath('/{userId}')
  .withPathVariables({ userId: '123' })
  .addQuery('fields', 'id,name,status')
  .addQuery('expand', 'posts')
  .build();

console.log(`User Profile URL: ${userProfileUrl}`);
// Expected: https://api.example.com/users/123?fields=id,name,status&expand=posts

// Build a URL for searching users with specific criteria
const searchUsersUrl = new URLBuilder(API_BASE)
  .addPath('/search')
  .addQuery('query', 'john doe')
  .addQuery('limit', 10)
  .addQuery('page', 2)
  .build();

console.log(`Search Users URL: ${searchUsersUrl}`);
// Expected: https://api.example.com/search?query=john+doe&limit=10&page=2

// Example with optional parameters and encoding
const itemSearchUrl = new URLBuilder('https://store.example.com')
  .addPath('/items')
  .addQuery('category', 'electronics')
  .addQuery('q', 'usb-c adapter & charger') // Spaces and special chars handled
  .build();

console.log(`Item Search URL: ${itemSearchUrl}`);
// Expected: https://store.example.com/items?category=electronics&q=usb-c+adapter+%26+charger