JavaScript asynchrone

Le code synchrone termine l’instruction en cours avant de passer à la suivante. Le JavaScript de ta page s’exécute sur un seul thread principal : deux parties de ce code ne s’exécutent donc pas au même instant. C’est facile à suivre jusqu’à ce qu’une instruction lance une opération dont le résultat arrivera plus tard.

Commencer maintenant, traiter le résultat plus tard

Une opération asynchrone commence maintenant et transmet son résultat ensuite, par une fonction de rappel ou une promesse. Le navigateur ou Node.js est l’environnement hôte. Il gère l’attente pendant que ton programme continue. Les minuteries, les actions de l’utilisateur et le chargement d’images fonctionnent tous de cette façon.

console.log("Opening");
setTimeout(() => console.log("Ready"), 700);
console.log("Waiting");

Lis l’appel à setTimeout comme « enregistre cette fonction ». Il se termine sans attendre 700 ms. Le script en cours affiche donc d’abord « Opening » et « Waiting ». Après environ 700 ms, la fonction de rappel peut s’exécuter et afficher « Ready ». Le délai exact dépend aussi du moment où le thread principal se libère.

Il y a ici deux activités distinctes : l’environnement suit la minuterie et JavaScript finit par appeler la fonction qui affiche le résultat. L’attente se superpose à d’autres opérations ; la fonction de rappel s’exécute toujours sur le thread principal.

Pourquoi une page se fige

Une longue boucle synchrone occupe le thread. Pendant son exécution, les gestionnaires de clic et les fonctions de rappel des minuteries ne peuvent pas s’exécuter, et la page ne peut pas mettre son affichage à jour par ce thread. Enregistrer une minuterie avec un délai nul ne l’autorise pas à interrompre la boucle.

Supposons qu’une minuterie arrive à son terme pendant qu’un calcul est encore en cours. L’environnement place sa fonction de rappel dans une file. C’est la fin du calcul qui libère le thread ; l’expiration du délai de la minuterie ne peut pas le faire à elle seule. Une fonction de rappel qui effectue un autre long calcul peut aussi figer la page.

Pour réduire l’effet d’un calcul sur la réactivité, divise-le en petites parties qui laissent d’autres tâches s’exécuter entre elles, ou déplace les opérations qui s’y prêtent dans un Web Worker, un thread distinct en arrière-plan fourni par le navigateur. Placer simplement une grande boucle dans une fonction asynchrone laisse cette boucle sur le thread principal.

Trois façons de recevoir un résultat

Une fonction de rappel transmet l’action suivante sous forme de fonction. Une promesse représente une issue future et permet d’ajouter des gestionnaires de réussite et d’échec. Une fonction asynchrone utilise des promesses, tandis que await permet de suspendre son exécution à un endroit précis.

Ces formes coexistent. Une minuterie reçoit toujours une fonction de rappel, même lorsque le code qui l’entoure utilise des promesses. Une fonction asynchrone peut attendre une promesse produite par une fonction enveloppante utilisant une fonction de rappel. Choisis la forme qui permet de suivre facilement le parcours du résultat.

Lorsque tu lis du code asynchrone, repère d’abord les instructions qui s’exécutent pendant l’appel en cours. Repère ensuite les fonctions enregistrées pour plus tard. Une ligne située dans une fonction de rappel enregistrée ne s’exécute pas simplement parce que l’exécution a atteint la ligne qui crée cette fonction.

La boucle d’événements coordonne les opérations prêtes à s’exécuter. Pour prévoir les résultats, distingue trois choses : les fonctions qui s’exécutent maintenant, les fonctions de rappel qui attendent comme tâches et les opérations liées aux promesses qui attendent comme microtâches.

Suivre la pile et les files

La pile d’appels contient les appels de fonctions actifs. Appeler une fonction y ajoute un cadre ; le retour de cette fonction retire le cadre. La fonction en cours s’exécute jusqu’à ce qu’elle se termine ou appelle une autre fonction.

Une tâche peut être un script, une fonction de rappel de minuterie ou un gestionnaire de clic. Les tâches s’exécutent une par une. Les navigateurs peuvent avoir plusieurs files de tâches : ne suppose donc pas que toutes les sources d’opérations partagent une seule file universelle où le premier arrivé est le premier servi.

La file de microtâches contient les gestionnaires de promesses de then, catch et finally, les continuations après await et les fonctions de rappel passées à queueMicrotask. À un point de contrôle des microtâches après le travail en cours, la file se vide avant la tâche suivante. Les microtâches ajoutées pendant ce traitement s’exécutent aussi avant la tâche suivante.

Suivre un script

console.log("begin");
setTimeout(() => console.log("timer"), 0);
Promise.resolve().then(() => console.log("promise"));
console.log("finish");

1. Le script affiche « begin ».
2. Il enregistre une fonction de rappel de minuterie ; il ne l’appelle pas.
3. Il place le gestionnaire de la promesse tenue dans la file comme microtâche.
4. Il affiche « finish » et termine le travail en cours.
5. La microtâche affiche « promise ».
6. La tâche de la minuterie affiche « timer ».

Une promesse déjà tenue planifie tout de même l’exécution de son gestionnaire pour plus tard. Un délai de 0 ms planifie tout de même une tâche de minuterie.

Inclure les opérations ajoutées en cours de route

Promise.resolve()
  .then(() => console.log("first"))
  .then(() => console.log("third"));
queueMicrotask(() => console.log("second"));
console.log("now");

Le script affiche « now ». La file de microtâches contient d’abord le premier gestionnaire de promesse, puis la fonction de rappel de queueMicrotask. Lorsque le premier gestionnaire affiche « first » et se termine, il rend le gestionnaire de promesse suivant prêt à s’exécuter. Ce nouveau gestionnaire rejoint la fin de la file. La suite des résultats est « second », puis « third ».

Achèvement et réactivité

Une fois qu’une tâche ou une microtâche commence, une opération ajoutée à une file de façon asynchrone ne peut pas l’interrompre. Ce fonctionnement d’exécution jusqu’à achèvement permet de raisonner sur une modification locale sans qu’une minuterie intervienne soudainement au milieu de la fonction.

Une fois les microtâches terminées, le navigateur peut mettre l’écran à jour lorsqu’une occasion de rendu se présente. Il n’a pas à redessiner la page après chaque tâche. Un flux infini de microtâches peut empêcher les tâches suivantes et le rendu : chaque nouvelle microtâche prolonge le traitement de la file en cours. Reporter une opération dans une microtâche ne garantit donc pas que la page aura l’occasion de réagir.

Pour suivre l’exécution, écris d’abord les résultats immédiats, traite les microtâches dans l’ordre jusqu’à vider leur file, puis passe aux tâches de minuterie prêtes. Ajoute les opérations nouvellement planifiées à la file appropriée au moment où le code les planifie effectivement.

Suivre une minuterie créée par une microtâche

setTimeout(() => console.log("outer timer"), 0);
Promise.resolve().then(() => {
  console.log("job one");
  setTimeout(() => console.log("inner timer"), 0);
}).then(() => console.log("job two"));
console.log("script");

