HTTP

FetchHttpClient

Client HTTP zero-dipendenze basato su Fetch API nativa. Compatibile con interfaccia Axios tramite FetchAdapter. Supporta auth strategy, retry su 401 e timeout.

Quando usarlo

Implementazione default consigliata. Zero dipendenze, bundle size minimo, nativo del browser e compatibile con Service Workers. Sostituisce Axios mantenendo la stessa shape di request/response tramite FetchAdapter.

Se il progetto richiede interceptors avanzati o progress tracking di upload/download, valuta AxiosHttpClient.

Costruttore

class FetchHttpClient implements IHttpClient {
  constructor(baseConfig?: AxiosRequestConfig)
}

Parametro	Tipo	Default	Descrizione
`baseConfig`	`AxiosRequestConfig`	`{}`	Configurazione applicata a tutte le richieste: `baseURL`, `headers`, `timeout`, `withCredentials`, ecc.

Le richieste mergiano baseConfig con la config per-call tramite spread, quindi i campi della singola richiesta prevalgono.

Esempio diretto

import { FetchHttpClient } from '@pzeta/postgrest'

const client = new FetchHttpClient({
  baseURL: 'https://api.example.com',
  timeout: 10000,
  headers: { Accept: 'application/json' },
})

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

Esempio via factory

import { HttpClientFactory } from '@pzeta/postgrest'

const client = HttpClientFactory.createFetchClient(
  { baseURL: 'https://api.example.com' },
  { withDefaultAuth: true } // applica una IAuthStrategy JWT
)

API

Metodo	Signature	Descrizione
`request`	`<T>(config: AxiosRequestConfig): Promise<AxiosResponse<T>>`	Richiesta generica. Applica autenticazione 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. Il body viene serializzato in JSON.
`put`	`<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>`	Sostituzione completa della risorsa.
`patch`	`<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>`	Aggiornamento parziale.
`delete`	`<T>(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>`	Eliminazione risorsa.
`setAuthStrategy`	`(strategy: IAuthStrategy): void`	Imposta la strategia di autenticazione moderna (approccio consigliato).
`setAuthHandler`	`(handler: IAuthHandler): void`	Imposta l'handler legacy. `@deprecated` — usa `setAuthStrategy`.
`setMaxRetries`	`(maxRetries: number): void`	Numero massimo di retry automatici su errori 401. Default `1`.
`getAxiosInstance`	`(): AxiosInstance`	Lancia errore: `FetchHttpClient` non usa Axios. Usa `AxiosHttpClient` se serve l'istanza.

Esempio con auth strategy

import { FetchHttpClient } from '@pzeta/postgrest'
import { AuthStrategyFactory } from '@pzeta/postgrest'

const client = new FetchHttpClient({ baseURL: 'https://api.example.com' })
client.setAuthStrategy(AuthStrategyFactory.createJwtStrategy())

// Le richieste includeranno automaticamente Authorization: Bearer <token>
const { data } = await client.get<User[]>('/users')

Vedi Auth Strategies per i tipi di strategia disponibili (JWT, Cookie, None).

Pattern interno

FetchHttpClient implementa internamente:

Conversione Axios → Fetch: ogni richiesta passa per FetchAdapter.toFetchRequest che produce [url, RequestInit].
Timeout: gestito via AbortController quando config.timeout è impostato. Allo scadere lancia un AxiosError con code: 'ECONNABORTED'.
Retry su 401: se la risposta è 401 e retryCount < maxRetries, chiama handleAuthError. Se la strategia o l'handler segnalano successo, riapplica l'autenticazione e ripete la richiesta.
Errori HTTP: per response.ok === false, il body viene convertito in AxiosError tramite FetchAdapter.toAxiosError (mantiene isAxiosError: true, config, response).

`FetchAdapter`

Adapter low-level usato internamente da FetchHttpClient. Espone metodi statici per convertire tra il formato Axios e la Fetch API.

class FetchAdapter {
  static toFetchRequest(config: AxiosRequestConfig): [string, RequestInit]
  static toAxiosResponse<T>(response: Response, config: AxiosRequestConfig): Promise<AxiosResponse<T>>
  static toAxiosError(response: Response, config: AxiosRequestConfig): Promise<AxiosError>
}

Metodo	Descrizione
`toFetchRequest`	Converte `AxiosRequestConfig` in tupla `[url, RequestInit]`. Compone `baseURL + url`, serializza `params` in query string, serializza `data` in JSON (default `Content-Type: application/json`), mappa `withCredentials` su `credentials: 'include'`.
`toAxiosResponse`	Converte `Response` Fetch in `AxiosResponse<T>`. Parsing automatico del body in base al `Content-Type`: `application/json` → JSON, `text/*` → string, altri → `Blob`.
`toAxiosError`	Costruisce un `AxiosError` da una `Response` di errore (4xx/5xx) con `isAxiosError: true`, `config`, `response` e `toJSON()`.

Normalmente non serve chiamare FetchAdapter direttamente — viene usato in modo trasparente da FetchHttpClient. Esposto per casi avanzati di integrazione personalizzata.

CORS

FetchHttpClient rispetta config.withCredentials (mappato su credentials: 'include' | 'same-origin'). Per setup multi-origine con headers e metodi espliciti vedi CorsAdapter, che è invece pensato per Axios.

Tipi correlati

IHttpClient — interfaccia implementata
IAuthStrategy — strategia di autenticazione moderna
HttpClientFactory — creazione preconfigurata
AxiosHttpClient — alternativa basata su Axios

CorsAdapter

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

HttpClientFactory

Factory centrale per creare client HTTP preconfigurati. Espone createFetchClient, createAxiosClient, createJwtClient, createCookieClient, createPublicClient, getDefaultHttpClient e createHttpClient.