TypeScript 제네릭 제약: extends와 keyof T

제네릭 제약은 타입 매개변수가 무엇이 될 수 있는지 제한합니다. <T extends { length: number }>는 숫자 length를 가진 타입(문자열, 배열, 직접 만든 객체)만 받고, 그 약속 덕분에 함수는 .length를 읽을 수 있습니다.

function longest<T extends { length: number }>(a: T, b: T): T {
  return a.length >= b.length ? a : b;
}

console.log(longest("apple", "fig"));        // apple
console.log(longest([1, 2, 3], [4]));        // [ 1, 2, 3 ]
console.log(longest({ length: 2, tag: "x" }, { length: 5, tag: "y" })); // { length: 5, tag: 'y' }

// @ts-expect-error: Argument of type 'number' is not assignable to parameter of type '{ length: number; }'.
longest(10, 20);

반환 타입은 { length: number }가 아니라 여전히 T입니다. 숫자 배열 두 개를 넘기면 number[]가 돌아오고, 객체는 tag를 유지합니다. 제약은 최소한을 기술할 뿐이고, 호출하는 쪽의 타입은 보존됩니다.

제약이 필요한 이유

제네릭 함수 안에서 제약 없는 T는 무엇이든 될 수 있습니다. 문자열, 숫자, null, 함수까지요. 그래서 TypeScript는 모든 타입에 동작하는 것만 허용하는데, 그런 것은 거의 없습니다.

// This does not compile: T could be number or undefined, which have no length.
function longest<T>(a: T, b: T): T {
  return a.length >= b.length ? a : b;
}

console.log(longest("apple", "fig"));

컴파일러는 이렇게 출력합니다.

index.ts(3,12): error TS2339: Property 'length' does not exist on type 'T'.
index.ts(3,24): error TS2339: Property 'length' does not exist on type 'T'.

해결책은 필요한 것을 말하는 것입니다: <T extends { length: number }>. 제약은 "어떤 타입이든"을 "이것을 가진 어떤 타입이든"으로 바꾸며, 대개 제네릭 함수가 뜻하는 것이 그것입니다.

인터페이스로 제약하기

제약은 이미 있는 인터페이스나 타입 별칭을 포함해 어떤 타입이든 될 수 있습니다. 그러면 함수는 적어도 그 멤버를 가진 무엇과도 동작하고, 여전히 호출하는 쪽의 전체 타입을 반환합니다.

interface HasId {
  id: number;
}

function byId<T extends HasId>(items: T[], id: number): T | undefined {
  return items.find((item) => item.id === id);
}

function indexById<T extends HasId>(items: T[]): Map<number, T> {
  return new Map(items.map((item) => [item.id, item]));
}

const users = [
  { id: 1, name: "Ada", role: "admin" },
  { id: 2, name: "Grace", role: "editor" },
];

const found = byId(users, 2);
console.log(found?.name);              // Grace (found keeps name and role)
console.log(indexById(users).get(1));  // { id: 1, name: 'Ada', role: 'admin' }

평범한 매개변수 타입과 비교해 보세요. function byId(items: HasId[], id: number): HasId | undefined는 같은 배열을 받지만 결과는 HasId뿐이므로 found.name은 오류일 것입니다. 제네릭 버전은 전체 타입을 그대로 전달합니다.

K extends keyof T: 안전한 속성 접근

가장 흔한 제약은 두 타입 매개변수를 관계 짓습니다. K extends keyof T는 K가 T의 속성 이름 중 하나여야 한다는 뜻이고, T[K]는 그 속성의 타입입니다.

function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

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

const book = { title: "Dune", year: 1965, tags: ["sci-fi"] };

const year = getProperty(book, "year");   // number
const title = getProperty(book, "title"); // string
console.log(year + 1, title.toUpperCase()); // 1966 DUNE

const books = [book, { title: "Emma", year: 1815, tags: [] }];
console.log(pluck(books, "year"));        // [ 1965, 1815 ]

// @ts-expect-error: Argument of type '"author"' is not assignable to parameter of type '"tags" | "title" | "year"'.
getProperty(book, "author");

철자가 틀리거나 없는 키는 컴파일 오류이고, 반환 타입은 키를 따라갑니다. "year"는 number를, "title"은 string을 줍니다. 인덱스 시그니처와 함께일 때의 동작을 포함해 keyof 자체는 keyof 페이지에서 다룹니다.

원시 타입으로 제약하기

제약은 원시 타입이나 그 유니언일 수도 있습니다. 유용한 부수 효과가 있습니다. T extends string(또는 number)이면 TypeScript가 인수를 넓히는 대신 리터럴 타입으로 추론합니다.

function maxOf<T extends number | bigint>(values: T[]): T {
  return values.reduce((a, b) => (b > a ? b : a)); // < and > work on the constraint
}

function createEvent<T extends string>(name: T): { type: T } {
  return { type: name };
}

console.log(maxOf([3, 9, 4]));           // 9
console.log(maxOf([10n, 2n]));           // 10n

const evt = createEvent("user.saved");   // evt: { type: "user.saved" }
const same: "user.saved" = evt.type;     // the literal survived
console.log(same);                       // user.saved

제약이 없으면 createEvent("user.saved")는 { type: string }을 반환합니다. TypeScript가 T에 대해 추론한 리터럴을 string으로 넓히기 때문입니다. T extends string이면 리터럴이 유지되며, 타입이 있는 이벤트와 라우팅 헬퍼가 평범한 문자열 인수에서 정확한 이름을 얻는 방법이 이것입니다.

흔한 오류

제약에만 맞는 것을 반환하기. T를 반환하는 함수는 제약에 맞는 아무 값이 아니라 T를 반환해야 합니다.

interface HasId {
  id: number;
}

function reset<T extends HasId>(item: T): T {
  return { id: item.id };
}
// error TS2322: Type '{ id: number; }' is not assignable to type 'T'.
//   '{ id: number; }' is assignable to the constraint of type 'T', but 'T' could be
//   instantiated with a different subtype of constraint 'HasId'.

T가 { id: number; name: string }이라면 새 객체에는 name이 없으므로 T가 아닙니다. 모든 속성을 유지하는 입력의 펼침 return { ...item, id: 0 };을 반환하거나, 그것만 만든다면 반환 타입을 HasId로 선언하세요.

제약을 깨는 타입 인수 넘기기. 명시적 타입 인수도 검사됩니다. function scale<T extends number>(x: T)에서 scale<string>("2") 호출은 Type 'string' does not satisfy the constraint 'number'.(TS2344)로 실패합니다.

제네릭이 필요 없는데 제약하기. T가 매개변수에만 나온다면 function print<T extends HasId>(item: T): void는 문법만 늘어난 function print(item: HasId): void일 뿐입니다. 제약은 T가 반환 타입이나 다른 매개변수에도 나올 때 의미가 있습니다.

기본값이 있는 제약

타입 매개변수는 제약과 기본값을 둘 다 가질 수 있습니다. 기본값은 제약을 만족해야 합니다.

interface Store<TState extends object = Record<string, unknown>> {
  get(): TState;
  set(next: Partial<TState>): void;
}

type AnyStore = Store;                              // Store<Record<string, unknown>>
type CounterStore = Store<{ count: number }>;       // fine
type BadStore = Store<number>;
// error TS2344: Type 'number' does not satisfy the constraint 'object'.

같은 extends 키워드는 조건부 타입 T extends string ? A : B에도 나오는데, 거기서는 제한이 아니라 검사입니다. 그 형태는 조건부 타입 페이지에서 다룹니다.