AbortController : annuler un fetch devenu inutile

Ce que vous saurez faire

Comprendre pourquoi une Promise n’est pas elle-même « annulable », transmettre un même signal à plusieurs opérations, utiliser l’annulation dans une fonction maison et nettoyer correctement un effet React.

1. AbortController est un protocole de coopération

Une Promise représente un résultat futur ; elle ne possède pas de bouton d’arrêt universel. Le DOM Standard sépare donc les rôles :

AbortController
      │ abort()
      ▼
 AbortSignal ─────────► fetch / stream / fonction compatible

L’opération décide d’écouter le signal. Lorsqu’elle le fait, elle peut interrompre son travail et rejeter sa Promise avec la raison d’annulation du signal.

Cette séparation est utile parce qu’un même signal peut coordonner plusieurs opérations :

const controller = new AbortController();
const { signal } = controller;

const profil = fetch('/api/profile', { signal });
const commandes = fetch('/api/orders', { signal });

// Quitter l'écran peut arrêter les deux demandes.
controller.abort();

Référence : DOM Standard — Aborting ongoing activities.

2. Un signal est à usage unique

Après abort(), signal.aborted reste vrai. Toute nouvelle opération utilisant ce même signal voit immédiatement qu’il est déjà annulé.

const controller = new AbortController();
controller.abort();

console.log(controller.signal.aborted); // true

// Cette requête part avec un signal déjà annulé.
fetch('/api/data', { signal: controller.signal })
  .catch((error) => console.log(error.name)); // AbortError

Le bon modèle pour une recherche successive est donc un contrôleur par tentative, pas un contrôleur global que l’on « réarme ».

Référence : MDN — AbortSignal.

3. Propager l’annulation dans votre propre fonction

Vos fonctions asynchrones peuvent accepter un AbortSignal exactement comme fetch().

async function chargerProfil(id, { signal } = {}) {
  signal?.throwIfAborted();

  const response = await fetch(`/api/users/${id}`, { signal });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);

  return response.json();
}

throwIfAborted() permet d’arrêter immédiatement une fonction si l’appelant a déjà annulé l’opération. Vous conservez ainsi une seule chaîne d’annulation du composant jusqu’au réseau.

Pour un traitement maison qui ne s’appuie pas sur une API déjà compatible, écoutez l’événement abort, libérez vos ressources et rejetez avec signal.reason. Retirez ensuite l’écouteur, ou utilisez un écouteur à usage unique, pour ne pas conserver inutilement des références.

4. Le nettoyage naturel dans React

Une utilisation fréquente apparaît lorsqu’un composant charge des données selon une propriété. Si cette propriété change ou si le composant disparaît, l’ancienne requête ne sert plus.

useEffect(() => {
  const controller = new AbortController();

  async function charger() {
    try {
      const response = await fetch(`/api/users/${userId}`, {
        signal: controller.signal,
      });
      if (!response.ok) throw new Error(`HTTP ${response.status}`);
      const data = await response.json();
      setUser(data);
    } catch (error) {
      if (error instanceof DOMException && error.name === 'AbortError') return;
      setError(error);
    }
  }

  charger();
  return () => controller.abort();
}, [userId]);

Le nettoyage de l’effet annule l’ancienne requête avant que l’effet suivant ne démarre, ou lorsque le composant est retiré. Cela évite de conserver une demande réseau dont le résultat n’a plus de destinataire pertinent.

5. Timeout et raison d’annulation

AbortSignal.timeout(5000) produit un signal qui s’annule automatiquement après cinq secondes. Le DOM Standard définit alors une raison de type TimeoutError.

try {
  await fetch('/api/report', {
    signal: AbortSignal.timeout(5000),
  });
} catch (error) {
  if (error instanceof DOMException && error.name === 'TimeoutError') {
    console.warn('Le serveur a dépassé le délai prévu.');
  } else {
    throw error;
  }
}

Une annulation volontaire et un timeout peuvent donc conduire à des messages différents. Ne transformez pas toutes les erreurs en « requête annulée » : une vraie panne réseau ou une erreur de parsing mérite toujours d’être visible.

Pièges importants

• Annuler n’est pas rollback. Le serveur peut avoir reçu et traité la requête avant l’annulation du client.
• Ne réutilisez pas un signal annulé. Il reste définitivement dans cet état.
• N’avalez pas toutes les erreurs. Ignorez uniquement l’annulation que votre interface considère comme normale ; propagez les autres.
• Le corps de réponse aussi peut être interrompu. Une annulation peut survenir après les en-têtes et pendant la lecture de response.json() ou d’un flux.
• L’annulation doit se propager. Si votre fonction appelle une autre API asynchrone sans lui transmettre le signal, seule une partie du travail s’arrête.

Mémo final

Pensez AbortSignal comme un petit canal de contrôle parallèle à vos données : l’appelant dit « je n’en ai plus besoin », et chaque couche compatible transmet cette décision jusqu’au travail réellement en cours. Cette mécanique ne remplace aucune garantie serveur ; elle rend surtout l’interface plus propre, plus économe et moins vulnérable aux résultats devenus obsolètes.