Asynchrones JavaScript

Synchroner Code beendet die aktuelle Anweisung, bevor er zur nächsten übergeht. Das JavaScript deiner Seite läuft auf einem Hauptthread, sodass zwei Teile dieses Codes nicht gleichzeitig ausgeführt werden. Das ist leicht nachzuvollziehen, bis eine Anweisung eine Aufgabe startet, deren Ergebnis erst später eintrifft.

Jetzt starten, das Ergebnis später verarbeiten

Eine asynchrone Operation startet jetzt und liefert ihr Ergebnis anschließend über einen Callback oder ein Promise. Der Browser oder Node.js ist die Hostumgebung. Sie übernimmt das Warten, während dein Programm weiterläuft. Timer, Nutzereingaben und das Laden von Bildern funktionieren auf diese Weise.

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

Lies den Aufruf von setTimeout als „Registriere diese Funktion“. Der Aufruf kehrt zurück, ohne 700 ms zu warten. Das aktuelle Skript gibt daher zuerst „Opening“ und „Waiting“ aus. Nach etwa 700 ms kann der Callback laufen und „Ready“ ausgeben. Die genaue Verzögerung hängt auch davon ab, wann der Hauptthread frei wird.

Hier gibt es zwei verschiedene Vorgänge: Die Umgebung überwacht den Timer und JavaScript ruft schließlich die Funktion auf, die das Ergebnis ausgibt. Das Warten überschneidet sich mit anderer Arbeit; der Callback läuft weiterhin auf dem Hauptthread.

Warum eine Seite einfriert

Eine lange synchrone Schleife hält den Thread beschäftigt. Während sie läuft, können Klick-Handler und Timer-Callbacks nicht ausgeführt werden und die Seite kann ihre Anzeige über diesen Thread nicht aktualisieren. Ein registrierter Timer mit null Verzögerung kann die Schleife nicht unterbrechen.

Angenommen, ein Timer wird bereit, während eine Berechnung noch läuft. Die Umgebung reiht seinen Callback in eine Warteschlange ein. Erst das Ende der Berechnung gibt den Thread frei; der Ablauf der Timerfrist allein kann das nicht. Auch ein Callback, der eine weitere lange Berechnung ausführt, kann die Seite einfrieren.

Um die Auswirkung einer Berechnung auf die Reaktionsfähigkeit zu verringern, zerlege sie in kleinere Teile, zwischen denen andere Tasks laufen können, oder lagere geeignete Arbeit an einen Webworker aus, einen separaten Hintergrundthread des Browsers. Setzt du eine große Schleife lediglich in eine async-Funktion, bleibt sie auf dem Hauptthread.

Drei Wege, ein Ergebnis zu erhalten

Mit einem Callback wird die nächste Aktion als Funktion übergeben. Ein Promise steht für ein späteres Ergebnis und lässt dich Handler für Erfolg und Fehler registrieren. Eine async-Funktion arbeitet mit Promises, während await ihre eigene Ausführung an einer klaren Stelle anhalten kann.

Diese Formen bestehen nebeneinander. Ein Timer nimmt weiterhin einen Callback entgegen, auch wenn der umgebende Code Promises nutzt. Eine async-Funktion kann auf ein Promise warten, das ein Callback-Wrapper erzeugt. Wähle den Stil, mit dem sich der Weg des Ergebnisses leicht verfolgen lässt.

Markiere beim Lesen asynchronen Codes zuerst die Anweisungen, die während des aktuellen Aufrufs laufen. Markiere danach die Funktionen, die für später registriert werden. Eine Zeile innerhalb eines registrierten Callbacks läuft nicht schon deshalb, weil die Ausführung die Zeile erreicht hat, die diese Funktion erstellt.

Die Ereignisschleife koordiniert ausführungsbereite Aufgaben. Um die Ausgabe vorherzusagen, halte drei Dinge auseinander: die jetzt laufenden Funktionen, als Tasks wartende Callbacks und als Microtasks wartende Promise-bezogene Aufgaben.

Verfolge Stapel und Warteschlangen

Der Aufrufstapel enthält aktive Funktionsaufrufe. Beim Aufruf einer Funktion wird ein Stapelrahmen daraufgelegt; bei der Rückkehr wird er entfernt. Die aktuelle Funktion läuft, bis sie zurückkehrt oder eine andere Funktion aufruft.

Ein Task kann ein Skript, ein Timer-Callback oder ein Klick-Handler sein. Tasks laufen einzeln. Browser können mehrere Task-Warteschlangen haben. Gehe deshalb nicht davon aus, dass alle Aufgabenquellen eine einzige gemeinsame Warteschlange nach dem Prinzip „zuerst hinein, zuerst heraus“ nutzen.

Die Microtask-Warteschlange enthält Promise-Handler aus then, catch und finally, Fortsetzungen nach await und an queueMicrotask übergebene Callbacks. An einem Microtask-Prüfpunkt nach der aktuellen Arbeit wird die Warteschlange vor dem nächsten Task geleert. Auch Microtasks, die währenddessen hinzukommen, laufen vor dem nächsten Task.

Verfolge ein Skript

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

1. Das Skript gibt „begin“ aus.
2. Es registriert einen Timer-Callback; es ruft ihn nicht auf.
3. Es reiht den Handler des erfüllten Promises als Microtask ein.
4. Es gibt „finish“ aus und beendet die aktuelle Arbeit.
5. Der Microtask gibt „promise“ aus.
6. Der Timer-Task gibt „timer“ aus.

Auch ein bereits erfülltes Promise plant seinen Handler für später ein. Auch eine Verzögerung von 0 ms plant einen Timer-Task ein.

Berücksichtige unterwegs hinzugefügte Aufgaben

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

Das Skript gibt „now“ aus. Die Microtask-Warteschlange enthält zunächst den ersten Promise-Handler und dann den queueMicrotask-Callback. Wenn der erste Handler „first“ ausgibt und zurückkehrt, macht er den nächsten Promise-Handler bereit. Dieser neue Handler wird am Ende der Warteschlange eingereiht. Die restliche Ausgabe lautet „second“, dann „third“.

Vollständige Ausführung und Reaktionsfähigkeit

Sobald ein Task oder Microtask beginnt, kann asynchron eingereihte Arbeit ihn nicht unterbrechen. Dieses Run-to-Completion-Prinzip lässt dich eine lokale Änderung nachvollziehen, ohne dass ein Timer plötzlich mitten in die Funktion eingreift.

Nach den Microtasks kann der Browser bei einer Gelegenheit zum Rendern den Bildschirm aktualisieren. Er muss nicht nach jedem Task neu zeichnen. Ein endloser Strom von Microtasks kann sowohl spätere Tasks als auch das Rendern verhindern: Jeder neue Microtask hält das aktuelle Leeren der Warteschlange aufrecht. Wenn du Arbeit an einen Microtask verschiebst, ist daher nicht garantiert, dass die Seite Gelegenheit erhält zu reagieren.

Schreibe für eine Ablaufverfolgung zuerst die unmittelbare Ausgabe auf, leere die Microtask-Warteschlange der Reihe nach und gehe erst dann zu bereiten Timer-Tasks über. Füge neu eingeplante Arbeit der passenden Warteschlange hinzu, sobald der Code sie tatsächlich einplant.

