TypeScript

TypeScript 핸드북 기반 타입 정의 및 베스트 프랙티스. 기본 문법·타입 조작·유틸리티 타입 상세는 [references/](references/) 및 Handbook 참고.

기본 원칙

1. 타입 추론 활용

불필요한 어노테이션 생략. 변경 시 이중 수정 부담 감소, 추론이 더 정확한 경우 많음.

// ❌
const name: string = "John";
const user: { name: string; age: number } = { name: "John", age: 30 };

// ✅
const name = "John";
const user = { name: "John", age: 30 };

2. 명시적 반환 타입

함수 계약 명확화, 반환 타입 오변경 방지. 공개 API·복잡한 로직에서 필수.

function calculateTotal(items: Item[]): number {
  return items.reduce((sum, item) => sum + item.price, 0);
}
async function fetchUser(id: string): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  return res.json();
}

3. any 사용 금지

타입 안전성·자동완성 무효화. unknown + 타입 가드 또는 구체 타입 사용.

// ❌
function process(data: any) {
  return data.value;
}

// ✅
function process(data: unknown): number {
  if (typeof data === "object" && data !== null && "value" in data)
    return (data as { value: number }).value;
  throw new Error("Invalid data");
}

함수 · 제네릭

• 함수: 인자·반환 타입 명시. 오버로드 시 구현 시그니처는 유니온으로.
• 제네릭: T, K extends keyof T 등 제약 명시. getProperty<T, K extends keyof T>(obj: T, key: K): T[K] 패턴 활용.

타입 가드

• typeof, instanceof, in으로 분기 후 타입 좁히기
• 복잡한 검사는 사용자 정의 가드 (value): value is T 사용

템플릿: assets/types.guards.ts

tsconfig

• 프로젝트 성격에 맞는 tsconfig를 사용
• 타입 안정성을 해치지 않는 선에서만 옵션을 조정
• 앱/서버/라이브러리는 설정 파일을 분리
• 타입 에러 회피 목적의 옵션 완화 금지

템플릿:

- assets/tsconfig.nextjs.ts
- assets/tsconfig.node.ts
- assets/tsconfig.react.ts

이벤트 타입

• DOM / React 이벤트는 내장 타입 사용
• 커스텀 이벤트만 별도 타입 정의
• 이벤트 재정의 금지

템플릿: assets/types.events.ts

유틸리티 타입

• TypeScript 내장 유틸리티 타입은 그대로 사용
• 커스텀 유틸리티 타입만 정의

템플릿: assets/types.utils.ts

실전 패턴

• interface 우선: 객체 계약·확장은 interface, 유니온/인터섹션은 type. API 설명은 명사형으로 작성 (/** 비활성화 상태 */).
• as const: 리터럴·객체 불변 보존. typeof obj[keyof typeof obj] 로 이넘처럼 활용.
• 브랜드 타입: type UserId = string & { readonly brand: unique symbol } 로 동일 원시 타입 구분.
• 타입 단언 최소화: as 대신 타입 가드.
• 제네릭 제약: T extends object 등 명시.

타입 에러 해결

디버깅: 호버로 추론 확인, 가드·제네릭·유틸리티 타입으로 해결 후 as는 최후 수단.

참고

이 문서들은 규칙이 아니라 참고용, 판단 기준은 각 skill 문서를 우선

• TypeScript Handbook - TypeScript 공식 개념·타입 시스템 레퍼런스
• Playground - 타입 동작 실험 및 예제 검증용