SHIN STORYSHIN STORY
홈포스트C#TypeScriptNext.jsNode.js시리즈
</>SHIN STORY

sdf

탐색

  • 홈
  • 모든 포스트
  • 시리즈
  • 검색

카테고리

  • C#
  • TypeScript
  • Next.js
  • Node.js
  • 알고리즘
  • 개발 도구

© 2025 Shin Blog. All rights reserved.

GitHubRSS
목록으로
TypeScript#TypeScript

TypeScript 팁 #5 — 타입 가드로 런타임 타입 좁히기

SHIN

2025년 4월 23일5분 읽기0
📚

TypeScript 실전 팁 10선

10편
  1. TypeScript 팁 #5 — 타입 가드로 런타임 타입 좁히기현재
  2. 6TypeScript 팁 #6 — 매핑 타입으로 타입 변환하기
  3. 10TypeScript 팁 #1 — strict 모드를 반드시 켜야 하는 이유
  4. 10TypeScript 팁 #2 — 유틸리티 타입 완전 정복
  5. 10TypeScript 팁 #3 — 판별 유니온으로 타입 안전한 상태 관리
  6. 10TypeScript 팁 #4 — 제네릭 제약 조건과 infer 활용
  7. 10TypeScript 팁 #7 — 템플릿 리터럴 타입으로 문자열 타입 조작
  8. 10TypeScript 팁 #8 — 선언 병합과 모듈 보강으로 타입 확장하기
  9. 10TypeScript 팁 #9 — 타입 안전한 에러 처리 패턴
  10. 10TypeScript 팁 #10 — 타입 성능 최적화와 실무 패턴

TypeScript 팁 #5 — 타입 가드로 런타임 타입 좁히기

TypeScript의 타입 시스템은 런타임까지 유지되지 않습니다. 외부 API 응답, 사용자 입력 등 런타임 데이터의 타입을 좁힐 때는 타입 가드가 필요합니다.

기본 타입 가드

CODE
function format(value: string | number) {
  if (typeof value === 'string') {
    return value.toUpperCase()  // string으로 좁혀짐
  }
  return value.toFixed(2)       // number로 좁혀짐
}

instanceof 가드

CODE
class ApiError extends Error {
  constructor(public code: number, message: string) {
    super(message)
  }
}

function handleError(err: unknown) {
  if (err instanceof ApiError) {
    console.error(`API 오류 ${err.code}: ${err.message}`)
  } else if (err instanceof Error) {
    console.error(err.message)
  } else {
    console.error('알 수 없는 오류')
  }
}

in 연산자 가드

CODE
interface Cat { meow(): void }
interface Dog { bark(): void }

function makeSound(animal: Cat | Dog) {
  if ('meow' in animal) {
    animal.meow()  // Cat으로 좁혀짐
  } else {
    animal.bark()  // Dog으로 좁혀짐
  }
}

사용자 정의 타입 가드 (is)

반환 타입에 parameterName is Type을 명시하면 if 블록 안에서 타입이 자동으로 좁혀집니다.

CODE
interface User   { type: 'user';  name: string }
interface Admin  { type: 'admin'; name: string; permissions: string[] }

type Person = User | Admin

function isAdmin(person: Person): person is Admin {
  return person.type === 'admin'
}

function greet(person: Person) {
  if (isAdmin(person)) {
    // Admin으로 좁혀짐
    console.log(`관리자 ${person.name}, 권한: ${person.permissions.join(', ')}`)
  } else {
    // User로 좁혀짐
    console.log(`사용자 ${person.name}`)
  }
}

API 응답 검증 타입 가드

CODE
interface ApiUser {
  id: number
  name: string
  email: string
}

function isApiUser(data: unknown): data is ApiUser {
  return (
    typeof data === 'object' &&
    data !== null &&
    typeof (data as any).id === 'number' &&
    typeof (data as any).name === 'string' &&
    typeof (data as any).email === 'string'
  )
}

async function fetchUser(id: number) {
  const res = await fetch(`/api/users/${id}`)
  const data: unknown = await res.json()

  if (!isApiUser(data)) {
    throw new Error('잘못된 API 응답')
  }

  // 여기서부터 data는 ApiUser
  return data
}

Assertion Function — 오류를 던지는 가드

CODE
function assertIsString(val: unknown): asserts val is string {
  if (typeof val !== 'string') {
    throw new TypeError(`Expected string, got ${typeof val}`)
  }
}

function processInput(input: unknown) {
  assertIsString(input)
  // 여기서부터 input은 string
  console.log(input.toUpperCase())
}

Zod로 런타임 검증 + 타입 추론

실제 프로젝트에서는 타입 가드를 직접 작성하기보다 Zod 같은 스키마 라이브러리를 활용합니다.

CODE
import { z } from 'zod'

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
})

type User = z.infer<typeof UserSchema>  // 스키마에서 타입 자동 추출

const parsed = UserSchema.safeParse(apiResponse)
if (parsed.success) {
  console.log(parsed.data.name)  // User 타입으로 좁혀짐
}

타입 가드는 TypeScript와 런타임 세계 사이의 다리 역할을 합니다. 외부 데이터를 다룰 때는 반드시 검증 후 사용하세요.

공유
S

SHIN

.NET 개발자입니다

GitHub
TypeScript 팁 #4 — 제네릭 제약 조건과 infer 활용

이전 포스트

TypeScript 팁 #4 — 제네릭 제약 조건과 infer 활용

다음 포스트

TypeScript 팁 #6 — 매핑 타입으로 타입 변환하기

같은 카테고리 포스트

TypeScript 팁 #10 — 타입 성능 최적화와 실무 패턴

TypeScript 팁 #10 — 타입 성능 최적화와 실무 패턴

2025년 5월 3일· 3분
TypeScript 팁 #9 — 타입 안전한 에러 처리 패턴

TypeScript 팁 #9 — 타입 안전한 에러 처리 패턴

2025년 5월 1일· 2분
TypeScript 팁 #8 — 선언 병합과 모듈 보강으로 타입 확장하기

TypeScript 팁 #8 — 선언 병합과 모듈 보강으로 타입 확장하기

2025년 4월 29일· 2분

댓글