TypeScript Record 타입: Record<K, V> 사용법과 예제

Record<K, V>는 키가 K 타입이고 값이 모두 V 타입인 객체를 나타내는 내장 유틸리티 타입입니다. string 키를 쓰면 딕셔너리를, 리터럴 유니언 키를 쓰면 정확히 그 키들을 가져야 하는 객체를 표현합니다.

// Any string key, number values
const stock: Record<string, number> = { apples: 12, pears: 0 };
stock.plums = 7;

// Exactly these three keys, each with a string value
type Lang = "en" | "de" | "fr";
const greeting: Record<Lang, string> = {
  en: "Hello",
  de: "Hallo",
  fr: "Bonjour",
};

console.log(stock);          // { apples: 12, pears: 0, plums: 7 }
console.log(greeting.de);    // Hallo

Record는 타입 시스템에만 존재합니다. 런타임에서 두 객체는 평범한 JavaScript 객체이므로 객체 리터럴, 스프레드, JSON.stringify 등 객체를 받는 모든 곳에서 동작합니다.

문법과 정의

Record<Keys, Value>

Keys는 객체 키가 될 수 있는 것이어야 합니다. string, number, symbol, 문자열이나 숫자 리터럴의 유니언, 템플릿 리터럴 타입입니다. Value는 어떤 타입이든 됩니다. TypeScript 표준 라이브러리의 정의 전체는 매핑된 타입 한 줄입니다.

type Record<K extends keyof any, T> = {
  [P in K]: T;
};

keyof any는 가능한 모든 키 타입의 집합인 string | number | symbol입니다. [P in K]: T는 K의 멤버마다 T 타입 속성을 하나씩 만듭니다. 아래의 두 동작이 모두 여기서 나옵니다. string 같은 넓은 K는 인덱스 시그니처(아무 키나 가능)를 만들고, 유니언 K는 멤버마다 필수 속성을 하나씩 만듭니다.

유니언 키: 모든 키가 필수

키가 리터럴의 유니언이면 Record는 그 키를 빠짐없이, 그리고 그 키만 나열해야 합니다. 컴파일러가 체크리스트가 되는 셈입니다.

type Status = "idle" | "loading" | "success" | "error";

const label: Record<Status, string> = {
  idle: "Ready",
  loading: "Loading...",
  success: "Done",
  error: "Something went wrong",
};

const color: Record<Status, `#${string}`> = {
  idle: "#888888",
  loading: "#3b82f6",
  success: "#16a34a",
  error: "#dc2626",
};

function render(s: Status): string {
  return `${label[s]} (${color[s]})`;
}

console.log(render("success")); // Done (#16a34a)

Status에 "cancelled"를 추가하면 새 상태에 라벨과 색을 줄 때까지 두 객체 모두 컴파일되지 않습니다. 키를 빠뜨리거나 유니언에 없는 키를 추가하면 컴파일 오류입니다.

// This does not compile: one key is missing and one is not allowed
type Status = "idle" | "loading" | "success" | "error";

const label: Record<Status, string> = {
  idle: "Ready",
  loading: "Loading...",
  success: "Done",
};

const icon: Record<Status, string> = {
  idle: "o", loading: "~", success: "v", error: "x", paused: "=",
};

index.ts(4,7): error TS2741: Property 'error' is missing in type '{ idle: string; loading: string; success: string; }' but required in type 'Record<Status, string>'.
index.ts(11,54): error TS2353: Object literal may only specify known properties, and 'paused' does not exist in type 'Record<Status, string>'.

문자열 enum을 키 타입으로 써도 똑같이 동작합니다. Record<Color, string>은 enum 멤버마다 항목을 하나씩 요구합니다.

Record<string, T>와 없는 키

string 키에서는 어떤 키든 허용되고, TypeScript는 존재하지 않는 키를 포함해 모든 조회를 T로 타입 지정합니다. 런타임에서 없는 키는 undefined를 줍니다.

const prices: Record<string, number> = { tea: 2.5, coffee: 3.2 };

const juice = prices["juice"]; // typed number, but undefined at runtime
console.log(juice);            // undefined
console.log(juice * 2);        // NaN, and no compile error

// Check before you use it
if ("juice" in prices) {
  console.log("juice costs", prices.juice);
} else {
  console.log("no juice"); // no juice
}

// Or put undefined in the value type so the compiler makes you check
const safePrices: Record<string, number | undefined> = { tea: 2.5 };
const maybe = safePrices["juice"]; // number | undefined
console.log(maybe ?? 0);           // 0

가장 흔한 Record 버그입니다. 대처 방법은 세 가지입니다. 읽기 전에 in이나 Object.hasOwn으로 확인하거나, 값을 V | undefined로 선언하거나, 프로젝트의 모든 인덱스 시그니처 읽기에 | undefined를 붙여 주는 noUncheckedIndexedAccess 컴파일러 옵션을 켜세요. 유니언 키를 쓴 Record는 모든 키가 존재한다고 보장되므로 이 문제가 없습니다.

Partial<Record<K, V>>: 일부 키만

키의 유니언을 쓰되 모든 키를 요구하지 않으려면 Record를 Partial로 감쌉니다. 그러면 읽기 결과가 V | undefined가 되어 실제와 맞습니다.

