유틸리티 타입

이 장에서 만든 조건부 타입과 매핑된 타입, infer는 표준 라이브러리의 유틸리티 타입(utility type)을 이루는 재료입니다. 자주 쓰는 변환은 이미 이름이 붙은 유틸리티로 들어 있으므로, 원리를 알고 나면 직접 만들기보다 표준 유틸리티를 골라 쓰는 일이 더 많습니다.

이 글은 표준 유틸리티를 무엇을 바꾸려는지에 따라 나누어 예제로 정리합니다. 마지막으로 유틸리티 타입이 타입만 계산할 뿐 실제 객체를 바꾸지 않는다는 점을, 공개할 속성만 고르는 예제로 확인합니다. 예제는 ts-first 프로젝트에 utility-types.ts를 만들고 include를 그 파일로 바꾸어 확인합니다.

위 그림처럼 유틸리티를 고를 때는 먼저 무엇을 바꾸려는지 정합니다. 속성의 필수 여부와 읽기 전용, 남길 키, 유니온의 멤버, 함수의 매개변수와 반환값, 비동기 결과는 각각 다른 유틸리티가 맡습니다. 그림의 카드 가운데 ImmutablePoint는 본문의 fixedPoint에 해당하고, toHex의 this를 Number로 적은 부분은 본문이 this: number로 선언했으므로 원시 타입 number로 읽어야 합니다.

속성의 규칙 바꾸기

Partial<T>는 모든 속성을 선택적으로, Required<T>는 모든 속성을 필수로, Readonly<T>는 모든 속성을 읽기 전용으로 만듭니다. 앞 글들에서 직접 만든 PartialType, RequiredType, ReadonlyType과 같은 선언입니다.

interface User {
  id: number;
  name: string;
  email: string;
}

interface ProductConfig {
  name?: string;
  price?: number;
  inStock?: boolean;
}

interface Point {
  x: number;
  y: number;
}

const userUpdate: Partial<User> = { name: "새로운 이름" };
const fullConfig: Required<ProductConfig> = { name: "Monitor", price: 300000, inStock: true };
const fixedPoint: Readonly<Point> = { x: 10, y: 20 };

console.log(userUpdate.name, fullConfig.price, fixedPoint.x);

새로운 이름 300000 10

Partial<User>는 일부 속성만 바꾸는 수정 요청처럼 객체의 일부만 다룰 때 씁니다. Required<ProductConfig>의 변수에 { name: "Test" }만 넣으면 price와 inStock이 빠졌다는 진단이 나오고, Readonly<Point>의 fixedPoint.x = 15는 TS2540으로 진단됩니다. 다만 Required가 빠진 값을 채워 주지는 않고, Readonly가 객체를 얼리지도 않습니다.

남길 키 고르기

Pick<T, K>는 T에서 키 K의 속성만 남기고, Omit<T, K>는 키 K의 속성을 뺍니다. Record<K, V>는 키 K마다 값이 V인 객체 타입을 만듭니다.

interface Todo {
  id: number;
  title: string;
  description: string;
  completed: boolean;
  createdAt: Date;
}

type TodoPreview = Pick<Todo, "id" | "title" | "completed">;
type TodoWithoutDescription = Omit<Todo, "description">;

type PageInfo = { title: string; url: string };
type Page = "home" | "about" | "contact";

const todoItem: TodoPreview = { id: 1, title: "타입스크립트 학습", completed: false };
const todoDisplay: TodoWithoutDescription = {
  id: 2,
  title: "회의 준비",
  completed: true,
  createdAt: new Date("2026-03-02T09:00:00Z"),
};
const site: Record<Page, PageInfo> = {
  home: { title: "메인 페이지", url: "/" },
  about: { title: "회사 소개", url: "/about" },
  contact: { title: "연락처", url: "/contact" },
};

console.log(todoItem.title, todoDisplay.createdAt.toISOString(), site.about.url);

타입스크립트 학습 2026-03-02T09:00:00.000Z /about

TodoPreview는 목록 화면처럼 세 속성만 필요한 곳에, TodoWithoutDescription은 설명만 빼고 나머지가 모두 필요한 곳에 씁니다. Record<Page, PageInfo>는 키가 정해진 유니온이므로, 앞 글에서 본 것처럼 세 페이지를 모두 적어야 하고 하나라도 빠지면 진단됩니다.

유니온 다루기

