TypeScript 타입 가드: 객체의 타입 확인하기

타입 가드는 TypeScript가 이해하는 런타임 검사로, 검사한 분기 안에서 타입을 좁힙니다. typeof, instanceof, in은 내장 가드이고, 그 밖의 경우에는 반환 타입이 타입 서술어 value is Type인 함수를 작성합니다.

interface User {
  name: string;
  age: number;
}

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" && value !== null &&
    "name" in value && typeof value.name === "string" &&
    "age" in value && typeof value.age === "number"
  );
}

const inputs: unknown[] = [{ name: "Ada", age: 36 }, { name: "Bob" }, "Ada", null];

for (const input of inputs) {
  if (isUser(input)) {
    console.log(`${input.name} is ${input.age}`); // input: User
  } else {
    console.log("not a user:", input);
  }
}

isUser는 런타임에 평범한 불리언을 반환합니다. 반환 타입 value is User는 true 결과가 무엇을 증명하는지 컴파일러에 알려 주고, 그러면 모든 if (isUser(x))가 x를 User로 좁힙니다.

내장 타입 가드

다음 검사는 헬퍼 함수 없이 좁힙니다.

모두 평범한 JavaScript로 실행됩니다. TypeScript가 더하는 것은 좁히기입니다. 검사를 읽고 각 분기의 타입을 조정합니다. 전체 형태 목록은 타입 좁히기 페이지에 있습니다. 직접 만드는 가드는 표현식 하나에 담기지 않거나 재사용하고 싶은 검사를 위한 것입니다.

타입 서술어 작성하기

타입 서술어는 parameterName is Type 형태이며 반환 타입 boolean을 대신합니다. 좁히기는 양방향으로 동작합니다. true는 Type으로 좁히고, false는 유니언에서 Type을 없앱니다.

type Cat = { kind: "cat"; meow: () => string };
type Dog = { kind: "dog"; bark: () => string };
type Pet = Cat | Dog;

function isCat(pet: Pet): pet is Cat {
  return pet.kind === "cat";
}

function speak(pet: Pet): string {
  if (isCat(pet)) {
    return pet.meow(); // pet: Cat
  }
  return pet.bark();   // pet: Dog (Cat was ruled out)
}

const pets: Pet[] = [
  { kind: "cat", meow: () => "meow" },
  { kind: "dog", bark: () => "woof" },
];

console.log(pets.map(speak));             // [ 'meow', 'woof' ]
console.log(pets.filter(isCat).length);   // 1 (and the result is typed Cat[])

가드를 filter에 넘기면 타입이 올바른 배열을 얻습니다. TypeScript 5.5부터는 컴파일러가 단순한 화살표 함수에서도 서술어를 추론하므로, 이름 있는 가드 없이도 pets.filter((p) => p.kind === "cat")가 Cat[]를 반환합니다.

서술어의 타입은 매개변수의 타입에 맞아야 합니다. function f(x: string): x is number는 오류 TS2677, A type predicate's type must be assignable to its parameter's type.입니다.

컴파일러는 가드를 믿는다

TypeScript는 가드가 불리언을 반환하는지 검사합니다. 그 불리언이 옳은지는 검사하지 않습니다. 잘못된 값에 true를 반환하는 가드는 타입을 거짓말하게 만들고, 프로그램은 컴파일 오류 없이 런타임에 실패합니다.

interface Product {
  title: string;
  price: number;
}

// Wrong: only checks title, never price
function isProduct(value: unknown): value is Product {
  return typeof value === "object" && value !== null && "title" in value;
}

const data: unknown = { title: "Lamp" };

if (isProduct(data)) {
  console.log(data.title); // Lamp
  try {
    console.log(data.price.toFixed(2)); // compiles, but throws at run time
  } catch (e) {
    console.log(e instanceof Error ? e.message : e);
    // Cannot read properties of undefined (reading 'toFixed')
  }
}

data.price.toFixed(2)는 런타임에 TypeError: Cannot read properties of undefined (reading 'toFixed')를 던집니다. 가드가 그렇다고 했으므로 컴파일러는 data.price를 number로 받아들였습니다. 나머지 코드가 기대는 모든 속성을 확인하고, 가드는 작게, 테스트를 거쳐, 그것이 기술하는 타입 가까이에 두세요.

