TypeScript async/await: 타입, 에러 처리, 병렬 호출

TypeScript에서 async 함수는 항상 Promise를 반환합니다. 본문이 string을 반환하면 타입은 Promise<string>입니다. 그 안에서 await는 Promise<T>를 T로 풉니다.

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

런타임 동작(await가 무엇을 멈추는지, 이벤트 루프)은 JavaScript의 영역이며 JavaScript async/await에서 다룹니다. TypeScript가 맡는 것은 들어가고 나오는 타입입니다.

async 함수의 반환 타입

async 함수의 선언된 반환 타입은 본문이 평범한 값을 반환하더라도 Promise<...>여야 합니다. 생략하면 TypeScript가 추론합니다.

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라고 쓰면 TS1064 오류(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>는 풀린 타입을 줍니다. Awaited<ReturnType<typeof count>>는 number입니다.

await를 빠뜨렸을 때

await를 빠뜨리면 T 대신 Promise<T>를 들고 있게 됩니다. 타입이 더 이상 맞지 않으므로 TypeScript가 대부분 잡아냅니다.

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) 버그는 실제로 일어납니다. Promise 객체는 항상 truthy이므로 접근을 허용해 버렸습니다. TypeScript는 이를 TS2801로 보고합니다. Promise를 boolean 변수에 대입하거나 Promise에 없는 속성을 읽어도 컴파일에 실패합니다. 결과를 무시하는 호출(save(user);)은 잡히지 않으며, typescript-eslint의 no-floating-promises 규칙이 이를 담당합니다.

try/catch로 에러 처리하기

거부된 Promise는 await에서 예외를 던지므로 평범한 try/catch가 동작합니다. strict에서 catch의 변수는 unknown이므로 .message를 읽기 전에 좁혀야 합니다.

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

async 함수 안의 throw는 호출한 곳에서 예외를 던지는 것이 아니라 그 함수의 Promise를 거부합니다. 사용자 정의 에러 클래스, 예외 대신 결과 반환하기 등 더 많은 패턴은 에러 처리 페이지에 있습니다.

최상위 await

함수 밖의 await는 ES 모듈에서만 동작합니다. CommonJS로 컴파일되는 파일(이 예제들, 그리고 "type": "module"이 없는 Node 프로젝트가 해당합니다)에서는 거부됩니다.

// 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.

이 페이지의 모든 예제처럼 코드를 async main 함수로 감싸서 호출하세요. ES 모듈 프로젝트(package.json에 "type": "module"이 있고 module이 node16이나 nodenext이거나, 번들러용으로 module: "esnext"인 경우)에서는 최상위 await가 허용됩니다.

순차 실행 vs 병렬 실행

각 await는 다음 줄이 시작되기 전에 자신의 Promise를 기다립니다. 서로 독립적인 호출이라면 모두 먼저 시작하고 Promise.all로 한꺼번에 await하세요.

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

순차 실행 부분에서 b는 아직 시작하지도 않았으므로 a보다 먼저 끝날 수 없습니다. 병렬 실행 부분에서는 d가 먼저 끝나고, 전체 시간은 합계가 아니라 가장 긴 호출 정도입니다. 그래도 Promise.all은 결과를 입력 순서대로, 튜플 타입으로 반환합니다.

forEach 함정

forEach는 async 콜백이 반환하는 Promise를 무시하므로 아무것도 작업을 기다리지 않습니다.

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와 함께 쓰는 for...of는 항목을 하나씩 처리하고, map과 함께 쓰는 Promise.all은 병렬로 실행한 뒤 모두 기다립니다. forEach는 어느 쪽도 하지 않으며, void를 반환하도록 타입 지정된 콜백은 Promise를 반환하는 콜백도 받아들이므로 TypeScript는 경고하지 않습니다.

for await로 비동기 순회하기

for await...of는 async 제너레이터 같은 비동기 이터러블을 순회하며 각 값을 await합니다.

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

요소 타입은 제너레이터의 AsyncGenerator<T> 타입 표기에서 오며, 생략하면 추론됩니다.