JavaScript/Objekte/Promise/allSettled

Die Methode Promise.allSettled dient dazu, eine Anzahl gleichzeitig schwebender Promises in einem Promise zu konsolidieren. Außer Promises können auch Thenables und beliebige andere Werte übergeben werden, letztere werden mittels Promise.resolve() in die Verarbeitung aufgenommen.

Die Methode wartet darauf, dass alle beteiligten Promises bzw. Thenables festgelegt werden, und fasst ihre Ergebnisse in einem Array zusammen.

Syntax

   const promise = Promise.allSettled( promises);

Parameter

promises

muss ein iterierbares Objekt sein (beispielsweise ein Array), das beim Durchlaufen die Werte liefert, die konsolidiert werden sollen.

Rückgabe

Ein Promise, das immer fulfilled wird. Sein Wert ist ein Array, das je übergebenem Promise ein Objekt enthält, das den Erfolg dieses Promise wiedergibt. Die Reihenfolge dieser Objekte im Array entspricht der Reihenfolge, wie die Iteration des Aufrufparameters sie geliefert hat.

Eigenschaften

Hinweis: Jedes Promise ist auch ein Thenable!

Die Promise.allSettled-Methode durchläuft die übergebenen Werte mit Hilfe des Iterator-Protokolls. Wenn sie dabei auf einen Thenable-Objekt trifft, registriert sie die erforderlichen Callbacks, um das Ergebnis dieses Thenable zu übernehmen.

Das Ergebnis für ein fulfilled-Promise ist ein Objekt der Form

   { status: "fulfilled", value: resolve-ergebnis }

Für ein rejected-Promise sieht das Objekt so aus

   { status: "rejected", reason: reject-ergebnis }

Andere Werte erhalten ein Objekt der Form

   { status: "fulfilled", value: wert }

Wenn der Aufrufparameter von allSettled keine Werte enthält, wird das zurückgegeben Promise bereits als fulfilled zurückgegeben. Sein Wert ist ein leeres Array.

Wenn Werte vorgefunden werden, ist das zurückgegeben Promise in jedem Fall zunächst pending. Die Festlegung auf fulfilled oder rejected erfolgt auf jeden Fall asynchron. Die Unterscheidung zwischen „sofort festgelegt“ und „asynchron festgelegt“ ist normalerweise nicht von Belang, kann aber darauf Einfluss haben, in welcher Reihenfolge Mikrotasks ausgeführt werden.

Ein Anwendungsfall ist das parallele Downloaden mehrerer Dateien. Zum Abschluss möchte man je Datei den Inhalt haben und bei Fehlern die Fehlerursache.

Paralleles Holen mehrerer Dateien

function promiseFile(name) {
   return fetch(name)
          .then(response => { 
             if (!response.ok)
                throw new Error(`${response.url} failed, status=${response.status}`); 
             return response.text()));
          });
}

const files = "a.dat", "b.dat", "c.dat";
const filePromises = files.map(promiseFile);    // Ein Promise je File 

Promise.allSettled( filePromises )
.then(results => {
   // results sind die Ergebnisobjekte mit Status und Inhalt bzw. Fehlergrund
};

Siehe auch

• Promise.all: Variante von allSettled, die nur dann fulfilled wird, wenn keins der übergebenen Promises zurückgewiesen wird
• Promise.race: Eine Concurrency-Methode, die sich nur für das erste fertige Promise interessiert, egal ob fulfilled oder rejected