TypeScript 매핑된 타입(Mapped Types): 문법, 제한자, 키 재매핑

매핑된 타입은 키 집합을 순회하며 새 객체 타입을 만듭니다. { [K in keyof T]: boolean }은 "T의 모든 키 K에 대해, boolean 타입의 K라는 속성"이라는 뜻입니다.

type Features = {
  darkMode: string;
  search: number;
  export: string[];
};

// Same keys as T, every property turned into a boolean
type Flags<T> = { [K in keyof T]: boolean };

const enabled: Flags<Features> = {
  darkMode: true,
  search: false,
  export: true,
};

console.log(enabled); // { darkMode: true, search: false, export: true }
// Leaving out "export" would be error TS2741: Property 'export' is missing

Features에 키를 추가하면 Flags<Features>도 그것을 요구합니다. 매핑된 타입은 컴파일 시점에만 존재합니다. 객체를 기술할 뿐, 만들지는 않습니다.

문법

매핑된 타입에는 세 부분이 있습니다. 키 변수, 순회할 키의 유니언, 그리고 키 변수를 쓸 수 있는 속성 타입입니다.

type MappedType = {
  [K in Keys]: PropertyType; // K takes each member of Keys in turn
};

Keys는 문자열, 숫자, 심볼의 어떤 유니언이든 될 수 있습니다. keyof에서 올 필요는 없습니다.

type Size = "small" | "medium" | "large";

type PriceTable = { [S in Size]: number };
// { small: number; medium: number; large: number }

const prices: PriceTable = { small: 3, medium: 4, large: 5 };

for (const size of ["small", "large"] as const) {
  console.log(size, prices[size]);
}
// small 3
// large 5

이것이 정확히 Record<Size, number>가 하는 일입니다. Record는 한 줄짜리 매핑된 타입입니다. 속성 타입은 키를 쓸 수 있습니다. { [K in keyof T]: T[K] }는 인덱스 접근을 통해 각 속성 타입을 복사하고, { [K in keyof T]: T[K] | null }은 모든 속성을 null 가능하게 만듭니다.

제한자: +와 -를 쓰는 readonly와 ?

매핑된 타입은 모든 속성의 readonly와 선택적(?) 제한자를 한꺼번에 더하거나 뺄 수 있습니다. 앞에 +를 붙이면 더하고(아무것도 쓰지 않을 때의 기본값), -를 붙이면 뺍니다.

type Account = {
  readonly id: number;
  email?: string;
};

type Mutable<T> = { -readonly [K in keyof T]: T[K] };
type AllRequired<T> = { [K in keyof T]-?: T[K] };
type Frozen<T> = { +readonly [K in keyof T]: T[K] };

const editable: Mutable<Account> = { id: 1 };
editable.id = 2; // allowed: readonly was removed

const complete: AllRequired<Account> = { id: 1, email: "a@b.co" };
// { id: 1 } alone would be error TS2741: Property 'email' is missing

const frozen: Frozen<{ n: number }> = { n: 1 };
// @ts-expect-error: Cannot assign to 'n' because it is a read-only property
frozen.n = 2;

console.log(editable, complete, frozen);
// { id: 2 } { id: 1, email: 'a@b.co' } { n: 2 }

마지막 줄은 readonly가 컴파일 시점의 규칙일 뿐이라는 것을 보여 줍니다. 대입은 보고되었지만(여기서는 @ts-expect-error로 억제), 출력된 JavaScript는 그대로 실행했습니다. -?는 물음표를 빼는 것 이상을 합니다. 속성 타입에서 undefined도 없애므로, AllRequired<Account>는 { id: 1, email: undefined }를 error TS2322: Type 'undefined' is not assignable to type 'string'으로 거부합니다.

Partial, Readonly, Pick, Record가 만들어진 방식

객체의 모양을 바꾸는 내장 유틸리티 타입은 매핑된 타입입니다. TypeScript 자체의 lib.es5.d.ts에 있는 정의입니다.

type Partial<T> = { [P in keyof T]?: T[P] };
type Required<T> = { [P in keyof T]-?: T[P] };
type Readonly<T> = { readonly [P in keyof T]: T[P] };
type Pick<T, K extends keyof T> = { [P in K]: T[P] };
type Record<K extends keyof any, T> = { [P in K]: T };