Verfolge einen Timer, der von einem Microtask erstellt wird

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");

Das Skript registriert den äußeren Timer und den ersten Promise-Handler und gibt dann „script“ aus. Der erste Microtask gibt „job one“ aus und registriert den inneren Timer. Die Rückkehr aus diesem Handler reiht „job two“ ein, was ebenfalls vor einem Timer-Task läuft. Die Ausgabe endet mit „outer timer“, dann „inner timer“: Beide Timer haben dieselbe Verzögerung und der äußere wurde zuerst registriert.

Wird ein Timer während eines Microtasks erstellt, macht das seinen Callback nicht zu einem Microtask. Ordne die Aufgabe anhand der API ein, die sie entgegennimmt und einplant, und füge sie dann der passenden Warteschlange hinzu.

Timer planen Callbacks für später ein. Sie messen eine Verzögerung in Millisekunden: 1000 ms sind 1 s. Die Verzögerung legt fest, ab wann ein Callback ausführungsbereit werden kann; andere Aufgaben und Beschränkungen des Browsers können seine Ausführung weiter verzögern.

Einen Aufruf einplanen und abbrechen

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

Zusätzliche Argumente nach der Verzögerung werden an den Callback übergeben. Eine fehlende Verzögerung zählt als 0. Speichere die zurückgegebene Timerkennung, falls du den Timer abbrechen musst. Browser geben eine numerische Kennung zurück; Node.js gibt ein Timeout-Objekt zurück. Beide funktionieren mit clearTimeout. Das Abbrechen eines abgelaufenen oder nicht existierenden Timers hat keine Wirkung.

Übergib eine Funktion: setTimeout(remind, 2000, "promises"). Schreibst du setTimeout(remind("promises"), 2000), wird remind sofort aufgerufen und sein Rückgabewert an den Timer übergeben. Eine Pfeilfunktion ist eine weitere Möglichkeit, einen Aufruf mit Argumenten zu verzögern: setTimeout(() => remind("promises"), 2000).

Mit einem Intervalltimer oder einem weiteren Timeout wiederholen

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

Der erste Durchlauf erfolgt nach etwa einer Sekunde. Der dritte Callback stoppt weitere Durchläufe. Bewahre die Kennung des Intervalltimers auf und verwende clearInterval, wenn die wiederholte Aufgabe enden soll.

Stattdessen kann ein Callback seinen nächsten Timeout selbst einplanen. Ruft er setTimeout am Ende seiner synchronen Arbeit auf, beginnt die nächste Verzögerung nach dieser Arbeit. Das ergibt eine Pause zwischen den Ausführungen und erlaubt jedes Mal eine andere Verzögerung. Ein Intervalltimer fordert Ausführungen nach einem festen Zeitplan an; bei langsamer Arbeit kann wenig Pause bleiben. Startet ein Durchlauf asynchrone Arbeit, warte auch auf deren Ende, bevor du den nächsten Durchlauf einplanst, falls eine Überschneidung problematisch wäre.

Grenzen der zeitlichen Steuerung

Ein beschäftigter Thread verzögert bereite Callbacks. Browser drosseln Timer in Hintergrund-Tabs außerdem oft auf etwa eine Prüfung pro Sekunde oder seltener. Ist die Verschachtelungstiefe von Timern größer als fünf, hebt die HTML-Timerregel Verzögerungen unter 4 ms auf 4 ms an. Auch bei sehr großen Verzögerungen ist Vorsicht nötig: Die übliche vorzeichenbehaftete 32-Bit-Grenze liegt bei 2147483647 ms, etwa 24,8 Tagen; Werte darüber können einen Überlauf verursachen und viel früher auslösen.

Den richtigen Schleifenwert erfassen

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

Jeder let-Schleifendurchlauf hat eine eigene Bindung, daher lautet die Ausgabe „1“, „2“, „3“. Mit var teilen sich alle Callbacks dieselbe Variable. Nach der Schleife steht sie auf 4, sodass jeder „4“ ausgibt.

Auf eine ruhige Phase warten

Debouncing bricht bei jedem neuen Ereignis einen ausstehenden Timeout ab. Ein neuer Timeout plant die Aktion dann nach dem letzten Ereignis ein. Bei einer Verzögerung von 300 ms verschiebt eine Eingabe alle 100 ms die Aktion immer weiter; sie läuft etwa 300 ms nach Ende der Eingabe. Speichere die Kennung außerhalb des Handlers, damit der nächste Aufruf den vorherigen Timer abbrechen kann.

Einen Debounce-Handler erstellen

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

Diese Aufrufe finden im selben Skript statt. Jeder bricht den vorherigen Timer ab, bevor er die Kennung ersetzt. Daher wird nach etwa 300 ms nur „Saved: note“ ausgegeben. Der letzte Callback erfasst den Textparameter dieses Aufrufs. Die Kennung liegt außerhalb der Funktion, damit jeder Aufruf den zuvor eingeplanten Timeout abbrechen kann.

Würde die Kennung innerhalb jedes Aufrufs neu deklariert, hätte der nächste Aufruf keinen Zugriff auf die Kennung des vorherigen Timers. Würde ein Handler einen Timer einplanen, ohne den vorherigen abzubrechen, würden alle drei Meldungen ausgegeben. Debouncing benötigt sowohl die gemeinsam genutzte Kennung als auch den Abbruch vor dem Ersetzen.

Ein Callback ist eine Funktion, die du an eine andere Funktion übergibst, damit diese sie aufruft. Der Code des Callbacks beschreibt, was mit einem Ergebnis geschehen soll. Ob er während des aktuellen Aufrufs oder später läuft, hängt von der API ab, die ihn entgegennimmt.

Ein Callback kann synchron laufen

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

map ruft seinen Callback für jedes Element auf, bevor es das neue Array zurückgibt. Das Ergebnis ist [4, 10]. Die Pfeilfunktion ist ein Callback, aber dieser Code plant keine spätere Arbeit ein. Du kannst doubled in der nächsten Zeile verwenden, weil das Array bereits vollständig ist.

Ein verzögertes Ergebnis bereitstellen

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

prepareLabel startet einen Timer und kehrt zurück. Das Skript gibt „Label requested“ aus. Nach etwa 200 ms erstellt der Timer-Callback die Beschriftung und ruft den übergebenen Callback auf, der „Label: Mira“ ausgibt. Die Operation entscheidet, wann sie aufruft; der aufrufende Code entscheidet, was mit dem Ergebnis geschieht.

Abhängige Arbeit dort platzieren, wo das Ergebnis vorliegt

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

Dies gibt undefined aus: Die Zuweisung ist noch nicht erfolgt. Verschiebe console.log(value) in den Callback. Würdest du vor dem Lesen von label einen längeren, unabhängigen Timeout einfügen, würdest du nur abschätzen, wann das Ergebnis verfügbar sein wird; mit dem Ergebnis-Callback knüpfst du die Arbeit an den tatsächlichen Abschluss.

