CKTIS / JavaScript
Promise.any — le premier résultat obtenu
Promise.any accepte un objet itérable et renvoie une promesse tenue avec la valeur du premier succès que la méthode observe. Les rejets des entrées ne mettent pas fin à l’attente, sauf si toutes les entrées sont rejetées ; dans ce cas, le résultat est rejeté avec AggregateError.
Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntaxe
Promise.any(iterable)Promise.any(iterable) est une méthode statique de Promise, introduite avec ECMAScript 2021 (ES12). Elle accepte un objet itérable synchrone, par exemple un tableau de promesses, de valeurs simples ou d’objets dotés d’une méthode then (thenables). Les valeurs sont converties par Promise.resolve ; ne passez pas de fonctions en vous attendant à ce que la méthode les exécute.
La promesse renvoyée adopte la valeur du premier succès que Promise.any observe, qui n’est pas nécessairement celui qui s’est produit le plus tôt. Si vous passez deux promesses ordinaires déjà tenues et que la méthode native Promise.resolve les renvoie toutes deux telles quelles, la première dans l’ordre d’itération l’emporte, même si elle a été tenue après la seconde. La méthode native Promise.resolve renvoie une promesse telle quelle si la valeur de sa propriété constructor est identique à la valeur de this lors de l’appel. Elle ne vérifie pas de quel environnement d’exécution (realm) provient la promesse. Si la première promesse provient d’un autre realm et possède son constructeur par défaut, la méthode locale Promise.resolve l’encapsule dans une nouvelle promesse. Cela retarde la réaction à son succès : la seconde peut donc l’emporter si elle est renvoyée telle quelle. En revanche, si la propriété constructor de la première promesse a pour valeur le Promise local, la méthode locale Promise.resolve la renvoie telle quelle malgré sa provenance. Avec Promise.race, le rejet d’une entrée peut déterminer le résultat si la méthode l’observe avant tout autre succès ou rejet. Avec Promise.any, les rejets des entrées n’entraînent le rejet du résultat avec AggregateError qu’une fois toutes les entrées rejetées, y compris lorsqu’une seule entrée est fournie et qu’elle est rejetée. La méthode n’annule pas les autres opérations après un succès.
Si toutes les entrées sont rejetées, le résultat est rejeté avec AggregateError. Son tableau errors contient les raisons dans l’ordre des entrées, et non dans l’ordre des rejets. Promise.any([]) renvoie une promesse déjà rejetée avec un tableau errors vide ; les gestionnaires s’exécutent tout de même de manière asynchrone. Une erreur lors de la lecture de l’itérateur peut également entraîner le rejet du résultat, sans AggregateError.
Utilisez cette méthode lorsqu’un seul résultat obtenu suffit. Gérez l’échec total avec try/catch autour de await ou avec .catch(). La spécification du langage ne garantit pas la prise en charge dans un navigateur donné : vérifiez l’environnement cible, par exemple avec typeof Promise.any === "function". La présence de Node 24 dans un dépôt ne prouve pas la prise en charge par les navigateurs.
Exemples
async function main() {
const value = await Promise.any([
Promise.reject("offline"),
Promise.resolve("ready")
]);
console.log(value);
try {
await Promise.any([
Promise.reject("first"),
Promise.reject("second")
]);
} catch (error) {
console.log(error instanceof AggregateError);
console.log(JSON.stringify(error.errors));
}
}
main().catch(console.error);Résultat
ready true ["first","second"]
Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.