Promise.any()

La méthode Promise.any() prend comme argument un itérable contenant des promesses (Promise) et, dès qu'une des promesses de cet itérable est tenue ou rompue, renvoie une promesse résolue avec cette valeur.

Si aucune promesse de l'itérable n'est tenue (c'est-à-dire si toutes les promesses sont rejetées), la promesse renvoyée est rompue avec un objet dont la teneur est encore en cours de spécification : un tableau des raisons pour les rejets de chaque promesse ou un objet AggregateError (une sous-clase de  Error qui regroupe un ensemble d'erreur).

Cette méthode est la méthode opposée à Promise.all() (qui renvoie une promesse tenue uniquement si toutes les promesses de l'itérable passé en argument a été tenu).

Attention ! La méthode Promise.any() est encore expérimentale et n'est pas encore prise en charge par les navigateurs. Sa spécification est actuellement (novembre 2019) un brouillon à l'étape 3 selon la procédure du TC39.

Syntaxe

Promise.any(iterable);

Paramètres

iterable
Un objet itérable tel qu'un tableau (Array) contenant des promesses (Promise).

Valeur de retour

  • Une promesse (Promise) déjà résolue si l'itérable passé en argument est vide.
  • Une promesse (Promise) résolue en asynchrone si l'itérable passé en argument ne contient pas de promesses.
  • Une promesse (Promise) en attente dans tous les autres cas. La promesse renvoyée est résolue (qu'elle soit tenue ou rompue) de façon asynchrone lorsqu'au moins une des promesses de l'itérable est tenue ou si toutes les promesses ont été rompues.

Description

Cette méthode est utile afin de renvoyer la première promesse tenue d'un ensemble de promesse. Elle permet de court-circuiter dès qu'une promesse est tenue, sans attendre que les autres promesses soient résolues. Contrairement à Promise.all() qui renvoie un tableau avec les valeurs de résolution des promesses, on a ici une seule valeur de résolution (celle de la première promesse tenue).

Cette méthode s'avère utile lorsqu'on a un ensemble de promesses et qu'on souhaite uniquement connaître la valeur de résolution de la première, sans apporter d'importance au fait de savoir laquelle des promesses a été tenue.

À la différence de Promise.race() qui renvoie la valeur de la première promesse résolue (qu'elle ait été tenue ou rompue), Promise.any() renvoie une promesse avec la valeur de la première promesse tenue. Cette méthode ignore les promesses qui sont rompues jusqu'à obtenir une promesse tenue.

Une des promesses est tenue

Si une des promesses de l'itérable réussit/est tenue, la promesse renvoyée par Promise.any() est résolue de façon asynchrone avec la valeur de résolution de cette promesse (que les autres promesses de l'itérable aient échoué ou non).

  • Si c'est un itérable vide qui est passé, la méthode renvoie (de façon synchrone) une promesse déjà résolue.
  • Si une des promesses est tenue ou que les valeurs fournies dans l'itérable ne sont pas des promesses, la promesse renvoyée par Promise.any() est résolue de façon asynchrone.

Toutes les promesses sont rompues

Si toutes les promesses de l'itérable échouent/sont rompues, Promise.any() renvoie une promesse qui échoue de façon asynchrone avec une de ces deux raisons (en cours de décision pour la spécification) :

  • Un tableau contenant l'ensemble des raisons d'échec des différentes promesses de l'itérable ou
  • Un objet AggregateError qui étend Error et qui contient un lien/une propriété vers une liste d'exception.

Voir aussi