이것을 읽어 보는 것은 좋은 연습입니다. Pick은 넘긴 키만 순회하고, Record는 원본 타입을 무시하고 모든 키에 같은 값 타입을 줍니다. Omit은 자체적인 매핑된 타입이 아니라 Pick<T, Exclude<keyof T, K>>입니다. 유틸리티 타입 레퍼런스에 모두 정리되어 있습니다.

as로 키 재매핑하기

키 뒤의 as 절은 속성 이름을 바꿉니다. 템플릿 리터럴 타입과 조합하면 기존 이름에서 새 이름을 만들 수 있습니다.

type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
};

type Person = { name: string; age: number };

// { getName: () => string; getAge: () => number }
const person: Getters<Person> = {
  getName: () => "Ada",
  getAge: () => 36,
};

console.log(person.getName(), person.getAge()); // Ada 36

keyof T에는 number와 symbol 키가 포함될 수 있고 Capitalize는 문자열만 받으므로 string & K가 있습니다. 교차 타입이 문자열 키만 남기고 나머지를 버립니다.

never로 키 걸러 내기

as 절이 어떤 키에 대해 never를 만들면 그 키는 제거됩니다. 조건부 타입과 함께 쓰면 속성의 타입에 따라 남기거나 버릴 수 있습니다.

type DataOnly<T> = {
  [K in keyof T as T[K] extends (...args: any[]) => unknown ? never : K]: T[K];
};

class Invoice {
  constructor(public id: number, public total: number) {}
  format(): string {
    return `#${this.id}: ${this.total.toFixed(2)}`;
  }
}

// { id: number; total: number }  (format is gone)
const data: DataOnly<Invoice> = { id: 7, total: 19.5 };

console.log(data);                        // { id: 7, total: 19.5 }
console.log(new Invoice(7, 19.5).format()); // #7: 19.50

DataOnly 같은 타입은 JSON.stringify를 거친 뒤 남는 것이나 폼이 편집하는 것, 즉 메서드를 뺀 필드를 기술할 때 유용합니다.

유지되는 제한자

어떤 타입 T의 keyof T를 순회하는 매핑된 타입을 준동형(homomorphic)이라고 하며, T에서 각 속성의 readonly와 ? 제한자를 복사합니다. 평범한 키 유니언을 순회하는 매핑된 타입은 제한자 없이 시작합니다.

type Account = { readonly id: number; email?: string };

type Copy<T> = { [K in keyof T]: T[K] };
type A = Copy<Account>;
// { readonly id: number; email?: string }  (modifiers kept)

type B = { [K in "id" | "email"]: Account[K] };
// { id: number; email: string | undefined }  (email is required now)

Account["email"]에 undefined가 포함되므로 B의 email 타입에는 여전히 undefined가 있지만, 속성 자체는 더 이상 선택적이지 않습니다. { id: 1 }은 거부됩니다. 이것이 Partial<T> 같은 타입이 keyof T를 순회하는 이유입니다. 명시적으로 바꾸지 않는 것은 모두 유지합니다.

제네릭 준동형 매핑된 타입을 배열이나 튜플에 적용하면, 숫자 키를 가진 객체가 아니라 배열이나 튜플이 만들어집니다. Readonly<string[]>는 readonly string[]이고, type Box<T> = { [K in keyof T]: { value: T[K] } }라면 Box<[string, number]>는 [{ value: string }, { value: number }]입니다.

매핑된 타입과 런타임 코드

매핑된 타입은 객체를 기술할 뿐이므로, 그런 객체를 만드는 함수에는 자체 런타임 반복문이 필요합니다. 그러면 타입이 그 결과를 기술합니다.

type Validators<T> = { [K in keyof T]: (value: T[K]) => boolean };

type SignUp = { email: string; age: number };

const rules: Validators<SignUp> = {
  email: (v) => v.includes("@"), // v is string
  age: (v) => v >= 13,           // v is number
};

function validate(form: SignUp): string[] {
  const failed: string[] = [];
  for (const key of Object.keys(rules) as (keyof SignUp)[]) {
    const ok = key === "email" ? rules.email(form.email) : rules.age(form.age);
    if (!ok) failed.push(key);
  }
  return failed;
}

console.log(validate({ email: "ada@example.com", age: 36 })); // []
console.log(validate({ email: "nope", age: 9 }));             // [ 'email', 'age' ]

콜백은 아무 표기 없이 매핑된 타입에서 매개변수 타입을 얻습니다(한쪽의 v는 string, 다른 쪽은 number). 타입 매핑이 아니라 Map 클래스를 찾아 여기 왔다면 TypeScript의 Map을 보세요.