Promise w JavaScript: then, catch i Promise.all

Promise to miejsce na przyszłą wartość

Gdy JavaScript musi zrobić coś, co zajmuje czas (zapytanie sieciowe, odczyt pliku, czekanie na timer), nie może od razu podać ci wyniku. Zamiast tego daje ci Promise: obiekt reprezentujący wartość, która w końcu się pojawi.

const promise = new Promise((resolve) => {
    setTimeout(() => resolve("gotowe"), 500);
});

console.log(promise);
promise.then((value) => console.log(value));

Pierwszy console.log pokazuje Promise w stanie oczekiwania. Pół sekundy później Promise się rozwiązuje, a callback z .then uruchamia się z wartością. Sam Promise to zwykły obiekt. Cała magia polega na tym, że wie, jak powiadomić wszystkich nasłuchujących, gdy pojawi się jego wartość.

Trzy stany

Promise zawsze jest w jednym z trzech stanów:

• pending: praca trwa. Wartości jeszcze nie ma.
• fulfilled: praca się udała. Wartość jest dostępna.
• rejected: praca się nie udała. Dostępny jest błąd.

Promise przechodzi ze stanu pending do fulfilled albo rejected dokładnie raz i zostaje w nim na zawsze. Nie da się cofnąć rozwiązania Promise ani rozwiązać go dwa razy.

const ok = Promise.resolve(42);
const bad = Promise.reject(new Error("nope"));

ok.then((v) => console.log("ok:", v));
bad.catch((e) => console.log("bad:", e.message));

Promise.resolve(value) tworzy Promise, który już jest spełniony, a Promise.reject(error) taki, który już jest odrzucony. Przydają się w testach i do zwracania Promise z funkcji, która czasem zna odpowiedź od razu.

Odczyt wartości: .then i .catch

Nie wyciągasz wartości z Promise bezpośrednio. Przekazujesz callback do .then, a Promise wywołuje go, gdy wartość jest gotowa:

function fetchUser(id) {
    return new Promise((resolve) => {
        setTimeout(() => resolve({ id, name: "Ada" }), 200);
    });
}

fetchUser(1)
    .then((user) => console.log("pobrano:", user.name))
    .catch((err) => console.log("błąd:", err.message));

.catch(fn) uruchamia się, gdy Promise zostanie odrzucony. Pod spodem to skrót od .then(undefined, fn). Jeden .catch() na końcu łańcucha obsługuje odrzucenia z każdego kroku powyżej, więc nie potrzebujesz go po każdym .then.

Łańcuchy: każde .then zwraca nowy Promise

To jest miejsce, w którym wiele osób się gubi. .then() nie tylko uruchamia callback. Zwraca nowy Promise, który rozwiązuje się tym, co zwrócił callback. Dzięki temu można tworzyć łańcuchy:

Promise.resolve(2)
    .then((n) => n + 1)
    .then((n) => n * 10)
    .then((n) => console.log(n));

Każdy krok zasila następny. Jeśli callback w .then zwróci Promise, łańcuch czeka na ten Promise, zanim pójdzie dalej, więc kroki asynchroniczne ładnie się składają:

function delay(ms, value) {
    return new Promise((resolve) => setTimeout(() => resolve(value), ms));
}

delay(100, "first")
    .then((v) => {
        console.log(v);
        return delay(100, "second");
    })
    .then((v) => {
        console.log(v);
        return delay(100, "third");
    })
    .then((v) => console.log(v));

Trzy kolejne kroki asynchroniczne i żadnego zagnieżdżania. Porównaj to z tą samą logiką napisaną na callbackach, a zobaczysz, dlaczego Promise się przyjęły.

Błędy spływają w dół łańcucha

Odrzucony Promise pomija każde .then, dopóki nie trafi na .catch. Na tym polega cały model obsługi błędów:

Promise.resolve(10)
    .then((n) => {
        throw new Error("coś się zepsuło");
    })
    .then((n) => {
        console.log("pominięte");
        return n * 2;
    })
    .catch((err) => console.log("złapano:", err.message));

Rzucenie wyjątku wewnątrz .then odrzuca Promise, który to .then zwróciło. Kolejne .then widzi odrzucenie i przekazuje je dalej, aż .catch je przechwyci. Zwykle wystarczy jeden .catch na końcu łańcucha, a łańcuch w ogóle bez .catch wygeneruje ostrzeżenie „unhandled promise rejection”, które warto naprawić.

Własny Promise przez new Promise