Auch ein return innerhalb eines verzögerten Callbacks kann den Wert nicht aus der äußeren Funktion zurückgeben. Der äußere Aufruf ist bereits beendet. Im Beispiel würde return "Label: Mira" innerhalb des Timer-Callbacks an die Timerverwaltung zurückgeben; der Aufrufer von prepareLabel erhielte die verzögerte Beschriftung nicht.

Die nächste Aktion übergeben, ohne sie aufzurufen

Ein benannter Callback funktioniert ebenfalls:

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

showLabel ist der Funktionswert. showLabel() würde die Funktion sofort ohne Beschriftung aufrufen und stattdessen ihren Rückgabewert übergeben. Nutze einen Pfeilfunktions-Wrapper, wenn die spätere Aktion ein bestimmtes Argument oder mehrere Anweisungen benötigt.

Bei zwei abhängigen asynchronen Schritten startest du den zweiten im Callback des ersten Schritts. Übergib zum Beispiel nach dem Erhalt eines Nutzers diesen Nutzer an eine Operation, die seine Einstellungen vorbereitet. Würdest du beide außerhalb ihrer Callbacks starten, entstünde diese Abhängigkeit nicht.

Die empfangende Funktion steuert, wie oft sie den Callback aufruft. Manche Callbacks, etwa Event-Handler, werden absichtlich häufig aufgerufen. Eine Operation mit einem Ergebnis sollte ihren Ergebnis-Callback einmal aufrufen. Ein Promise gibt einer solchen Operation ein Ergebnis, das nur einmal abgeschlossen werden kann.

Eine asynchrone Operation kann sowohl fehlschlagen als auch erfolgreich sein. Eine Callback-API braucht eine klare Möglichkeit, jedes Ergebnis zu melden, und eine klare Stelle, an der der aufrufende Code es behandelt.

Prüfe zuerst den Fehler

Die Error-first-Konvention nutzt callback(err, result). Ein erfolgreicher Aufruf übergibt null für den Fehler. Ein fehlgeschlagener Aufruf übergibt ein Error-Objekt und liefert kein nutzbares Ergebnis.

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);
});

Die bereitstellende Funktion stoppt, nachdem sie eine ungültige Kennung gemeldet hat, und kann daher nicht auch Erfolg melden. Der verarbeitende Code stoppt, nachdem er einen Fehler erkannt hat, und kann daher nicht versuchen, label.text aus einem fehlenden Ergebnis zu lesen. Mit der Kennung 4 lautet die Ausgabe „Draft“. Mit der Kennung 0 lautet sie „Invalid label id“.

Beide return-Anweisungen sind wichtig. Ohne das return im verarbeitenden Code könnte ein zweiter Fehler über einen nicht definierten Wert die hilfreiche ursprüngliche Meldung verdecken. Ohne das return in der bereitstellenden Funktion könnte eine Operation den Callback zweimal aufrufen. Bei einer API mit einem Ergebnis gilt: Melde genau ein Ergebnis.

Ein umgebendes try ist bereits beendet

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

Das try plant den Timer ein und endet. Der Callback löst in einem späteren Task eine Ausnahme aus, wenn dieses try nicht mehr aktiv ist. Daher wird „Handled“ nicht ausgegeben. Fange eine mögliche Ausnahme innerhalb des Callbacks ab oder gib einen Fehler über den Fehlerparameter der API weiter. Ein späterer Promise-Wrapper muss diesen Callback-Fehler ausdrücklich in eine Ablehnung umwandeln.

Abhängige Schritte lesbar halten

Callback-Code wird schwer nachvollziehbar, wenn jeder nächste Schritt innerhalb des Callbacks des vorherigen steht. Das Lesen eines Profils, dann seiner Projekte und dann der Aufgaben eines Projekts erzeugt mehrere Verschachtelungsebenen. Jede Operation benötigt außerdem eine eigene Fehlerprüfung. Dieses Muster wird oft Callback-Hölle oder Pyramide des Verderbens genannt.

Benannte Funktionen können diesen Schritten aussagekräftige Namen geben und die sichtbare Verschachtelung verringern. Melde Fehler durchgehend einheitlich: Ein späterer Schritt kann ebenso fehlschlagen wie der erste. Promises und async-Funktionen bieten eine flachere Möglichkeit, dieselbe Abfolge auszudrücken und dabei die Weitergabe von Fehlern zusammenhängend zu halten.

Nicht alle Callback-APIs verwenden einen Fehlerparameter. Manche Browserobjekte haben getrennte Ereignisse für Erfolg und Fehler. Setze bei einem Bild die Handler onload und onerror, bevor du src zuweist, damit beide Ergebnisse beim Start des Ladevorgangs einen Handler haben. Lies den Vertrag der API, bevor du annimmst, dass ein Parameter namens err existiert.

Ein Promise steht für ein späteres Ergebnis. Eine Funktion kann es sofort zurückgeben, sodass der aufrufende Code Aufgaben mit einem Ergebnis verbinden kann, das noch nicht vorliegt.

Zustände und Abschluss

Ein Promise ist ausstehend, bis es mit einem Wert erfüllt oder mit einem Grund abgelehnt wird. Erfüllte und abgelehnte Promises sind abgeschlossen; ihr Ergebnis kann sich nicht mehr ändern.

„Aufgelöst“ hat eine genauere Bedeutung als das umgangssprachliche Synonym für „erfolgreich“. Ein mit einem anderen ausstehenden Promise aufgelöstes Promise übernimmt dessen späteres Ergebnis, auch eine Ablehnung. Es kann daher aufgelöst und zugleich noch ausstehend sein.

Ein Promise um eine Operation erstellen

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

new Promise ruft seine Executor-Funktion sofort auf. Diese registriert einen Timer. Wenn der Timer resolve aufruft, wird das Promise mit undefined erfüllt und der registrierte then-Handler läuft später als Microtask. Diese Hilfsfunktion bietet eine wiederverwendbare Pause, ohne den Thread zu blockieren.

Eine Executor-Funktion kann sowohl resolve als auch reject erhalten:

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));

Für diese positiven Mengen wird der erste Aufruf mit 5 erfüllt und der zweite mit „Not enough stock“ abgelehnt. Das Promise lässt den aufrufenden Code beide möglichen Ergebnisse über dasselbe zurückgegebene Objekt erhalten.

Das Erstellen startet die Executor-Funktion

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

Die Ausgabe lautet „before“, „creating“, „after“, „12“. Das Registrieren von then startet diese Executor-Funktion nicht. Der Konstruktor hat sie bereits ausgeführt; then registriert Code zur Verarbeitung ihres Ergebnisses.

Nur der erste Aufruf von resolve oder reject entscheidet über das weitere Schicksal des Promises. Spätere Aufrufe können diese Entscheidung nicht ersetzen. Das gilt auch, wenn die erste Auflösung ein anderes Promise übernimmt, dessen Ergebnis noch aussteht. Der Aufruf von resolve stoppt den gewöhnlichen Code der Executor-Funktion nicht. Nutze daher return, wenn ein Ausführungszweig enden soll.

Jeden Ausführungspfad korrekt abschließen

