TypeScript는 강력한 타입 시스템을 제공하지만, 타입은 런타임에 제거됩니다. 타입 가드는 런타임에서 타입을 좁히면서 컴파일 타임의 타입 안전성을 유지합니다.
타입 가드란?
타입 가드는 조건 블록 내에서 변수의 타입을 좁히는 런타임 체크입니다.
// Without type guard — TypeScript only knows 'value' is string | number
function process(value: string | number) {
// value.toUpperCase(); // Error: Property 'toUpperCase' does not exist on type 'number'
// With type guard — TypeScript narrows the type
if (typeof value === 'string') {
console.log(value.toUpperCase()); // OK: value is string here
} else {
console.log(value.toFixed(2)); // OK: value is number here
}
}typeof 타입 가드
typeof 연산자는 가장 간단한 타입 가드입니다.
function formatValue(value: string | number | boolean): string {
if (typeof value === 'string') {
// TypeScript knows: value is string
return value.trim().toLowerCase();
}
if (typeof value === 'number') {
// TypeScript knows: value is number
return value.toLocaleString('en-US', { maximumFractionDigits: 2 });
}
// TypeScript knows: value is boolean
return value ? 'Yes' : 'No';
}
// typeof works for these primitive types:
// 'string' | 'number' | 'bigint' | 'boolean'
// 'symbol' | 'undefined' | 'object' | 'function'
// Caveat: typeof null === 'object'
function processNullable(value: string | null) {
if (typeof value === 'object') {
// value could be null here! typeof null === 'object'
}
if (value !== null && typeof value === 'object') {
// Safe: value is not null
}
}instanceof 타입 가드
instanceof는 객체가 클래스의 인스턴스인지 확인합니다.
class HttpError extends Error {
constructor(public statusCode: number, message: string) {
super(message);
this.name = 'HttpError';
}
}
class ValidationError extends Error {
constructor(public field: string, message: string) {
super(message);
this.name = 'ValidationError';
}
}
function handleError(error: Error) {
if (error instanceof HttpError) {
// TypeScript knows: error is HttpError
console.log(`HTTP ${error.statusCode}: ${error.message}`);
if (error.statusCode === 401) {
redirectToLogin();
}
} else if (error instanceof ValidationError) {
// TypeScript knows: error is ValidationError
console.log(`Validation failed on field: ${error.field}`);
highlightField(error.field);
} else {
// TypeScript knows: error is Error
console.log(`Unexpected error: ${error.message}`);
}
}
// instanceof with Date
function formatDate(input: string | Date): string {
if (input instanceof Date) {
return input.toISOString();
}
return new Date(input).toISOString();
}"in" 연산자 타입 가드
in 연산자는 속성의 존재를 확인합니다.
interface Bird {
fly(): void;
layEggs(): void;
}
interface Fish {
swim(): void;
layEggs(): void;
}
function move(animal: Bird | Fish) {
if ('fly' in animal) {
// TypeScript knows: animal is Bird
animal.fly();
} else {
// TypeScript knows: animal is Fish
animal.swim();
}
}
// Practical example: API responses
interface SuccessResponse {
data: unknown;
status: 'ok';
}
interface ErrorResponse {
error: string;
code: number;
}
function handleResponse(res: SuccessResponse | ErrorResponse) {
if ('error' in res) {
// TypeScript knows: res is ErrorResponse
console.error(`Error ${res.code}: ${res.error}`);
} else {
// TypeScript knows: res is SuccessResponse
processData(res.data);
}
}커스텀 타입 가드 함수
타입 술어를 반환하는 함수로 복잡한 체크를 캡슐화합니다.
// Type predicate syntax: paramName is Type
interface User {
id: string;
name: string;
email: string;
}
interface Admin extends User {
role: 'admin';
permissions: string[];
}
// Custom type guard function
function isAdmin(user: User): user is Admin {
return 'role' in user && (user as Admin).role === 'admin';
}
function showDashboard(user: User) {
if (isAdmin(user)) {
// TypeScript knows: user is Admin
console.log(`Admin: ${user.name}, Permissions: ${user.permissions.join(', ')}`);
renderAdminPanel(user.permissions);
} else {
// TypeScript knows: user is User (not Admin)
console.log(`User: ${user.name}`);
renderUserDashboard();
}
}
// Type guard for checking non-null
function isNotNull<T>(value: T | null | undefined): value is T {
return value !== null && value !== undefined;
}
// Use with .filter() to narrow array types
const items: (string | null)[] = ['hello', null, 'world', null];
const strings: string[] = items.filter(isNotNull);
// strings is string[] — no more nulls!
// Type guard for object shapes
function isValidUser(data: unknown): data is User {
return (
typeof data === 'object' &&
data !== null &&
'id' in data &&
'name' in data &&
'email' in data &&
typeof (data as User).id === 'string' &&
typeof (data as User).name === 'string' &&
typeof (data as User).email === 'string'
);
}판별 유니온
공통 리터럴 속성으로 유니온 멤버를 구별합니다.
// The discriminant property: 'type'
interface Circle {
type: 'circle';
radius: number;
}
interface Rectangle {
type: 'rectangle';
width: number;
height: number;
}
interface Triangle {
type: 'triangle';
base: number;
height: number;
}
type Shape = Circle | Rectangle | Triangle;
function calculateArea(shape: Shape): number {
switch (shape.type) {
case 'circle':
// TypeScript knows: shape is Circle
return Math.PI * shape.radius ** 2;
case 'rectangle':
// TypeScript knows: shape is Rectangle
return shape.width * shape.height;
case 'triangle':
// TypeScript knows: shape is Triangle
return (shape.base * shape.height) / 2;
}
}
// Real-world: Redux actions
type Action =
| { type: 'FETCH_START' }
| { type: 'FETCH_SUCCESS'; payload: User[] }
| { type: 'FETCH_ERROR'; error: string }
| { type: 'SET_FILTER'; filter: string };
function reducer(state: State, action: Action): State {
switch (action.type) {
case 'FETCH_START':
return { ...state, loading: true };
case 'FETCH_SUCCESS':
// TypeScript knows: action.payload exists and is User[]
return { ...state, loading: false, users: action.payload };
case 'FETCH_ERROR':
// TypeScript knows: action.error exists and is string
return { ...state, loading: false, error: action.error };
case 'SET_FILTER':
return { ...state, filter: action.filter };
}
}어설션 함수
어설션 실패 시 에러를 던져 타입을 좁힙니다.
// Assertion function syntax: asserts paramName is Type
function assertIsString(value: unknown): asserts value is string {
if (typeof value !== 'string') {
throw new TypeError(`Expected string, got ${typeof value}`);
}
}
// Usage: type narrows AFTER the assertion call
function processInput(input: unknown) {
assertIsString(input);
// TypeScript knows: input is string from here on
console.log(input.toUpperCase());
}
// Assert non-null
function assertDefined<T>(
value: T | null | undefined,
name: string
): asserts value is T {
if (value === null || value === undefined) {
throw new Error(`${name} must be defined`);
}
}
// Practical: Form validation
interface FormData {
name: unknown;
email: unknown;
age: unknown;
}
function assertValidForm(data: FormData): asserts data is {
name: string;
email: string;
age: number;
} {
if (typeof data.name !== 'string' || data.name.length === 0) {
throw new ValidationError('name', 'Name is required');
}
if (typeof data.email !== 'string' || !data.email.includes('@')) {
throw new ValidationError('email', 'Valid email is required');
}
if (typeof data.age !== 'number' || data.age < 0 || data.age > 150) {
throw new ValidationError('age', 'Valid age is required');
}
}
function handleSubmit(data: FormData) {
assertValidForm(data);
// TypeScript knows all fields are properly typed here
console.log(`Name: ${data.name}, Email: ${data.email}, Age: ${data.age}`);
}제어 흐름 타입 좁히기
TypeScript는 제어 흐름 분석으로 타입을 좁힙니다.
참/거짓 좁히기
참/거짓 체크에 기반하여 타입을 좁힙니다.
function greet(name: string | null | undefined) {
if (name) {
// TypeScript knows: name is string (not null/undefined)
console.log(`Hello, ${name.toUpperCase()}!`);
}
}
// Truthy narrowing with arrays
function processItems(items?: string[]) {
if (items && items.length > 0) {
// TypeScript knows: items is string[] (defined and non-empty)
const first = items[0]; // string
}
}
// Logical operators for narrowing
function getValue(a: string | null, b: string | null): string {
// || narrows: returns first truthy value
return a || b || 'default';
}
// Nullish coalescing for narrowing
function getConfig(config?: { timeout: number }) {
const timeout = config?.timeout ?? 3000;
// timeout is number (never undefined)
}동등성 좁히기
값 비교로 타입을 좁힙니다.
function example(x: string | number, y: string | boolean) {
if (x === y) {
// TypeScript knows: both x and y are string
// (the only common type)
console.log(x.toUpperCase());
console.log(y.toUpperCase());
}
}
// Equality narrowing with null
function process(value: string | null) {
if (value !== null) {
// TypeScript knows: value is string
console.log(value.length);
}
}
// Switch statement narrowing
function handleStatus(status: 'loading' | 'success' | 'error') {
switch (status) {
case 'loading':
showSpinner();
break;
case 'success':
hideSpinner();
break;
case 'error':
showError();
break;
}
}고급 타입 가드 패턴
never를 이용한 완전성 검사
never 타입으로 모든 케이스 처리를 보장합니다.
type Shape = Circle | Rectangle | Triangle;
function assertNever(x: never): never {
throw new Error(`Unexpected value: ${x}`);
}
function getArea(shape: Shape): number {
switch (shape.type) {
case 'circle':
return Math.PI * shape.radius ** 2;
case 'rectangle':
return shape.width * shape.height;
case 'triangle':
return (shape.base * shape.height) / 2;
default:
// If you add a new Shape variant and forget to handle it,
// TypeScript will error here because shape won't be 'never'
return assertNever(shape);
}
}
// Alternative: satisfies + exhaustive check
function describeShape(shape: Shape): string {
switch (shape.type) {
case 'circle': return `Circle with radius ${shape.radius}`;
case 'rectangle': return `${shape.width}x${shape.height} rectangle`;
case 'triangle': return `Triangle with base ${shape.base}`;
default: {
const _exhaustive: never = shape;
return _exhaustive;
}
}
}제네릭 타입 가드
모든 타입에 작동하는 제네릭 타입 가드를 만들 수 있습니다.
// Generic type guard for checking object keys
function hasProperty<K extends string>(
obj: unknown,
key: K
): obj is Record<K, unknown> {
return typeof obj === 'object' && obj !== null && key in obj;
}
// Usage
function processData(data: unknown) {
if (hasProperty(data, 'name') && hasProperty(data, 'age')) {
console.log(data.name, data.age); // both are 'unknown' but accessible
}
}
// Generic type guard for arrays
function isArrayOf<T>(
arr: unknown,
guard: (item: unknown) => item is T
): arr is T[] {
return Array.isArray(arr) && arr.every(guard);
}
const isString = (value: unknown): value is string =>
typeof value === 'string';
function handleInput(data: unknown) {
if (isArrayOf(data, isString)) {
// data is string[]
data.forEach(s => console.log(s.toUpperCase()));
}
}배열 타입 가드
Array.isArray()와 타입 안전한 filter 패턴을 사용합니다.
// Filtering with type guards
const mixed: (string | number | null)[] = ['a', 1, null, 'b', 2, null];
// Filter nulls with type predicate
const nonNull = mixed.filter(
(item): item is string | number => item !== null
);
// nonNull: (string | number)[]
// Filter to specific type
const stringsOnly = mixed.filter(
(item): item is string => typeof item === 'string'
);
// stringsOnly: string[]
// Type-safe .find()
const found = mixed.find(
(item): item is string => typeof item === 'string'
);
// found: string | undefined
// Array.isArray() type guard
function flatten(input: string | string[]): string[] {
if (Array.isArray(input)) {
return input; // string[]
}
return [input]; // wrap single string in array
}실제 예제
API 응답 처리
API 응답의 런타임 검증에 필수적입니다.
// API response types
interface ApiSuccess<T> {
success: true;
data: T;
}
interface ApiError {
success: false;
error: { message: string; code: string };
}
type ApiResponse<T> = ApiSuccess<T> | ApiError;
// Type guard based on discriminant
function isApiSuccess<T>(res: ApiResponse<T>): res is ApiSuccess<T> {
return res.success === true;
}
// Usage with fetch
async function fetchUser(id: string): Promise<User> {
const response = await fetch(`/api/users/${id}`);
const json: ApiResponse<User> = await response.json();
if (isApiSuccess(json)) {
return json.data; // TypeScript knows: json.data is User
} else {
throw new Error(json.error.message);
}
}
// Validate unknown API data
function isUser(data: unknown): data is User {
if (typeof data !== 'object' || data === null) return false;
const obj = data as Record<string, unknown>;
return (
typeof obj.id === 'string' &&
typeof obj.name === 'string' &&
typeof obj.email === 'string'
);
}이벤트 처리
DOM 이벤트 타입을 좁힙니다.
function handleEvent(event: Event) {
if (event instanceof MouseEvent) {
console.log(`Mouse at (${event.clientX}, ${event.clientY})`);
} else if (event instanceof KeyboardEvent) {
console.log(`Key pressed: ${event.key}`);
} else if (event instanceof TouchEvent) {
console.log(`Touch points: ${event.touches.length}`);
}
}
// Input element type narrowing
function handleInput(event: Event) {
const target = event.target;
if (target instanceof HTMLInputElement) {
console.log(target.value); // string
} else if (target instanceof HTMLSelectElement) {
console.log(target.selectedIndex); // number
}
}에러 처리
다양한 에러 타입을 타입 안전하게 처리합니다.
// Type guard for unknown caught errors
function isError(error: unknown): error is Error {
return error instanceof Error;
}
function getErrorMessage(error: unknown): string {
if (isError(error)) return error.message;
if (typeof error === 'string') return error;
return 'An unknown error occurred';
}
// Safe error handling in async code
async function safeFetch(url: string) {
try {
const res = await fetch(url);
if (!res.ok) throw new HttpError(res.status, res.statusText);
return await res.json();
} catch (error) {
if (error instanceof HttpError) {
handleHttpError(error); // error.statusCode available
} else if (error instanceof TypeError) {
handleNetworkError(error); // Network failure
} else {
handleUnknownError(getErrorMessage(error));
}
}
}모범 사례
- 가능하면 판별 유니온 우선.
- 타입 가드 함수를 단순하게.
- 앱 경계에서 어설션 함수 사용.
- else 케이스를 항상 처리.
- 유니온 타입에서 Array.isArray() 사용.
- 여러 타입 가드를 조합.
- 커스텀 타입 가드를 철저히 테스트.
결론
TypeScript 타입 가드는 컴파일 타임 타입 안전성과 런타임 동작의 격차를 메우는 필수 도구입니다. 이러한 패턴을 마스터하여 타입 안전하고 견고한 코드를 작성하세요.
FAQ
타입 술어와 어설션 함수의 차이는?
타입 술어는 boolean을 반환하고, 어설션 함수는 에러를 던져 타입을 좁힙니다.
판별 유니온과 커스텀 타입 가드는 언제 사용하나요?
타입을 제어할 수 있을 때는 판별 유니온, 외부 데이터에는 타입 가드.
타입 가드가 런타임 에러를 일으킬 수 있나요?
커스텀 타입 가드의 로직이 부정확하면 에러가 발생할 수 있습니다.
배열 내 타입을 어떻게 좁히나요?
Array.isArray()와 타입 술어가 있는 .filter()를 사용합니다.