Promise w TypeScript: Promise<T>, Promise.all i allSettled

W TypeScript promise ma typ Promise<T>, gdzie T to typ wartości, którą się rozwiązuje. Funkcja zwracająca promise deklaruje to w typie zwracanym, a wartość, którą dostajesz z then lub await, ma typ T.

type User = { id: number; name: string };

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

fetchUser(1).then((user) => {
    // user is User here
    console.log(user.name.toUpperCase()); // ADA
});

Mechanika promise'ów (stany, kolejka mikrozadań, łańcuchowanie) to zwykły JavaScript, omówiony w JavaScript promises. Ta strona dotyczy typów.

Typowanie new Promise i resolve

Gdy new Promise jest wartością zwracaną funkcji z zadeklarowanym typem zwracanym, T pochodzi stamtąd. Samodzielnie TypeScript nie wnioskuje T z wywołań resolve i dostajesz Promise<unknown>. Przekaż argument typu jawnie:

const untyped = new Promise((resolve) => resolve(42));
// untyped is Promise<unknown>

const typed = new Promise<number>((resolve, reject) => {
    const n = 42;
    if (n < 0) reject(new Error("negative"));
    else resolve(n);
});

// A promise that resolves with no value is Promise<void>.
const done = new Promise<void>((resolve) => setTimeout(resolve, 10));

async function main() {
    const n = await typed;
    console.log(n.toFixed(1)); // 42.0
    await done;
    console.log("done");
    const u = await untyped;
    // @ts-expect-error: 'u' is of type 'unknown'.
    console.log(u.toFixed(1)); // 42.0 at runtime, but the compiler cannot know that
}
main();

Dwa szczegóły. resolve jest typowane na podstawie T, więc resolve("42") w Promise<number> to błąd kompilacji. A resolve() bez argumentu jest dozwolone tylko wtedy, gdy T zawiera void: w Promise<number> to błąd TS2794 (Expected 1 arguments, but got 0. Did you forget to include 'void' in your type argument to 'Promise'?).

Strona reject nie jest typowana. Nie ma Promise<T, E>: promise może zostać odrzucony dowolną wartością.

then, catch i finally

Każde then zwraca nowy promise o typie tego, co zwraca jego callback. Jeśli callback zwraca promise, TypeScript go rozpakowuje, więc nigdy nie dostajesz Promise<Promise<T>>.

const price = Promise.resolve("19.99");

const withTax = price
    .then((s) => Number(s))                     // Promise<number>
    .then((n) => Promise.resolve(n * 1.2))      // still Promise<number>
    .then((n) => n.toFixed(2));                 // Promise<string>

withTax
    .then((s) => console.log(s)) // 23.99
    .catch((e: unknown) => {
        console.log(e instanceof Error ? e.message : String(e));
    })
    .finally(() => console.log("finished"));

Parametr callbacku catch ma w bibliotece standardowej typ any, a nie unknown. Nic nie powstrzyma cię przed napisaniem e.message na wartości, która może być stringiem. Oznacz go jako unknown, jak wyżej, i zawęź przed użyciem. try/catch wokół await radzi sobie lepiej: przy strict jego zmienna catch już jest unknown (zobacz obsługę błędów).

Promise.all zwraca krotkę

Dla literału tablicy z promise'ami różnych typów Promise.all zwraca promise krotki, w której każda pozycja zachowuje własny typ:

const getUser = () => Promise.resolve({ name: "Ada" });
const getCount = () => Promise.resolve(3);
const getTags = () => Promise.resolve(["admin", "dev"]);

async function main() {
    const [user, count, tags] = await Promise.all([getUser(), getCount(), getTags()]);
    // user: { name: string }, count: number, tags: string[]
    console.log(user.name, count + 1, tags.join("/")); // Ada 4 admin/dev

    // Same element type: the result is an array.
    const ids = [1, 2, 3];
    const doubled = await Promise.all(ids.map((id) => Promise.resolve(id * 2)));
    console.log(doubled); // [ 2, 4, 6 ]
}
main();

Można też wmieszać wartości niebędące promise'ami, przechodzą bez zmian. Promise.all odrzuca, gdy tylko jedno wejście zostanie odrzucone, a pozostałe wyniki przepadają. Promise.race rozwiązuje się lub odrzuca wynikiem pierwszego zakończonego i ma typ unii wejść; Promise.any rozwiązuje się pierwszym sukcesem i odrzuca z AggregateError tylko wtedy, gdy zawiodą wszystkie wejścia.

Promise.allSettled i typ jego wyniku

Promise.allSettled czeka na każde wejście i nigdy nie odrzuca. Każdy wynik to PromiseSettledResult<T>, unia, którą zawężasz polem status:

function load(id: number): Promise<string> {
    return id % 2 === 0
        ? Promise.resolve(`item ${id}`)
        : Promise.reject(new Error(`item ${id} not found`));
}

async function main() {
    const results = await Promise.allSettled([load(1), load(2), load(4)]);

    for (const r of results) {
        if (r.status === "fulfilled") {
            console.log("ok:", r.value); // value: string
        } else {
            // reason: any, so narrow it like a caught error
            console.log("failed:", r.reason instanceof Error ? r.reason.message : r.reason);
        }
    }

    const values = results
        .filter((r): r is PromiseFulfilledResult<string> => r.status === "fulfilled")
        .map((r) => r.value);
    console.log(values); // [ 'item 2', 'item 4' ]
}
main();

r.value istnieje dopiero po sprawdzeniu status, bo wariant odrzucony nie ma value. reason to any, z tego samego powodu co w catch. filter używa predykatu typu, żeby przefiltrowana tablica miała typ spełnionych wyników.

Opakowywanie API z callbackami w promise

Starsze API zgłaszają wyniki przez callback, często w stylu Node (err, result) => void. Opakuj je raz w funkcję zwracającą otypowany promise, a reszta kodu może używać await:

type Callback<T> = (err: Error | null, result?: T) => void;

// An old-style API.
function lookupPort(service: string, cb: Callback<number>): void {
    setTimeout(() => {
        if (service === "http") cb(null, 80);
        else cb(new Error(`unknown service ${service}`));
    }, 10);
}

function lookupPortAsync(service: string): Promise<number> {
    return new Promise((resolve, reject) => {
        lookupPort(service, (err, port) => {
            if (err) reject(err);
            else resolve(port!); // present whenever err is null
        });
    });
}

async function main() {
    console.log(await lookupPortAsync("http")); // 80
    try {
        await lookupPortAsync("gopher");
    } catch (e) {
        if (e instanceof Error) console.log(e.message); // unknown service gopher
    }
}
main();

W Node util.promisify robi to dla funkcji zgodnych z konwencją (err, result), a wiele wbudowanych modułów ma już wersje oparte na promise'ach (node:fs/promises, node:timers/promises).

Typowe błędy

• Zwracanie T tam, gdzie sygnatura mówi Promise<T>, lub odwrotnie. Funkcja nie-async zadeklarowana jako Promise<User> musi zwrócić promise; funkcja async zwraca go automatycznie.
• Zapominanie o obsłudze promise'a. Wywołanie takie jak save(user); bez await, then czy catch kompiluje się bez problemu, a odrzucenie staje się nieobsłużonym odrzuceniem (które domyślnie kończy proces Node). Wyłapuje to reguła typescript-eslint no-floating-promises.
• Ufanie typowi .catch((e) => ...). Jego e to any. Oznacz go jako unknown.
• Używanie new Promise wokół czegoś, co już zwraca promise. Po prostu zwróć istniejący promise albo użyj na nim await.