util-http

library0.0.15jsnpmunverified

util-http is a JavaScript and TypeScript utility library designed to simplify and standardize HTTP requests by providing a unified API layer over several popular underlying HTTP clients. It currently supports wrapping `Axios`, the native `Fetch API`, `Undici` for high-performance Node.js environments, and `Superagent` for isomorphic (Node.js and browser) use cases. The library is currently in an early development phase, at version 0.0.15, implying a potentially rapid release cadence with possible breaking changes between minor versions. Its primary differentiator is the ability to swap out the underlying HTTP client while maintaining a consistent `ClientConfig` for global settings and `ClientOptions` for per-request overrides, complete with robust TypeScript type definitions for enhanced developer experience. It aims to abstract away client-specific configurations and error handling into a standardized interface, allowing developers to choose their preferred backend client without changing their application's request logic.

http-networking serialization

npm install util-http

github ↗package ↗

INSTALL

IMPORT

SIG · UTIL-HTTP

util-http

http-networkingjavascriptv0.0.15

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.

AxiosClient

✓ import { AxiosClient } from 'util-http';

✗ const AxiosClient = require('util-http').AxiosClient;

The library is primarily designed for ESM usage, though CommonJS may work with bundlers.

HttpClient

✓ import { HttpClient } from 'util-http';

✗ import HttpClient from 'util-http';

HttpClient is a static utility class exposing all client implementations and common utilities, not a default export.

ClientConfig

✓ import type { ClientConfig } from 'util-http';

This is a TypeScript interface for configuring client options.

Initializes an AxiosClient with global configurations, sets up an error interceptor, and performs a GET request to an API endpoint.

import { AxiosClient } from 'util-http'; interface MyApiResponse { id: number; name: string; status: string; } const apiClient = new AxiosClient({ baseURL: 'https://api.example.com', timeout: 10000, headers: { 'Authorization': `Bearer ${process.env.API_TOKEN ?? ''}`, 'Content-Type': 'application/json', }, onError: (err) => { console.error('API request failed:', err.message, err.statusCode); // Custom error transformation or logging before re-throwing if (err.statusCode === 401) { console.error('Authentication error. Please re-authenticate.'); } throw err; // Re-throw the transformed error } }); async function fetchData() { try { const response = await apiClient.get<MyApiResponse[]>('/items', { params: { page: 1, limit: 10 }, headers: { 'X-Custom-Header': 'Hello' } // Overrides global headers }); console.log('Fetched data:', response.data); } catch (error) { console.error('Error fetching data:', error); } } fetchData();

Debug

Known issues

breakingAs of version 0.0.15, this library is in early development. Minor versions (e.g., 0.0.x to 0.0.y) may introduce breaking changes to the API surface or internal client implementations without strict adherence to SemVer principles for major versions.

fix

Refer to the GitHub repository's commit history and README for specific changes between versions. It is recommended to pin exact versions or conduct thorough testing when upgrading.

affects: >=0.0.1

gotchaTo use specific client wrappers (e.g., `AxiosClient`, `UndiciClient`, `SuperAgentClient`), you must explicitly install the corresponding underlying HTTP library as a separate dependency in your project.

fix

If using `AxiosClient`, run `npm install axios`. If using `UndiciClient`, run `npm install undici`. If using `SuperAgentClient`, run `npm install superagent`.

affects: >=0.0.1

gotchaThere is a distinction between `ClientConfig` (global settings passed to the constructor) and `ClientOptions` (per-request settings). `ClientOptions` will always override `ClientConfig` for any conflicting properties.

fix

Always review the method signatures and documentation for `ClientConfig` and `ClientOptions` to ensure you are applying settings at the correct scope and precedence. Global headers, timeouts, and base URLs are set via `ClientConfig`, while specific URL, method, and data for a single request are set via `ClientOptions`.

affects: >=0.0.1

Errors

Common errors & fixes

Error: Cannot find module 'axios'

Attempting to use `AxiosClient` without having the `axios` package installed as a dependency.

fix

Install `axios`: `npm install axios` or `pnpm add axios`.

TS2345: Argument of type '{ baseURL: string; timeout: number; ... }' is not assignable to parameter of type 'ClientConfig'.

Incorrectly structuring the `ClientConfig` object or providing properties not defined in the interface.

fix

Review the `ClientConfig` interface for expected property names and types. Ensure all properties conform to the interface definition.

TypeError: Cannot read properties of undefined (reading 'get')

Trying to call a request method (like `get`) on a client instance that hasn't been properly initialized or assigned.

fix

Ensure the client object (e.g., `new AxiosClient(...)`) is correctly instantiated and assigned to a variable before attempting to make requests.

Upgrade

Version history

0.0.15latest on npm

Audit

Dependencies

axiosoptionalRequired if using AxiosClient for HTTP requests.

undicioptionalRequired if using UndiciClient for HTTP requests (Node.js high-performance client).

superagentoptionalRequired if using SuperAgentClient for HTTP requests.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Tutitoos/util-http ↗

packagehttps://www.npmjs.com/package/util-http ↗