JavaScript Promise API
Apprenez l'API Promise JavaScript : Promise.all, allSettled, race, any, resolve et reject. Comparez fast-fail et allSettled avec des exemples exécutables.
La classe Promise propose plusieurs méthodes statiques pour combiner et créer des promesses. Au lieu de chaîner manuellement plusieurs chaînes .then(), vous passez un tableau de promesses à un combinateur et obtenez en retour une seule promesse qui se règle dès que le groupe atteint un état défini.
Cette page couvre les quatre combinateurs — Promise.all, Promise.allSettled, Promise.race et Promise.any — ainsi que les deux assistants de création Promise.resolve et Promise.reject. Si vous débutez avec les promesses, commencez par JavaScript : les Promises.
Les exemples ci-dessous utilisent
.then()/.catch()pour rendre le flux de contrôle explicite. Dans du code réel, vous liriez généralement le résultat avecasync/await.
Choisir le bon combinateur
| Méthode | Se résout quand… | Rejette quand… | Usage typique |
|---|---|---|---|
Promise.all | toutes les promesses sont résolues | n'importe quelle promesse rejette (fast-fail) | Vous avez besoin de chaque résultat et un échec doit annuler l'ensemble |
Promise.allSettled | toutes les promesses se règlent (ne rejette jamais) | — | Vous voulez chaque résultat, qu'il soit succès ou échec |
Promise.race | la première promesse se règle (résolution ou rejet) | la première promesse rejette en premier | Délais d'expiration, « le premier qui répond gagne » |
Promise.any | la première promesse se résout | toutes les promesses rejettent | Premier résultat réussi, ignorer les échecs individuels |
La distinction clé : Promise.all échoue rapidement — elle rejette dès qu'une entrée rejette, même si d'autres promesses sont encore en attente. Si vous souhaitez plutôt attendre toutes les promesses quoi qu'il arrive, utilisez Promise.allSettled.
Utiliser Promise.all pour des tâches concurrentes
Promise.all est une méthode essentielle pour gérer plusieurs promesses de manière concurrente. Lorsque vous devez effectuer plusieurs opérations asynchrones et ne poursuivre qu'une fois toutes réussies, Promise.all est l'outil qu'il vous faut.
Comment implémenter Promise.all
Voici un exemple illustrant l'utilisation de Promise.all pour gérer plusieurs requêtes API simultanément :
Dans cet exemple, Promise.all prend un tableau de promesses et se résout en un tableau de leurs résultats dans le même ordre que les entrées (et non dans l'ordre d'achèvement). Si une promesse rejette, Promise.all rejette immédiatement avec la raison de ce premier rejet — les résultats des autres sont ignorés. Voir Gestion des erreurs avec les promesses pour savoir comment récupérer de tels échecs.
Maîtriser Promise.allSettled
Contrairement à Promise.all, la méthode Promise.allSettled retourne une promesse qui se résout après que toutes les promesses données se sont soit résolues, soit rejetées, avec un tableau d'objets décrivant chacun le résultat de chaque promesse.
Exemple de Promise.allSettled
Voici comment utiliser Promise.allSettled :
Remarque : Promise.allSettled ne rejette jamais. Elle se résout toujours avec un tableau d'objets résultats, chacun contenant une propriété status ('fulfilled' ou 'rejected') et soit une propriété value, soit une propriété reason.
Cette méthode est particulièrement utile lorsque vous devez vous assurer que toutes les promesses arrivent à terme, qu'elles soient résolues ou rejetées.
Implémenter Promise.race
Promise.race est un autre outil puissant qui permet de gérer plusieurs promesses en se résolvant ou en rejetant dès que l'une des promesses de l'itérable se résout ou rejette.
Comment utiliser Promise.race
Voici une application pratique de Promise.race :
Cette méthode est idéale pour les scénarios où vous avez besoin du résultat le plus rapide parmi plusieurs opérations asynchrones — par exemple, faire la course entre une requête et une promesse de délai d'expiration. Notez que race se règle sur la première promesse à se régler, qu'elle se résolve ou rejette.
Obtenir le premier succès avec Promise.any
Promise.any est le pendant optimiste de Promise.race. Elle ignore les rejets et se résout avec la valeur de la première promesse à se réaliser. Elle ne rejette que si toutes les promesses rejettent, auquel cas elle lance une AggregateError dont la propriété .errors contient toutes les raisons individuelles.
Comment utiliser Promise.any
Utilisez Promise.any lorsque vous avez plusieurs sources pour les mêmes données (par exemple des serveurs miroir) et que vous ne vous intéressez qu'au premier qui réussit.
Créer des promesses avec resolve et reject
Promise.resolve(value) et Promise.reject(reason) sont des raccourcis pour construire une promesse déjà réglée sans le code répétitif de new Promise(executor).
Promise.resolve(value)retourne une promesse déjà résolue avecvalue. Sivalueest lui-même un thenable, il est « adopté » et suivi.Promise.reject(reason)retourne une promesse déjà rejetée avecreason.
Ces assistants sont couramment utilisés pour retourner une valeur mise en cache depuis une fonction autrement asynchrone, ou pour démarrer une chaîne .then().
Créer un Polyfill pour Promise.allSettled
Tous les environnements ne prennent pas en charge Promise.allSettled nativement. Par conséquent, implémenter un polyfill peut garantir la compatibilité dans différents environnements JavaScript.
Polyfill pour Promise.allSettled
Voici comment créer un polyfill simple :
Ce polyfill fournit une fonctionnalité de base où chaque promesse est gérée individuellement et résolue selon son résultat respectif, garantissant que le comportement d'allSettled est reproduit efficacement.
En intégrant ces techniques avancées de promesses et en comprenant les mécanismes sous-jacents des polyfills, vous pouvez élever votre code JavaScript à de nouveaux sommets. Ces méthodes améliorent non seulement la fiabilité du code, mais offrent également un contrôle affiné sur les opérations asynchrones, ouvrant la voie à des applications web plus robustes.