본문 바로가기

제네릭 함수

호출 시점의 타입을 보존하는 제네릭 함수를 만들고 여러 타입 변수·extends 제약·keyof로 안전한 속성 접근을 구현합니다.

우리는 지금까지 숫자, 문자열, 객체처럼 구체적인 타입을 다루는 함수들을 살펴봤습니다.

하지만 실무에서는 특정 타입에 묶이지 않고 다양한 타입에서 동작하는 재사용 함수가 필요합니다.

예를 들어 배열의 마지막 요소를 반환하는 함수를 만들 때, 숫자 배열이든 문자열 배열이든 객체 배열이든 동일하게 쓰고 싶은 상황이 대표적입니다.

이런 상황에서 제네릭(Generics)이 빛을 발합니다.

제네릭은 C#이나 Java에서도 널리 쓰이는 개념으로, 타입스크립트에서는 함수, 클래스, 인터페이스 전반에서 사용할 수 있습니다.

코드를 작성할 때 타입을 고정하지 않고, 사용 시점에 타입을 결정하도록 열어 둘 수 있다는 점이 핵심입니다.

덕분에 재사용성과 타입 안전성을 동시에 확보할 수 있습니다.


제네릭 함수의 기본 개념

identity의 입력 타입 T가 반환 타입 T와 연결됩니다. pair는 두 타입 변수를 튜플에 보존하고 extends Lengthwise는 length 접근을 허용하는 제약입니다.

TYPE / RUNTIME / CONTRACT

같은 T가 입력과 반환 타입을 연결합니다

identity<T>(arg: T): T는 호출마다 타입 관계를 보존합니다. 제네릭 본문은 모든 허용 T에 맞게 검사되며 호출마다 새 JavaScript 구현이 생기지는 않습니다.

입력과 반환의 타입 관계입력T→identity실행→반환T의3노드2간선관계다. 같은타입을관계로표현하며런타임객체복제나유효성검사생성을뜻하지않는다.
입력 Tstring · number 등
연결 관계입력 T · string · number 등 → identity<T> · 입력 arg 반환
identity<T>입력 arg 반환
연결 관계identity<T> · 입력 arg 반환 → 반환 T · 입력의 타입 관계
반환 T입력의 타입 관계
입력과 반환의 타입 관계 · 모바일입력T→identity실행→반환T의3노드2간선관계다. 같은타입을관계로표현하며런타임객체복제나유효성검사생성을뜻하지않는다. 모바일에서도 노드와 연결 방향·독립 경로가 같다.
입력 Tstring · number 등
연결 관계입력 T · string · number 등 → identity<T> · 입력 arg 반환
identity<T>입력 arg 반환
연결 관계identity<T> · 입력 arg 반환 → 반환 T · 입력의 타입 관계
반환 T입력의 타입 관계

IDENTITY

any와 다르게 타입 정보를 유지

identity<string>("myString") 결과는 string입니다. length는 사용할 수 있지만 toFixed는 오류입니다. 타입 인자를 생략해 추론할 수도 있습니다.

PAIR

두 입력을 서로 다른 변수로 연결

pair("hello", 123)은 [string, number]입니다. 실제 결과의 메서드 호출은 HELLO와 123.00을 출력합니다.

CONSTRAINT

허용 멤버를 명시

T extends Lengthwise는 length: number를 요구합니다. 본문 예제는 문자열 11·배열 3·객체 10을 반환하며 숫자·boolean 인수는 오류입니다.

ERASURE

타입 관계는 검사 시점에 사용

타입 변수와 제약은 JavaScript 출력에서 제거됩니다. 런타임 입력 검증이나 호출마다 별도 코드를 자동 생성하지 않습니다.

T는 입력과 출력 사이의 관계를 표현합니다. 제약을 만족하는 아무 값이나 반환해도 원래 T를 보존하는 것은 아닙니다.

제네릭 함수를 만들 때는 타입 변수(Type Variable)를 사용합니다.

이 타입 변수는 함수가 다룰 타입을 위한 임시적인 플레이스홀더(Placeholder) 역할을 합니다.