type Lang = "en" | "de" | "fr" | "ja";

// Translations are optional per language, but only these languages are allowed
const title: Partial<Record<Lang, string>> = {
  en: "Settings",
  de: "Einstellungen",
};

function translate(lang: Lang): string {
  return title[lang] ?? title.en ?? "(missing)";
}

console.log(translate("de")); // Einstellungen
console.log(translate("ja")); // Settings

// Required "en", optional others
type Labels = Record<"en", string> & Partial<Record<Exclude<Lang, "en">, string>>;
const save: Labels = { en: "Save", fr: "Enregistrer" };
console.log(save); // { en: 'Save', fr: 'Enregistrer' }

jp처럼 철자가 틀린 키는 여전히 오류이며, 이것이 Record<string, string>보다 나은 점입니다.

Record 순회하기

Object.keys, Object.values, Object.entries 모두 동작합니다. 문제는 키 타입입니다. Object.keys는 string[]을, Object.entries는 [string, V][]를 반환하며, 여러분의 키 유니언을 돌려주지 않습니다.

type Plan = "free" | "pro" | "team";
const seats: Record<Plan, number> = { free: 1, pro: 1, team: 10 };

for (const [plan, n] of Object.entries(seats)) {
  console.log(plan, n); // plan is string, n is number
}
// free 1
// pro 1
// team 10

// When you need the union type, cast the keys
const plans = Object.keys(seats) as Plan[];
const total = plans.reduce((sum, p) => sum + seats[p], 0);
console.log(total); // 12

// for...in gives string keys too
for (const key in seats) {
  console.log(key.toUpperCase()); // FREE, PRO, TEAM on separate lines
}

TypeScript는 일부러 키를 string으로 둡니다. 런타임에 객체는 타입에 적힌 것보다 많은 속성을 가질 수 있으므로, 일반적으로 Plan[]을 약속하는 것은 안전하지 않습니다. seats처럼 리터럴로 직접 만든 객체라면 캐스팅해도 안전합니다.

데이터로 Record 만들기

Record는 배열을 그룹으로 묶거나 인덱싱한 결과로 흔히 나옵니다. Record 타입의 빈 객체에서 시작해 채워 나갑니다.

interface Book {
  id: string;
  title: string;
  genre: "fiction" | "science" | "history";
}

const books: Book[] = [
  { id: "b1", title: "Dune", genre: "fiction" },
  { id: "b2", title: "Cosmos", genre: "science" },
  { id: "b3", title: "Emma", genre: "fiction" },
];

// Index by id
const byId: Record<string, Book> = {};
for (const b of books) byId[b.id] = b;

// Group by genre (every genre present, even if empty)
const byGenre: Record<Book["genre"], string[]> = { fiction: [], science: [], history: [] };
for (const b of books) byGenre[b.genre].push(b.title);

console.log(byId.b2.title); // Cosmos
console.log(byGenre);       // { fiction: [ 'Dune', 'Emma' ], science: [ 'Cosmos' ], history: [] }

// Object.fromEntries gives { [k: string]: V }, which fits Record<string, V>
const titles: Record<string, string> = Object.fromEntries(books.map((b) => [b.id, b.title]));
console.log(titles); // { b1: 'Dune', b2: 'Cosmos', b3: 'Emma' }

Book["genre"]는 인터페이스의 유니언을 키 타입으로 재사용하므로, Book에 장르를 추가하면 byGenre가 새 항목을 요구합니다.

Record<string, unknown>과 인터페이스

Record<string, unknown>은 "문자열 키를 가진 어떤 객체"를 나타낼 때 흔히 쓰는 타입입니다. 객체 리터럴과 type 별칭으로 타입을 지정한 값은 받지만, 인터페이스는 거부됩니다.

// This does not compile: interfaces have no implicit index signature
interface User {
  name: string;
}

function logFields(obj: Record<string, unknown>) {
  console.log(Object.keys(obj));
}

const user: User = { name: "Ada" };
logFields(user);

index.ts(11,11): error TS2345: Argument of type 'User' is not assignable to parameter of type 'Record<string, unknown>'.
  Index signature for type 'string' is missing in type 'User'.

인터페이스는 선언 병합으로 확장될 수 있으므로 TypeScript는 인터페이스가 인덱스 시그니처에 맞는다고 가정하지 않습니다. 타입 별칭은 다시 열 수 없으므로 type User = { name: string }은 통과합니다. 흔한 해결책은 대신 object를 받거나(여전히 Object.keys를 호출할 수 있습니다), 함수를 제네릭으로 만들거나(<T extends object>(obj: T)), User를 type으로 선언하는 것입니다(다른 차이는 interface와 type 페이지에서 다룹니다).

Record vs 인덱스 시그니처 vs Map

키 집합을 알고 있다면 유니언 키의 Record를 고르세요. 모든 키가 있는지 검사해 주는 유일한 선택지입니다. 열린 문자열 키라면 Record<string, V>와 인덱스 시그니처는 서로 바꿔 쓸 수 있고, 많은 코드베이스가 가독성 때문에 Record를 선호합니다. 런타임에 키를 추가하고 삭제하거나, 키가 문자열이 아니거나, 추가 작업 없이 크기와 삽입 순서가 필요하다면 Map을 쓰세요.