Promise.any()

Probieren Sie es aus

const promise1 = Promise.reject(new Error("error"));
const promise2 = new Promise((resolve) => setTimeout(resolve, 100, "quick"));
const promise3 = new Promise((resolve) => setTimeout(resolve, 500, "slow"));

const promises = [promise1, promise2, promise3];

Promise.any(promises).then((value) => console.log(value));

// Expected output: "quick"

Syntax

Promise.any(iterable)

Parameter

iterable

Ein Iterable von Promises, beispielsweise ein Array. Auf diese Werte wird mit await gewartet. Daher werden auch andere Thenables aufgelöst, während Werte, die keine Thenables sind, unverändert zurückgegeben werden.

Rückgabewert

Ein Promise, das:

• bereits abgelehnt ist, wenn das übergebene iterable leer ist.
• asynchron erfüllt wird, sobald eines der Promises im übergebenen iterable erfüllt wird. Der Erfüllungswert ist der Wert des zuerst erfüllten Promise.
• asynchron abgelehnt wird, wenn alle Promises im übergebenen iterable abgelehnt werden. Der Ablehnungsgrund ist ein AggregateError, dessen Eigenschaft errors ein Array mit den Ablehnungsgründen enthält. Die Fehler stehen in der Reihenfolge der übergebenen Promises, unabhängig davon, in welcher Reihenfolge diese abgeschlossen werden. Wenn das übergebene iterable nicht leer ist, aber keine ausstehenden Promises enthält, wird das zurückgegebene Promise dennoch asynchron statt synchron abgelehnt.

Beschreibung

Die Methode Promise.any() gehört zu den Methoden für die gleichzeitige Verarbeitung von Promises. Sie ist nützlich, wenn das erste erfüllte Promise zurückgegeben werden soll. Sobald ein Promise erfüllt wird, wartet die Methode nicht mehr auf den Abschluss der übrigen Promises.

Anders als Promise.all(), das ein Array von Erfüllungswerten zurückgibt, erhalten wir nur einen Erfüllungswert – vorausgesetzt, mindestens ein Promise wird erfüllt. Das ist hilfreich, wenn nur ein Promise erfüllt werden muss und es keine Rolle spielt, welches. Ein weiterer Unterschied: Diese Methode lehnt ein leeres Iterable ab, da es keine Elemente enthält, die erfüllt werden könnten. Promise.any() und Promise.all() lassen sich mit Array.prototype.some() und Array.prototype.every() vergleichen.

Anders als Promise.race(), das den Wert des ersten abgeschlossenen Promise zurückgibt – unabhängig davon, ob es erfüllt oder abgelehnt wurde –, gibt diese Methode den ersten Erfüllungswert zurück. Bis zum ersten erfüllten Promise ignoriert sie alle abgelehnten Promises.

Wie andere Methoden zur Kombination von Promises markiert Promise.any() beim Aufruf sofort alle Promises als „behandelt“, indem es ihre .then()-Methoden aufruft. Spätere Ablehnungen nach der ersten Erfüllung werden ignoriert und lösen keine unhandledrejection-Ereignisse aus.

Wenn das zurückgegebene Promise erfüllt wird, werden die verbleibenden Operationen nicht abgebrochen und die an ihre Promises angehängten Handler nicht entfernt. Wird ein langlebiges, ausstehendes Promise wiederholt an Promise.any() übergeben, können sich Handler für dieses Promise ansammeln, selbst wenn jedes Mal ein anderes übergebenes Promise erfüllt wird.

Beispiele

Promise.any() verwenden

Promise.any() wird mit dem Wert des ersten erfüllten Promise erfüllt, selbst wenn zuvor ein anderes Promise abgelehnt wurde. Im Gegensatz dazu wird Promise.race() entsprechend dem ersten abgeschlossenen Promise erfüllt oder abgelehnt.

const pErr = new Promise((resolve, reject) => {
  reject(new Error("Always fails"));
});

const pSlow = new Promise((resolve, reject) => {
  setTimeout(resolve, 500, "Done eventually");
});

const pFast = new Promise((resolve, reject) => {
  setTimeout(resolve, 100, "Done quick");
});

Promise.any([pErr, pSlow, pFast]).then((value) => {
  console.log(value);
  // pFast fulfills first
});
// Logs:
// Done quick

Ablehnungen mit AggregateError

Promise.any() wird mit einem AggregateError abgelehnt, wenn kein Promise erfüllt wird.

const failure = new Promise((resolve, reject) => {
  reject(new Error("Always fails"));
});

Promise.any([failure]).catch((err) => {
  console.log(err);
});
// AggregateError: No Promise in Promise.any was resolved

Das zuerst geladene Bild anzeigen

In diesem Beispiel ruft eine Funktion ein Bild ab und gibt einen Blob zurück. Mit Promise.any() rufen wir mehrere Bilder ab und zeigen das zuerst verfügbare Bild an, also das Bild, dessen Promise zuerst erfüllt wurde.

async function fetchAndDecode(url, description) {
  const res = await fetch(url);
  if (!res.ok) {
    throw new Error(`HTTP error! status: ${res.status}`);
  }
  const data = await res.blob();
  return [data, description];
}

const coffee = fetchAndDecode("coffee.jpg", "Coffee");
const tea = fetchAndDecode("tea.jpg", "Tea");

Promise.any([coffee, tea])
  .then(([blob, description]) => {
    const objectURL = URL.createObjectURL(blob);
    const image = document.createElement("img");
    image.src = objectURL;
    image.alt = description;
    document.body.appendChild(image);
  })
  .catch((e) => {
    console.error(e);
  });

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Polyfill für Promise.any in core-js
• Polyfill für Promise.any von es-shims
• Promise
• Promise.all()
• Promise.allSettled()
• Promise.race()