Les requêtes réseau, les lectures de fichiers et les minuteries se terminent toutes plus tard, mais JavaScript ne peut pas simplement s’arrêter et attendre, sinon la page se bloquerait. Les promesses JavaScript vous donnent un moyen simple de dire “quand cela se termine, faites cela, et si cela échoue, faites ceci à la place”.

Même si vous écrivez principalement async et await, vous utilisez des promesses en dessous, donc les comprendre rend le débogage beaucoup plus facile. Nous avons exécuté ces exemples sur Node.js 24, et le résultat affiché provient de cette exécution. Ils se comportent de la même manière dans les navigateurs modernes.

Qu’est-ce qu’une promesse ?

Une promesse est un espace réservé pour une valeur future. Pensez au buzzer qu’un restaurant vous remet lorsque vous commandez. Vous n’avez pas encore votre nourriture, mais vous tenez quelque chose qui vous dira quand elle sera prête ou qu’il y aura un problème, et en attendant vous êtes libre de faire autre chose.

Dans le code, une fonction asynchrone renvoie immédiatement une promesse et vous joignez ce qui devrait se passer ensuite :

fetch("/api/user")
  .then((response) => response.json())
  .then((user) => console.log(user.name))
  .catch((error) => console.log("Failed:", error.message));

Les trois états promis

Une promesse qui est tenue ou rejetée est appelée réglée. Une promesse ne peut être conclue qu’une seule fois. Après cela, son état et sa valeur sont corrigés, et les appels ultérieurs à resolve ou reject sont ignorés.

Créer une promesse

Vous consommez généralement les promesses d’API comme fetch, mais en créer une montre comment elles fonctionnent. Le constructeur reçoit deux fonctions, resolve et reject :

function fetchUser(id) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (id > 0) {
        resolve({ id, name: "Asha" });
      } else {
        reject(new Error("Invalid id"));
      }
    }, 100);
  });
}

console.log(fetchUser(1));

// Promise { <pending> }

L’enregistrement immédiat de la promesse montre qu’elle est toujours en attente, car le minuteur ne s’est pas déclenché. La valeur ne peut être atteinte que via un gestionnaire ou await. Rejetez toujours avec un objet Error plutôt qu’une chaîne, car un Error comporte une trace de pile qui facilite le débogage.

puis, attrape et enfin

Ces trois méthodes attachent des gestionnaires à une promesse :

fetchUser(1).then((user) => console.log(user.name));
// Asha

fetchUser(-1)
  .then((user) => console.log("never runs", user))
  .catch((error) => console.log("caught:", error.message))
  .finally(() => console.log("finally"));

// caught: Invalid id
// finally

then s’exécute en cas de succès, catch s’exécute en cas d’échec et finally s’exécute dans les deux sens. Cela fait de finally le bon endroit pour le nettoyage, comme cacher une roulette de chargement. Il ne reçoit aucun argument, car il ne devrait pas se soucier du résultat.

Enchaîner les promesses

L’idée clé est que then renvoie toujours une nouvelle promesse. Tout ce que renvoie votre gestionnaire devient la valeur de cette nouvelle promesse :

Promise.resolve(2)
  .then((n) => n * 10)
  .then((n) => n + 1)
  .then((n) => console.log("chain:", n));

// chain: 21

Si un gestionnaire renvoie une autre promesse, la chaîne attend qu’elle se règle avant de continuer. C’est ce qui transforme les rappels imbriqués en une séquence plate d’étapes :

getUser(id)
  .then((user) => getOrders(user.id))
  .then((orders) => getInvoice(orders[0].id))
  .then((invoice) => console.log(invoice.total))
  .catch(handleError);

Comment les erreurs se propagent dans une chaîne

Une promesse rejetée saute tous les then jusqu’à ce qu’elle atteigne un catch. Lancer à l’intérieur d’un gestionnaire compte également comme un rejet. Et un catch qui revient remet normalement la chaîne sur les rails :

Promise.resolve("start")
  .then(() => {
    throw new Error("step 2 failed");
  })
  .then(() => console.log("skipped"))
  .catch((error) => {
    console.log("caught:", error.message);
    return "recovered";
  })
  .then((value) => console.log("continues:", value));

// caught: step 2 failed
// continues: recovered

Considérez cela comme la version asynchrone de try et catch. Un catch à la fin couvre généralement toute la chaîne. Si vous souhaitez uniquement enregistrer une erreur et que vous échouez toujours, relancez-la depuis l’intérieur du catch.

Promise.all, allSettled, race et tout

Ces méthodes statiques coordonnent plusieurs promesses à la fois. Tous prennent un tableau et renvoient une promesse.

