TypeScript 유틸리티 타입 총정리: 전체 목록과 예제

유틸리티 타입은 TypeScript에 내장된 제네릭 타입으로, 한 타입을 다른 타입으로 바꿉니다. 모든 필드가 선택적인 User 타입을 하나 더 쓰는 대신 Partial<User>라고 쓰고, 필드 세 개를 복사하는 대신 Pick<User, "id" | "name">이라고 씁니다. 전역 타입이므로 import가 필요 없습니다.

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

type UserPatch = Partial<User>;                 // every field optional
type UserCard = Pick<User, "id" | "name">;      // only id and name
type PublicUser = Omit<User, "password">;       // everything but password
type UsersById = Record<number, PublicUser>;    // an object keyed by id

const patch: UserPatch = { email: "new@example.com" };
const card: UserCard = { id: 1, name: "Ada" };
const users: UsersById = {
  1: { id: 1, name: "Ada", email: "ada@example.com" },
};

console.log(patch, card, users[1].email);
// { email: 'new@example.com' } { id: 1, name: 'Ada' } ada@example.com

User가 바뀌면 파생된 네 타입도 모두 따라 바뀝니다. TypeScript 표준 라이브러리(lib.es5.d.ts)에는 유틸리티 타입이 22개 선언되어 있습니다. 아래 섹션에서는 다루는 타입의 종류별로 모두 정리하고, 자세한 페이지가 있으면 링크를 달았습니다.

객체 타입: Partial, Required, Readonly, Pick, Omit, Record

interface Config {
  host: string;
  port?: number;
  debug?: boolean;
}

const defaults: Required<Omit<Config, "host">> = { port: 8080, debug: false };

function withDefaults(config: Config): Readonly<Required<Config>> {
  return { ...defaults, ...config };
}

const cfg = withDefaults({ host: "localhost", debug: true });
console.log(cfg); // { port: 8080, debug: true, host: 'localhost' }
// cfg.port = 1 would be error TS2540: Cannot assign to 'port' because it is a read-only property.

Required<T>는 Partial<T>의 반대입니다. Partial 페이지에서 둘 다 다루며, 이런 스프레드가 통과시키는 명시적 undefined 문제도 설명합니다.

유니언 타입: Exclude, Extract, NonNullable

type Status = "draft" | "review" | "published" | "archived";

type Live = Exclude<Status, "draft" | "archived">; // "review" | "published"
type Mixed = string | number | (() => void);
type Callable = Extract<Mixed, (...args: never[]) => unknown>; // () => void

function lookup(id: number): string | undefined {
  return id === 1 ? "Ada" : undefined;
}
type Found = NonNullable<ReturnType<typeof lookup>>; // string

const s: Live = "review";
const run: Callable = () => console.log("called");
const found: Found = lookup(1) ?? "nobody";
run();
console.log(s, found); // review Ada

이 세 가지는 객체가 아니라 유니언에 동작합니다. 객체 타입과 그 키 목록을 받는 Pick, Omit과의 핵심 차이가 바로 이것입니다.

함수와 클래스 타입: Parameters, ReturnType 등

function createOrder(customer: string, items: string[], express = false) {
  return { customer, items, express, total: items.length * 10 };
}

type OrderArgs = Parameters<typeof createOrder>; // [customer: string, items: string[], express?: boolean | undefined]
type Order = ReturnType<typeof createOrder>;     // { customer: string; items: string[]; express: boolean; total: number }

const args: OrderArgs = ["Ada", ["book", "pen"]];
const order: Order = createOrder(...args);
console.log(order.total, order.express); // 20 false

class Point {
  constructor(public x: number, public y: number) {}
}
const coords: ConstructorParameters<typeof Point> = [3, 4];
const p: InstanceType<typeof Point> = new Point(...coords);
console.log(p); // Point { x: 3, y: 4 }

이 유틸리티들은 타입을 받는데 createOrder는 값이므로 typeof createOrder가 필요합니다. 클래스도 마찬가지입니다. typeof Point는 생성자 타입이고, 타입 자리에 쓴 Point는 이미 인스턴스 타입을 뜻합니다.

