CKTIS / JavaScript
Promise.any — první úspěšný výsledek
Promise.any přijímá iterovatelný objekt a vrací promise, která se splní prvním úspěšným výsledkem, jejž metoda zaznamená. Zamítnutí jednotlivých vstupů čekání neukončí, pokud nejsou zamítnuty všechny; v takovém případě se výsledek zamítne s AggregateError.
Verze: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntaxe
Promise.any(iterable)Promise.any(iterable) je statická metoda objektu Promise, zavedená v ECMAScript 2021 (ES12). Přijímá synchronní iterovatelný objekt, například pole promises, běžných hodnot nebo objektů s metodou then (thenables). Hodnoty se převedou pomocí Promise.resolve; nepředávejte funkce s očekáváním, že je metoda zavolá.
Vrácená promise převezme hodnotu z prvního splnění, které Promise.any zaznamená. Nemusí jít o splnění, k němuž došlo nejdříve. Pokud předáte dvě běžné, již splněné promise a vestavěná metoda Promise.resolve obě vrátí beze změny, vyhraje první v pořadí iterace, i když se splnila později než druhá. Vestavěná metoda Promise.resolve vrátí promise beze změny, pokud je hodnota její vlastnosti constructor totožná s hodnotou this při volání. Nezkoumá, z jakého prostředí (realmu) promise pochází. Pokud první promise pochází z jiného realmu a má svůj výchozí konstruktor, místní Promise.resolve ji zabalí do nové promise. Tím se zpozdí reakce na její splnění, takže druhá může vyhrát, pokud se vrátí beze změny. Pokud je ale hodnotou vlastnosti constructor první promise místní Promise, místní Promise.resolve ji navzdory jejímu původu vrátí beze změny. U Promise.race může zamítnutí vstupu určit výsledek, pokud ho metoda zaznamená dříve než jakékoli jiné splnění nebo zamítnutí. U Promise.any vedou zamítnutí vstupů k zamítnutí výsledku s AggregateError až po zamítnutí všech vstupů. To platí i tehdy, když je zamítnut jediný zadaný vstup. Metoda po úspěchu ostatní operace nezruší.
Pokud budou zamítnuty všechny vstupy, výsledek se zamítne s AggregateError. Jeho pole errors obsahuje důvody v pořadí vstupů, nikoli v pořadí zamítnutí. Promise.any([]) vrátí již zamítnutou promise s prázdným polem errors; obslužné funkce se přesto spustí asynchronně. Výsledek může zamítnout také chyba při čtení iterátoru, a to bez AggregateError.
Tuto metodu použijte, když stačí jeden úspěšný výsledek. Situaci, kdy žádný vstup neuspěje, ošetřete pomocí try/catch kolem await nebo pomocí .catch(). Jazyková specifikace nepotvrzuje podporu v konkrétním prohlížeči: ověřte cílové prostředí, například pomocí typeof Promise.any === "function". Přítomnost Node 24 v repozitáři nedokazuje podporu v prohlížeči.
Příklady
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);Výsledek
ready true ["first","second"]
Zobrazený kód a uvedený výsledek byly ověřeny v izolovaném prostředí metodou zaznamenanou v dokladu o ověření této přesné verze.