TypeScript 제네릭 쉽게 이해하기: props와 API 응답 타입으로 감 잡기

identity 함수

아래 개념 조각에서 참조하는 학습용 타입과 값입니다. 프로젝트 파일을 import하지 않습니다. 같은 이름을 다시 선언하는 비교 코드는 별도 파일에서 확인하세요.

type Task = { id: string; title: string; completed: boolean };
const tasks: Task[] = [{ id: '1', title: '학습', completed: false }];

function identity<T>(
  value: T,
): T {
  return value;
}

호출:

const name =
  identity('TypeScript');


const count =
  identity(10);

각 호출에서 T는 string, number로 추론됩니다.

입력 타입과 반환 타입의 관계가 유지됩니다.

any와 차이

function identityAny(
  value: any,
): any {
  return value;
}

반환 타입 정보가 사라집니다.

const value =
  identityAny('hello');


value.notExists();

any는 이런 호출도 막지 못합니다.

generic:

const value =
  identity('hello');

value는 string으로 유지됩니다.

배열 helper

function first<T>(
  items: T[],
): T | undefined {
  return items[0];
}

const firstTask =
  first(tasks);

tasks가 Task[]이면 결과는 Task | undefined입니다.

API 응답

type ApiResponse<T> = {
  data: T;
  status: number;
};

type TaskResponse =
  ApiResponse<Task>;


type TaskListResponse =
  ApiResponse<Task[]>;

같은 응답 구조를 여러 데이터 타입에 재사용할 수 있습니다.

독립 확인: props와 응답에서 같은 타입 관계 쓰기

React 화면 없이 props의 데이터·callback 계약만 확인하는 타입 예제입니다. tsconfig.json이 없는 별도 연습 폴더의 props-api.ts에 아래 전체 내용을 저장합니다. 같은 이름을 쓰는 위 개념 조각과 합치지 않습니다.

type BoxProps<T> = {
  value: T;
  onChange: (value: T) => void;
};
type ApiResponse<T> = {
  data: T;
  status: number;
};
const props: BoxProps<number> = {
  value: 1,
  onChange(next) {
    console.log(next.toFixed(0));
  },
};
const response: ApiResponse<string> = {
  data: "준비 완료",
  status: 200,
};
props.onChange(2);
console.log(response.data.toUpperCase());

npx tsc --strict --noEmit props-api.ts로 검사합니다. 기대 결과는 value와 onChange가 number로 연결되고 응답 data는 string으로 유지되어 정상 코드는 허용되는 것입니다. props.onChange(2)의 인수를 문자열 “2”로 바꾸거나 response.data에 숫자를 넣으면 타입 오류가 나야 합니다. 타입 검사는 위 Console 호출을 실행하지 않습니다. 추가 예제는 Node.js 24.18.0의 타입 제거 실행에서 2와 준비 완료 출력을 확인했습니다. 이 추가 예제의 tsc 타입 검사와 오류 인수 사례는 미확인입니다.

자가 확인: BoxProps<string>으로 바꾸면 value·callback의 연산도 문자열에 맞춰야 하는 이유를 설명해 보세요. ApiResponse 선언은 외부 JSON의 실제 구조를 검증하는 함수가 아니며 실행 시 검증은 별도입니다. 근거: TypeScript 제네릭 공식 문서 (2026-10-12).

함수 타입

type Mapper<
  TInput,
  TOutput
> = (
  value: TInput,
) => TOutput;

두 타입 사이의 관계를 표현할 수 있습니다.

명시적 type argument

대부분은 추론을 우선합니다.

first(tasks);

필요할 때만 직접 작성합니다.

first<Task>([]);

빈 배열처럼 추론 정보가 부족한 경우 도움이 될 수 있습니다.

generic이 필요 없는 경우

function getTaskTitle(
  task: Task,
): string {
  return task.title;
}

Task만 처리하는 도메인 함수라면 generic으로 바꿀 이유가 없습니다.

function getTitle<T>(
  value: T,
) {
  ...
}

오히려 어떤 property를 쓸 수 있는지 불분명해집니다.

학습 완료 체크리스트

BoxProps의 value와 onChange 매개변수가 같은 T를 쓰는 이유, ApiResponse의 status는 같아도 data만 달라지는 이유를 설명해 보세요. 빈 배열의 undefined 처리도 재사용성과 별개의 결과 계약입니다.