HttpClientOptions

HttpClientOptions se décide une fois par API cible. Les champs essentiels ne doivent pas être déduits implicitement par l'application.

Options essentielles

Option	Obligatoire	Défaut	Effet	À utiliser quand	À éviter si
baseUrl	Oui	Aucun	Construit toutes les URL relatives.	Toujours, avec une racine stable comme https://api.example.com/v1.	Ne pas mettre /users/42 ou mélanger plusieurs backends.
auth	Oui	Aucun	Produit la politique d'auth avant les guards applicatifs.	bearerAuth, cookieAuth, apiKeyAuth, basicAuth ou noAuth.	Ne pas simuler une absence d'auth avec un token vide.
parser	Oui	Aucun	Transforme le corps brut en ClientResult<T>.	Choisir un preset REST, Laravel, Nest, GraphQL ou structured.	Ne pas analyser la réponse dans les composants UI.
fetch	Non	globalThis.fetch	Implémentation transport utilisée par le client.	Tests, runtimes spécifiques, mocks ou instrumentation bas niveau.	Ne pas passer une référence window.fetch détachée sans bind dans les vieux environnements.

Options de comportement

Option	Défaut	Explication précise
cache	Désactivé	Store de cache lu uniquement sur GET quand la requête fournit RequestOptions.cache. memoryCache supporte TTL, tags et taille max.
notifier	consoleNotifier	Reçoit les événements réseau, HTTP et parsing si defaults.shouldNotify le permet.
redirects	{ mode: "follow", maxHops: 5 }	Contrôle les redirections applicatives. Les headers auth doivent être retirés sur redirection cross-origin.
plugins	[]	Plugins appliqués à la création du client et dédupliqués par nom.
guards	[]	Pipeline de middleware exécuté dans l'ordre déclaré après le guard d'auth interne.

Defaults

Option	Défaut	Usage recommandé
defaults.headers	{}	En-têtes constants : Accept-Language, X-App-Version, tenant id. Ne pas y mettre Authorization.
defaults.timeoutMs	Aucun timeout global	Poser une limite lisible pour une API interactive, par exemple 10_000.
defaults.shouldNotify	(result) => !result.ok	Filtrer les 400 de validation si elles doivent rester dans les formulaires.

Exemple strict

import {
  bearerAuth,
  createApiParserStructured,
  createHttpClient,
  memoryCache
} from "@cedvict/http-guardian";

export const api = createHttpClient({
  baseUrl: "https://api.example.com/v1",
  auth: bearerAuth(() => authStore.accessToken(), {
    allowedOrigins: ["https://api.example.com"]
  }),
  parser: createApiParserStructured(),
  cache: memoryCache({ maxEntries: 500 }),
  defaults: {
    headers: { "X-App-Version": "web-1.0.0" },
    timeoutMs: 10_000,
    shouldNotify: ({ ok, status }) => !ok && (status === 0 || status >= 500)
  }
});