{"id":17396,"library":"util-http","title":"HTTP Client Utility Module","description":"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.","status":"active","version":"0.0.15","language":"javascript","source_language":"en","source_url":"https://github.com/Tutitoos/util-http","tags":["javascript","http","axios","fetch","undici","superagent","http-client","http-requests","typescript"],"install":[{"cmd":"npm install util-http","lang":"bash","label":"npm"},{"cmd":"yarn add util-http","lang":"bash","label":"yarn"},{"cmd":"pnpm add util-http","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required if using AxiosClient for HTTP requests.","package":"axios","optional":true},{"reason":"Required if using UndiciClient for HTTP requests (Node.js high-performance client).","package":"undici","optional":true},{"reason":"Required if using SuperAgentClient for HTTP requests.","package":"superagent","optional":true}],"imports":[{"note":"The library is primarily designed for ESM usage, though CommonJS may work with bundlers.","wrong":"const AxiosClient = require('util-http').AxiosClient;","symbol":"AxiosClient","correct":"import { AxiosClient } from 'util-http';"},{"note":"HttpClient is a static utility class exposing all client implementations and common utilities, not a default export.","wrong":"import HttpClient from 'util-http';","symbol":"HttpClient","correct":"import { HttpClient } from 'util-http';"},{"note":"This is a TypeScript interface for configuring client options.","symbol":"ClientConfig","correct":"import type { ClientConfig } from 'util-http';"}],"quickstart":{"code":"import { AxiosClient } from 'util-http';\n\ninterface MyApiResponse {\n  id: number;\n  name: string;\n  status: string;\n}\n\nconst apiClient = new AxiosClient({\n  baseURL: 'https://api.example.com',\n  timeout: 10000,\n  headers: {\n    'Authorization': `Bearer ${process.env.API_TOKEN ?? ''}`,\n    'Content-Type': 'application/json',\n  },\n  onError: (err) => {\n    console.error('API request failed:', err.message, err.statusCode);\n    // Custom error transformation or logging before re-throwing\n    if (err.statusCode === 401) {\n        console.error('Authentication error. Please re-authenticate.');\n    }\n    throw err; // Re-throw the transformed error\n  }\n});\n\nasync function fetchData() {\n  try {\n    const response = await apiClient.get<MyApiResponse[]>('/items', {\n      params: { page: 1, limit: 10 },\n      headers: { 'X-Custom-Header': 'Hello' } // Overrides global headers\n    });\n    console.log('Fetched data:', response.data);\n  } catch (error) {\n    console.error('Error fetching data:', error);\n  }\n}\n\nfetchData();","lang":"typescript","description":"Initializes an AxiosClient with global configurations, sets up an error interceptor, and performs a GET request to an API endpoint."},"warnings":[{"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.","message":"As 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.","severity":"breaking","affected_versions":">=0.0.1"},{"fix":"If using `AxiosClient`, run `npm install axios`. If using `UndiciClient`, run `npm install undici`. If using `SuperAgentClient`, run `npm install superagent`.","message":"To 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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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`.","message":"There 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.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install `axios`: `npm install axios` or `pnpm add axios`.","cause":"Attempting to use `AxiosClient` without having the `axios` package installed as a dependency.","error":"Error: Cannot find module 'axios'"},{"fix":"Review the `ClientConfig` interface for expected property names and types. Ensure all properties conform to the interface definition.","cause":"Incorrectly structuring the `ClientConfig` object or providing properties not defined in the interface.","error":"TS2345: Argument of type '{ baseURL: string; timeout: number; ... }' is not assignable to parameter of type 'ClientConfig'."},{"fix":"Ensure the client object (e.g., `new AxiosClient(...)`) is correctly instantiated and assigned to a variable before attempting to make requests.","cause":"Trying to call a request method (like `get`) on a client instance that hasn't been properly initialized or assigned.","error":"TypeError: Cannot read properties of undefined (reading 'get')"}],"ecosystem":"npm","meta_description":null}