Typescript에서 Object.keys()가 항상 string[] 타입인 이유

type Product = "apple" | "banana" | "orange";

const menu: Record<Product, number> = {
    apple: 1000,
    banana: 2000,
    orange: 1500
};

const products = Object.keys(menu);
// products의 타입은?

위와 같은 Typescript 코드에서, `products`의 타입은 뭘로 추론될까? `menu`는 `Record<Product, number>` 타입의 객체니까, 이 객체의 키의 타입은 Product일 것이다. `Object.keys()` 메소드는 객체의 모든 키를 배열로 반환하는 메소드이다. 따라서 `products`의 타입은 `Product[]`로 추론되는 것이 마땅하다.

 

하지만, 이 글의 제목에도 나와있다시피, 정답은 `string[]`이다. 직접 확인해보고 싶으시다면 TS Playground에서 확인해볼 수 있다.

 

이유가 뭘까? `menu`의 키는 `Product` 타입임이 확실하지 않나? 그런데 왜 굳이 더 넓은 범위인 `string[]`으로 추론되는 것일까? 실제로 이 현상을 버그라고 생각한 한 사람이 Typescript 레포지토리에 이슈를 올린 적이 있다.

 

This is intentional. Types in TS are open ended. So keysof will likely be less than all properties you would get at runtime.

 

답변은 단호했다. 의도적인 설계라고 말한다. 도무지 납득할 수 없다. 그 이유는 무엇일까?

 

📌 Typescript의 구조적 타이핑

TypeScript의 핵심 철학 중 하나는 구조적 타이핑이다. 이는 타입 정의가 "이 속성들만 가지고 있어야 한다."가 아니라, "적어도 이 속성들은 가지고 있어야 한다"는 의미다.

 

이해를 돕기 위해 아래 예시를 봐보자.

interface Person {
  name: string;
}

const student = {
  name: "Sean",
  grade: 3,
};

const person: Person = student;

`person` 변수는 `Person` 타입으로 선언되었지만, 실제 런타임에는 `grade`라는 추가 속성을 가진 객체가 할당될 수 있다. 타입스크립트의 타입은 객체의 모든 형태를 확정 짓는 것이 아니라, 최소한의 조건을 검사할 뿐이다.

 

💣  만약 string[]이 아니라면

Object.keys(person).forEach((key) => {
  console.log(person[key].toUpperCase());
});

Typescript가 `Object.keys(person)`의 타입을 `("name")[]`으로 추론한다고 가정하자.

• 반복문 내의 `key`는 무조건 "name"이라고 추론된다.
• 반복문 내의 `person[key]`는 무조건 `string`으로 추론된다.
• `string`에는 `toUpperCase()` 메소드가 있기 때문에, 오류가 없다 !

하지만 실제로 런타임에서의 상황을 살펴보자.

• 반복문 내의 `key`는 "name"일 수도, "grade"일 수도 있다.
• 반복문 내의 `person[key]`는 `string`일 수도, `number`일 수도 있다.
• `number`에는 `toUpperCase()` 메소드가 없기 때문에, 런타임 오류가 발생한다 !

결과적으로 개발자는 컴파일러를 믿고 `toUpperCase()` 메소드를 썼지만, 런타임 에러가 발생하는 것이다. 이러한 이유에서 Typescript는 `Object.keys()` 메소드의 반환 타입을 `string[]`으로 설정하는 보수적인 선택을 한 것이다.

 

✅ 해결법

방법 1. 타입 단언

const products = Object.keys(menu) as Product[];

가장 간단하지만, 개발자가 실수하면 런타임 에러로 이어질 수 있다.

 

방법 2. 타입 가드 + 필터링

type Product = "apple" | "banana" | "orange";
const PRODUCT_KEYS: Product[] = ["apple", "banana", "orange"];

const menu = {
  apple: 1000,
  banana: 2000,
  orange: 1500,
  grade: 3
};

function isProductKey(key: string): key is Product {
  return PRODUCT_KEYS.includes(key);
}

const safeKeys = Object.keys(menu).filter(isProductKey);

 

키 배열을 미리 만들어두고, `Object.keys`로 나온 키들이 그 목록에 있는지 확인해서 걸러내는 방법이다. 이 방식을 쓰면 예상하지 않은 키(`grade`)가 객체에 섞여 있어도 filter() 메소드에서 걸러진다. 따라서 결과 배열에는 `Product`만 남게 되고, `safeKeys` 역시 타입 가드에 의해 `Product[]` 타입으로 추론된다.

 

하지만 `PRODUCT_KEYS`라는 배열을 따로 관리해야 한다는 번거로움이 있다.

 

방법 3. Zod 사용하기

import { z } from "zod";

const ProductSchema = z.enum(["apple", "banana", "orange"]);
type Product = z.infer<typeof ProductSchema>;

const menu = {
  apple: 1000,
  banana: 2000,
  grade: 3,
};

const keys = Object.keys(menu);

const safeKeys = keys.filter((key): key is Product => {
  const result = ProductSchema.safeParse(key);
  return result.success;
});

console.log(safeKeys);

키 배열 생성과 검증 로직을 Zod에게 맡기는 방법이다. 키 배열을 따로 만들 필요도 없고, 필터링 로직도 직접 구현할 필요가 없어서 그나마 편하긴 하다. 그러나 런타임 시 검증 비용이 조금 발생할 수도 있고, 역시나 코드 길이가 길어진다는 단점은 존재한다.

 

결국에는 안전성과 편의성의 트레이드오프인 것 같다. 상황에 따라 개발자가 적절히 선택하는 것이 맞아 보인다.

 

💡 결론

TypeScript가 `Object.keys()`를 `string[]`으로 추론하는 것은 버그가 아니라, 구조적 타이핑으로부터 발생하는 런타임 에러를 방지하기 위한 안전 장치이다.

 

불편하게 느껴질 수도 있지만, 이는 Typescript가 프로그램의 안전성을 보장하기 위한 태도이기도 하다. 이 원리를 이해하고 위에서 언급한 해결법을 적절히 적용하는 것이 현명한 사용법일 것이다.