Promise.race()

Baseline Large disponibilité

Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis juillet 2015.

La méthode Promise.race() renvoie une promesse qui est résolue ou rejetée dès qu'une des promesses de l'itérable passé en argument est résolue ou rejetée. La valeur (dans le cas de la résolution) ou la raison (dans le cas d'un échec) utilisée est celle de la promesse de l'itérable qui est resolue/qui échoue.

Dans cet article

Exemple interactif

const promise1 = new Promise((resolve, reject) => {
  setTimeout(resolve, 500, "one");
});

const promise2 = new Promise((resolve, reject) => {
  setTimeout(resolve, 100, "two");
});

Promise.race([promise1, promise2]).then((value) => {
  console.log(value);
  // Both resolve, but promise2 is faster
});
// Expected output: "two"

Syntaxe

Promise.race(itérable);

Paramètres

itérable

Un objet itérable, par exemple un Array. Voir la page itérable.

Valeur de retour

Une promesse (Promise) à résoudre qui est résolue de façon asynchrone dès que l'une des promesses de l'itérable est tenue ou rompue.

Description

La fonction race renvoie une Promise qui est résolue/rejetée de la même façon que la première promesse de l'itérable à être résolue/rejetée.

Si l'itérable passé en argument est vide, la promesse sera continuellement en attente.

Si l'itérable contient une ou plusieurs valeurs qui ne sont pas des promesses ou une promesse déjà résolue, Promise.race fournira une promesse résolue avec la première de ces valeurs trouvées dans l'itérable.

Exemples

Caractère asynchrone de Promise.race()

L'exemple qui suit illuste le caractère asynchrone de Promise.race:

js
// On passe un tableau de promesses déjà résolues
// en argument afin de déclencher Promise.race
// dès que possible
var resolvedPromisesArray = [Promise.resolve(33), Promise.resolve(44)];

var p = Promise.race(resolvedPromisesArray);
// On affiche immédiatement la valeur p dans la console
console.log(p);

// Avec setTimeout on peut exécuter du code
// une fois que la pile est vide
setTimeout(function () {
  console.log("La pile est désormais vide");
  console.log(p);
});

// affichera, dans cet ordre :
// Promise { <state>: "pending" }
// La pile est désormais vide
// Promise { <state>: "fulfilled", <value>: 33 }

Un itérable vide renverra une promesse qui restera en attente :

js
var foreverPendingPromise = Promise.race([]);
console.log(foreverPendingPromise);
setTimeout(function () {
  console.log("La pile est désormais vide");
  console.log(foreverPendingPromise);
});

// affichera, dans cet ordre :
// Promise { <state>: "pending" }
// La pile est désormais vide
// Promise { <state>: "pending" }

Si l'itérable contient une ou plusieurs valeurs qui ne sont pas des promesses ou des promesses déjà résolues, Promise.race considèrera la première valeur ainsi trouvée dans l'itérable :

js
var foreverPendingPromise = Promise.race([]);
var alreadyResolvedProm = Promise.resolve(666);

var arr = [foreverPendingPromise, alreadyResolvedProm, "non-Promise value"];
var arr2 = [foreverPendingPromise, "non-Promise value", Promise.resolve(666)];
var p = Promise.race(arr);
var p2 = Promise.race(arr2);

console.log(p);
console.log(p2);
setTimeout(function () {
  console.log("the stack is now empty");
  console.log(p);
  console.log(p2);
});

// affichera dans l'ordre :
// Promise { <state>: "pending" }
// Promise { <state>: "pending" }
// the stack is now empty
// Promise { <state>: "fulfilled", <value>: 666 }
// Promise { <state>: "fulfilled", <value>: "non-Promise value" }

Utilisation de Promise.race – exemples avec setTimeout

js
var p1 = new Promise(function (resolve, reject) {
  setTimeout(resolve, 500, "un");
});
var p2 = new Promise(function (resolve, reject) {
  setTimeout(resolve, 100, "deux");
});

Promise.race([p1, p2]).then(function (value) {
  console.log(value); // "deux"
  // Les deux promesses sont résolues mais p2 est plus rapide
});

var p3 = new Promise(function (resolve, reject) {
  setTimeout(resolve, 100, "trois");
});
var p4 = new Promise(function (resolve, reject) {
  setTimeout(reject, 500, "quatre");
});

Promise.race([p3, p4]).then(
  function (value) {
    console.log(value); // "trois"
    // p3 est plus rapide et entraîne la résolution de la promesse de compétition
  },
  function (reason) {
    // N'est pas appelée
  },
);

var p5 = new Promise(function (resolve, reject) {
  setTimeout(resolve, 500, "cinq");
});
var p6 = new Promise(function (resolve, reject) {
  setTimeout(reject, 100, "six");
});

Promise.race([p5, p6]).then(
  function (value) {
    // N'est pas appelée
  },
  function (reason) {
    console.log(reason); // "six"
    // p6 est plus rapide et rejète la promesse de compétition
  },
);

Note : Voir la documentation sur setTimeout.

Aider à améliorer MDN

Cette page vous a-t-elle été utile ?

Oui Non

Apprendre à contribuer

Cette page a été modifiée le 17 févr. 2025 par les contributeur·ice·s du MDN.

Voir cette page sur GitHub • Signaler un problème avec ce contenu

Objets natifs standards
Promise
Constructeur
1. Constructeur Promise()
Méthodes statiques
Propriétés statiques
1. [Symbol.species]
Méthodes d'instance
Héritage
Object/Function
Méthodes statiques
Propriétés statiques
Méthodes d'instance
Propriétés d'instance
1. Object.prototype.__proto__
2. Object.prototype.constructor