본문으로 건너뛰기

TypeScript 제네릭, 실무에서 쓰는 패턴만

제네릭 기본 문법을 짧게 훑고, Pick/Omit/ReturnType을 직접 만들어보며 API 응답 래퍼 타입 같은 실무 패턴을 정리합니다.

· 3분 읽기

TypeScript 제네릭, 실무에서 쓰는 패턴만

개요

제네릭 강의를 보면 항상 identity<T> 예제로 시작하죠. 그런데 실무 코드에서 그 예제를 그대로 쓰는 경우는 거의 없었습니다. 3년쯤 TypeScript를 쓰면서 실제로 자주 쓰게 된 제네릭 패턴만 모아봤습니다. 타입 라이브러리를 만드는 게 아니라, 애플리케이션 코드에서 유용했던 것들입니다.

기본: 타입을 인자로 넘긴다

제네릭은 결국 “타입을 값처럼 넘겨서, 넣은 타입에 따라 결과 타입이 결정되게” 하는 장치입니다. 중요한 것은 대부분의 제네릭은 직접 명시할 필요 없이 추론된다는 점입니다.

function firstOrDefault<T>(arr: T[], fallback: T): T {
  return arr.length > 0 ? arr[0] : fallback;
}

// T는 number로 추론됨 — 명시할 필요 없음
const a = firstOrDefault([1, 2, 3], 0);

// 제네릭을 명시해야 할 때: 빈 배열로 추론 근거가 없을 때
const b = firstOrDefault<string>([], 'none');

실무 원칙을 하나 들자면: 호출부에서 타입 인자를 생략할 수 있게 설계된 제네릭이 좋은 제네릭입니다. 매번 명시해야 한다면 시그니처를 의심해봅니다.

Pick, Omit, ReturnType 직접 만들어보기

유틸리티 타입은 제네릭 학습에 최고의 교재입니다. 직접 만들어보면 mapped type과 keyof, 조건부 타입이 어떻게 조합되는지 체감됩니다.

// Pick: T에서 K에 해당하는 키만 골라 새 타입 생성
type MyPick<T, K extends keyof T> = {
  [P in K]: T[P];
};

// Omit: T에서 K를 제외한 나머지
type MyOmit<T, K extends keyof T> = MyPick<T, Exclude<keyof T, K>>;

// ReturnType: 함수 타입 T의 반환 타입 추출
type MyReturnType<T> = T extends (...args: never[]) => infer R ? R : never;

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

type UserPreview = MyPick<User, 'id' | 'name'>;
type UserUpdate = MyOmit<User, 'id' | 'createdAt'>;

function fetchUser() {
  return { id: 1, name: '김' };
}
type FetchedUser = MyReturnType<typeof fetchUser>; // { id: number; name: string }

핵심 문법 세 가지가 전부입니다.

  • keyof T: T의 키들의 유니온
  • [P in K]: mapped type — K의 각 키로 프로퍼티를 생성
  • infer R: 조건부 타입에서 특정 타입을 “캡처”해 오른쪽에서 사용

API 응답 래퍼 타입 패턴

실무에서 제네릭이 가장 빛나는 곳이 API 응답 타입니다. 공통 래퍼를 한 번 정의해두면 모든 API 함수가 재사용합니다.

// 공통 응답 형태
interface ApiResponse<T> {
  code: number;
  message: string;
  data: T;
}

interface Paginated<T> {
  items: T[];
  total: number;
  page: number;
  pageSize: number;
}

// 사용
async function getUser(id: number): Promise<ApiResponse<User>> {
  const res = await fetch(`/api/users/${id}`);
  return res.json();
}

async function listUsers(page: number): Promise<ApiResponse<Paginated<User>>> {
  const res = await fetch(`/api/users?page=${page}`);
  return res.json();
}

// data의 타입이 정확히 추론됨
const user = (await getUser(1)).data; // User

여기에 페이지네이션 응답이 계속 늘어난다면 제네릭 기본값으로 중복을 줄일 수도 있습니다.

type ListResponse<T, P = Paginated<T>> = ApiResponse<P>;

// 두 표기는 동일
type A = ListResponse<User>;
type B = ListResponse<User, Paginated<User>>;

함수 시그니처에 제네릭 제약 걸기

마지막으로 자주 쓰는 패턴. 객체에서 안전하게 키로 접근하는 헬퍼인데, K extends keyof T 제약 덕분에 존재하지 않는 키를 컴파일 타임에 잡아줍니다.

function pluck<T, K extends keyof T>(items: T[], key: K): T[K][] {
  return items.map((item) => item[key]);
}

const names = pluck(users, 'name');   // string[]
const ids = pluck(users, 'id');       // number[]
// pluck(users, 'nickname');          // 컴파일 에러: User에 없는 키

이렇게 제약(extends)을 걸면 제네릭이 “무엇이든”이 아니라 “이 형태를 만족하는 것”으로 좁혀져서, 함수 내부에서도 item[key]가 안전해집니다.

마무리

실무 제네릭의 대부분은 이 글의 패턴 조합입니다. 래퍼 타입(ApiResponse<T>), 유틸리티 조합(Pick/Omit/ReturnType), 제약이 있는 헬퍼(K extends keyof T). 여기에 조건부 타입과 infer만 더하면 대부분의 타입 문제를 라이브러리 없이 풀 수 있습니다. 제네릭이 복잡해지는 순간은 보통 설계가 복잡해졌다는 신호이므로, 타입을 줄이는 방향으로 먼저 고민해보시길 권합니다.

Related

· 17 min read Build Logs

spec-studio 구축기 — 화면설계서의 번호를 객체로 옮기고, SQLite 한 파일을 정본으로 두기

기획 올인원 툴을 버리고 그린필드로 다시 세운 spec-studio. 화면 위 번호 핀을 불변 객체로 만들고, 로컬 SQLite 한 파일을 정본으로 두고, Confluence에는 단방향 사본만 보냅니다. 6타입·7링크 추적 그래프, L0→L1→L2, 제안→결정→되돌리기, LLM 제안과 한국어 골든셋 30건 eval까지 — 커밋 16개, 테스트 157개, mock 기준 스키마 100%·타입 93%·링크 92%의 기록입니다.

프론트엔드AI
→
· 18 min read Build Logs

damon-chat-desk 구축기 — 로컬 에이전트 데몬의 /ws 위에 얇은 웹 데스크를 얹기

로컬 AI 에이전트 데몬(damon-agent-core) 위에 정적 SPA 채팅 데스크를 얹었습니다. OpenAI 호환 경로 대신 /ws JSON-RPC v2와 일회용 ws_ticket을 고른 이유, 툴 실행 아코디언·turn.steer·plan.respond CAS·session.fork, 메모리 게이트(-32011)를 UI 문장으로 옮기는 법, ⌘K 팔레트, https 페이지에서 loopback 데몬에 붙을 수 없을 때의 demo 폴백까지 — PR 4건 +18,477줄, 테스트 223개, 번들 375kB의 기록입니다.

프론트엔드AI
→