Promise.any() — Methode · JavaScript-Referenz

Signatur

Promise.any(iterable)

Beschreibung

Die statische Methode Promise.any() nimmt ein Iterable von Promises als Eingabe und gibt ein einzelnes Promise zurück. Dieses zurückgegebene Promise wird erfüllt, sobald eines der Eingabe-Promises erfüllt wird, und zwar mit dem Wert dieser ersten Erfüllung. Es wird abgelehnt, wenn alle Eingabe-Promises abgelehnt werden (einschließlich des Falls, dass ein leeres Iterable übergeben wird), mit einem AggregateError, der ein Array von Ablehnungsgründen enthält.

Die Methode Promise.any() ist eine der Methoden zur Promise-Nebenläufigkeit (promise concurrency). Diese Methode ist nützlich, um das erste Promise zurückzugeben, das erfüllt wird. Sie bricht ab, sobald ein Promise erfüllt wird, wartet also nicht darauf, dass die anderen Promises abgeschlossen werden, sobald sie eines gefunden hat.

Im Gegensatz zu Promise.all(), das ein Array von Erfüllungswerten zurückgibt, erhalten wir nur einen Erfüllungswert (vorausgesetzt, mindestens ein Promise wird erfüllt). Dies kann von Vorteil sein, wenn nur ein Promise erfüllt werden muss, es uns aber egal ist, welches. Beachten Sie einen weiteren Unterschied: Diese Methode wird bei einem leeren Iterable abgelehnt, da das Iterable dann tatsächlich keine Elemente enthält, die erfüllt werden können. Sie können Promise.any() und Promise.all() mit Array.prototype.some() und Array.prototype.every() vergleichen.

Ebenso gibt diese Methode im Gegensatz zu Promise.race(), das den ersten abgeschlossenen Wert zurückgibt (entweder Erfüllung oder Ablehnung), den ersten erfüllten Wert zurück. Diese Methode ignoriert alle abgelehnten Promises bis zum ersten Promise, das erfüllt wird.

Wie andere Promise-Kombinatoren markiert Promise.any() alle Promises sofort als „behandelt", wenn es aufgerufen wird (durch Aufruf ihrer .then()-Methoden). Nachfolgende Ablehnungen nach der ersten Erfüllung werden ignoriert und lösen keine unhandledrejection-Ereignisse aus.

Die Erfüllung des zurückgegebenen Promise bricht die verbleibenden Operationen nicht ab und meldet nicht die an ihren Promises angehängten Handler ab. Wenn wiederholt ein langlebiges, ausstehendes Promise an Promise.any() übergeben wird, können sich Handler auf diesem Promise anhäufen, selbst wenn jedes Mal ein anderes Eingabe-Promise erfüllt wird.

Parameter

Name	Typ	Default	Beschreibung
$iterable Pflicht	Iterable	—	Ein Iterable (wie ein `Array`) von Promises. Diese Werte werden mittels `await` abgewartet, sodass auch andere thenables aufgelöst werden, während Nicht-thenables unverändert zurückgegeben werden.

Rückgabewert

Typ

Promise

Beschreibung

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 Erfüllungswert des ersten erfüllten Promise; asynchron abgelehnt wird, wenn alle Promises im übergebenen iterable abgelehnt werden — der Ablehnungsgrund ist ein AggregateError, der in seiner errors-Eigenschaft ein Array von Ablehnungsgründen enthält. Die Fehler sind in der Reihenfolge der übergebenen Promises, unabhängig von der Abschlussreihenfolge. Wenn das übergebene iterable nicht leer ist, aber keine ausstehenden Promises enthält, wird das zurückgegebene Promise dennoch asynchron (statt synchron) abgelehnt.

Beispiele

Verwendung von Promise.any()

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

Done quick

Ablehnungen mit AggregateError

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

AggregateError: No Promise in Promise.any was resolved

Anzeigen des ersten geladenen Bildes

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

Siehe auch

Promise Promise.all() Promise.allSettled() Promise.race() AggregateError