[TypeScript] Type Narrowing (Type Guards)

TypeScript Narrowing, TypeScript Type Guards, TS narrowing, type predicate, user-defined type guard, asserts type guard, assertion function, TypeScript 타입 가드

정의

Type Narrowing 은 TypeScript 컴파일러가 제어 흐름 분석 (control flow analysis) 을 통해 특정 위치에서 값의 타입을 더 좁게 추론하는 기능입니다. typeof, instanceof, in, 리터럴 비교, 사용자 정의 type guard 로 union 을 각 branch 별 구체 타입으로 좁힙니다.

typeof narrowing

primitive 타입 (string, number, boolean, bigint, symbol, undefined, object, function) 검사.

function padLeft(padding: number | string, input: string): string {
  if (typeof padding === "number") {
    return " ".repeat(padding) + input;   // padding: number
  }
  return padding + input;                  // padding: string
}

instanceof narrowing

class Cat { meow() {} }
class Dog { bark() {} }

function pet(x: Cat | Dog): void {
  if (x instanceof Cat) {
    x.meow();     // x: Cat
  } else {
    x.bark();     // x: Dog
  }
}

함정: interface 는 instanceof 못 씀 (런타임에 없음). class 여야 함.

in operator

객체에 특정 필드가 있는지 검사.

type Cat = {meow(): void};
type Dog = {bark(): void};

function pet(x: Cat | Dog): void {
  if ("meow" in x) {
    x.meow();     // x: Cat
  } else {
    x.bark();     // x: Dog
  }
}

Interface (런타임 정보 없음) 에도 적용 가능.

Truthiness narrowing

function getLength(s: string | null | undefined): number {
  if (s) {
    return s.length;    // s: string (null, undefined, "" 배제)
  }
  return 0;
}

주의: if (s) 는 falsy 모두 배제. "", 0, false, NaN, null, undefined. 명시적으로 원하는 것만 배제:

if (s !== null && s !== undefined) { ... }
if (s != null) { ... }              // == null 은 null + undefined

Equality narrowing

리터럴 비교로 좁힘:

function example(x: string | number, y: string | boolean): void {
  if (x === y) {
    // 둘 다 string 이어야 == 가능
    x.toUpperCase();   // x: string
    y.toUpperCase();   // y: string
  }
}

Discriminated Union

Union 의 각 case 에 리터럴 필드 (discriminant) 를 두어 좁힘.

type Shape =
  | {kind: "circle"; radius: number}
  | {kind: "square"; side: number};

function area(s: Shape): number {
  if (s.kind === "circle") {
    return Math.PI * s.radius ** 2;   // s: {kind: "circle", radius: number}
  }
  return s.side ** 2;                  // s: {kind: "square", side: number}
}

자세한 것은 Union / Intersection 참조.

Assignment narrowing

let x: string | number;
x = "hello";
x.toUpperCase();     // x: string
x = 42;
x.toFixed(2);         // x: number

Assignment 이후 실제 타입으로 좁혀짐. 이 좁힘은 다음 재할당까지 유효.

Control flow analysis

TypeScript 는 return, throw, continue 등을 인식.

function process(x: string | null): string {
  if (x === null) {
    throw new Error("null!");
  }
  return x.toUpperCase();    // x: string (null 은 throw 로 배제됨)
}

User-Defined Type Guard (is)

함수의 return type 을 arg is Type 으로 선언하면 컴파일러가 그 함수를 type guard 로 인식.

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

function isCat(x: Cat | Dog): x is Cat {
  return "meow" in x;
}

function pet(x: Cat | Dog): void {
  if (isCat(x)) {
    x.meow();     // x: Cat
  } else {
    x.bark();     // x: Dog
  }
}

실전 예시

function isNonNull<T>(v: T | null | undefined): v is T {
  return v != null;
}

const users = [user1, null, user3, undefined, user5];
const validUsers = users.filter(isNonNull);
// validUsers: User[] (User | null | undefined 에서 좁혀짐)

배열 filter narrowing (TS 5.5+)

TypeScript 5.5 부터는 filter 안 predicate 를 자동으로 type guard 로 인식:

const validUsers = users.filter((u): u is User => u != null);
// 또는 5.5+ 에서는 자동
const validUsers = users.filter(u => u != null);

Assertion Function (asserts)

함수가 조건 검증에 실패하면 예외 던짐. 이후 코드는 조건이 참이라고 가정.

function assertNumber(x: unknown): asserts x is number {
  if (typeof x !== "number") {
    throw new Error("not a number");
  }
}

function process(x: unknown): void {
  assertNumber(x);
  x.toFixed(2);    // x: number (이 시점부터 좁혀짐)
}

assertNever (exhaustive check)

function assertNever(x: never): never {
  throw new Error(`unexpected: ${x}`);
}

function area(s: Shape): number {
  switch (s.kind) {
    case "circle": return Math.PI * s.radius ** 2;
    case "square": return s.side ** 2;
    default: return assertNever(s);
  }
}

새 case 를 추가하면 컴파일 시 오류. Discriminated union 의 필수 도구.

비타 - Node.js assert 모듈과 통합

import assert from "node:assert";

function process(x: unknown): void {
  assert(typeof x === "string");
  x.toUpperCase();    // x: string
}

node:assert 는 asserts 를 반환하므로 자동 narrowing 대상.

Array narrowing

function last<T>(arr: T[]): T | undefined {
  if (arr.length > 0) {
    return arr[arr.length - 1];   // 여전히 T | undefined
  }
  return undefined;
}

arr.length > 0 은 배열의 element 타입에 영향 없음 (T[] 여도 arr[i] 는 T | undefined 로 좁혀지지 않음. 그럼에도 접근 가능한 이유는 strictNullChecks 만으로는 noUncheckedIndexedAccess 없이 배열 접근이 T 로 낙관 취급됨).

noUncheckedIndexedAccess: true 활성 시 arr[i] 는 T | undefined.

in-operator narrowing 심화

TS 4.9+: in 이 optional 필드도 좁힘.

type Cat = {meow(): void; name?: string};
type Dog = {bark(): void; name?: string};

function example(x: Cat | Dog): void {
  if ("meow" in x) {
    x.meow();
    // x.name?: string  (optional 필드)
  }
}

Class field narrowing

class Animal {
  static isCat(x: Animal): x is Cat {
    return x instanceof Cat;
  }
}

Static method 로 type guard.

함정

관련 위키

• TypeScript - 상위 개요
• Primitive Types - typeof
• Union / Intersection - Discriminated union
• Interfaces - in narrowing
• Generics - Generic type guard
• Conditional Types
• Utility Types - NonNullable
• Strict Mode - strictNullChecks
• JavaScript null/undefined