CKTIS / JavaScript
Promise.any — pierwszy pomyślny wynik
Promise.any przyjmuje obiekt iterowalny i zwraca obietnicę, która spełnia się wartością z pierwszego zaobserwowanego spełnienia. Odrzucenia wejściowe nie kończą oczekiwania, chyba że wszystkie wejścia zostaną odrzucone; wtedy wynikiem jest odrzucenie z AggregateError.
Wersja: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Składnia
Promise.any(iterable)Promise.any(iterable) to statyczna metoda Promise, wprowadzona w ECMAScript 2021 (ES12). Przyjmuje synchroniczny obiekt iterowalny, np. tablicę obietnic, zwykłych wartości lub obiektów z metodą then (thenables). Wartości są przekształcane przez Promise.resolve; nie należy przekazywać funkcji z oczekiwaniem, że metoda je uruchomi.
Zwrócona obietnica przyjmuje wartość z pierwszego spełnienia zaobserwowanego przez Promise.any, niekoniecznie z tego, które nastąpiło najwcześniej. Jeśli przekażesz dwie zwykłe, już spełnione obietnice i wbudowane Promise.resolve zwróci je bez zmian, wygrywa pierwsza w kolejności iteracji, nawet jeśli spełniła się później niż druga. Wbudowane Promise.resolve zwraca obietnicę bez zmian, jeśli wartość jej właściwości constructor jest identyczna z wartością this wywołania. Nie sprawdza, z którego środowiska wykonania (realm) pochodzi obietnica. Jeśli pierwsza obietnica pochodzi z innego środowiska i ma domyślny konstruktor, lokalne Promise.resolve opakuje ją w nową obietnicę. Opóźnia to reakcję na jej spełnienie, więc druga może wygrać, jeśli zostanie zwrócona bez zmian. Jeśli jednak właściwość constructor pierwszej obietnicy ma wartość równą lokalnemu Promise, lokalne Promise.resolve zwróci ją bez zmian, mimo że pochodzi z innego środowiska. Odrzucenie wejścia może rozstrzygnąć wynik Promise.race, jeśli metoda zaobserwuje je przed jakimkolwiek innym spełnieniem lub odrzuceniem. W Promise.any odrzucenia wejść powodują odrzucenie wyniku z AggregateError dopiero wtedy, gdy wszystkie wejścia zostaną odrzucone — także wtedy, gdy odrzucone wejście jest jedynym. Metoda nie anuluje pozostałych operacji po uzyskaniu sukcesu.
Jeśli wszystkie wejścia zostaną odrzucone, wynik zostaje odrzucony z AggregateError. Jego tablica errors zawiera przyczyny w kolejności wejściowej, nie w kolejności odrzuceń. Promise.any([]) zwraca już odrzuconą obietnicę z pustą tablicą errors; procedury obsługi nadal wykonują się asynchronicznie. Błąd odczytu iteratora również może odrzucić wynik, bez AggregateError.
Używaj tej metody, gdy wystarczy jeden pomyślny wynik. Obsłuż brak sukcesu przez try/catch z await lub przez .catch(). Specyfikacja języka nie potwierdza obsługi w konkretnej przeglądarce: sprawdź środowisko docelowe, np. typeof Promise.any === "function". Obecność Node 24 w repozytorium nie dowodzi obsługi w przeglądarce.
Przykłady
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);Wynik
ready true ["first","second"]
Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.