WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

Promise.any — das erste erfolgreiche Ergebnis

Promise.any akzeptiert ein iterierbares Objekt und gibt ein Promise zurück, das mit dem ersten von der Methode beobachteten erfolgreichen Ergebnis erfüllt wird. Ablehnungen einzelner Eingaben beenden das Warten nicht, solange nicht alle Eingaben abgelehnt werden; dann wird das Ergebnis mit AggregateError abgelehnt.

Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

Promise.any(iterable)

Promise.any(iterable) ist eine statische Methode von Promise, die mit ECMAScript 2021 (ES12) eingeführt wurde. Sie akzeptiert ein synchrones iterierbares Objekt, zum Beispiel ein Array mit Promises, einfachen Werten oder Objekten mit einer then-Methode (Thenables). Werte werden über Promise.resolve umgewandelt; übergib keine Funktionen in der Erwartung, dass die Methode sie aufruft.

Das zurückgegebene Promise übernimmt den Wert der ersten Erfüllung, die Promise.any beobachtet. Das ist nicht unbedingt die Erfüllung, die zeitlich zuerst eingetreten ist. Übergibst du zwei gewöhnliche, bereits erfüllte Promises und gibt die eingebaute Methode Promise.resolve beide unverändert zurück, gewinnt das erste in der Iterationsreihenfolge, auch wenn es später erfüllt wurde als das zweite. Die eingebaute Methode Promise.resolve gibt ein Promise unverändert zurück, wenn der Wert seiner Eigenschaft constructor mit dem this-Wert des Aufrufs identisch ist. Aus welchem Realm das Promise stammt, prüft sie nicht. Stammt das erste Promise aus einem anderen Realm und hat es seinen Standardkonstruktor, verpackt die lokale Methode Promise.resolve es in ein neues Promise. Das verzögert die Reaktion auf seine Erfüllung, sodass das zweite gewinnen kann, wenn es unverändert zurückgegeben wird. Entspricht die Eigenschaft constructor des ersten Promise dagegen dem lokalen Promise, gibt die lokale Methode Promise.resolve es trotz seiner Herkunft unverändert zurück. Bei Promise.race kann die Ablehnung einer Eingabe das Ergebnis bestimmen, wenn die Methode sie vor jeder anderen Erfüllung oder Ablehnung beobachtet. Bei Promise.any führen Ablehnungen von Eingaben erst dann zur Ablehnung des Ergebnisses mit AggregateError, wenn alle Eingaben abgelehnt wurden. Das gilt auch, wenn die einzige Eingabe abgelehnt wird. Nach einem Erfolg bricht die Methode die übrigen Vorgänge nicht ab.

Werden alle Eingaben abgelehnt, wird das Ergebnis mit AggregateError abgelehnt. Dessen Array errors enthält die Gründe in der Reihenfolge der Eingaben, nicht in der Reihenfolge der Ablehnungen. Promise.any([]) gibt ein bereits abgelehntes Promise mit einem leeren errors-Array zurück; Handler werden trotzdem asynchron ausgeführt. Auch ein Fehler beim Lesen des Iterators kann das Ergebnis ablehnen, dann jedoch ohne AggregateError.

Verwende diese Methode, wenn ein erfolgreiches Ergebnis genügt. Behandle den Fall, dass nichts erfolgreich ist, mit try/catch um await oder mit .catch(). Die Sprachspezifikation bestätigt nicht die Unterstützung in einem bestimmten Browser: Prüfe die Zielumgebung, zum Beispiel mit typeof Promise.any === "function". Dass sich Node 24 in einem Repository befindet, beweist keine Browser-Unterstützung.

Beispiele

async function main() {
  const value = await Promise.any([
    Promise.reject("offline"),
    Promise.resolve("ready")
  ]);
  console.log(value);

  try {
    await Promise.any([
      Promise.reject("first"),
      Promise.reject("second")
    ]);
  } catch (error) {
    console.log(error instanceof AggregateError);
    console.log(JSON.stringify(error.errors));
  }
}

main().catch(console.error);

Ergebnis

ready
true
["first","second"]

Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.

Quellen