Registry / http-networking / http-url-builder

http-url-builder

library1.1.0jsnpmunverified

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.

http-networking

npm install http-url-builder

github ↗package ↗

INSTALL

IMPORT

SIG · HTTP-URL-BUILDER

http-url-builder

http-networkingjavascriptv1.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

URLBuilder

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

✗ const URLBuilder = require('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.

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

Debug

Known issues

breakingPrior 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.

affects: <1.1.0

gotchaThe `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`.

affects: >=1.0.0

gotchaWhen 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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: URLBuilder is not a constructor

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.

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()`.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/FlamingTuri/url-builder ↗

packagehttps://www.npmjs.com/package/http-url-builder ↗