TypeScript Async Await: Tipler, Hatalar ve Paralel Çağrılar

TypeScript'te bir async fonksiyon her zaman bir promise döndürür: gövdesi bir string döndürüyorsa tipi Promise<string> olur. Fonksiyonun içinde await, bir Promise<T>'yi açıp T yapar.

type Order = { id: number; total: number };

function fetchOrder(id: number): Promise<Order> {
    return new Promise((resolve) => setTimeout(() => resolve({ id, total: 42 }), 20));
}

async function orderSummary(id: number): Promise<string> {
    const order = await fetchOrder(id); // order: Order, not Promise<Order>
    return `Order #${order.id}: $${order.total.toFixed(2)}`;
}

async function main() {
    const text = await orderSummary(7);
    console.log(text); // Order #7: $42.00
}
main();

Çalışma zamanı davranışı (await'in neyi duraklattığı, event loop) JavaScript'e aittir ve JavaScript async/await sayfasında anlatılır. TypeScript'in payı giren ve çıkan tiplerdir.

Async Fonksiyonların Dönüş Tipleri

Bir async fonksiyonun belirtilen dönüş tipi, gövde düz değeri döndürse bile Promise<...> olmalıdır. Yazmazsanız TypeScript onu çıkarır.

async function count(): Promise<number> {
    return 3; // a number, wrapped in a promise automatically
}

async function log(message: string): Promise<void> {
    console.log(message); // returns nothing: Promise<void>
}

const double = async (n: number) => n * 2; // inferred: (n: number) => Promise<number>

class Repo {
    async findName(id: number): Promise<string | undefined> {
        return id === 1 ? "Ada" : undefined;
    }
}

async function main() {
    await log("start");
    console.log(await count(), await double(21)); // 3 42
    console.log(await new Repo().findName(2));   // undefined
}
main();

async function count(): number yazmak TS1064 hatasıdır (The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'?). Awaited<T> utility type'ı açılmış tipi verir: Awaited<ReturnType<typeof count>> sonucu number olur.

await'i Unutmak

Eksik bir await, elinizde bir T yerine bir Promise<T> bırakır. TypeScript bunların çoğunu yakalar, çünkü tipler artık uymaz:

async function isAdmin(id: number): Promise<boolean> {
    return id === 1;
}

async function main() {
    const ok = isAdmin(2); // forgot await: ok is Promise<boolean>

    // @ts-expect-error: This condition will always return true since this 'Promise<boolean>' is always defined.
    if (ok) console.log("access granted (wrong!)");

    if (await isAdmin(2)) console.log("never printed");
    else console.log("access denied"); // correct
}
main();

if (ok) hatası gerçektir: bir promise nesnesi her zaman truthy'dir, bu yüzden erişim izni verilmiştir. TypeScript bunu TS2801 olarak bildirir. Promise'i bir boolean değişkene atamak ya da promise'te olmayan bir özelliği okumak da derlenmez. Sonucunu yok saydığınız bir çağrı (save(user);) ise yakalanmaz; bunu typescript-eslint'in no-floating-promises kuralı kapsar.

try/catch ile Hata Yönetimi

Reject olan bir promise, await'in hata fırlatmasına neden olur, bu yüzden sıradan try/catch çalışır. strict altında catch içindeki değişken unknown'dır ve .message okumadan önce onu daraltırsınız:

async function loadConfig(name: string): Promise<{ port: number }> {
    if (name !== "prod") throw new Error(`no config named "${name}"`);
    return { port: 443 };
}

async function main() {
    try {
        const cfg = await loadConfig("dev");
        console.log(cfg.port);
    } catch (e) {
        // e: unknown
        if (e instanceof Error) console.log("failed:", e.message);
        else console.log("failed with", e);
    } finally {
        console.log("cleanup runs either way");
    }
}
main();
// failed: no config named "dev"
// cleanup runs either way

Bir async fonksiyonun içindeki throw, çağrıldığı yerde hata fırlatmak yerine fonksiyonun promise'ini reject eder. Özel hata class'ları ve hata fırlatmak yerine sonuç döndürmek gibi başka kalıplar hata yönetimi sayfasındadır.

Top-Level await

Herhangi bir fonksiyonun dışındaki await yalnızca bir ES modülünde çalışır. CommonJS olarak derlenen bir dosya (bu örneklerde ve "type": "module" olmayan Node projelerinde durum budur) onu reddeder:

// This does not compile: top-level await in a CommonJS file.
const data = await Promise.resolve([1, 2, 3]);
console.log(data);

index.ts(2,14): error TS1309: The current file is a CommonJS module and cannot use 'await' at the top level.

Bu sayfadaki her örnekte olduğu gibi kodu async bir main fonksiyonuna sarın ve onu çağırın. Bir ES modülü projesinde (package.json içinde "type": "module" ile module değeri node16 ya da nodenext, veya bir bundler için module: "esnext") top-level await kullanılabilir.

Sıralı ve Paralel

Her await, sonraki satır başlamadan önce kendi promise'ini bekler. Birbirinden bağımsız çağrılar için önce hepsini başlatın, sonra Promise.all ile birlikte bekleyin:

const wait = (ms: number, label: string) =>
    new Promise<string>((resolve) => setTimeout(() => {
        console.log(`  finished ${label}`);
        resolve(label);
    }, ms));

async function main() {
    console.log("sequential:");
    const a = await wait(60, "a");
    const b = await wait(20, "b"); // starts only after a is done
    console.log(" ", [a, b]);

    console.log("parallel:");
    const [c, d] = await Promise.all([wait(60, "c"), wait(20, "d")]);
    console.log(" ", [c, d]); // results keep input order
}
main();

Sıralı bölümde b, a'dan önce bitemez çünkü henüz başlamamıştır. Paralel bölümde önce d biter ve toplam süre çağrıların toplamı değil, yaklaşık olarak en uzun çağrının süresidir. Promise.all yine de sonuçları girdi sırasıyla, bir tuple olarak tiplenmiş şekilde döndürür.

forEach Tuzağı

forEach, async bir callback'in döndürdüğü promise'i yok sayar, bu yüzden işi hiçbir şey beklemez:

const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));

async function main() {
    const ids = [1, 2, 3];

    ids.forEach(async (id) => {
        await sleep(10);
        console.log("forEach saved", id);
    });
    console.log("after forEach (runs first!)");
    await sleep(50); // only so the output above appears in order

    for (const id of ids) {
        await sleep(10);
        console.log("for...of saved", id);
    }
    console.log("after for...of (really after)");

    await Promise.all(ids.map(async (id) => {
        await sleep(10);
        console.log("map saved", id);
    }));
    console.log("after Promise.all (really after)");
}
main();

await ile for...of öğeleri tek tek işler; map ile Promise.all onları paralel çalıştırır ve hepsini bekler. forEach ikisini de yapmaz ve TypeScript uyarmaz, çünkü void döndürecek şekilde tiplenmiş bir callback, promise döndüren bir callback'i kabul eder.

for await ile Async İterasyon

for await...of, async generator gibi bir async iterable üzerinde döner ve her değeri bekler:

async function* pages(total: number): AsyncGenerator<string[]> {
    for (let page = 1; page <= total; page++) {
        await new Promise((r) => setTimeout(r, 10));
        yield [`item ${page}a`, `item ${page}b`];
    }
}

async function main() {
    for await (const batch of pages(3)) {
        console.log(batch.join(", ")); // batch: string[]
    }
}
main();

Eleman tipi, generator'ın AsyncGenerator<T> işaretlemesinden ya da işaretlemeyi yazmadığınızda tip çıkarımından gelir.