Eine synchron in der Executor-Funktion ausgelöste Ausnahme lehnt das Promise automatisch ab. Eine Ausnahme in einem späteren Timer-Callback liegt außerhalb dieses Aufrufs und wird nicht in eine Ablehnung umgewandelt. Nutze dort reject(new Error("...")); andernfalls kann der Fehler unbehandelt bleiben, während das Promise ausstehend bleibt.

Ein Ausführungszweig, der keine der beiden Funktionen aufruft, kann den aufrufenden Code dauerhaft warten lassen. Nutze Error-Objekte als Ablehnungsgründe, damit Handler eine Meldung lesen und Debugging-Werkzeuge nützliche Fehlerinformationen anzeigen können.

Promise.resolve(value) erstellt für einen gewöhnlichen Wert ein erfülltes Promise oder übernimmt das Ergebnis eines anderen Promises. Promise.reject(error) erstellt ein abgelehntes Promise. Registriere bei letzterem eine Behandlung für die Ablehnung.

Ein übernommenes Ergebnis verfolgen

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));

Die innere Executor-Funktion startet ihren Timer während der Erstellung. Die äußere Executor-Funktion löst dann das äußere Promise mit dem inneren auf und bindet es damit an dessen späteres Ergebnis. Der spätere Aufruf von reject kann diese Entscheidung nicht ersetzen. Das äußere Promise bleibt ausstehend, bis das innere erfüllt wird, und sein Handler gibt nach etwa 250 ms „packed“ aus.

Würde das innere Promise stattdessen abgelehnt, würde das äußere diese Ablehnung übernehmen. Der erste Aufruf von resolve hat ausgewählt, welchem Ergebnis gefolgt wird; er hat keinen Erfolg garantiert. Diese Unterscheidung ist wichtig, wenn ein Wrapper ein anderes Promise weiterreicht, statt einen fertigen gewöhnlichen Wert bereitzustellen.

Promise-Handler verbinden Code mit einem Erfolg, einem Fehler oder beiden möglichen Ergebnissen. Jede Registrierung eines Handlers gibt außerdem ein neues Promise zurück, sodass der nächste Code auf dem aufbauen kann, was der Handler liefert.

Den passenden Handler für das Ergebnis nutzen

p.then(onFulfilled) erhält den Wert eines erfüllten Promises. p.catch(onRejected) erhält einen Ablehnungsgrund; es ist eine Kurzschreibweise für p.then(undefined, onRejected). Handler sind Funktionen und laufen als Microtasks, auch wenn p bereits abgeschlossen ist.

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

Das Skript gibt „registered“ aus, bevor der Handler „draft“ ausgibt. Ein sofort verfügbarer Wert macht den Handler nicht synchron.

Es ist entscheidend, eine Funktion zu übergeben. then(console.log("draft")) gibt „draft“ während der Registrierung aus und übergibt undefined als Handler. Nutze then(() => console.log("draft")), wenn die Meldung später ausgegeben werden soll. then(console.log) übergibt die Ausgabefunktion selbst, sodass sie den Wert erhält.

Nach Erfolg oder Fehler aufräumen

finally eignet sich dazu, nach Abschluss einer Operation eine Ladeanzeige auszublenden oder eine Schaltfläche zu aktivieren. Sein Callback erhält weder einen Wert noch einen Fehler als Argument.

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

Die Ausgabe lautet „Cleanup“, dann „4“. Gibt der Aufräum-Callback einen gewöhnlichen Wert zurück, ersetzt dieser die 4 nicht. Ein zurückgegebenes Promise kann den nächsten Schritt verzögern, bis das Aufräumen beendet ist. Löst der Aufräum-Callback eine Ausnahme aus oder gibt er ein abgelehntes Promise zurück, wird dieser Fehler zum neuen Ergebnis der Kette.

Ein typischer Ablauf auf einer Seite setzt vor dem Start einen Ladezustand, verarbeitet ein Ergebnis in then, meldet einen Fehler in catch und setzt den Ladezustand in finally zurück. Platziere Arbeit, die vom Ergebnis abhängt, in then oder catch, wo das benötigte Argument vorliegt.

Getrennte Abonnements und eine Kette unterscheiden

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

Dies sind zwei getrennte Abonnements von p. Beide erhalten 4. Das Ergebnis der Multiplikation gehört zum neuen Promise, das das erste then zurückgibt; es verändert weder p noch liefert es einen Wert an das zweite Abonnement.

Verbinde sie, um den veränderten Wert weiterzugeben:

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

Nun erhält der letzte Handler 8. Der Unterschied liegt darin, an welchem Promise der jeweilige Handler registriert ist.

Das zurückgegebene Objekt ist weiterhin ein Promise

In const next = p.then(value => value * 2) ist next ein neues Promise und nicht die Zahl 8. Der Handler kann erst nach dem Ende des umgebenden Skripts laufen und selbst eine verzögerte Aufgabe zurückgeben. Nutze einen weiteren Handler oder await, um den Wert zu erhalten. Wenn du next sofort wie eine Zahl behandelst, geht diese zeitliche Information verloren.

Eine Promise-Kette macht die Ausgabe eines Handlers zur Eingabe des nächsten. Jedes Glied muss den Wert oder das Promise zurückgeben, das die späteren Glieder benötigen.

Werte durch die Kette weitergeben

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

Der erste Handler erhält 3 und gibt 12 zurück. Der zweite erhält 12 und gibt 14 zurück. Der letzte Handler gibt „14“ aus. Ein Ausdrucksrumpf einer Pfeilfunktion gibt seinen Wert automatisch zurück; ein Funktionsrumpf mit geschweiften Klammern benötigt ein ausdrückliches return, um einen Wert weiterzugeben.

Ein Promise für einen abhängigen Schritt zurückgeben

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 liefert nach etwa 100 ms „P4“. Der nächste Handler gibt das Promise von makeLabel zurück. Die Kette folgt diesem Promise, wartet etwa weitere 200 ms und gibt „Parcel P4“ an den letzten Handler weiter. Der aufrufende Code erhält eine Beschriftung und kein innerhalb des Werts verschachteltes Promise.

Ein unterbrochenes Glied finden

Vergleiche den mittleren Handler mit diesem:

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

Er startet makeLabel, gibt aber nichts zurück. Sein neues Promise wird mit undefined erfüllt, ohne auf die Beschriftung zu warten. Der nächste Handler erhält daher nach dem Schritt für den Code undefined, während die Erstellung der Beschriftung getrennt weiterläuft. Auch Fehler aus dieser getrennten Arbeit werden nicht mehr durch die äußere Kette weitergegeben.

Korrigiere dies mit return makeLabel(code); innerhalb der geschweiften Klammern oder entferne die Klammern, um den Ausdruck zurückzugeben. Dieselbe Regel gilt, wenn ein Handler eine Pause startet: .then(() => wait(200)) wartet; .then(() => { wait(200); }) wartet nicht.

Verschachtelung verringern und benötigte Werte behalten

Ein weiteres then tief innerhalb des ersten Handlers kann erneut eine Verschachtelung wie bei Callbacks erzeugen. Gib das innere Promise zurück und platziere den nächsten Handler auf der äußeren Ebene. So bleiben Zeitablauf, Werte und Fehler auf einem gemeinsamen Pfad.