Exclude와 Extract, NonNullable은 유니온의 멤버를 걸러 냅니다. Exclude와 Extract의 원리는 5장 2편에서 본 분배 조건부 타입입니다. NonNullable은 같은 글에서 본 것처럼 T & {}로 선언되어, {}와의 인터섹션이 null과 undefined를 걸러 냅니다.

type MyColors = "red" | "green" | "blue" | "black" | "white";
type PrimaryColors = Exclude<MyColors, "black" | "white">;

type MixedValue = string | number | (() => void);
type OnlyFunctions = Extract<MixedValue, Function>;

type NonNullString = NonNullable<string | null | undefined>;

Exclude는 두 번째 인수에 할당되는 멤버를 빼고, Extract는 그런 멤버만 남깁니다. 함수 타입 () => void만 Function에 할당되므로 OnlyFunctions는 그 함수 타입 하나가 됩니다.

함수 타입 다루기

Parameters<T>는 함수 타입의 매개변수 목록을 튜플로, ReturnType<T>는 반환 타입을 꺼냅니다. this 매개변수가 있는 함수에서는 ThisParameterType<T>로 this의 타입을 꺼내거나, OmitThisParameter<T>로 this를 뺀 함수 타입을 만들 수 있습니다.

type MyFunction = (name: string, age: number) => string;

type Params = Parameters<MyFunction>;
type MyFunctionReturn = ReturnType<MyFunction>;

function toHex(this: number, suffix: number): string {
  return this.toString(16) + suffix.toString(16);
}

type ToHexThis = ThisParameterType<typeof toHex>;
type ToHexWithoutThis = OmitThisParameter<typeof toHex>;

console.log(toHex.call(255, 1));

ff1

Params는 [name: string, age: number], MyFunctionReturn은 string입니다. typeof toHex는 함수 toHex의 타입을 꺼내는 타입 연산자이고, ToHexThis는 number, ToHexWithoutThis는 (suffix: number) => string입니다. toHex.call(255, 1)은 this를 255로 정해 부르므로 "ff"와 "1"을 이은 ff1이 출력되며, OmitThisParameter는 타입에서 this를 뺄 뿐 실행 중의 this를 정해 주지는 않습니다.

비동기 결과 꺼내기

Awaited<T>는 await가 돌려줄 값의 타입을 계산합니다. Promise가 여러 겹이면 끝까지 풀고, 유니온이면 멤버마다 따로 풉니다.

async function loadCount(): Promise<number> {
  return 3;
}

type LoadCountReturn = ReturnType<typeof loadCount>;
type LoadedCount = Awaited<LoadCountReturn>;
type Nested = Awaited<Promise<Promise<number>>>;
type Mixed = Awaited<string | Promise<number>>;

LoadCountReturn은 Promise<number>이고, 여기에 Awaited를 씌운 LoadedCount는 number입니다. Nested도 두 겹을 모두 풀어 number가 되고, Mixed는 string은 그대로 두고 Promise<number>만 풀어 string | number가 됩니다. 비동기 함수가 결국 무엇을 돌려주는지 타입으로 쓸 때 Awaited<ReturnType<typeof 함수>>의 모양을 자주 씁니다.

타입은 값을 바꾸지 않는다

유틸리티 타입은 새 타입을 계산할 뿐, 실제 객체에서 속성을 고르거나 지우지 않습니다. 회원 정보에서 공개할 속성만 고르는 예제로 이 차이를 확인합니다.

interface StoredProfile {
  id: number;
  name: string;
  email: string;
}

type PublicProfile = Pick<StoredProfile, "id" | "name">;

const storedProfile: StoredProfile = { id: 7, name: "지수", email: "[email protected]" };
const typedView: PublicProfile = storedProfile;

function toPublicProfile(profile: StoredProfile): PublicProfile {
  return { id: profile.id, name: profile.name };
}

const publicProfile = toPublicProfile(storedProfile);
console.log(Object.keys(typedView).join(","));
console.log(Object.keys(publicProfile).join(","));
console.log(typedView === storedProfile, publicProfile === storedProfile);

id,name,email
id,name
true false

typedView의 타입으로는 email을 쓸 수 없지만, 실제로는 원래 객체를 그대로 가리키므로 세 키가 모두 남아 있습니다. 이 값을 그대로 응답으로 보내면 email도 함께 나가게 됩니다. 반면 toPublicProfile은 허용한 두 속성만 읽어 새 객체를 만들므로, 실행 결과에서도 email이 빠집니다.