Najczęściej korzystasz z Promise, które dają ci biblioteki. Czasem jednak trzeba opakować coś, co Promise nie zwraca, zwykle stare API oparte na callbackach:

function wait(ms) {
    return new Promise((resolve, reject) => {
        if (ms < 0) {
            reject(new Error("ms must be non-negative"));
            return;
        }
        setTimeout(() => resolve(ms), ms);
    });
}

wait(200)
    .then((ms) => console.log(`waited ${ms}ms`))
    .catch((err) => console.log(err.message));

Funkcja przekazana do new Promise to tak zwany executor. Dostaje dwa argumenty: resolve (wywołaj z wartością sukcesu) i reject (wywołaj z błędem). Wywołaj jeden z nich dokładnie raz. Kolejne wywołania są ignorowane.

Dwa nawyki, które oszczędzają kłopotów:

• Sięgaj po new Promise tylko wtedy, gdy opakowujesz coś, co nie jest jeszcze oparte na Promise. Jeśli funkcja już zwraca Promise, po prostu go zwróć.
• Zawsze wywołuj reject z obiektem Error, a nie ze stringiem. Stack trace warto zachować.

Równoległe zadania: Promise.all

Łańcuchy .then działają sekwencyjnie. Gdy masz kilka niezależnych zadań asynchronicznych i chcesz, żeby działały jednocześnie, narzędziem jest Promise.all:

function delay(ms, value) {
    return new Promise((resolve) => setTimeout(() => resolve(value), ms));
}

const start = Date.now();

Promise.all([
    delay(300, "users"),
    delay(200, "posts"),
    delay(400, "comments"),
]).then((results) => {
    console.log(results);
    console.log(`took ${Date.now() - start}ms`);
});

Wszystkie trzy timery działają równolegle. Promise.all rozwiązuje się tablicą wyników w tej samej kolejności co wejście, gdy tylko spełni się każdy Promise. Całkowity czas to około 400 ms, a nie 900 ms.

Haczyk: Promise.all zostaje odrzucony, gdy tylko którykolwiek z jego Promise zostanie odrzucony, a pozostałe wyniki przepadają. To właściwe zachowanie, gdy potrzebujesz wszystkich elementów (np. do wyrenderowania strony, która wymaga trzech wywołań API). Gdy nie potrzebujesz, użyj allSettled.

Gdy część błędów jest dopuszczalna: Promise.allSettled

Promise.allSettled czeka, aż każdy Promise się zakończy, spełniony albo odrzucony, i daje ci raport:

const promises = [
    Promise.resolve("a"),
    Promise.reject(new Error("b failed")),
    Promise.resolve("c"),
];

Promise.allSettled(promises).then((results) => {
    for (const r of results) {
        if (r.status === "fulfilled") console.log("ok:", r.value);
        else console.log("err:", r.reason.message);
    }
});

Każdy wynik to obiekt: { status: "fulfilled", value } albo { status: "rejected", reason }. Przydaje się, gdy częściowy sukces jest do przyjęcia: logowanie paczki zdarzeń, pobieranie wielu miniatur, uruchamianie niezależnych health checków.

Dwa inne kombinatory warte poznania:

• Promise.race([...]): kończy się, gdy tylko zakończy się pierwszy Promise, sukcesem albo błędem. Przydatne przy timeoutach.
• Promise.any([...]): spełnia się pierwszym sukcesem i ignoruje odrzucenia. Zostaje odrzucony tylko wtedy, gdy odrzucone zostaną wszystkie Promise.

Promise są zawsze asynchroniczne

Nawet Promise, który już jest rozwiązany, wywołuje callback z .then asynchronicznie, nigdy synchronicznie i nigdy w tym samym ticku:

console.log("przed");
Promise.resolve("natychmiast").then((v) => console.log(v));
console.log("po");

Wynik to przed, po, natychmiast. Callback z .then czeka, aż bieżący kod się skończy, a potem uruchamia się z kolejki mikrozadań. Ta zasada („callback Promise nigdy nie uruchamia się synchronicznie”) sprawia, że łączenie Promise z kodem synchronicznym jest przewidywalne: kod synchroniczny zawsze kończy się pierwszy.

Dalej: async/await

Łańcuchy wywołań .then działają, ale przy więcej niż dwóch czy trzech krokach zaczynają przypominać schody. async/await to składnia zbudowana na Promise, która pozwala napisać tę samą logikę tak, jakby była synchroniczna, z try/catch do obsługi błędów i zwykłymi zmiennymi na wartości pośrednie. O tym dalej.