숏컷 코드

async function fetchName(): Promise<string> {
  return "Mina";
}

type Name = Awaited<ReturnType<typeof fetchName>>;

비동기 흐름

비동기 타입에서 먼저 봐 둘 기본형은 아래입니다.

• async function f(): Promise<T>
• function f(): Promise<T>
• const value = await f()
• const [a, b] = await Promise.all([...])
• type R = Awaited<Promise<T>>
• type R = Awaited<ReturnType<typeof f>>

1) async 함수는 값을 직접 반환해 보여도 타입은 Promise<T>

async를 붙인 함수는 내부에서 문자열이나 숫자를 return해도, 호출자 입장에서는 항상 Promise<T>를 받습니다. 반환 타입을 명시하지 않아도 TypeScript는 이 함수를 Promise 반환 함수로 추론합니다.

async function fetchCount(): Promise<number> {
  return 3;
}

즉 동기 함수처럼 보여도 계약은 비동기라는 점이 중요합니다.

2) await는 Promise 안쪽 타입으로 다시 좁힌다

await를 쓰면 TypeScript는 Promise가 감싼 안쪽 타입으로 다시 내려옵니다.

async function run() {
  const name = await fetchName(); // string
}

그래서 비동기 코드를 읽을 때는 "Promise냐 아니냐"보다 "await 이후 타입이 무엇이냐"가 더 실전적입니다.

3) Awaited<T>는 타입 수준에서 최종 결과를 추출한다

유틸리티 타입 Awaited<T>는 Promise가 감싼 최종 결과 타입을 계산합니다.

type Name = Awaited<Promise<string>>; // string

함수 반환 타입 재사용이나 비동기 래퍼 유틸 구현에서 특히 유용합니다.

4) 여러 비동기 결과를 묶으면 Promise.all 결과 타입도 같이 본다

비동기 작업을 함께 기다릴 때는 "Promise 배열"이 아니라, 최종적으로 어떤 값 구조가 돌아오는지를 같이 읽어야 합니다.

const [user, posts] = await Promise.all([
  fetchUser(),
  fetchPosts(),
]);

TypeScript는 이 지점에서 각 결과의 순서와 타입을 함께 추적하므로, 병렬 처리 코드에서는 반환 구조를 먼저 고정하는 편이 좋습니다.

5) 동기/비동기 혼용 API는 계약이 더 중요하다

어떤 함수는 바로 값을 돌려주고, 어떤 함수는 Promise를 돌려주면 호출자가 매번 흐름을 의식해야 합니다. 그래서 비동기 경계에서는 반환 타입을 더 분명하게 적는 편이 좋습니다.

function readSync(): string {
  return "done";
}

async function readAsync(): Promise<string> {
  return "done";
}

값 모양이 같아 보여도 호출 계약은 전혀 다르므로, 라이브러리나 shared util에서는 이 경계를 더 분명히 적는 편이 좋습니다.

언제 어떤 타입이 되나

체크포인트

• 비동기 함수 반환 타입이다: Promise<T>
• await 뒤 최종 값 타입을 본다: Awaited<T>
• 비동기 함수 반환값을 재사용한다: ReturnType + Awaited
• 동기/비동기 혼용 API다: 반환 계약 더 명확히 검토
• 값처럼 보인다고 바로 값 타입으로 읽지 않는다

주의할 점

async function getName() {
  return "Mina";
}

// ❌ string으로 착각
const name: string = getName();

// ✅ Promise<string> 또는 await 사용
const promise: Promise<string> = getName();

// ✅ 실제 값이 필요하면 await 이후 타입을 본다
async function main() {
  const name: string = await getName();
}