HTTP Client Utility Module

Common errors

• Error: Cannot find module 'axios'

  cause 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'.

  cause 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')

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

Warnings

• breaking 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.
  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.
• gotcha 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.
  Fix: If using `AxiosClient`, run `npm install axios`. If using `UndiciClient`, run `npm install undici`. If using `SuperAgentClient`, run `npm install superagent`.
• gotcha 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.
  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`.

Install

• npm install util-http npm
• yarn add util-http yarn
• pnpm add util-http pnpm

Imports

• AxiosClient
  wrong:

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

  correct:

  import { AxiosClient } from 'util-http';

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

  import HttpClient from 'util-http';

  correct:

  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.

Quickstart

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();