Le script enregistre la minuterie externe et le premier gestionnaire de promesse, puis affiche « script ». La première microtâche affiche « job one » et enregistre la minuterie interne. Le retour de ce gestionnaire place « job two » dans la file ; cette microtâche s’exécute aussi avant toute tâche de minuterie. Les résultats se terminent par « outer timer », puis « inner timer » : les deux minuteries ont le même délai et la minuterie externe a été enregistrée en premier.

Créer une minuterie pendant une microtâche ne fait pas de sa fonction de rappel une microtâche. Classe l’opération selon l’API de planification qui la reçoit, puis ajoute-la à la file appropriée.

Les minuteries planifient l’exécution ultérieure de fonctions de rappel. Elles mesurent un délai en millisecondes : 1 000 ms correspondent à 1 s. Le délai détermine à partir de quand une fonction de rappel peut être exécutée ; d’autres opérations et les limites du navigateur peuvent retarder son exécution.

Planifier et annuler un appel

function remind(topic) {
  console.log("Review " + topic);
}
const reminder = setTimeout(remind, 2000, "promises");
// To cancel before it runs:
clearTimeout(reminder);

Les arguments supplémentaires placés après le délai sont transmis à la fonction de rappel. Un délai omis est considéré comme égal à 0. Conserve l’identifiant de minuterie renvoyé si tu peux avoir besoin de l’annuler. Les navigateurs renvoient un identifiant numérique ; Node.js renvoie un objet Timeout. Les deux fonctionnent avec clearTimeout. Annuler une minuterie terminée ou inexistante n’a aucun effet.

Passe une fonction : setTimeout(remind, 2000, "promises"). Écrire setTimeout(remind("promises"), 2000) appelle remind immédiatement et passe sa valeur de retour à la minuterie. Une fonction fléchée est une autre façon de différer un appel avec des arguments : setTimeout(() => remind("promises"), 2000).

Répéter avec une minuterie périodique ou une nouvelle temporisation

let ticks = 0;
const clock = setInterval(() => {
  ticks++;
  console.log("Tick " + ticks);
  if (ticks === 3) clearInterval(clock);
}, 1000);

La première exécution a lieu après environ une seconde. La troisième fonction de rappel arrête les exécutions suivantes. Conserve l’identifiant de la minuterie périodique et utilise clearInterval lorsque l’opération répétée doit prendre fin.

Une fonction de rappel peut aussi planifier sa propre prochaine temporisation. Lorsqu’elle appelle setTimeout à la fin de son travail synchrone, le délai suivant commence après ce travail. Cela crée une pause entre les exécutions et permet de modifier le délai à chaque fois. Une minuterie périodique continue de demander des exécutions à intervalles fixes ; une opération lente peut laisser peu de pause. Si une exécution lance une opération asynchrone, attends aussi la fin de celle-ci avant de planifier la prochaine exécution lorsque leur chevauchement poserait problème.

Les limites des délais

Un thread occupé retarde les fonctions de rappel prêtes à s’exécuter. Les navigateurs ralentissent aussi les minuteries dans les onglets en arrière-plan, souvent à environ une vérification par seconde ou moins. Lorsque le niveau d’imbrication des minuteries dépasse cinq, la règle HTML sur les minuteries porte les délais inférieurs à 4 ms à 4 ms. Les très grands délais demandent aussi de l’attention : la limite habituelle d’un entier signé sur 32 bits est 2147483647 ms, soit environ 24,8 jours ; les valeurs supérieures peuvent provoquer un dépassement et déclencher la minuterie bien plus tôt.

Capturer la bonne valeur de boucle

for (let i = 1; i <= 3; i++) {
  setTimeout(() => console.log(i), 100);
}

Chaque itération avec let possède sa propre liaison : la console affiche donc « 1 », « 2 », « 3 ». Avec var, toutes les fonctions de rappel partagent la même variable. Après la boucle, elle vaut 4 : chacune affiche donc « 4 ».

Attendre une période sans activité

L’anti-rebond annule une temporisation en attente chaque fois qu’un nouvel événement arrive. Une nouvelle temporisation planifie alors l’action après le dernier événement. Avec un délai de 300 ms, une frappe toutes les 100 ms continue de reporter l’action ; elle s’exécute environ 300 ms après la fin de la saisie. Stocke l’identifiant hors du gestionnaire pour que l’appel suivant puisse annuler la minuterie précédente.

Construire un gestionnaire avec anti-rebond

let pendingSave;
function scheduleSave(text) {
  clearTimeout(pendingSave);
  pendingSave = setTimeout(() => {
    console.log("Saved: " + text);
  }, 300);
}
scheduleSave("n");
scheduleSave("no");
scheduleSave("note");

Ces appels ont lieu dans le même script. Chacun annule la minuterie associée à l’identifiant précédent avant de le remplacer : seul « Saved: note » s’affiche donc, après environ 300 ms. La dernière fonction de rappel capture le paramètre de texte de cet appel. L’identifiant existe hors de la fonction afin que chaque appel puisse annuler la temporisation planifiée précédemment.

Si l’identifiant était déclaré à nouveau dans chaque appel, l’appel suivant ne conserverait pas l’identifiant de la minuterie précédente. Si un gestionnaire planifiait une temporisation sans annuler la précédente, il produirait les trois messages. L’anti-rebond a besoin à la fois de l’identifiant partagé et de l’annulation avant son remplacement.

Une fonction de rappel est une fonction que tu passes à une autre fonction pour que celle-ci l’appelle. Le code de la fonction de rappel décrit ce qui doit être fait d’un résultat. Son exécution pendant l’appel en cours ou plus tard dépend de l’API qui la reçoit.

Une fonction de rappel peut s’exécuter de façon synchrone

const doubled = [2, 5].map(n => n * 2);
console.log(doubled);

map appelle sa fonction de rappel pour chaque élément avant de renvoyer le nouveau tableau. Le résultat est [4, 10]. La fonction fléchée est une fonction de rappel, mais ce code ne planifie aucune opération future. Tu peux utiliser doubled à la ligne suivante car le tableau est déjà complet.

Transmettre un résultat différé

function prepareLabel(name, callback) {
  setTimeout(() => {
    callback("Label: " + name);
  }, 200);
}
prepareLabel("Mira", label => {
  console.log(label);
});
console.log("Label requested");

prepareLabel lance une minuterie et se termine. Le script affiche « Label requested ». Après environ 200 ms, la fonction de rappel de la minuterie construit le libellé et appelle la fonction de rappel fournie, qui affiche « Label: Mira ». L’opération choisit quand appeler la fonction ; le code appelant choisit quoi faire du résultat.

Placer les opérations dépendantes là où le résultat existe

let label;
prepareLabel("Mira", value => {
  label = value;
});
console.log(label);

Ce code affiche undefined : l’affectation n’a pas encore eu lieu. Déplace console.log(value) dans la fonction de rappel. Ajouter une temporisation indépendante plus longue avant de lire label reviendrait seulement à deviner quand le résultat sera disponible ; utiliser la fonction de rappel du résultat lie l’opération à sa fin effective.