Jeder Handler hat seinen eigenen lokalen Gültigkeitsbereich. Benötigt ein späterer Schritt sowohl den Code als auch die Beschriftung, gib ein Objekt zurück, das beide enthält:

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

Dieser kleine innere Handler erstellt den kombinierten Wert und wird zurückgegeben, sodass er mit der Kette verbunden bleibt. Eine async-Funktion kann beide Ergebnisse ebenfalls in gewöhnlichen lokalen Variablen speichern.

Eine Ablehnung überspringt spätere Erfüllungshandler, bis ein Ablehnungshandler erreicht wird. Ein abschließendes catch kann Fehler aus allen vorherigen verbundenen Schritten behandeln. Abhängige Arbeit gehört in diese Abfolge; unabhängige Arbeit kann mit Promise.all gemeinsam gestartet werden.

Eine async-Funktion gibt immer ein Promise zurück. Innerhalb der Funktion hält await sie an, bis ein Wert verfügbar ist, sodass sich abhängige Schritte von oben nach unten lesen lassen.

Einen Wert über ein Promise zurückgeben

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

Der Aufruf von getCount() liefert ein Promise, das mit 6 erfüllt wird. Der Handler gibt „6“ aus. Löst die Funktion eine Ausnahme aus, wird das zurückgegebene Promise abgelehnt. Gibt sie ein anderes Promise zurück, übernimmt die async-Funktion dessen späteres Ergebnis.

Du kannst eine async-Funktion mit async function name(), als asynchrone Pfeilfunktion wie const name = async () => {} oder als asynchrone Objektmethode deklarieren. Das Verhalten bei der Rückgabe des Promises ist gleich.

Bei await anhalten

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");

Die Ausgabe beginnt mit „Step one“, dann folgt „Caller continues“. Etwa 300 ms später wird „Step two“ ausgegeben. Beim Aufruf der Funktion läuft ihr Rumpf synchron bis zum ersten await. Die Pause gibt die Kontrolle an den aufrufenden Code zurück. Sobald das Promise erfüllt ist, wird der Rest von showSteps über die Microtask-Warteschlange fortgesetzt.

Await hält seine Funktion an, nicht den ganzen Thread. Andere bereite Tasks können während des Wartens laufen. Eine große synchrone Berechnung vor oder nach dem await kann den Thread während ihrer Ausführung weiterhin blockieren.

Einen Wert lesen oder einen Fehler erhalten

Ein erfülltes Promise liefert seinen Wert: const count = await getCount(); setzt count auf 6. Ein abgelehntes Promise löst seinen Grund an der await-Zeile aus. Umgib die erwartete Operation mit try und catch, wenn diese Funktion den Fehler behandeln soll.

await akzeptiert auch gewöhnliche Werte. In const count = await 6; ist das Ergebnis weiterhin 6, aber die Fortsetzung der Funktion wird auf später verschoben. Sie wird nicht synchron, nur weil keine wartende Operation nötig war.

Prüfen, wohin await gehört

Nutze await innerhalb der async-Funktion, deren Rumpf es enthält. Es ist auch auf der obersten Ebene eines JavaScript-Moduls erlaubt. Ein gewöhnlicher Funktionsrumpf darf kein await enthalten; eine äußere async-Funktion macht einen verschachtelten gewöhnlichen Callback nicht asynchron.

Der aufrufende Code erhält weiterhin ein Promise. Um den endgültigen Wert zu nutzen, warte aus einer anderen async-Funktion darauf oder registriere then. Zum Beispiel speichert const total = getCount(); ein Promise und nicht 6.

Ein Event-Handler kann selbst asynchron sein. Der Handler kann auf einen Vorbereitungsschritt warten, bevor er eine Seite aktualisiert. Gib dieser Aktion eine eigene Fehlerbehandlung, denn die Ereignisauslösung wartet nicht auf das vom Handler zurückgegebene Promise. Auf der obersten Ebene eines Programms gibt ein Aufruf wie showSteps().catch(console.error) einem unerwarteten Fehler einen Handler.

Eine Promise-Kette kann zu einer async-Funktion werden, ohne ihre Abhängigkeiten zu verändern. Jedes Ergebnis erhält eine lokale Variable und jeder mit await erwartete Schritt beginnt erst, wenn das benötigte frühere Ergebnis vorliegt.

Handler durch Zuweisungen mit await ersetzen

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);

Das erste await liefert einen Nutzer. Erst dann kann getOrders(user) starten. Nach insgesamt etwa 300 ms gibt die Funktion „Nia: 2 orders“ aus. Sowohl user als auch orders liegen für diese letzte Zeile im Gültigkeitsbereich. In einer Kette würde der Parameter jedes Handlers zu einem getrennten lokalen Gültigkeitsbereich gehören.

Die entsprechende Kette würde getOrders(user) aus dem ersten Handler zurückgeben. Das Umschreiben mit await macht dieses Warten sichtbar und erhält zugleich die Reihenfolge. Ein abschließendes catch der Kette wird zu einem try/catch um die erwarteten Schritte; finally wird zu einem Aufräumblock.

Eine Callback-API in eine Promise-API umwandeln

Wenn du einem Wrapper async hinzufügst, wird der verzögerte Wert einer Callback-API nicht zu dessen Rückgabewert. Verbinde den Callback mit dem Abschluss des Promises:

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);
    });
  });
}

Innerhalb einer async-Funktion liefert const tag = await readTagAsync(8); „Tag 8“. Ein Aufruf mit 0 löst stattdessen bei await „Invalid tag“ aus. Bei Erfolg wird das Promise des Wrappers aufgelöst, bei einem Fehler abgelehnt. Der Adapter ändert, wie das Ergebnis bereitgestellt wird, nicht was die zugrunde liegende Operation tut.

Diese Umwandlung heißt Promisifizierung. Für gewöhnliche Error-first-APIs mit einem Ergebnis stellt Node.js außerdem util.promisify bereit, und viele eingebaute Module haben bereits Promise-basierte Varianten wie fs/promises.

Einen klaren Pfad beibehalten

Mit einer Hilfsfunktion wait, die ein Promise zurückgibt, werden Timer zu Pausen. Eine asynchrone Schleife kann einen Schritt ausgeben, auf die Pause warten und dann den nächsten Schleifendurchlauf beginnen. Mit Callbacks müsste der nächste Schritt innerhalb des vorherigen Callbacks eingeplant werden.

Promises, Ketten und async-Funktionen arbeiten zusammen: Eine async-Funktion kann auf eine Kette warten und der aufrufende Code kann then am zurückgegebenen Promise einer async-Funktion registrieren. Nutze innerhalb einer Funktion die Form, mit der Abhängigkeiten und Fehlerbehandlung leicht nachzuvollziehen sind. Ein zusätzlicher Promise-Konstruktor ist nützlich, um einen Callback anzupassen, aber auf vorhandene Operationen, die Promises zurückgeben, kann direkt mit await gewartet werden.

Asynchroner Code kann synchron aussehen und dennoch Promises zwischen Funktionen weitergeben. Viele Fehler entstehen, weil der spätere Wert zu früh gelesen wird oder weil man annimmt, eine Hilfsfunktion warte auf Callbacks, die sie ignoriert.