타입 변수는 일반적으로 꺾쇠 괄호(< >) 안에 선언하며, <T>처럼 단일 대문자를 사용하는 것이 일반적입니다.

예시를 통해 제네릭 함수의 기본 구조를 살펴보겠습니다.

입력받은 값을 그대로 반환하는 간단한 identity 함수를 만들어봅시다.

// 1. 제네릭을 사용하지 않은 경우 (any 타입 사용)
function identityAny(arg: any): any {
  return arg;
}
let outputAny1 = identityAny("myString"); // outputAny1의 타입은 any
let outputAny2 = identityAny(123);      // outputAny2의 타입은 any

// any를 사용하면 어떤 타입이든 받을 수 있지만, 반환되는 값의 타입 정보를 잃어버립니다.
// outputAny1.length; // 현재 값은 문자열입니다. any는 이 조회를 검사하지 않으며, 숫자 값의 .length는 보통 undefined입니다.

// 2. 제네릭을 사용한 경우
function identity<T>(arg: T): T {
  return arg;
}

// 함수 호출 시 타입 인자(Type Argument)를 명시적으로 전달
let output1 = identity<string>("myString"); // output1의 타입은 string으로 추론됩니다.
let output2 = identity<number>(123);      // output2의 타입은 number로 추론됩니다.

// 대부분의 경우 타입 추론에 의해 타입 인자를 생략할 수 있습니다.
let output3 = identity("anotherString"); // output3의 타입은 string으로 추론됩니다.
let output4 = identity(true);           // output4의 타입은 boolean으로 추론됩니다.

console.log(output1.length); // 안전하게 .length 속성에 접근 가능
// console.log(output2.toFixed(2)); // 안전하게 .toFixed(2) 메서드에 접근 가능

// console.log(output1.toFixed(2)); // 오류: 'string' 형식에 'toFixed' 속성이 없습니다. (타입 안전성 유지)
제네릭 함수의 핵심
  • 타입 변수 <T>: 함수 이름 바로 뒤에 T와 같은 타입 변수를 선언합니다. 이 T는 함수가 호출될 때 실제 타입(예: string, number)으로 대체됩니다.
  • 유연성: arg: T를 통해 함수의 매개변수 arg가 어떤 타입이든 받을 수 있고, 받은 그 타입과 동일한 타입을 반환함을 명시합니다.
  • 타입 안전성 유지: any처럼 타입 검사를 포기하는 것이 아니라, 실제 사용될 타입 정보를 보존하여 타입 안전성을 유지합니다. output1은 string 타입으로 추론되었으므로 toFixed와 같은 number 타입 메서드에 접근하면 오류를 발생시킵니다.

제네릭 여러 개 사용하기

하나의 제네릭 함수는 여러 개의 타입 변수를 가질 수 있습니다.

예를 들어, 두 개의 다른 타입 인자를 받아 처리해야 할 때 유용합니다.

function pair<T1, T2>(arg1: T1, arg2: T2): [T1, T2] {
  return [arg1, arg2];
}

let myPair = pair("hello", 123); // myPair의 타입은 [string, number]로 추론됩니다.
let anotherPair = pair(true, { name: "Alice" }); // anotherPair의 타입은 [boolean, { name: string }]으로 추론됩니다.

console.log(myPair[0].toUpperCase()); // "HELLO" (string 메서드 사용 가능)
console.log(myPair[1].toFixed(2));    // "123.00" (number 메서드 사용 가능)

pair<T1, T2>처럼 여러 타입 변수를 콤마로 구분하여 선언할 수 있습니다.

반환 타입 [T1, T2]는 두 타입 변수를 요소로 갖는 튜플을 반환하겠다는 의미입니다.


제네릭 제약 조건

때로는 제네릭 타입 변수가 모든 타입을 허용하는 것이 아니라, 특정 조건을 만족하는 타입만 허용하도록 제한하고 싶을 때가 있습니다.

예를 들어, length 속성을 가진 값만 받을 수 있는 함수를 만들고 싶다면, string이나 배열(Array)은 가능하지만 number는 불가능하게 해야 합니다.