Un return dans une fonction de rappel différée ne peut pas non plus renvoyer la valeur depuis la fonction qui l’englobe. L’appel à cette dernière est déjà terminé. Dans l’exemple, return "Label: Mira" dans la fonction de rappel de la minuterie renverrait la valeur au mécanisme de la minuterie, laissant le code qui a appelé prepareLabel sans le libellé différé.

Passer l’action suivante sans l’appeler

Une fonction de rappel nommée fonctionne aussi :

function showLabel(label) {
  console.log(label);
}
prepareLabel("Mira", showLabel);

showLabel est la fonction elle-même. showLabel() l’appellerait immédiatement sans libellé et passerait sa valeur de retour à la place. Utilise une fonction fléchée enveloppante lorsque l’action ultérieure a besoin d’un argument particulier ou de plusieurs instructions.

Pour deux étapes asynchrones dépendantes, lance la seconde dans la fonction de rappel de la première. Par exemple, après avoir reçu un utilisateur, passe cet utilisateur à une opération qui prépare ses paramètres. Lancer les deux opérations en dehors de leurs fonctions de rappel n’établirait pas cette dépendance.

La fonction qui reçoit la fonction de rappel décide du nombre de fois où elle l’appelle. Certaines fonctions de rappel, comme les gestionnaires d’événements, sont volontairement appelées de nombreuses fois. Une opération qui produit un seul résultat doit appeler sa fonction de rappel de résultat une fois. Une promesse donne à une telle opération un résultat qui ne peut s’acquitter qu’une seule fois.

Une opération asynchrone peut aussi bien échouer que réussir. Une API à fonctions de rappel a besoin d’un moyen clair de transmettre chaque issue et d’un endroit précis où le code appelant peut la traiter.

Vérifier d’abord l’erreur

La convention de l’erreur en premier utilise callback(err, result). Un appel réussi passe null pour l’erreur. Un appel échoué passe un objet Error et ne fournit pas de résultat utilisable.

function readLabel(id, callback) {
  setTimeout(() => {
    if (id <= 0) {
      callback(new Error("Invalid label id"));
      return;
    }
    callback(null, { id: id, text: "Draft" });
  }, 200);
}
readLabel(4, (err, label) => {
  if (err) {
    console.log(err.message);
    return;
  }
  console.log(label.text);
});

Le code qui produit le résultat s’arrête après avoir signalé un identifiant non valide : il ne peut donc pas aussi signaler une réussite. Le code qui consomme le résultat s’arrête après avoir constaté une erreur : il ne peut donc pas essayer de lire label.text dans un résultat absent. Avec l’identifiant 4, la console affiche « Draft ». Avec l’identifiant 0, elle affiche « Invalid label id ».

Les deux retours sont importants. Sans le retour du code qui consomme le résultat, une seconde erreur concernant une valeur non définie pourrait masquer le message initial utile. Sans le retour du code qui produit le résultat, une opération pourrait appeler deux fois la fonction de rappel. Pour une API qui produit un seul résultat, signale exactement une issue.

Le bloc try autour de l’appel est déjà terminé

try {
  setTimeout(() => {
    throw new Error("Late failure");
  }, 0);
} catch (err) {
  console.log("Handled");
}

Le try planifie la minuterie et se termine. La fonction de rappel lève une exception dans une tâche ultérieure, lorsque ce try n’est plus actif : « Handled » ne s’affiche donc pas. Intercepte une éventuelle exception dans la fonction de rappel ou transmets l’échec par le paramètre d’erreur de l’API. Une fonction enveloppante renvoyant une promesse devra ensuite convertir explicitement cette erreur de fonction de rappel en rejet.

Garder les étapes dépendantes lisibles

Le code utilisant des fonctions de rappel devient difficile à suivre lorsque chaque étape suivante apparaît dans la fonction de rappel de l’étape précédente. Lire un profil, puis ses projets, puis les tâches d’un projet crée plusieurs niveaux d’imbrication. Chaque opération a aussi besoin de sa propre vérification d’erreur. Ce schéma est souvent appelé enfer des fonctions de rappel ou pyramide de malheur.

Des fonctions nommées peuvent donner à ces étapes des noms qui ont un sens et réduire l’imbrication visible. Garde une transmission des erreurs cohérente entre elles : une étape ultérieure peut échouer tout autant que la première. Les promesses et les fonctions asynchrones offrent une façon moins imbriquée d’exprimer la même séquence tout en maintenant la propagation des échecs.

Toutes les API à fonctions de rappel n’utilisent pas un paramètre d’erreur. Certains objets du navigateur disposent d’événements distincts pour la réussite et l’échec. Pour une image, définis les gestionnaires onload et onerror avant d’affecter une valeur à src, afin que les deux issues aient un gestionnaire au début du chargement. Lis le contrat de l’API avant de supposer qu’un paramètre nommé err existe.

Une promesse représente une issue future. Une fonction peut la renvoyer immédiatement, ce qui permet au code appelant de relier des opérations à un résultat qui n’existe pas encore.

États et acquittement

Une promesse est en attente jusqu’à ce qu’elle soit tenue avec une valeur ou rejetée avec une raison. Les promesses tenues et rejetées sont acquittées ; leur issue ne peut plus changer.

« Résolue » a un sens plus précis que celui d’un synonyme courant de « réussie ». Une promesse résolue avec une autre promesse en attente suit l’issue future de cette dernière, y compris son éventuel rejet. Elle peut donc être résolue tout en étant encore en attente.

Créer une promesse autour d’une opération

function wait(ms) {
  return new Promise(resolve => {
    setTimeout(resolve, ms);
  });
}
wait(200).then(() => console.log("Pause finished"));

new Promise appelle immédiatement sa fonction exécutrice. Celle-ci enregistre une minuterie. Lorsque la minuterie appelle resolve, la promesse est tenue avec undefined et le gestionnaire then enregistré s’exécute plus tard comme microtâche. Cette fonction utilitaire fournit une pause réutilisable sans bloquer le thread.

Une fonction exécutrice peut recevoir à la fois resolve et reject :

function reserve(quantity) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (quantity <= 8) resolve(8 - quantity);
      else reject(new Error("Not enough stock"));
    }, 200);
  });
}
reserve(3).then(left => console.log(left));
reserve(9).catch(err => console.log(err.message));

Pour ces quantités positives, le premier appel est tenu avec 5 et le second est rejeté avec « Not enough stock ». La promesse permet au code appelant de recevoir l’une ou l’autre issue par le même objet renvoyé.

La création lance la fonction exécutrice

console.log("before");
const result = new Promise(resolve => {
  console.log("creating");
  resolve(12);
});
console.log("after");
result.then(value => console.log(value));

La console affiche « before », « creating », « after », « 12 ». Ajouter then ne lance pas cette fonction exécutrice. Le constructeur l’a déjà exécutée ; then enregistre le code qui utilisera son résultat.

Seul le premier appel à resolve ou reject détermine le sort de la promesse. Les appels suivants ne peuvent pas le modifier. Cela s’applique aussi lorsque la première résolution adopte une autre promesse dont le résultat est encore en attente. Appeler resolve n’arrête pas le code ordinaire de la fonction exécutrice : utilise donc return lorsqu’une branche doit se terminer.