Vor der Verwendung auf den Wert warten

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

Dies gibt „54“ aus. Ohne await würde quantity ein Promise enthalten. Die Multiplikation dieses Promises mit 3 ergibt NaN und keine verzögerte Berechnung, die sich automatisch aktualisiert.

Eine Bedingung enthält dieselbe Falle. Eine asynchrone Prüfung, die false zurückgibt, gibt dennoch ein Promise-Objekt zurück, und Objekte sind truthy. Nutze if (await allowed()) innerhalb einer async-Funktion, wenn der Ausführungszweig vom späteren booleschen Wert abhängt. if (allowed()) prüft das Objekt selbst.

forEach sammelt keine Callback-Promises

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“ erscheint vor den Beschriftungen. forEach ruft beide Callbacks auf, ignoriert deren zurückgegebene Promises und beendet seine eigene synchrone Iteration. Selbst await ids.forEach(...) würde auf undefined warten, nicht auf die Arbeit der Callbacks. Ein Fehler innerhalb dieser ignorierten Promises liegt ebenfalls außerhalb des von labelAll zurückgegebenen Promises.

Schreibe für eine Verarbeitung in Reihenfolge eine gewöhnliche Schleife:

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

Hier ist labelOne eine Operation, die ein Promise zurückgibt. Jeder Eintrag beginnt, nachdem der vorherige abgeschlossen ist. Verwende für unabhängige Einträge vor der letzten Ausgabe await Promise.all(ids.map(id => labelOne(id)));. map sammelt die zurückgegebenen Promises und Promise.all gibt dem aufrufenden Code ein Promise für deren Abschluss.

Unabhängigkeit und Syntax auseinanderhalten

Wartest du sofort auf jede Operation, laufen die Wartezeiten nacheinander ab. Für unabhängige Wartezeiten von 1000, 2000 und 1500 ms dauert das etwa 4500 ms. Startest du alle drei und kombinierst sie, dauert es etwa 2000 ms. Ein Schritt, der ein früheres Ergebnis benötigt, muss weiterhin darauf warten.

Fehler verbunden halten

Eine verschachtelte Funktion benötigt ihr eigenes Schlüsselwort async, um await zu nutzen. Dieses Schlüsselwort allein bringt den aufrufenden Code aber nicht dazu, auf das Ergebnis zu warten. Prüfe beide Seiten: Gibt der Callback ein Promise zurück und nutzt der aufrufende Code es?

Für Arbeit, die absichtlich gestartet wird, ohne auf ihren Abschluss zu warten, registriere einen Ablehnungshandler wie backgroundTask().catch(console.error). Prüfe auch Rückgaben in async-Wrappern: async function prepare() { await wait(100); } wird mit undefined erfüllt. Auf einen Schritt zu warten und sein Ergebnis zurückzugeben sind getrennte Entscheidungen.

Ergebnisse der korrigierten Gruppe zurückgeben

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(", ")));

Jeder map-Callback gibt ein Promise zurück und map speichert diese Promises in einem Array. Promise.all wartet auf beide und liefert ["Item 6", "Item 2"]. Die Funktion prepareAll gibt dieses Array über ihr eigenes Promise zurück, sodass der aufrufende Code nach Abschluss der Gruppe „Item 6, Item 2“ ausgibt.

Würdest du die Rückgabe von prepareAll entfernen, würde die Funktion weiterhin auf die Gruppe warten, aber der aufrufende Code erhielte undefined. Würdest du map durch forEach ersetzen, ginge das Array der Promises verloren. Prüfe beim Korrigieren einer Aktion mit mehreren Einträgen das Sammeln, Warten und Zurückgeben getrennt.

Die Ablehnung eines Promises folgt der verbundenen Kette, bis ein Ablehnungshandler sie behandelt. Wenn du verstehst, was dieser Handler zurückgibt, weißt du, ob die Kette nach dem Fehler fortgesetzt wird oder weiterhin fehlschlägt.

Eine Ablehnung an Erfolgshandlern vorbei verfolgen

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));

Die Ausnahme lehnt das neue Promise ab, das das erste then zurückgibt. Der nächste Erfüllungshandler wird übersprungen, sodass „Unused“ nie ausgegeben wird. Das catch gibt „Count rejected“ aus und liefert 2 zurück. Diese Rückgabe erfüllt das nächste Glied, sodass der letzte Handler „Using 2“ ausgibt.

Ein ausdrücklich abgelehntes Promise und eine innerhalb eines Handlers ausgelöste Ausnahme gelangen auf denselben Ablehnungspfad. Deshalb kann ein abschließendes catch Fehler aus mehreren vorherigen verbundenen Schritten behandeln.

Zwischen Fortsetzung und Weitergabe wählen

Ein Ablehnungshandler, der einen Wert zurückgibt, setzt die Verarbeitung nach dem Fehler mit diesem Wert fort. Gibt er nichts zurück, wird die Verarbeitung ebenfalls fortgesetzt, aber mit undefined. Einen Fehler zu protokollieren ist daher nicht dasselbe, wie die Kette abgelehnt zu lassen:

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

Der letzte Handler erhält undefined. Benötigt späterer Code eine tatsächliche Beschriftung, ist diese stille Fortsetzung wahrscheinlich falsch. Gib einen nutzbaren Ersatzwert zurück oder löse den Fehler erneut aus.

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

Wird diese Funktion in catch verwendet, protokolliert sie den Fehler und das nächste Promise bleibt mit demselben Grund abgelehnt. Ein späterer Aufrufer in der Kette kann entscheiden, was zu tun ist.

Den Handler nach der geschützten Arbeit platzieren

Ein catch behandelt Fehler oberhalb seiner Position. Setzt es die Verarbeitung nach einem Fehler fort, laufen spätere Schritte normal weiter und deren neue Fehler benötigen einen späteren Handler. Ein Handler in der Mitte kann keine Fehler abfangen, die noch nicht aufgetreten sind.

Es gibt außerdem einen wichtigen Unterschied zwischen .then(success, failure) und .then(success).catch(failure). Die beiden Handler in einem then reagieren auf das Ergebnis des eingehenden Promises. Sein Fehlerhandler fängt keine Ausnahme ab, die sein eigener Erfolgshandler auslöst. Dieser Fehler gehört zum neuen Promise, das der Aufruf zurückgibt, sodass ein nachfolgendes catch benötigt wird.

Nützliche Fehler erhalten

Lehne mit Error-Objekten ab, damit Handler err.message und err.name lesen können. Eine Zeichenkette auszulösen oder als Ablehnungsgrund zu verwenden ist erlaubt, aber Code, der die Felder eines Error-Objekts erwartet, erhält sie nicht. Bewahre beim Weitergeben eines Fehlers den ursprünglichen Fehler, sofern zusätzlicher Kontext dem Aufrufer nicht hilft zu verstehen, welche Operation fehlgeschlagen ist.

try, catch und finally ermöglichen einer async-Funktion, Fehler dort zu behandeln, wo sie auf Ergebnisse wartet. Nutze diese Struktur, um Ergebnisverarbeitung, Fortsetzung nach Fehlern und Aufräumen zusammenzuhalten.