이때 제네릭 제약 조건을 사용합니다.

제약 조건은 extends 키워드를 사용하여 정의하며, T는 X 타입의 속성을 가지고 있어야 한다는 의미를 가집니다.

interface Lengthwise {
  length: number;
}

// T는 Lengthwise 인터페이스를 확장해야 합니다.
function getLengthWithConstraint<T extends Lengthwise>(arg: T): number {
  return arg.length;
}

// Lengthwise 인터페이스를 만족하는 타입들은 허용됩니다.
console.log(getLengthWithConstraint("hello world"));     // 11 (string은 length 속성을 가집니다.)
console.log(getLengthWithConstraint([1, 2, 3]));         // 3 (배열도 length 속성을 가집니다.)
console.log(getLengthWithConstraint({ length: 10, value: "test" })); // 10 (객체 리터럴도 가능)

// 오류: length 속성이 없는 타입은 허용되지 않습니다.
// console.log(getLengthWithConstraint(123)); // Error: 'number' 형식에 'length' 속성이 없습니다.
// console.log(getLengthWithConstraint(true)); // Error: 'boolean' 형식에 'length' 속성이 없습니다.

T extends Lengthwise는 타입 변수 T가 Lengthwise 인터페이스가 정의하는 length: number 속성을 반드시 가지고 있어야 한다는 제약 조건을 설정합니다.

이로 인해 함수 내부에서 arg.length에 안전하게 접근할 수 있게 됩니다. 제약은 length가 number라는 정적 형태를 요구하며, 값이 자연수인지 또는 외부 객체가 실제로 이 계약을 지키는지 자동으로 검증하지는 않습니다.


keyof 연산자와 제네릭

keyof는 타입의 키 영역을 구합니다. 일반 객체의 명시적 키뿐 아니라 숫자·심벌 키와 인덱스 시그니처도 반영하므로 결과가 항상 문자열 리터럴 유니온인 것은 아닙니다.

이 keyof 연산자를 제네릭과 함께 사용하면, 객체의 특정 속성에 안전하게 접근하는 함수를 만들 수 있습니다.

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

let user = {
  name: "김철수",
  age: 30,
  city: "서울",
};

// K는 'name', 'age', 'city' 중 하나여야 합니다.
let userName = getProperty(user, "name"); // userName의 타입은 string
let userAge = getProperty(user, "age");   // userAge의 타입은 number

console.log(userName); // 김철수
console.log(userAge);  // 30

// 오류: 'address'는 user 객체의 속성이 아닙니다.
// let userAddress = getProperty(user, "address"); // Error: Argument of type '"address"' is not assignable to parameter of type '"name" | "age" | "city"'.

여기서 K extends keyof T는 타입 변수 K가 T 타입의 객체가 가질 수 있는 속성 이름들(즉, keyof T) 중 하나여야 함을 의미합니다.

이렇게 하면 선택한 키와 결과 타입 T[K]의 정적 관계를 유지합니다. 실제 객체에 해당 키가 존재하는지를 런타임에 검사하는 코드는 생성되지 않습니다.

user의 name·age·city 키에서 name을 선택하면 string, age를 선택하면 number가 됩니다. address는 허용 키가 아니며 런타임 존재 검사는 자동 생성되지 않습니다.

TYPE / RUNTIME / CONTRACT

선택한 키 K에 따라 결과 T[K]가 달라집니다

getProperty(user, "name")은 string, "age"는 number입니다. keyof는 키의 타입 영역이고 K extends keyof T가 허용 키를 제한합니다.