Faire en sorte que chaque chemin se termine correctement

Une exception levée de façon synchrone dans la fonction exécutrice rejette automatiquement la promesse. Une exception levée plus tard dans une fonction de rappel de minuterie se produit en dehors de cet appel et n’est pas convertie en rejet. Utilise reject(new Error("...")) à cet endroit ; sinon, l’erreur peut ne pas être interceptée tandis que la promesse reste en attente.

Une branche qui n’appelle aucune des deux fonctions peut laisser le code appelant attendre indéfiniment. Utilise des objets Error comme raisons de rejet afin que les gestionnaires puissent lire un message et que les outils de débogage puissent afficher des informations utiles sur l’erreur.

Promise.resolve(value) crée une promesse tenue pour une valeur ordinaire ou adopte l’issue d’une autre promesse. Promise.reject(error) crée une promesse rejetée. Ajoute un gestionnaire de rejet lorsque tu utilises cette dernière.

Suivre une issue adoptée

const inner = new Promise(resolve => {
  setTimeout(() => resolve("packed"), 250);
});
const outer = new Promise((resolve, reject) => {
  resolve(inner);
  reject(new Error("Too late to replace it"));
});
outer.then(value => console.log(value));

La fonction exécutrice interne lance sa minuterie pendant la construction. La fonction exécutrice externe se résout ensuite avec inner, ce qui lie définitivement outer à l’issue future de inner. L’appel ultérieur à reject ne peut pas modifier cette décision. Outer reste en attente jusqu’à ce que inner soit tenue, puis son gestionnaire affiche « packed » après environ 250 ms.

Si inner était rejetée, outer suivrait ce rejet. Le premier appel à resolve a choisi l’issue à suivre ; il n’a pas garanti une réussite. Cette distinction compte lorsqu’une fonction enveloppante transmet une autre promesse au lieu de fournir une valeur ordinaire déjà disponible.

Les gestionnaires de promesses relient du code à une réussite, à un échec ou aux deux issues possibles. Chaque enregistrement d’un gestionnaire renvoie aussi une nouvelle promesse, ce qui permet au code suivant de recevoir ce que produit ce gestionnaire.

Utiliser le gestionnaire adapté à l’issue

p.then(onFulfilled) reçoit la valeur d’une promesse tenue. p.catch(onRejected) reçoit la raison d’un rejet ; c’est une forme abrégée de p.then(undefined, onRejected). Les gestionnaires sont des fonctions et s’exécutent comme des microtâches, même si p est déjà acquittée.

Promise.resolve("draft")
  .then(text => console.log(text));
console.log("registered");

Le script affiche « registered » avant que le gestionnaire n’affiche « draft ». Une valeur immédiatement disponible ne rend pas le gestionnaire synchrone.

Il est essentiel de passer une fonction. then(console.log("draft")) affiche « draft » pendant l’enregistrement et passe undefined comme gestionnaire. Utilise then(() => console.log("draft")) lorsque le message doit s’afficher plus tard. then(console.log) passe la fonction d’affichage elle-même, qui reçoit donc la valeur.

Effectuer le nettoyage après une réussite ou un échec

finally est utile pour masquer un indicateur de chargement ou réactiver un bouton après l’acquittement d’une opération. Sa fonction de rappel ne reçoit ni valeur ni erreur en argument.

Promise.resolve(4)
  .finally(() => console.log("Cleanup"))
  .then(value => console.log(value));

La console affiche « Cleanup », puis « 4 ». Renvoyer une valeur ordinaire depuis la fonction de rappel de nettoyage ne remplace pas 4. Une promesse renvoyée peut retarder l’étape suivante jusqu’à la fin du nettoyage. Si le nettoyage lève une erreur ou renvoie une promesse rejetée, cet échec devient la nouvelle issue de la chaîne.

Sur une page, on définit généralement un état de chargement avant de commencer, on traite le résultat dans then, on signale l’échec dans catch et on réinitialise l’état de chargement dans finally. Place les opérations qui dépendent du résultat dans then ou catch, où l’argument nécessaire existe.

Distinguer les abonnements d’une chaîne

const p = Promise.resolve(4);
p.then(value => value * 2);
p.then(value => console.log(value));

Ce sont deux abonnements distincts à p. Tous deux reçoivent 4. La multiplication appartient à la nouvelle promesse renvoyée par le premier then ; elle ne modifie pas p et ne transmet rien au second abonnement.

Relie-les pour transmettre la valeur transformée :

p.then(value => value * 2)
  .then(value => console.log(value));

Le dernier gestionnaire reçoit maintenant 8. La différence tient à la promesse à laquelle chaque gestionnaire est associé.

L’objet renvoyé reste une promesse

Dans const next = p.then(value => value * 2), next est une nouvelle promesse, et non le nombre 8. Le gestionnaire peut s’exécuter après la fin du script qui l’entoure et peut lui-même renvoyer une opération différée. Utilise un autre gestionnaire ou await pour obtenir la valeur. Traiter immédiatement next comme un nombre fait perdre cette information sur le moment où la valeur sera disponible.

Une chaîne de promesses transmet le résultat d’un gestionnaire au suivant. Chaque maillon doit renvoyer la valeur ou la promesse dont les maillons suivants ont besoin.

Transmettre des valeurs dans la chaîne

Promise.resolve(3)
  .then(count => count * 4)
  .then(total => total + 2)
  .then(total => console.log(total));

Le premier gestionnaire reçoit 3 et renvoie 12. Le deuxième reçoit 12 et renvoie 14. Le dernier affiche « 14 ». Une fonction fléchée dont le corps est une expression renvoie automatiquement cette expression ; un corps de fonction entre accolades a besoin d’un return explicite pour transmettre une valeur.

Renvoyer une promesse pour une étape dépendante

