CKTIS / JavaScript
Promise.any — het eerste succesvolle resultaat
Promise.any accepteert een iterable en retourneert een promise die wordt vervuld met het eerste succesvolle resultaat dat de methode waarneemt. Afwijzingen van invoerwaarden beëindigen het wachten niet, tenzij alle invoerwaarden worden afgewezen; in dat geval wordt het resultaat afgewezen met AggregateError.
Versie: 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) is een statische methode van Promise, geïntroduceerd in ECMAScript 2021 (ES12). De methode accepteert een synchrone iterable, zoals een array met promises, gewone waarden of objecten met een then-methode (thenables). Waarden worden omgezet via Promise.resolve; geef geen functies door in de verwachting dat de methode ze aanroept.
De geretourneerde promise neemt de waarde aan van de eerste vervulling die Promise.any waarneemt. Dat is niet noodzakelijk de vervulling die als eerste plaatsvond. Geef je twee gewone, al vervulde promises door en retourneert de ingebouwde methode Promise.resolve beide ongewijzigd, dan wint de eerste in de iteratievolgorde, ook als die later is vervuld dan de tweede. De ingebouwde methode Promise.resolve retourneert een promise ongewijzigd als de waarde van de eigenschap constructor gelijk is aan de this-waarde van de aanroep. De methode kijkt niet uit welke realm de promise komt. Komt de eerste promise uit een andere realm en heeft die zijn standaardconstructor, dan verpakt de lokale methode Promise.resolve die in een nieuwe promise. Daardoor wordt de reactie op de vervulling vertraagd en kan de tweede winnen als die ongewijzigd wordt geretourneerd. Is de waarde van de eigenschap constructor van de eerste promise echter gelijk aan de lokale Promise, dan retourneert de lokale methode Promise.resolve die promise ondanks zijn herkomst ongewijzigd. Bij Promise.race kan de afwijzing van een invoerwaarde het resultaat bepalen als de methode die afwijzing vóór elke andere vervulling of afwijzing waarneemt. Bij Promise.any leiden afwijzingen van invoerwaarden pas tot afwijzing van het resultaat met AggregateError als alle invoerwaarden zijn afgewezen. Dat geldt ook als er maar één invoerwaarde is en die wordt afgewezen. De methode annuleert de overige bewerkingen niet nadat er een succes is.
Als alle invoerwaarden worden afgewezen, wordt het resultaat afgewezen met AggregateError. De array errors bevat de redenen in de volgorde van de invoer, niet in de volgorde van afwijzing. Promise.any([]) retourneert een al afgewezen promise met een lege errors-array; handlers worden nog steeds asynchroon uitgevoerd. Ook een fout bij het uitlezen van de iterator kan het resultaat afwijzen, zonder AggregateError.
Gebruik deze methode wanneer één succesvol resultaat volstaat. Handel het uitblijven van succes af met try/catch rond await of met .catch(). De taalspecificatie bevestigt niet dat een bepaalde browser ondersteuning biedt: controleer de doelomgeving, bijvoorbeeld met typeof Promise.any === "function". De aanwezigheid van Node 24 in een repository bewijst geen browserondersteuning.
Voorbeelden
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);Resultaat
ready true ["first","second"]
De getoonde code en het opgegeven resultaat zijn in een geïsoleerde omgeving geverifieerd met de methode die in het verificatiebewijs voor exact deze versie is vastgelegd.