Installation

Prérequis

HTTP Guardian cible les projets TypeScript modernes qui disposent de fetch.

Sujet	Valeur attendue	Pourquoi
Node	>= 22	Runtime CI et développement aligné sur les packages actuels.
TypeScript	Résolution de modules moderne	Les déclarations publiques doivent être résolues par le consommateur.
Navigateur	fetch, Headers, AbortController	Utilisés par le terminal HTTP et les timeouts.
RxJS	Optionnel	Requis uniquement avec @cedvict/http-guardian-rx.

Installer le noyau

npm i @cedvict/http-guardian

Ajouter RxJS seulement si l'application en a besoin

npm i @cedvict/http-guardian-rx rxjs

L'adaptateur RxJS ne change pas le contrat de parsing. Il expose les mêmes résultats sous forme d'Observable, ce qui évite d'avoir deux modèles d'erreurs dans une application Angular.

Ajouter des plugins au cas par cas

npm i @cedvict/http-guardian-plugin-retry
npm i @cedvict/http-guardian-plugin-timeout
npm i @cedvict/http-guardian-plugin-logger
npm i @cedvict/http-guardian-plugin-sentry
npm i @cedvict/http-guardian-plugin-otel
npm i @cedvict/http-guardian-plugin-rate-limit

Chaque plugin doit correspondre à une politique explicite. Installer un package ne suffit pas : il faut aussi le passer dans plugins ou dans les guards selon son contrat.

Premier client

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

type User = { id: string; email: string };

export const api = createHttpClient({
  baseUrl: "https://api.example.com/v1",
  auth: bearerAuth(() => localStorage.getItem("token")),
  parser: createApiParserRestClassic(),
  cache: memoryCache({ maxEntries: 500 })
});

const result = await api.get<User>("/me", {
  cache: { ttlMs: 30_000, tags: ["me"] }
});

if (result.ok) {
  console.log(result.data.email);
} else {
  console.error(result.errors);
}

Ne pas masquer la configuration

Même une API publique doit déclarer auth: noAuth(). Une absence silencieuse d'auth rend les refresh guards, les diagnostics et les exceptions par requête plus ambigus.