function wait(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
function makeCode() {
  return wait(100).then(() => "P4");
}
function makeLabel(code) {
  return wait(200).then(() => "Parcel " + code);
}
makeCode()
  .then(code => makeLabel(code))
  .then(label => console.log(label));

makeCode fournit « P4 » après environ 100 ms. Le gestionnaire suivant renvoie la promesse de makeLabel. La chaîne suit cette promesse, attend environ 200 ms de plus et transmet « Parcel P4 » au dernier gestionnaire. Le code appelant reçoit un libellé, et non une promesse imbriquée dans la valeur.

Repérer un maillon rompu

Compare ce gestionnaire intermédiaire avec celui-ci :

.then(code => {
  makeLabel(code);
})

Il lance makeLabel mais ne renvoie rien. Sa nouvelle promesse est tenue avec undefined sans attendre le libellé. Le gestionnaire suivant reçoit donc undefined après l’étape du code, tandis que la préparation du libellé se poursuit séparément. Les erreurs de cette opération séparée ne se propagent plus non plus dans la chaîne externe.

Corrige-le avec return makeLabel(code); entre les accolades ou retire les accolades pour renvoyer l’expression. La même règle s’applique lorsqu’un gestionnaire lance une pause : .then(() => wait(200)) attend ; .then(() => { wait(200); }) n’attend pas.

Réduire l’imbrication et conserver les valeurs nécessaires

Placer un autre then profondément dans le premier gestionnaire peut recréer l’imbrication des fonctions de rappel. Renvoie la promesse interne et place le gestionnaire suivant au niveau externe. Cela conserve un seul parcours pour les délais, les valeurs et les erreurs.

Chaque gestionnaire possède sa propre portée locale. Si une étape ultérieure a besoin à la fois du code et du libellé, renvoie un objet qui les contient :

makeCode()
  .then(code => makeLabel(code).then(label => ({ code, label })))
  .then(pair => console.log(pair.code + ": " + pair.label));

Ce petit gestionnaire interne construit la valeur combinée. La promesse issue de son enregistrement est renvoyée et reste donc reliée à la chaîne. Une fonction asynchrone peut aussi conserver les deux résultats dans des variables locales ordinaires.

Un rejet ignore les gestionnaires de réussite suivants jusqu’à atteindre un gestionnaire de rejet. Un catch final peut gérer les échecs de toutes les étapes précédentes reliées à la chaîne. Les opérations dépendantes ont leur place dans cette séquence ; les opérations indépendantes peuvent être lancées ensemble avec Promise.all.

Une fonction asynchrone renvoie toujours une promesse. À l’intérieur, await suspend cette fonction jusqu’à ce qu’une valeur soit disponible, ce qui permet de lire les étapes dépendantes de haut en bas.

Renvoyer une valeur par une promesse

async function getCount() {
  return 6;
}
getCount().then(count => console.log(count));

Appeler getCount() donne une promesse tenue avec 6. Le gestionnaire affiche « 6 ». Si la fonction lève une erreur, la promesse qu’elle renvoie est rejetée. Si elle renvoie une autre promesse, la fonction asynchrone suit l’issue future de cette promesse.

Tu peux déclarer une fonction asynchrone avec async function name(), une fonction fléchée asynchrone comme const name = async () => {}, ou une méthode d’objet asynchrone. Dans tous les cas, elle renvoie une promesse.

Suspendre l’exécution avec await

function wait(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
async function showSteps() {
  console.log("Step one");
  await wait(300);
  console.log("Step two");
}
showSteps();
console.log("Caller continues");

La console affiche d’abord « Step one », puis « Caller continues ». Environ 300 ms plus tard, elle affiche « Step two ». L’appel de la fonction exécute son corps de façon synchrone jusqu’au premier await. La pause rend le contrôle au code appelant. Une fois la promesse tenue, le reste de showSteps reprend par la file de microtâches.

Await suspend sa fonction, pas le thread entier. D’autres tâches prêtes peuvent s’exécuter pendant l’attente. Un long calcul synchrone avant ou après await peut toujours bloquer le thread pendant son exécution.

Lire une valeur ou recevoir une erreur

Une promesse tenue fournit sa valeur : const count = await getCount(); affecte 6 à count. Une promesse rejetée lève sa raison à la ligne de await. Entoure l’opération attendue de try et catch lorsque cette fonction doit gérer l’échec.

await accepte aussi des valeurs ordinaires. Dans const count = await 6;, le résultat est toujours 6, mais la continuation de la fonction est différée. Elle ne devient pas synchrone simplement parce qu’aucune opération n’avait besoin d’être attendue.

Vérifier où placer await

Utilise await dans la fonction asynchrone dont le corps le contient. Il est aussi autorisé au niveau supérieur d’un module JavaScript. Le corps d’une fonction ordinaire ne peut pas contenir await ; une fonction asynchrone externe ne rend pas asynchrone une fonction de rappel ordinaire imbriquée.

Le code appelant reçoit toujours une promesse. Pour utiliser la valeur finale, attends-la depuis une autre fonction asynchrone ou ajoute then. Par exemple, const total = getCount(); stocke une promesse ; cette instruction ne stocke pas 6.

Un gestionnaire d’événements peut lui-même être asynchrone. Il peut attendre une étape de préparation avant de mettre une page à jour. Prévois une gestion des erreurs propre à cette action, car le déclenchement de l’événement n’attend pas la promesse renvoyée par le gestionnaire. Au niveau supérieur d’un programme, un appel comme showSteps().catch(console.error) associe un gestionnaire à un échec imprévu.

Une chaîne de promesses peut devenir une fonction asynchrone sans changer ses dépendances. Chaque résultat reçoit une variable locale et chaque étape attendue ne commence qu’une fois disponible le résultat précédent dont elle a besoin.

Remplacer les gestionnaires par des affectations avec attente

function wait(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
function getUser(id) {
  return wait(100).then(() => ({ id, name: "Nia" }));
}
function getOrders(user) {
  return wait(200).then(() => [user.name + "-1", user.name + "-2"]);
}
async function showOrders(id) {
  const user = await getUser(id);
  const orders = await getOrders(user);
  console.log(user.name + ": " + orders.length + " orders");
}
showOrders(8).catch(console.error);

Le premier await fournit un utilisateur. Alors seulement, getOrders(user) peut commencer. Après environ 300 ms au total, la fonction affiche « Nia: 2 orders ». user et orders sont tous deux accessibles dans la portée de cette dernière ligne. Dans une chaîne, le paramètre de chaque gestionnaire appartiendrait à une portée locale distincte.

La chaîne correspondante renverrait getOrders(user) depuis le premier gestionnaire. La réécrire avec await rend cette attente explicite tout en conservant l’ordre. Un catch final de chaîne devient un try/catch autour des étapes attendues ; finally devient un bloc de nettoyage.

Convertir une API à fonctions de rappel en API à promesses

Ajouter async à une fonction enveloppante ne fait pas de la valeur différée d’une API à fonctions de rappel sa valeur de retour. Relie la fonction de rappel à l’acquittement de la promesse :

function readTag(id, callback) {
  setTimeout(() => {
    if (id <= 0) callback(new Error("Invalid tag"));
    else callback(null, "Tag " + id);
  }, 100);
}
function readTagAsync(id) {
  return new Promise((resolve, reject) => {
    readTag(id, (err, tag) => {
      if (err) {
        reject(err);
        return;
      }
      resolve(tag);
    });
  });
}

Dans une fonction asynchrone, const tag = await readTagAsync(8); donne « Tag 8 ». L’appeler avec 0 lève à la place « Invalid tag » au niveau de await. Une réussite résout la promesse de la fonction enveloppante ; un échec la rejette. L’adaptateur change la façon dont l’issue est transmise, pas ce que fait l’opération sous-jacente.

Cette conversion s’appelle la promessification. Pour les API ordinaires qui produisent un seul résultat et suivent la convention de l’erreur en premier, Node.js fournit aussi util.promisify, et de nombreux modules intégrés disposent déjà de variantes utilisant des promesses, comme fs/promises.

Garder un parcours clair

Les minuteries deviennent des pauses grâce à une fonction utilitaire wait qui renvoie une promesse. Une boucle asynchrone peut afficher une étape, attendre la pause, puis commencer l’itération suivante. Avec des fonctions de rappel, il faudrait planifier l’étape suivante dans la fonction de rappel précédente.

Les promesses, les chaînes et les fonctions asynchrones fonctionnent ensemble : une fonction asynchrone peut attendre une chaîne et le code appelant peut ajouter then à la promesse qu’elle renvoie. Dans une fonction, utilise la forme qui permet de suivre facilement les dépendances et la gestion des erreurs. Un constructeur Promise supplémentaire est utile pour adapter une fonction de rappel, mais les opérations qui renvoient déjà des promesses peuvent être attendues directement.

Le code asynchrone peut ressembler à du code synchrone tout en transmettant des promesses entre les fonctions. De nombreux bogues viennent d’une lecture trop précoce de la valeur future ou de la supposition qu’une fonction utilitaire attend des fonctions de rappel qu’elle ignore.

Attendre la valeur avant de l’utiliser

async function getQuantity() {
  return 18;
}
async function total() {
  const quantity = await getQuantity();
  console.log(quantity * 3);
}
total().catch(console.error);

Ce code affiche « 54 ». Sans await, quantity contiendrait une promesse. Multiplier cette promesse par 3 produit NaN, et non un calcul différé qui se met automatiquement à jour.

Une condition présente le même piège. Une vérification asynchrone qui renvoie false renvoie tout de même un objet promesse, et les objets sont des valeurs vraies. Utilise if (await allowed()) dans une fonction asynchrone lorsque la branche dépend du booléen futur. Tester if (allowed()) revient à tester l’objet lui-même.

forEach ne collecte pas les promesses des fonctions de rappel

function wait(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
async function labelAll(ids) {
  ids.forEach(async id => {
    await wait(100);
    console.log("Label " + id);
  });
  console.log("Labels finished");
}
labelAll([4, 9]).catch(console.error);

« Labels finished » apparaît avant les libellés. forEach appelle les deux fonctions de rappel, ignore les promesses qu’elles renvoient et termine sa propre itération synchrone. Même await ids.forEach(...) attendrait undefined, et non le travail des fonctions de rappel. Un échec dans ces promesses ignorées se situe aussi hors de la promesse renvoyée par labelAll.

Pour un traitement ordonné, écris une boucle ordinaire :

for (const id of ids) {
  await labelOne(id);
}
console.log("Labels finished");

Ici, labelOne est une opération qui renvoie une promesse. Chaque élément commence après la fin du précédent. Pour des éléments indépendants, utilise await Promise.all(ids.map(id => labelOne(id))); avant le dernier affichage. map collecte les promesses renvoyées et Promise.all donne au code appelant une seule promesse pour leur achèvement.

Distinguer l’indépendance de la syntaxe

Attendre immédiatement chaque opération rend les attentes séquentielles. Pour des attentes indépendantes de 1 000, 2 000 et 1 500 ms, cela prend environ 4 500 ms. Lancer les trois et les combiner prend environ 2 000 ms. Une étape qui a besoin d’un résultat précédent doit toujours l’attendre.

Garder les échecs reliés

Une fonction imbriquée a besoin de son propre mot-clé async pour utiliser await, mais ce mot-clé seul ne fait pas attendre le résultat par le code appelant. Vérifie les deux côtés : la fonction de rappel renvoie-t-elle une promesse et le code appelant l’utilise-t-il ?

Pour une opération lancée volontairement sans attendre son achèvement, ajoute un gestionnaire de rejet comme backgroundTask().catch(console.error). Vérifie aussi les retours dans les fonctions enveloppantes asynchrones : async function prepare() { await wait(100); } est tenue avec undefined. Attendre une étape et renvoyer son résultat sont deux décisions distinctes.

Renvoyer les résultats du groupe corrigé

function wait(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
async function prepareItem(id) {
  await wait(50);
  return "Item " + id;
}
async function prepareAll(ids) {
  return await Promise.all(ids.map(id => prepareItem(id)));
}
prepareAll([6, 2]).then(items => console.log(items.join(", ")));

Chaque fonction de rappel de map renvoie une promesse et map conserve ces promesses dans un tableau. Promise.all attend les deux et fournit ["Item 6", "Item 2"]. La fonction prepareAll renvoie ce tableau par sa propre promesse : le code appelant affiche donc « Item 6, Item 2 » après la fin du groupe.

Retirer le return de prepareAll attendrait toujours le groupe, mais le code appelant recevrait undefined. Remplacer map par forEach ferait perdre le tableau de promesses. Vérifie séparément la collecte, l’attente et le retour lorsque tu corriges une action portant sur plusieurs éléments.

Le rejet d’une promesse suit la chaîne à laquelle elle est reliée jusqu’à ce qu’un gestionnaire de rejet le traite. Comprendre ce que ce gestionnaire renvoie permet de savoir si la chaîne a récupéré après l’erreur ou si elle reste en échec.

Suivre un rejet au-delà des gestionnaires de réussite

Promise.resolve(8)
  .then(value => {
    throw new Error("Count rejected");
  })
  .then(value => console.log("Unused: " + value))
  .catch(err => {
    console.log(err.message);
    return 2;
  })
  .then(value => console.log("Using " + value));

L’exception rejette la nouvelle promesse renvoyée par le premier then. Le gestionnaire de réussite suivant est ignoré : « Unused » ne s’affiche donc jamais. Le catch affiche « Count rejected » et renvoie 2. Ce retour tient le maillon suivant et le dernier gestionnaire affiche donc « Using 2 ».

Une promesse explicitement rejetée et une exception levée dans un gestionnaire empruntent le même chemin de rejet. C’est pourquoi un seul catch final peut gérer les échecs de plusieurs étapes précédentes reliées à la chaîne.

Choisir entre récupération et propagation

Un gestionnaire de rejet qui renvoie une valeur récupère après l’erreur avec cette valeur. Ne rien renvoyer permet aussi de récupérer, mais avec undefined. Consigner un échec ne revient donc pas à laisser la chaîne rejetée :

Promise.reject(new Error("Label missing"))
  .catch(err => console.log(err.message))
  .then(value => console.log(value));

Le dernier gestionnaire reçoit undefined. Si le code suivant exige un libellé réel, cette récupération silencieuse est probablement incorrecte. Renvoie une solution de repli utilisable ou relance l’erreur.

function reportAndRethrow(err) {
  console.error(err);
  throw err;
}

Utiliser cette fonction dans catch consigne l’erreur et laisse la promesse suivante rejetée avec la même raison. Un appelant situé plus loin dans la chaîne peut décider quoi faire.

Placer le gestionnaire après les opérations qu’il protège

Un catch gère les échecs qui le précèdent. S’il récupère après l’erreur, les étapes suivantes s’exécutent normalement et leurs nouveaux échecs ont besoin d’un gestionnaire ultérieur. Un gestionnaire placé au milieu ne peut pas intercepter des erreurs qui ne se sont pas encore produites.

Il existe aussi une différence importante entre .then(success, failure) et .then(success).catch(failure). Les deux gestionnaires d’un même then réagissent à l’issue de la promesse reçue. Son gestionnaire d’échec n’intercepte pas une erreur levée par son propre gestionnaire de réussite. Cette erreur appartient à la nouvelle promesse renvoyée par l’appel : un catch ultérieur est donc nécessaire.

Conserver les erreurs utiles

Rejette les promesses avec des objets Error pour que les gestionnaires puissent lire err.message et err.name. Lever une chaîne ou rejeter une promesse avec une chaîne est autorisé, mais le code qui attend les champs d’un objet Error ne les recevra pas. Conserve l’erreur initiale lors de la propagation d’un échec, sauf si l’ajout de contexte aide le code appelant à comprendre quelle opération a échoué.

try, catch et finally permettent à une fonction asynchrone de gérer les échecs à l’endroit où elle les attend. Utilise cette structure pour regrouper le traitement du résultat, la récupération et le nettoyage.

Une erreur transfère le contrôle

Un objet Error décrit un échec. new Error("Label missing") a pour message « Label missing » et pour nom « Error » ; les outils de débogage peuvent aussi afficher sa pile. Les erreurs intégrées ont des types comme TypeError.

throw arrête l’exécution normale à cet endroit et transfère le contrôle au catch applicable le plus proche. Le code situé après le traitement peut encore s’exécuter lorsque la fonction intercepte sa propre erreur. Lève des objets Error pour que les gestionnaires suivants reçoivent des champs utiles.

Attendre dans le bloc protégé

async function run() {
  console.log("Working");
  try {
    await Promise.reject(new Error("Device busy"));
    console.log("Complete");
  } catch (err) {
    console.log("Failed: " + err.message);
  } finally {
    console.log("Controls enabled");
  }
}
run().catch(console.error);

La promesse rejetée lève une erreur à la ligne de await. Le reste de try est ignoré. La console affiche « Working », « Failed: Device busy », puis « Controls enabled ». Une opération réussie atteindrait « Complete » et exécuterait tout de même le même nettoyage.

Utilise finally pour un indicateur de chargement, l’état d’un bouton ou une autre ressource qui doit être réinitialisée quelle que soit l’issue. Il s’exécute même lorsque try ou catch contient une instruction return. Évite que le nettoyage lève une erreur, sauf si ce nouvel échec doit volontairement remplacer l’issue précédente. Un return dans finally peut remplacer un retour ou une exception antérieurs : évite donc de l’utiliser pour un nettoyage ordinaire.

Ici, renvoyer une promesse est différent de l’attendre

async function readSetting() {
  try {
    return await Promise.reject(new Error("Missing setting"));
  } catch {
    return "light";
  }
}
readSetting().then(value => console.log(value));

Ce code affiche « light ». La fonction attend dans try : le rejet atteint donc le catch local. Retirer await renvoie immédiatement la promesse rejetée ; la fonction adopte son rejet, mais le catch local ne traite pas cette issue ultérieure. Le code appelant devrait l’intercepter.

Donner à chaque échec un périmètre adapté

Un seul try peut couvrir un groupe d’attentes lorsque toute l’action doit s’arrêter si une étape échoue. Donne à une étape facultative un périmètre plus restreint si elle peut récupérer indépendamment. Par exemple, const settings = await loadSettings().catch(() => ({ theme: "light" })); utilise un objet par défaut et continue.

Une variable déclarée dans try a une portée de bloc. Si le code après le bloc en a besoin, déclare let result; avant try ou termine les opérations qui dépendent du résultat dans try. Ne déplace pas une valeur hors de sa portée simplement pour garder un affichage final à l’endroit que tu préfères.

Lorsque la fonction en cours ne peut pas récupérer après l’erreur, laisse le rejet atteindre le code appelant. L’intercepter uniquement pour le masquer empêche cet appelant de prendre une décision utile.

Une action a besoin d’un périmètre d’interception des erreurs : un endroit qui reçoit son échec final et choisit une réponse. Sans ce périmètre, une promesse peut être rejetée alors que personne ne gère son issue.

Gérer le dernier chemin

Un rejet non géré est un rejet qui n’a toujours pas de gestionnaire lorsque l’hôte effectue sa vérification. La gestion peut utiliser catch, l’argument de rejet de then ou try/catch autour de await. Un navigateur signale le problème et peut déclencher unhandledrejection. Node.js s’arrête par défaut en cas de rejet non géré selon sa politique habituelle : en laisser un sans gestionnaire peut donc mettre fin à un programme.

Une action comme main() ou un gestionnaire de clic asynchrone doit gérer sa promesse finale. Les fonctions de niveau inférieur peuvent transmettre les échecs vers le haut, mais le parcours doit aboutir à un endroit où une décision est prise. Un écouteur global de rejets peut aider à consigner les échecs manqués ; il ne peut pas choisir la meilleure récupération pour chaque action.

Un catch vide passe l’échec sous silence. Consigne les détails techniques avec console.error(err) et affiche un message clair si l’action de l’utilisateur a échoué. Un message comme « Le libellé n’a pas pu être enregistré. Réessaie dans quelques instants. » indique à l’utilisateur une action possible sans exposer de trace de pile.

Ajouter du contexte sans perdre la cause

async function prepareLabel() {
  try {
    return await Promise.reject(new Error("Device offline"));
  } catch (err) {
    throw new Error("Could not prepare label", { cause: err });
  }
}
prepareLabel().catch(err => {
  console.log(err.message);
  console.log(err.cause.message);
});

Ce code affiche « Could not prepare label » et « Device offline ». Le message externe indique l’action qui a échoué. La propriété cause conserve l’erreur de niveau inférieur pour le diagnostic. L’option de cause d’Error fait partie d’ECMAScript 2022.

Relancer une nouvelle opération, avec une limite

function wait(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
async function withRetry(task, attempts) {
  for (let attempt = 1; attempt <= attempts; attempt++) {
    try {
      return await task();
    } catch (err) {
      if (attempt === attempts) throw err;
      await wait(200);
    }
  }
}

Appelle cette fonction avec une fonction qui lance une nouvelle tentative et une limite exprimée par un entier positif. Si task échoue deux fois et réussit à son troisième appel, une limite de quatre arrête les essais au troisième appel et renvoie sa valeur. Si les quatre tentatives échouent, la quatrième erreur est relancée. Le délai n’a lieu qu’entre les tentatives.

return await garde le rejet dans ce try, où catch peut lancer une nouvelle tentative. Passer une promesse déjà rejetée au lieu d’une fonction de tâche ne relancerait pas l’opération.

Fais une nouvelle tentative lorsqu’un échec peut être temporaire. Utilise une solution de repli lorsque la fonctionnalité peut fonctionner avec des données par défaut. Arrête l’opération et informe l’utilisateur lorsqu’elle ne peut pas réussir. Si une fonction de niveau inférieur ne peut pas faire ce choix, conserve l’erreur et laisse le code appelant décider.

Des opérations asynchrones indépendantes peuvent attendre en même temps. Le choix de les lancer ensemble dépend des données dont elles ont besoin, et non de l’ajout du mot async.

Lancer les opérations indépendantes avant de toutes les attendre

function wait(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
function makePart(name, ms) {
  return wait(ms).then(() => name);
}
async function assemble() {
  const parts = await Promise.all([
    makePart("cover", 1000),
    makePart("pages", 2000),
    makePart("label", 1500)
  ]);
  console.log(parts.join(", "));
}
assemble().catch(console.error);

Les trois appels commencent avant que Promise.all n’attende leurs résultats. Environ 2 000 ms plus tard, le tableau contient ["cover", "pages", "label"]. Attendre chaque appel avant de lancer le suivant prendrait environ 4 500 ms. Les délais des minuteries sont approximatifs : les durées réelles peuvent donc être plus longues.

Ici, en parallèle signifie que les attentes se chevauchent. Les gestionnaires de promesses s’exécutent toujours un par un sur le thread principal. Appeler trois fonctions synchrones lourdes dans le tableau exécuterait ces calculs les uns après les autres ; Promise.all ne les déplacerait pas vers des threads distincts.

Les résultats conservent leur place dans les entrées

Le libellé se termine avant les pages, mais reste troisième dans le tableau. Promise.all conserve l’ordre des entrées, et non l’ordre d’achèvement. La déstructuration permet de nommer ces positions :

const [cover, pages] = await Promise.all([
  makePart("cover", 1000),
  makePart("pages", 2000)
]);

Utilise ce code dans une fonction asynchrone. Pour une collection, ids.map(id => loadItem(id)) lance une opération qui renvoie une promesse par identifiant et donne à Promise.all le tableau de promesses. N’attends pas chaque élément dans une boucle s’ils sont tous indépendants et doivent se chevaucher.

Un échec met fin à l’attente combinée

Promise.all est rejetée dès qu’une entrée est rejetée. Si une partie échoue après environ 300 ms, un catch peut alors recevoir cette raison ; il n’a pas besoin d’attendre la fin de l’opération réussie qui prend le plus de temps.

Les autres opérations continuent de s’exécuter. Leurs effets de bord peuvent encore se produire, mais la promesse combinée ne sera pas tenue plus tard avec leurs valeurs. Cette règle d’échec immédiat (fail-fast) est utile lorsque l’étape suivante exige tous les résultats.

Respecter les dépendances et ajouter rapidement des gestionnaires

Si une opération a besoin d’un utilisateur produit par une autre, obtiens d’abord cet utilisateur. Les appels suivants ne peuvent être combinés que s’ils sont indépendants les uns des autres une fois cet utilisateur disponible.

Lancer deux promesses et les attendre séparément fait bien se chevaucher leurs attentes, mais la seconde peut être rejetée avant que le code n’atteigne son await. Si elle n’a toujours pas de gestionnaire lorsque l’hôte vérifie les rejets, un rejet non géré peut être signalé. Combiner rapidement les promesses avec Promise.all associe un gestionnaire aux deux entrées et donne au code appelant un seul chemin pour les échecs.

Les valeurs ordinaires sont autorisées parmi les entrées et conservent leur place. Promise.all([]) est déjà tenue avec un tableau vide. Un gestionnaire qui lui est associé s’exécute toujours de façon asynchrone.

Le bon combinateur de promesses dépend de ce qui constitue un résultat utile. Détermine si tu as besoin de toutes les réussites, de toutes les issues, du premier acquittement ou de la première réussite.

Conserver les résultats partiels avec allSettled

Promise.allSettled attend chaque entrée et renvoie des objets décrivant les issues dans l’ordre des entrées. Une réussite devient { status: "fulfilled", value } ; un échec devient { status: "rejected", reason }. Une entrée rejetée ne rejette pas la promesse combinée.

Promise.allSettled([
  Promise.resolve("Map ready"),
  Promise.reject(new Error("Chart unavailable"))
]).then(results => {
  for (const result of results) {
    if (result.status === "fulfilled") console.log(result.value);
    else console.log(result.reason.message);
  }
});

Ce code affiche « Map ready » et « Chart unavailable ». Il convient à des panneaux indépendants, lorsqu’un panneau qui fonctionne reste utile même si un autre échoue. Lis value uniquement dans un objet correspondant à une promesse tenue et reason dans un objet correspondant à une promesse rejetée.

Laisser le premier acquittement décider avec race

Promise.race suit la première entrée acquittée, qu’elle soit tenue ou rejetée. Un échec après 100 ms l’emporte sur une réussite après 200 ms. C’est utile pour un délai d’expiration :

function wait(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
function timeout(ms) {
  return new Promise((_, reject) => {
    setTimeout(() => reject(new Error("Time limit reached")), ms);
  });
}
Promise.race([
  wait(600).then(() => "Prepared"),
  timeout(250)
]).then(console.log).catch(err => console.log(err.message));

Le délai d’expiration provoque un rejet en premier : la console affiche donc « Time limit reached ». L’opération de 600 ms continue de s’exécuter. Une course acquitte la promesse combinée du code appelant ; elle n’annule pas les opérations perdantes.

Attendre la première réussite avec any

Promise.any ignore les entrées qui échouent tant qu’une réussite reste possible. Si une opération échoue après 100 ms et qu’une autre est tenue après 200 ms, elle donne la valeur de cette dernière. Un rejet plus rapide ne l’emporte pas.

Si toutes les entrées sont rejetées, any est rejetée avec une AggregateError. Son tableau errors conserve les raisons des rejets dans l’ordre des entrées. Le code appelant peut ainsi examiner pourquoi chaque tentative a échoué, même si les échecs sont arrivés dans un ordre différent.

Comparer les règles de décision

• all : toutes les valeurs sont nécessaires ; rejet au premier rejet.
• allSettled : toutes les issues sont nécessaires ; attente de tous les objets de résultat.
• race : le premier acquittement décide, y compris en cas d’échec.
• any : la première promesse tenue décide ; rejet uniquement si toutes sont rejetées.

Sans entrée, all et allSettled sont tenues avec []. any est rejetée avec une AggregateError, car aucune réussite n’est possible. race reste en attente, car rien ne peut l’acquitter.

Les quatre sont pris en charge dans les navigateurs actuels et dans Node.js. all et race sont entrées dans ECMAScript en 2015, allSettled en 2020 et any en 2021.

Comparer une paire d’issues

Supposons que les deux opérations commencent maintenant : la première entrée échoue après environ 100 ms, tandis que la seconde est tenue avec « usable » après environ 300 ms. Appliquer chaque combinateur à cette même paire donne des résultats différents :

• All est rejetée vers 100 ms avec l’erreur de la première entrée, car chaque entrée doit réussir.
• AllSettled est tenue vers 300 ms avec un objet de résultat rejeté suivi d’un objet de résultat tenu, en conservant l’ordre des entrées.
• Race est rejetée vers 100 ms, car c’est le premier acquittement.
• Any est tenue vers 300 ms avec « usable », car l’échec précédent ne peut pas fournir de réussite.

All et race sont toutes deux rejetées dans ce cas, mais elles utilisent des règles différentes. Si la première entrée rapide réussissait et que la seconde échouait plus tard, race conserverait sa réussite initiale tandis que all serait rejetée lors de l’échec ultérieur. Choisis en fonction de l’issue nécessaire, et non du délai observé dans un exemple.