Ein Fehler überträgt die Kontrolle

Ein Error-Objekt beschreibt einen Fehler. new Error("Label missing") hat die Meldung „Label missing“ und den Namen „Error“; Debugging-Werkzeuge können auch seinen Stacktrace anzeigen. Eingebaute Fehler haben Typen wie TypeError.

throw stoppt an dieser Stelle den normalen Ablauf und überträgt die Kontrolle an das nächstgelegene passende catch. Code nach der Behandlung kann weiterhin laufen, wenn die Funktion ihren eigenen Fehler abfängt. Löse Error-Objekte aus, damit spätere Handler nützliche Felder erhalten.

Innerhalb des geschützten Blocks warten

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);

Das abgelehnte Promise löst an der await-Zeile eine Ausnahme aus. Der Rest von try wird übersprungen. Die Ausgabe lautet „Working“, „Failed: Device busy“, dann „Controls enabled“. Eine erfolgreiche Operation würde „Complete“ erreichen und trotzdem denselben Aufräumcode ausführen.

Nutze finally für eine Ladeanzeige, den Zustand einer Schaltfläche oder eine andere Ressource, die nach beiden möglichen Ergebnissen zurückgesetzt werden muss. Der Block läuft auch, wenn try oder catch eine return-Anweisung enthält. Vermeide, dass der Aufräumcode eine Ausnahme auslöst, sofern dieser neue Fehler nicht absichtlich das frühere Ergebnis ersetzen soll. Ein return in finally kann eine frühere Rückgabe oder Ausnahme überschreiben. Vermeide es daher beim gewöhnlichen Aufräumen.

Ein Promise zurückzugeben ist hier etwas anderes als darauf zu warten

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

Dies gibt „light“ aus. Die Funktion wartet innerhalb von try, sodass die Ablehnung das lokale catch erreicht. Entfernst du await, wird das abgelehnte Promise sofort zurückgegeben; die Funktion übernimmt seine Ablehnung, aber das lokale catch behandelt dieses spätere Ergebnis nicht. Der aufrufende Code müsste es abfangen.

Für jeden Fehler einen passenden Fehlerbehandlungsbereich wählen

Ein try kann eine Gruppe von awaits abdecken, wenn die gesamte Aktion bei einem Fehler in einem beliebigen Schritt stoppen soll. Gib einem optionalen Schritt einen kleineren Fehlerbehandlungsbereich, wenn er unabhängig fortgesetzt werden kann. Zum Beispiel nutzt const settings = await loadSettings().catch(() => ({ theme: "light" })); ein Standardobjekt und fährt fort.

Eine innerhalb von try deklarierte Variable hat Blockgültigkeitsbereich. Benötigt Code nach dem Block sie, deklariere let result; vor try oder erledige die vom Ergebnis abhängige Arbeit innerhalb von try. Verschiebe einen Wert nicht allein deshalb aus seinem Gültigkeitsbereich, um eine abschließende Ausgabe an einer bevorzugten Stelle zu behalten.

Kann die aktuelle Funktion die Verarbeitung nicht fortsetzen, lass die Ablehnung den aufrufenden Code erreichen. Fängst du sie nur ab, um sie zu verbergen, kann der aufrufende Code keine sinnvolle Entscheidung treffen.

Eine Aktion braucht einen Fehlerbehandlungsbereich: eine Stelle, die ihren endgültigen Fehler erhält und eine Reaktion auswählt. Ohne diesen Bereich kann ein Promise abgelehnt werden, während niemand sein Ergebnis behandelt.

Den letzten Pfad behandeln

Eine unbehandelte Promise-Ablehnung ist eine Ablehnung, für die bei der Prüfung durch die Hostumgebung noch ein Handler fehlt. Die Behandlung kann mit catch, dem Ablehnungsargument von then oder mit try/catch um await erfolgen. Ein Browser meldet das Problem und kann unhandledrejection auslösen. Node.js beendet das Programm bei unbehandelten Ablehnungen unter seiner normalen Einstellung standardmäßig, sodass eine unbehandelte Ablehnung ein Programm beenden kann.

Eine Aktion wie main() oder ein asynchroner Klick-Handler sollte ihr letztes Promise behandeln. Funktionen auf niedrigerer Ebene können Fehler nach oben weitergeben, aber der Pfad muss an einer Stelle enden, die entscheidet, was zu tun ist. Ein globaler Listener für Ablehnungen kann helfen, übersehene Fehler zu protokollieren; er kann nicht für jede Aktion die beste Fortsetzung wählen.

Ein leeres catch verschluckt den Fehler. Protokolliere technische Einzelheiten mit console.error(err) und zeige eine klare Meldung an, wenn die Aktion des Nutzers fehlgeschlagen ist. Eine Meldung wie „Die Beschriftung konnte nicht gespeichert werden. Versuche es gleich noch einmal.“ zeigt dem Nutzer eine Handlungsmöglichkeit, ohne einen Stacktrace offenzulegen.

Kontext ergänzen, ohne die Ursache zu verlieren

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);
});

Dies gibt „Could not prepare label“ und „Device offline“ aus. Die äußere Meldung benennt die fehlgeschlagene Aktion. Die Eigenschaft cause bewahrt den Fehler auf niedrigerer Ebene für die Diagnose. Die Error-Option für die Fehlerursache ist Teil von ECMAScript 2022.

Eine neue Operation mit begrenzter Anzahl von Versuchen wiederholen

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);
    }
  }
}

Rufe diese Funktion mit einer Funktion auf, die einen neuen Versuch startet, und einer positiven Ganzzahl als Obergrenze. Schlägt task zweimal fehl und ist beim dritten Aufruf erfolgreich, stoppt die Funktion bei einer Grenze von vier beim dritten Aufruf und gibt dessen Wert zurück. Schlagen alle vier Versuche fehl, wird der vierte Fehler erneut ausgelöst. Die Verzögerung tritt nur zwischen den Versuchen auf.

return await hält eine Ablehnung innerhalb dieses try, wo catch einen Wiederholungsversuch starten kann. Würdest du statt einer Aufgabenfunktion ein bereits abgelehntes Promise übergeben, würde die Arbeit nicht erneut gestartet.

Wiederhole eine Operation, wenn ein Fehler vorübergehend sein kann. Nutze eine Rückfalllösung, wenn die Funktion mit Standarddaten arbeiten kann. Brich ab und informiere den Nutzer, wenn die Aktion nicht gelingen kann. Kann eine Funktion auf niedrigerer Ebene diese Entscheidung nicht treffen, bewahre den Fehler und lass den aufrufenden Code entscheiden.

Unabhängige asynchrone Operationen können gleichzeitig warten. Ob du sie gemeinsam startest, hängt davon ab, welche Daten sie benötigen, nicht davon, ob du das Wort async hinzufügst.

Unabhängige Operationen starten, bevor auf alle gewartet wird

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);

Die drei Aufrufe starten, bevor Promise.all wartet. Etwa 2000 ms später enthält das Array ["cover", "pages", "label"]. Würdest du auf jeden Aufruf warten, bevor du den nächsten startest, dauerte es stattdessen etwa 4500 ms. Timerverzögerungen sind Näherungswerte, daher können die tatsächlich verstrichenen Zeiten länger sein.