객체가 어떤 타입인지 확인하기

대부분의 직접 만든 가드 뒤에 있는 질문입니다. 데이터가 unknown으로 도착하고(JSON.parse, fetch, localStorage, 메시지에서) 그것이 인터페이스에 맞는지 알아야 합니다. 방법은 이렇습니다.

1. typeof value === "object" && value !== null(null이 아닌 객체).
2. 필수 속성마다 "prop" in value. unknown에 대해 in은 그 속성을 unknown 타입으로 타입에 추가합니다.
3. 속성마다 그 타입에 대한 typeof value.prop === "..."(또는 중첩 가드).
4. 배열에는 Array.isArray(value.items) && value.items.every(isItem).

interface Order {
  id: string;
  lines: { sku: string; qty: number }[];
}

function isLine(v: unknown): v is Order["lines"][number] {
  return typeof v === "object" && v !== null &&
    "sku" in v && typeof v.sku === "string" &&
    "qty" in v && typeof v.qty === "number" && Number.isInteger(v.qty);
}

function isOrder(v: unknown): v is Order {
  return typeof v === "object" && v !== null &&
    "id" in v && typeof v.id === "string" &&
    "lines" in v && Array.isArray(v.lines) && v.lines.every(isLine);
}

const good: unknown = JSON.parse('{"id":"A1","lines":[{"sku":"pen","qty":2}]}');
const bad: unknown = JSON.parse('{"id":"A2","lines":[{"sku":"pen","qty":"2"}]}');

console.log(isOrder(good), isOrder(bad)); // true false
if (isOrder(good)) console.log(good.lines[0].qty * 3); // 6

모양이 크거나 깊이 중첩되어 있으면 이것을 손으로 쓰기가 번거로워집니다. Zod나 Valibot 같은 스키마 라이브러리를 쓰면 모양을 한 번 기술하고 런타임 검사와 TypeScript 타입을 둘 다 얻을 수 있습니다.

단언 함수: asserts value is Type

단언 함수는 검사가 실패하면 예외를 던지고, 그렇지 않으면 정상적으로 반환합니다. 반환 타입은 asserts value is Type(또는 asserts condition)이며, if 없이도 호출 뒤의 모든 곳이 좁혀집니다.

function assertIsString(value: unknown, name: string): asserts value is string {
  if (typeof value !== "string") {
    throw new TypeError(`${name} must be a string, got ${typeof value}`);
  }
}

function assert(condition: unknown, message: string): asserts condition {
  if (!condition) throw new Error(message);
}

function greet(input: unknown, count: number | null): string {
  assertIsString(input, "input");
  assert(count !== null, "count is required");
  // input: string, count: number
  return input.toUpperCase().repeat(count);
}

console.log(greet("hi", 2)); // HIHI

try {
  greet(42, 1);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // input must be a string, got number
}

사람들이 걸려 넘어지는 규칙이 하나 있습니다. 단언 함수는 명시적 타입이 있는 이름을 통해 호출해야 합니다. 표기 없는 const 화살표 함수 const check = (v: unknown): asserts v is string => {...}는 호출한 곳에서 오류 TS2775, Assertions require every name in the call target to be declared with an explicit type annotation.를 냅니다. function 선언을 쓰거나, 상수에 함수 타입을 표기하세요.

가드, 단언, 캐스트 비교

타입 단언(as)은 아무것도 검사하지 않고 타입을 바꿉니다. 외부에서 데이터가 들어오는 경계에서는 가드나 단언 함수가 같은 생각의 안전한 버전입니다.

클래스의 this 기반 가드

메서드는 this is Type으로 자신이 호출된 객체를 좁힐 수 있습니다. 클래스 계층에서 편리합니다.

class FileNode {
  constructor(public name: string) {}
  isDirectory(): this is DirectoryNode {
    return this instanceof DirectoryNode;
  }
}

class DirectoryNode extends FileNode {
  children: FileNode[] = [];
}

function count(node: FileNode): number {
  return node.isDirectory() ? node.children.length : 0; // node: DirectoryNode in the true branch
}