NoInfer는 제네릭이 타입을 어디서 가져올지 제어합니다.

function pickColor<C extends string>(colors: C[], fallback: NoInfer<C>): C {
  return colors[0] ?? fallback;
}

console.log(pickColor(["red", "green"], "green")); // red
// @ts-expect-error: "blue" is not "red" | "green"
pickColor(["red", "green"], "blue");

NoInfer가 없으면 TypeScript는 두 인수 모두에서 C를 추론해 "red" | "green" | "blue"로 넓히므로, fallback의 오타가 그대로 통과합니다.

문자열 타입: Uppercase, Lowercase, Capitalize, Uncapitalize

이 네 가지는 TypeScript로 작성된 것이 아니라 컴파일러에 내장되어 있으며, 이벤트 핸들러 이름을 만드는 `on${Capitalize<E>}`처럼 템플릿 리터럴 타입 안에서 가장 유용합니다.

Promise: Awaited

async function fetchUser(id: number) {
  return { id, name: "Ada" };
}

type Pending = ReturnType<typeof fetchUser>;           // Promise<{ id: number; name: string }>
type User = Awaited<ReturnType<typeof fetchUser>>;      // { id: number; name: string }

async function main() {
  const user: User = await fetchUser(1);
  const all: User[] = await Promise.all([fetchUser(2), fetchUser(3)]);
  console.log(user.name, all.map((u) => u.id)); // Ada [ 2, 3 ]
}
main();

Awaited<ReturnType<typeof fn>>은 async 함수의 결과 타입을 따로 선언하지 않고 이름 붙이는 표준 방법입니다.

유틸리티 타입 조합하기

유틸리티 타입은 중첩할 수 있습니다. 자주 나오는 조합 몇 가지는 외워 둘 만합니다.

interface Post {
  id: number;
  title: string;
  body: string;
  tags: string[];
}

// Create: everything except the server-generated id
type NewPost = Omit<Post, "id">;
// Update: id required, everything else optional
type PostUpdate = Pick<Post, "id"> & Partial<Omit<Post, "id">>;
// A lookup table of read-only summaries
type PostIndex = Record<number, Readonly<Pick<Post, "id" | "title">>>;

const created: NewPost = { title: "Hello", body: "...", tags: [] };
const update: PostUpdate = { id: 1, title: "Hello again" };
const index: PostIndex = { 2: { id: 2, title: "Idea" } };
console.log(created.title, update, index[2]);
// Hello { id: 1, title: 'Hello again' } { id: 2, title: 'Idea' }

중첩된 유틸리티 타입은 안쪽부터 읽습니다. Readonly<Pick<Post, "id" | "title">>는 먼저 속성 두 개를 남기고, 그다음 읽기 전용으로 만듭니다. 같은 부품으로 일부 키만 선택적으로 만드는 PartialBy 헬퍼도 만들 수 있으며, Partial 페이지에 구현이 있습니다.

유틸리티 타입은 런타임에 아무것도 하지 않는다

모든 유틸리티 타입은 컴파일할 때 지워집니다. Omit<User, "password"> 타입의 값도 원래 객체에 password가 있었다면 런타임에 그대로 가지고 있을 수 있습니다.

interface User {
  name: string;
  password: string;
}

const full: User = { name: "Ada", password: "hunter2" };

const leaky: Omit<User, "password"> = full; // allowed: extra properties are fine
console.log(JSON.stringify(leaky)); // {"name":"Ada","password":"hunter2"}

const { password, ...safe } = full;          // this actually removes it
console.log(JSON.stringify(safe));  // {"name":"Ada"}

타입은 코드가 무엇을 읽을 수 있는지만 제한합니다. 데이터에서 필드를 제거하려면 마지막 줄처럼 구조 분해로 떼어 내고, 런타임 변경을 막으려면 Readonly가 아니라 Object.freeze를 쓰세요. 내장 타입은 한 줄짜리 매핑된 타입과 조건부 타입이므로, 같은 도구로 직접 만들 수도 있습니다.