TypeScript Promise: Promise<T>, Promise.all ve allSettled

TypeScript'te bir promise'in tipi Promise<T>'dir; burada T, promise'in resolve olduğu değerin tipidir. Promise döndüren bir fonksiyon bunu dönüş tipinde belirtir ve then ya da await ile aldığınız değer T tipindedir.

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
});

Promise'in işleyişi (durumlar, microtask kuyruğu, zincirleme) düz JavaScript'tir ve JavaScript promise'leri sayfasında anlatılır. Bu sayfa tiplerle ilgilidir.

new Promise ve resolve'u Tiplemek

new Promise, dönüş tipi belirtilmiş bir fonksiyonun dönüş değeri olduğunda T oradan gelir. Tek başına kullanıldığında TypeScript T'yi resolve çağrılarından çıkarmaz ve Promise<unknown> elde edersiniz. Tip argümanını açıkça verin:

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();

İki ayrıntı var. resolve tipini T'den alır, bu yüzden bir Promise<number> içinde resolve("42") bir derleme hatasıdır. Argümansız resolve() ise yalnızca T içinde void varsa kabul edilir: bir Promise<number> içinde bu TS2794 hatasıdır (Expected 1 arguments, but got 0. Did you forget to include 'void' in your type argument to 'Promise'?).

reject tarafı tiplenmez. Promise<T, E> diye bir şey yoktur: bir promise herhangi bir değerle reject olabilir.

then, catch ve finally

Her then, callback'inin döndürdüğü şeye göre tiplenmiş yeni bir promise döndürür. Callback bir promise döndürürse TypeScript onu açar, bu yüzden hiçbir zaman Promise<Promise<T>> elde etmezsiniz.

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"));

catch callback'inin parametresi standart kütüphanede unknown değil any olarak tiplenmiştir. String olabilecek bir değer üzerinde e.message yazmanızı hiçbir şey engellemez. Yukarıdaki gibi unknown olarak işaretleyin ve kullanmadan önce daraltın. await etrafındaki try/catch daha iyisini yapar: strict altında catch değişkeni zaten unknown olur (bkz. hata yönetimi).

Promise.all Bir Tuple Döndürür

Farklı promise tiplerinden oluşan bir dizi literal'i verildiğinde Promise.all, her konumun kendi tipini koruduğu bir tuple'ın promise'ini döndürür:

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();

Promise olmayan değerler de araya karıştırılabilir ve olduğu gibi geçer. Promise.all, bir girdi reject olur olmaz reject olur ve diğer sonuçlar kaybolur. Promise.race ilk sonuçlanan girdiyle resolve ya da reject olur ve girdilerin union'ı olarak tiplenir; Promise.any ilk başarılı sonuçla resolve olur ve yalnızca bütün girdiler başarısız olursa bir AggregateError ile reject olur.

Promise.allSettled ve Sonuç Tipi

Promise.allSettled her girdiyi bekler ve asla reject olmaz. Her sonuç, status alanıyla daralttığınız bir union olan PromiseSettledResult<T> tipindedir:

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 yalnızca status kontrolünden sonra vardır, çünkü reject olan varyantta value yoktur. reason, catch'teki aynı nedenle any'dir. filter, filtrelenmiş dizinin fulfilled sonuçlar olarak tiplenmesi için bir type predicate kullanır.

Callback API'sini Promise ile Sarmak

Eski API'ler sonuçları bir callback üzerinden bildirir, çoğu zaman Node tarzında (err, result) => void biçiminde. Onları bir kez tipli bir promise döndüren bir fonksiyonla sarın, kodun geri kalanı await kullanabilir:

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();

Node'da util.promisify, (err, result) kuralını izleyen fonksiyonlar için bunu yapar; birçok yerleşik modülün de zaten promise sürümleri vardır (node:fs/promises, node:timers/promises).

Sık Yapılan Hatalar

• İmza Promise<T> derken T döndürmek ya da tersi. Promise<User> olarak tanımlanmış async olmayan bir fonksiyon bir promise döndürmek zorundadır; bir async fonksiyon ise otomatik olarak bir promise döndürür.
• Bir promise'i ele almayı unutmak. await, then ya da catch olmadan yazılmış save(user); gibi bir çağrı sorunsuz derlenir ve bir reject, ele alınmamış bir reddedilmeye dönüşür (bu da varsayılan olarak bir Node sürecini sonlandırır). typescript-eslint'in no-floating-promises kuralı bunları yakalar.
• .catch((e) => ...) tipine güvenmek. Buradaki e, any'dir. unknown olarak işaretleyin.
• Zaten promise döndüren bir şeyin etrafında new Promise kullanmak. Var olan promise'i doğrudan döndürün ya da await edin.