Pour les tester, nous avons utilisé deux petits assistants, un qui réussit après un certain temps et un qui échoue après un certain temps :

const wait = (ms, value) =>
  new Promise((resolve) => setTimeout(() => resolve(value), ms));
const fail = (ms, message) =>
  new Promise((_, reject) => setTimeout(() => reject(new Error(message)), ms));

Promise.all

await Promise.all([wait(300, "a"), wait(100, "b"), wait(200, "c")]);

// [ 'a', 'b', 'c' ]   took about 300 ms

Deux détails à noter. Les résultats conservent l’ordre de saisie, même si b a terminé en premier. Et le temps total était d’environ 300 ms, le temps de la tâche la plus lente et non la somme de 600 ms, car les trois s’exécutaient déjà en même temps. Si l’un d’eux refuse, l’ensemble rejette aussitôt :

await Promise.all([wait(100, "a"), fail(50, "b failed")]);

// rejected: b failed

Promise.allSettled

Celui-ci attend tout et rapporte chaque résultat, afin qu’un échec ne perde pas le reste. Cela convient à un tableau de bord où chaque widget se charge indépendamment :

const results = await Promise.allSettled([wait(50, "a"), fail(50, "b failed")]);
results.map((r) => r.status);

// [ 'fulfilled', 'rejected' ]

Promise.race et Promise.any

await Promise.race([wait(300, "slow"), wait(100, "fast")]);   // fast
await Promise.any([fail(50, "x"), wait(100, "ok")]);          // ok

La différence est que race prend le premier à s’installer, même s’il échoue, tandis que any ignore les échecs tant que quelque chose réussit. Une utilisation classique de race consiste à ajouter un délai d’attente à une requête lente, bien que la tâche la plus lente continue de s’exécuter en arrière-plan à moins que vous ne l’annuliez.

Promesses et asynchrone/attente

async et await sont une manière plus lisible de travailler avec les mêmes promesses. Une fonction async renvoie toujours une promesse, et await met cette fonction en pause jusqu’à ce qu’une promesse soit satisfaite :

async function showInvoice(id) {
  try {
    const user = await getUser(id);
    const orders = await getOrders(user.id);
    console.log(orders.length);
  } catch (error) {
    console.log("Failed:", error.message);
  }
}

Les rejets deviennent des erreurs renvoyées, donc les travaux ordinaires try et catch. Vous avez toujours besoin de Promise.all pour le travail parallèle, car attendre un appel après l’autre les exécute dans l’ordre. Notre Guide JavaScript async/await approfondit ce sujet.

Promesses et boucle d’événements

Les gestionnaires de promesses ne sont jamais appelés immédiatement, même lorsque la promesse est déjà conclue. Ils s’exécutent après la fin du code actuel et avant tout minuteur. Voici la preuve :

setTimeout(() => console.log("timeout"), 0);
Promise.resolve().then(() => console.log("microtask"));
console.log("sync");

// sync
// microtask
// timeout

Le code synchrone s’exécute en premier. Vient ensuite la file d’attente de microtâches, qui contient les gestionnaires de promesses. Ce n’est qu’alors que la boucle d’événements reprend la tâche suivante, telle qu’un minuteur. Il s’agit d’une question d’entretien populaire qui explique pourquoi un setTimeout de zéro n’est pas vraiment immédiat.

Promesses vs rappels

Erreurs courantes

• Oublier de rentrer à l’intérieur de then. Sans un return, l’étape suivante reçoit undefined et n’attend pas votre promesse intérieure.
• Non catch du tout. Cela provoque un rejet non géré, et dans Node.js, cela arrête le processus par défaut.
• Imbrication au lieu de chaînage. Mettre then à l’intérieur de then recrée l’enfer des rappels. Renvoyez la promesse et continuez la chaîne.
• Envelopper une promesse dans new Promise. Si une fonction renvoie déjà une promesse, utilisez-la simplement.
• Utilisation de forEach avec des rappels asynchrones. Il n’attend pas. Utilisez for...of ou Promise.all avec map, comme indiqué dans notre guide des méthodes de tableau JavaScript.
• Penser qu’une promesse peut être annulée. Elle ne peut pas être annulée d’elle-même. Pour les requêtes, utilisez AbortController.

Pour conclure

Les promesses se résument à quelques règles : une promesse est réglée une fois, then renvoie une nouvelle promesse et les erreurs parcourent la chaîne jusqu’à ce que quelque chose les rattrape. Une fois que ces règles semblent naturelles, async et await cessent d’être magiques. Pour vous entraîner, réécrivez une fonction basée sur le rappel à l’aide de promesses, puis récupérez deux points de terminaison avec Promise.all et gérez correctement un échec.

Questions fréquentes

Continuez à apprendre