@pzeta/utils
HTTP

AxiosHttpClient

Client HTTP basato su Axios (peer dependency opzionale). Ideale quando servono interceptors, progress tracking o quando il progetto già usa Axios.

Quando usarlo

Implementazione alternativa a FetchHttpClient, basata su Axios. Da preferire quando:

  • il progetto usa già Axios e si vuole condividere l'istanza (interceptors, baseURL, ecc.);
  • servono funzionalità Axios-specifiche non disponibili in Fetch API (es. progress tracking di upload/download, cancellazione tramite CancelToken);
  • esistono interceptors di terze parti (telemetria, refresh token custom) già configurati.
Per la maggior parte dei progetti nuovi PZeta è preferibile FetchHttpClient: zero dipendenze, bundle più piccolo, nativo del browser.

Installazione

axios è una peer dependency opzionale. Va installato esplicitamente dove serve:

npm install axios

Costruttore

class AxiosHttpClient implements IHttpClient {
  constructor(axiosInstance?: AxiosInstance)
}
ParametroTipoDefaultDescrizione
axiosInstanceAxiosInstanceaxios.create()Istanza Axios preconfigurata. Se omesso, viene creata un'istanza default.

Esempio diretto

import axios from 'axios'
import { AxiosHttpClient } from '@pzeta/postgrest'

const axiosInstance = axios.create({
  baseURL: 'https://api.example.com',
  timeout: 10000,
})

const client = new AxiosHttpClient(axiosInstance)

const { data } = await client.get<User[]>('/users')

Esempio via factory

import { HttpClientFactory } from '@pzeta/postgrest'

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

createAxiosClient è asincrono perché importa Axios in modalità lazy (await import('axios')): se Axios non è installato il caricamento fallisce.

Esempio con interceptors esistenti

import axios from 'axios'
import { AxiosHttpClient } from '@pzeta/postgrest'

const axiosInstance = axios.create({ baseURL: 'https://api.example.com' })

axiosInstance.interceptors.request.use((config) => {
  config.headers['X-Correlation-Id'] = crypto.randomUUID()
  return config
})

const client = new AxiosHttpClient(axiosInstance)

API

MetodoSignatureDescrizione
request<T>(config: AxiosRequestConfig): Promise<AxiosResponse<T>>Richiesta generica. Applica Authorization e gestisce retry su 401.
get<T>(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>Richiesta GET.
post<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>Richiesta POST.
put<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>Sostituzione completa.
patch<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>Aggiornamento parziale.
delete<T>(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>Eliminazione.
setAuthHandler(handler: IAuthHandler): voidImposta l'handler di autenticazione. Espone getToken(), refreshToken(), handleAuthError().
setMaxRetries(maxRetries: number): voidNumero massimo di retry su 401. Default 1.
getAxiosInstance(): AxiosInstanceRestituisce l'istanza Axios sottostante (per aggiungere interceptors o leggere config).

Auth e retry

AxiosHttpClient usa il modello legacy IAuthHandler:

  1. Su ogni richiesta legge authHandler.getToken() e aggiunge Authorization: Bearer <token>.
  2. Su risposta 401, se retryCount < maxRetries, chiama authHandler.handleAuthError(error).
  3. Se l'handler approva, chiama authHandler.refreshToken() e ripete la richiesta con il nuovo token.

Per il modello moderno basato su IAuthStrategy usa StrategyAwareHttpClient o FetchHttpClient.

Accesso all'istanza Axios

const client = new AxiosHttpClient(axiosInstance)

client.getAxiosInstance().interceptors.response.use(
  (response) => response,
  (error) => {
    console.error('API error:', error)
    return Promise.reject(error)
  }
)

Integrazione con @pzeta/vue-attachment

Se nel progetto è già presente l'adapter Axios di @pzeta/vue-attachment (createAxiosAdapter), puoi riusare la stessa istanza per coerenza di interceptors e refresh token:

import { createAxiosAdapter } from '@pzeta/vue-attachment'
import { AxiosHttpClient } from '@pzeta/postgrest'

const adapter = createAxiosAdapter({ baseURL: '/api' })
const client = new AxiosHttpClient(adapter.axiosInstance)

Tipi correlati

HTTP

Client HTTP duale (Fetch API e Axios), factory di creazione, gestione CORS e wrapper strategy-aware per @pzeta/postgrest.

CorsAdapter

Adapter per configurazione CORS cross-origin. Fornisce CorsConfig, ICorsAdapter, CorsAdapter e CorsAdapterFactory con preset per sviluppo.