Hier bedeutet parallel, dass sich Wartezeiten überschneiden. Die Promise-Handler laufen weiterhin einzeln auf dem Hauptthread. Würdest du drei aufwendige synchrone Funktionen innerhalb des Arrays aufrufen, liefen diese Berechnungen nacheinander; Promise.all würde sie nicht auf getrennte Threads verschieben.

Ergebnisse behalten ihre Eingabepositionen

Die Beschriftung wird vor den Seiten fertig, bleibt aber an dritter Stelle im Array. Promise.all behält die Eingabereihenfolge bei, nicht die Abschlussreihenfolge. Mit Destrukturierung kannst du diese Positionen benennen:

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

Nutze diesen Code innerhalb einer async-Funktion. Bei einer Sammlung startet ids.map(id => loadItem(id)) eine Operation pro Kennung, die ein Promise zurückgibt, und übergibt Promise.all das Promise-Array. Warte nicht innerhalb einer Schleife auf jeden Eintrag, wenn alle unabhängig sind und sich überschneiden sollen.

Ein Fehler beendet das gemeinsame Warten

Promise.all wird abgelehnt, sobald eine Eingabe abgelehnt wird. Schlägt ein Teil nach etwa 300 ms fehl, kann ein catch den Grund dann erhalten; es muss nicht auf den am längsten dauernden erfolgreichen Teil warten.

Die anderen Operationen laufen weiter. Ihre Seiteneffekte können weiterhin auftreten, aber das kombinierte Promise wird später nicht mit ihren Werten erfüllt. Dieses Fail-fast-Verhalten ist nützlich, wenn der nächste Schritt jedes Ergebnis benötigt.

Abhängigkeiten beachten und Handler rechtzeitig registrieren

Benötigt eine Operation einen Nutzer, den eine andere erzeugt, ermittle zuerst den Nutzer. Die späteren Aufrufe können nur kombiniert werden, wenn sie voneinander unabhängig sind, sobald der Nutzer vorliegt.

Startest du zwei Promises und wartest getrennt auf sie, überschneiden sich ihre Wartezeiten zwar, aber das zweite kann abgelehnt werden, bevor der Code sein await erreicht. Hat es bei der Prüfung durch die Hostumgebung noch keinen Handler, kann eine unbehandelte Promise-Ablehnung gemeldet werden. Kombinierst du die Promises rechtzeitig mit Promise.all, wird die Behandlung an beiden Eingaben registriert und der aufrufende Code erhält einen Fehlerpfad.

Gewöhnliche Werte sind unter den Eingaben erlaubt und behalten ihre Positionen. Promise.all([]) ist bereits mit einem leeren Array erfüllt. Ein daran registrierter Handler läuft dennoch asynchron.

Der richtige Promise-Kombinator hängt davon ab, was als nützliches Ergebnis zählt. Entscheide, ob du alle Erfolge, alle Ergebnisse, den ersten Abschluss oder den ersten Erfolg benötigst.

Teilergebnisse mit allSettled behalten

Promise.allSettled wartet auf jede Eingabe und gibt Ergebnisdatensätze in Eingabereihenfolge zurück. Ein Erfolg wird zu { status: "fulfilled", value }; ein Fehler wird zu { status: "rejected", reason }. Eine abgelehnte Eingabe lehnt das kombinierte Promise nicht ab.

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);
  }
});

Dies gibt „Map ready“ und „Chart unavailable“ aus. Es eignet sich für unabhängige Bereiche, bei denen ein funktionierender Bereich auch dann nützlich bleibt, wenn ein anderer fehlschlägt. Lies value nur bei einem erfüllten Datensatz und reason bei einem abgelehnten Datensatz.

Mit race den ersten Abschluss entscheiden lassen

Promise.race folgt der ersten Eingabe, die abgeschlossen wird, unabhängig davon, ob sie erfüllt oder abgelehnt wird. Ein Fehler nach 100 ms gewinnt vor einem Erfolg nach 200 ms. Das ist für eine Zeitbegrenzung nützlich:

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));

Der Timeout wird zuerst abgelehnt, daher lautet die Ausgabe „Time limit reached“. Die 600-ms-Operation läuft weiter. Ein solcher Aufruf schließt das kombinierte Promise des aufrufenden Codes ab; er bricht die unterlegenen Operationen nicht ab.

Mit any auf den ersten Erfolg warten

Promise.any ignoriert fehlgeschlagene Eingaben, solange ein Erfolg noch möglich ist. Schlägt eine Operation nach 100 ms fehl und wird eine andere nach 200 ms erfüllt, liefert es den Wert der zweiten. Eine schnellere Ablehnung gewinnt nicht.

Werden alle Eingaben abgelehnt, wird any mit einem AggregateError abgelehnt. Sein Array errors bewahrt die Ablehnungsgründe in Eingabereihenfolge. So kann der aufrufende Code prüfen, warum jeder Versuch fehlgeschlagen ist, selbst wenn die Fehler in einer anderen Reihenfolge eingetroffen sind.

Die Entscheidungsregeln vergleichen

• all: Jeder Wert wird benötigt; bei der ersten Ablehnung ablehnen.
• allSettled: Jedes Ergebnis wird benötigt; auf alle Datensätze warten.
• race: Der erste Abschluss entscheidet, auch bei einem Fehler.
• any: Die erste Erfüllung entscheidet; nur ablehnen, wenn alle ablehnen.

Ohne Eingaben werden all und allSettled mit [] erfüllt. any wird mit AggregateError abgelehnt, weil kein Erfolg möglich ist. race bleibt ausstehend, weil nichts es abschließen kann.

Alle vier werden in aktuellen Browsern und Node.js unterstützt. all und race kamen 2015 zu ECMAScript, allSettled 2020 und any 2021.

Ein Ergebnispaar vergleichen

Angenommen, beide Operationen starten jetzt: Die erste Eingabe schlägt nach etwa 100 ms fehl, während die zweite nach etwa 300 ms mit „usable“ erfüllt wird. Wendet man jeden Kombinator auf dasselbe Paar an, ergeben sich unterschiedliche Ergebnisse:

• All wird nach etwa 100 ms mit dem Fehler der ersten Eingabe abgelehnt, weil jede Eingabe erfolgreich sein muss.
• AllSettled wird nach etwa 300 ms mit einem abgelehnten Datensatz, gefolgt von einem erfüllten Datensatz, erfüllt und behält dabei die Eingabepositionen bei.
• Race wird nach etwa 100 ms abgelehnt, weil dies der erste Abschluss ist.
• Any wird nach etwa 300 ms mit „usable“ erfüllt, weil der frühere Fehler keinen Erfolg liefern kann.

All und race werden in diesem Fall zufällig zum selben Zeitpunkt abgelehnt, folgen aber unterschiedlichen Regeln. Wäre die schnelle erste Eingabe erfolgreich und schlüge die zweite später fehl, behielte race seinen frühen Erfolg, während all beim späteren Fehler abgelehnt würde. Wähle anhand des benötigten Ergebnisses, nicht anhand des zeitlichen Ablaufs eines einzelnen Beispiels.