위 그림은 같은 원래 객체에서 출발한 두 경로를 단계별로 비교합니다. 타입으로만 바꾸어 본 경로는 같은 객체를 가리키고, 함수를 거친 경로는 두 키만 가진 새 객체를 만듭니다. 이 함수는 원시 값 세 개를 옮기는 예이며, 바깥에서 들어온 값을 검증하거나 중첩된 객체를 깊게 복사해 주지는 않습니다. 그림 아래쪽 카드의 FullProductConfig와 ImmutablePoint는 본문의 fullConfig와 fixedPoint이며, 본문의 userUpdate는 그림과 달리 email 없이 name만 담습니다. 각 유틸리티의 정의는 공식 유틸리티 타입 목록에 있습니다.

더 깊이: 표준 라이브러리의 선언에서 읽을 수 있는 것

표준 유틸리티는 컴파일러와 함께 배포되는 lib.es5.d.ts에 타입 선언으로 들어 있어서, 선언을 읽으면 이름만으로는 알 수 없는 차이가 보입니다. 대표적인 예가 Pick과 Omit입니다. Pick<T, K extends keyof T>는 K를 T의 키로 제한하므로 없는 키를 적으면 진단되지만, Omit<T, K extends keyof any>는 K를 문자열과 숫자, 심벌 가운데 아무 키로나 받습니다. 그래서 Omit<Todo, "descriptoin">처럼 키의 철자를 틀리면 진단 없이 아무 속성도 빼지 않은 타입이 됩니다.

ReturnType과 Parameters는 조건부 타입을 다룬 글에서 본 것처럼 T에 (...args: any) => any라는 제약을 둔 조건부 타입입니다. Awaited는 await의 동작을 흉내 내도록 재귀적으로 선언되어 있는데, null과 undefined는 그대로 돌려주고, then 메서드를 가진 객체(thenable)라면 그 then이 콜백에 넘기는 값의 타입을 다시 Awaited로 풉니다. 선언의 주석은 Promise가 아닌 thenable은 never가 되어야 한다고 적고 있으며, 실제 선언은 then의 첫 매개변수가 함수 모양이 아닐 때 never를 고릅니다.

모든 유틸리티를 타입 문법으로 적을 수 있는 것은 아닙니다. 매핑된 타입을 다룬 글에서 쓴 Capitalize와 같은 계열의 Uppercase, Lowercase, Uncapitalize, 그리고 3장에서 본 NoInfer는 선언의 오른쪽이 intrinsic이라는 키워드로 되어 있는데, 이는 계산 규칙이 타입 선언이 아니라 컴파일러 안에 구현되어 있다는 표시입니다. 그래서 이 유틸리티들은 선언을 읽어도 계산 규칙이 보이지 않고, 동작은 문서와 릴리스 노트로 확인해야 합니다.

정리

• Partial, Required, Readonly는 속성의 규칙을 바꾸고, Pick, Omit, Record는 남길 키나 키마다의 값을 정합니다.
• Exclude, Extract, NonNullable은 유니온의 멤버를 걸러 내고, Parameters, ReturnType, ThisParameterType, OmitThisParameter는 함수 타입을 다룹니다.
• Awaited는 Promise를 끝까지 풀어 await가 돌려줄 값의 타입을 계산합니다.
• 유틸리티 타입은 실제 객체를 바꾸지 않으므로, 속성을 고른 객체가 필요하면 그 속성만 읽어 새 객체를 만드는 코드를 따로 씁니다.

연습 문제

1. 공개할 키 바꾸기

공개 응답을 id와 email 두 속성으로 바꾸려 합니다. PublicProfile과 toPublicProfile을 각각 어떻게 고쳐야 하나요? 고친 뒤 publicProfile과 storedProfile의 키는 각각 무엇인가요?

2. 새 속성이 생겼을 때

StoredProfile에 passwordHash: string이 더해졌습니다. 공개 타입을 Pick<StoredProfile, "id" | "name">로 정의했을 때와 Omit<StoredProfile, "email">로 정의했을 때, 공개 타입에는 각각 어떤 속성이 있나요?

3. 비동기 함수의 결과 타입

async function loadNames() { return ["민지", "준호"]; }가 있을 때, ReturnType<typeof loadNames>와 Awaited<ReturnType<typeof loadNames>>는 각각 어떤 타입인가요?

이것으로 5장의 고급 타입을 마칩니다. 다음 장의 제네릭 제약 조건에서는 3장에서 본 제네릭을 다시 꺼내, 제약 조건을 더 다양하게 쓰는 방법을 다룹니다.