@molecule/app-http-axios

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Axios HTTP client provider for @molecule/app-http.

This package provides an Axios-based implementation of the molecule HttpClient interface, allowing you to use molecule's HTTP abstractions with Axios.

Quick Start

import { createAxiosClient } from '@molecule/app-http-axios'
import { setClient } from '@molecule/app-http'

const client = createAxiosClient({
  baseURL: 'https://api.example.com',
  timeout: 10000,
})

setClient(client)

// Now use via `@molecule/app-http`
import { get, post } from '@molecule/app-http'
const users = await get('/users')
const newUser = await post('/users', { name: 'John' })

Type

provider

Installation

npm install @molecule/app-http-axios @molecule/app-http axios

API

Interfaces

AxiosHttpClientConfig

Axios-specific configuration.

interface AxiosHttpClientConfig {
  /**
   * Base URL for all requests.
   */
  baseURL?: string

  /**
   * Default headers for all requests.
   */
  defaultHeaders?: Record<string, string>

  /**
   * Default timeout in milliseconds.
   */
  timeout?: number

  /**
   * Whether to include credentials by default.
   */
  withCredentials?: boolean

  /**
   * Existing Axios instance to wrap (optional).
   */
  instance?: AxiosInstance

  /**
   * Additional Axios-specific config.
   */
  axiosConfig?: AxiosRequestConfig
}

FullRequestConfig

Full request configuration including method and URL.

interface FullRequestConfig extends RequestConfig {
  /**
   * HTTP method.
   */
  method: HttpMethod
  /**
   * Request URL (can be relative or absolute).
   */
  url: string
  /**
   * Request body data.
   */
  data?: unknown
}

HttpClient

HTTP client interface.

All HTTP providers must implement this interface.

interface HttpClient {
  /**
   * Base URL for all requests.
   */
  baseURL: string
  /**
   * Default headers for all requests.
   */
  defaultHeaders: Record<string, string>
  /**
   * Makes a generic HTTP request.
   */
  request<T = unknown>(config: FullRequestConfig): Promise<HttpResponse<T>>
  /**
   * Makes a GET request.
   */
  get<T = unknown>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>
  /**
   * Makes a POST request.
   */
  post<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>
  /**
   * Makes a PUT request.
   */
  put<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>
  /**
   * Makes a PATCH request.
   */
  patch<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>
  /**
   * Makes a DELETE request.
   */
  delete<T = unknown>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>
  /**
   * Adds a request interceptor.
   * Returns a function to remove the interceptor.
   */
  addRequestInterceptor(interceptor: RequestInterceptor): () => void
  /**
   * Adds a response interceptor.
   * Returns a function to remove the interceptor.
   */
  addResponseInterceptor(interceptor: ResponseInterceptor): () => void
  /**
   * Adds an error interceptor.
   * Returns a function to remove the interceptor.
   */
  addErrorInterceptor(interceptor: ErrorInterceptor): () => void
  /**
   * Sets the authorization token.
   */
  setAuthToken(token: string | null): void
  /**
   * Returns the current authorization token, or `null` if not set.
   */
  getAuthToken(): string | null
  /**
   * Registers a handler for authentication errors (401).
   *
   * @returns An unsubscribe function.
   */
  onAuthError(handler: () => void): () => void
}

HttpClientConfig

HTTP client configuration.

interface HttpClientConfig {
  /**
   * Base URL for all requests.
   */
  baseURL?: string
  /**
   * Default headers for all requests.
   */
  defaultHeaders?: Record<string, string>
  /**
   * Default timeout in milliseconds.
   */
  timeout?: number
  /**
   * Whether to include credentials by default.
   */
  withCredentials?: boolean
}

HttpResponse

Parsed HTTP response with status code, headers, and typed body data.

interface HttpResponse<T = unknown> {
  /**
   * Response data.
   */
  data: T
  /**
   * HTTP status code.
   */
  status: number
  /**
   * HTTP status text.
   */
  statusText: string
  /**
   * Response headers.
   */
  headers: Record<string, string>
  /**
   * Original request config.
   */
  config: FullRequestConfig
}

RequestConfig

HTTP request options (headers, query params, timeout, credentials, response type, abort signal).

interface RequestConfig {
  /**
   * Request headers.
   */
  headers?: Record<string, string>
  /**
   * Query parameters.
   */
  params?: Record<string, string | number | boolean | undefined>
  /**
   * Request timeout in milliseconds.
   */
  timeout?: number
  /**
   * Whether to include credentials (cookies).
   */
  withCredentials?: boolean
  /**
   * Response type.
   */
  responseType?: 'json' | 'text' | 'blob' | 'arraybuffer'
  /**
   * Abort signal for cancellation.
   */
  signal?: AbortSignal
  /**
   * Request body data.
   */
  data?: unknown
  /**
   * Custom request options (implementation-specific).
   */
  options?: Record<string, unknown>
}

Types

ErrorInterceptor

Intercepts HTTP errors to transform, retry, or rethrow them. Throwing from this interceptor propagates the error to the caller.

type ErrorInterceptor = (error: HttpError) => HttpError | Promise<HttpError> | never

HttpMethod

HTTP request method.

type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS'

RequestInterceptor

Intercepts outgoing requests to modify headers, URL, or body before the request is sent.

type RequestInterceptor = (
  config: FullRequestConfig,
) => FullRequestConfig | Promise<FullRequestConfig>

ResponseInterceptor

Intercepts incoming responses to transform data, check status, or perform side effects before the response reaches the caller.

type ResponseInterceptor<T = unknown> = (
  response: HttpResponse<T>,
) => HttpResponse<T> | Promise<HttpResponse<T>>

Classes

HttpError

HTTP error with response details.

Functions

createAxiosClient(config)

Creates an Axios-based HTTP client implementing the molecule HttpClient interface. Supports request/response/error interceptors, auth token management, and 401 error handlers.

function createAxiosClient(config?: AxiosHttpClientConfig): HttpClient

• config — Axios client configuration (base URL, headers, timeout, credentials, or an existing Axios instance).

Returns: An HttpClient backed by Axios with interceptor and auth token support.

Constants

provider

Default Axios-based HTTP client created with default options (no base URL, 30s timeout).

const provider: HttpClient

Core Interface

Implements @molecule/app-http interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setClient } from '@molecule/app-http'
import { provider } from '@molecule/app-http-axios'

export function setupHttpAxios(): void {
  setClient(provider)
}

Injection Notes

Requirements

Peer dependencies:

• @molecule/app-http ^1.0.1
• axios ^1.6.0

Runtime Dependencies

• @molecule/app-http

• axios

• Call setClient(...) at startup, BEFORE any get/post from @molecule/app-http runs. The core's getClient() lazily bonds its own fetch-based fallback on first use — requests issued before setClient() silently bypass the Axios client (no interceptors, no auth token).

• get()/post()/… resolve to HttpResponse<T> — read .data for the body (const { data: users } = await get('/users')).

• The exported provider constant is a pre-built default client (no baseURL, 30 s timeout); prefer createAxiosClient({...}) so baseURL/credentials are explicit.

• instance/axiosConfig accept raw Axios options — anything the app sets there couples it to Axios; keep app code on the @molecule/app-http interface so the bond stays swappable.