키와 결과 타입의 연결객체타입T→허용키K→결과T[K]의3노드2간선정적관계다. name선택string및age선택number관계를나타내며선택속성의undefined가능성과런타임검증은별도다.
객체 타입 Tname · age · city
연결 관계객체 타입 T · name · age · city → 허용 키 K · K extends keyof T
허용 키 KK extends keyof T
연결 관계허용 키 K · K extends keyof T → 결과 T[K] · 선택 속성의 타입
결과 T[K]선택 속성의 타입
키와 결과 타입의 연결 · 모바일객체타입T→허용키K→결과T[K]의3노드2간선정적관계다. name선택string및age선택number관계를나타내며선택속성의undefined가능성과런타임검증은별도다. 모바일에서도 노드와 연결 방향·독립 경로가 같다.
객체 타입 Tname · age · city
연결 관계객체 타입 T · name · age · city → 허용 키 K · K extends keyof T
허용 키 KK extends keyof T
연결 관계허용 키 K · K extends keyof T → 결과 T[K] · 선택 속성의 타입
결과 T[K]선택 속성의 타입

ACTUAL EXAMPLE

본문 객체의 키와 값

name은 김철수, age는 30입니다. address 호출은 오류입니다. 객체와 키를 같은 T·K 계약으로 검사합니다.

KEY DOMAIN

문자열 키로만 한정되지 않습니다

명시적 숫자·symbol 키도 반영됩니다. string 인덱스 시그니처의 keyof는 JavaScript 키 변환 때문에 string | number가 될 수 있습니다.

INDEXED ACCESS

선택 속성의 타입을 보존

optional 속성 조회 타입에는 undefined가 포함됩니다. 여러 키의 유니온을 선택하면 결과도 해당 속성 타입의 유니온이 됩니다. 선택 속성은 본문의 member 확장 연습에서도 확인합니다. 여러 키의 유니온은 같은 조회 원리의 확장입니다.

RUNTIME

실제 키 존재 검사는 별도

obj[key] 조회 코드는 남지만 keyof·제약은 제거됩니다. 외부 입력의 객체 구조를 검증하는 코드는 이 예제에 없습니다.

키의 정적 허용 여부와 실제 객체에 대한 런타임 검증을 구분합니다.


제네릭 함수는 입력 타입과 반환 타입의 관계를 보존하면서 함수를 재사용하게 해 줍니다.

빈 배열까지 반환 계약에 포함하기

처음에 언급한 마지막 요소 함수는 타입 보존뿐 아니라 요소가 없는 경우도 표현해야 합니다. 입력의 요소 타입 T와 결과 타입 T를 연결하되, 빈 배열 결과는 undefined입니다. readonly 배열도 읽기만 하므로 받을 수 있습니다.

function last<T>(values: readonly T[]): T | undefined {
  return values[values.length - 1];
}
const latest = last([10, 20]); // number | undefined
if (latest !== undefined) console.log(latest.toFixed(0)); // 20
console.log(last<string>([])); // undefined

T가 number로 결정되어도 배열의 길이가 양수라는 조건을 추가한 것은 아닙니다. 반환한 값의 존재를 확인한 뒤 number 메서드를 사용합니다. identity의 T는 타입 관계이며 입력 객체를 복제하거나 런타임 검사기를 만드는 규칙도 아닙니다. 공식 제네릭 설명의 입력·출력 관계와 연결해 볼 수 있습니다.

혼자 결과 타입과 실제 값 구별하기

last에 ['봄', '여름']을 전달할 때 결과 타입·실제 값을 적고, 빈 문자열 배열의 결과에서 바로 .toUpperCase()를 호출할 수 있는지 판단합니다. 이어 아래 선택 속성을 원 getProperty로 읽으면 반환 타입과 실제 값이 무엇인지 적습니다.

const member: { name: string; nickname?: string } = { name: '김철수' };
const nickname = getProperty(member, 'nickname');
console.log(nickname);
// nickname.toUpperCase(); // 존재 확인 전에는 오류
관계와 결측 해설

last의 결과 타입은 string|undefined이고 실제 값은 여름입니다. 빈 배열에서는 undefined라 문자열 메서드를 바로 호출할 수 없습니다. nickname은 선택 속성의 타입인 string|undefined이며, 위 실제 member에는 값이 없어 undefined입니다. keyof가 nickname을 허용하는 것과 그 값이 항상 존재하는 것은 다른 조건입니다. 이름·나이의 유니온 키로 조회하면 결과도 각 속성 타입의 유니온이 된다는 인덱스 접근 타입 원리를 적용합니다.