TypeScript 완전정복: 실무에서 3년간 써본 타입 설계 패턴

// 팀 준비도 체크리스트
interface TeamReadiness {
  // 기술적 준비
  jsExperience: 'beginner' | 'intermediate' | 'advanced';
  es6Knowledge: boolean;
  nodeToolingFamiliarity: boolean;

  // 문화적 준비
  learningMotivation: number; // 1-10 점수
  changeResistance: 'low' | 'medium' | 'high';
  codeQualityFocus: boolean;
}

// 우리 팀의 실제 평가 결과
const ourTeamReadiness: TeamReadiness = {
  jsExperience: 'advanced',
  es6Knowledge: true,
  nodeToolingFamiliarity: true,
  learningMotivation: 8,
  changeResistance: 'medium',
  codeQualityFocus: true
};

// 1단계: 새로운 파일만 TypeScript로 작성
// ✅ 기존 코드에 영향 없음
// ✅ 점진적 학습 가능

// 2단계: 유틸리티 함수와 상수부터 마이그레이션
// utils/constants.ts
export const API_ENDPOINTS = {
  USERS: '/api/users',
  PRODUCTS: '/api/products'
} as const;

export type ApiEndpoint = typeof API_ENDPOINTS[keyof typeof API_ENDPOINTS];

// 3단계: 핵심 타입 정의 구축
// types/api.ts
export interface ApiResponse<T> {
  success: boolean;
  data: T;
  message: string;
  timestamp: string;
}

// 4단계: 컴포넌트와 비즈니스 로직 마이그레이션
// 5단계: 엄격한 타입 체크 활성화

// 기본 엔티티 타입
interface BaseEntity {
  id: string;
  createdAt: Date;
  updatedAt: Date;
}

// 사용자 도메인
namespace UserDomain {
  export interface User extends BaseEntity {
    email: string;
    username: string;
    profile: UserProfile;
    preferences: UserPreferences;
  }

  export interface UserProfile {
    firstName: string;
    lastName: string;
    avatar?: string;
    bio?: string;
  }

  export interface UserPreferences {
    theme: 'light' | 'dark' | 'system';
    language: 'ko' | 'en' | 'ja';
    notifications: NotificationSettings;
  }

  export interface NotificationSettings {
    email: boolean;
    push: boolean;
    sms: boolean;
  }

  // 도메인별 행동 정의
  export type UserAction =
    | { type: 'UPDATE_PROFILE'; payload: Partial<UserProfile> }
    | { type: 'CHANGE_PREFERENCES'; payload: Partial<UserPreferences> }
    | { type: 'DELETE_ACCOUNT' };
}

// 상품 도메인
namespace ProductDomain {
  export interface Product extends BaseEntity {
    name: string;
    description: string;
    price: Price;
    category: Category;
    inventory: Inventory;
    tags: string[];
  }

  export interface Price {
    amount: number;
    currency: 'KRW' | 'USD' | 'JPY';
    discountedAmount?: number;
  }

  export interface Category {
    id: string;
    name: string;
    slug: string;
    parentId?: string;
  }

  export interface Inventory {
    stock: number;
    reserved: number;
    available: number;
  }
}

// API 엔드포인트 정의
type ApiEndpoints = {
  // GET 요청
  'GET /api/users': {
    query?: { page?: number; limit?: number; search?: string };
    response: ApiResponse<UserDomain.User[]>;
  };

  'GET /api/users/:id': {
    params: { id: string };
    response: ApiResponse<UserDomain.User>;
  };

  // POST 요청
  'POST /api/users': {
    body: Omit<UserDomain.User, 'id' | 'createdAt' | 'updatedAt'>;
    response: ApiResponse<UserDomain.User>;
  };

  // PUT 요청
  'PUT /api/users/:id': {
    params: { id: string };
    body: Partial<Omit<UserDomain.User, 'id' | 'createdAt' | 'updatedAt'>>;
    response: ApiResponse<UserDomain.User>;
  };

  // DELETE 요청
  'DELETE /api/users/:id': {
    params: { id: string };
    response: ApiResponse<{ deleted: boolean }>;
  };
};

// 타입 안전한 API 클라이언트
class TypedApiClient {
  private baseURL: string;

  constructor(baseURL: string) {
    this.baseURL = baseURL;
  }

  async request<T extends keyof ApiEndpoints>(
    endpoint: T,
    options: ApiEndpoints[T] extends { params: any }
      ? { params: ApiEndpoints[T]['params'] } & Omit<RequestInit, 'body'> &
        (ApiEndpoints[T] extends { body: any } ? { body: ApiEndpoints[T]['body'] } : {}) &
        (ApiEndpoints[T] extends { query: any } ? { query?: ApiEndpoints[T]['query'] } : {})
      : Omit<RequestInit, 'body'> &
        (ApiEndpoints[T] extends { body: any } ? { body: ApiEndpoints[T]['body'] } : {}) &
        (ApiEndpoints[T] extends { query: any } ? { query?: ApiEndpoints[T]['query'] } : {})
  ): Promise<ApiEndpoints[T]['response']> {
    // URL 구성
    let url = this.baseURL + endpoint.split(' ')[1];

    // 파라미터 교체
    if ('params' in options && options.params) {
      Object.entries(options.params).forEach(([key, value]) => {
        url = url.replace(`:${key}`, String(value));
      });
    }

    // 쿼리 파라미터 추가
    if ('query' in options && options.query) {
      const queryString = new URLSearchParams(
        Object.entries(options.query)
          .filter(([_, value]) => value !== undefined)
          .map(([key, value]) => [key, String(value)])
      ).toString();

      if (queryString) {
        url += '?' + queryString;
      }
    }

    // 요청 옵션 구성
    const fetchOptions: RequestInit = {
      method: endpoint.split(' ')[0],
      headers: {
        'Content-Type': 'application/json',
        ...options.headers,
      },
    };

    // 바디 데이터 추가
    if ('body' in options && options.body) {
      fetchOptions.body = JSON.stringify(options.body);
    }

    const response = await fetch(url, fetchOptions);
    return response.json();
  }
}

// 사용 예시 - 완전한 타입 체크
const apiClient = new TypedApiClient('https://api.example.com');

// ✅ 모든 타입이 자동으로 추론됨
const users = await apiClient.request('GET /api/users', {
  query: { page: 1, limit: 10 }
});

const user = await apiClient.request('GET /api/users/:id', {
  params: { id: 'user-123' }
});

const newUser = await apiClient.request('POST /api/users', {
  body: {
    email: 'test@example.com',
    username: 'testuser',
    profile: {
      firstName: 'Test',
      lastName: 'User'
    },
    preferences: {
      theme: 'dark',
      language: 'ko',
      notifications: {
        email: true,
        push: false,
        sms: false
      }
    }
  }
});

// ❌ 컴파일 타임에 에러 발생
// const invalid = await apiClient.request('GET /api/users/:id', {
//   params: { wrongParam: 'value' }  // 에러: 'wrongParam'은 존재하지 않음
// });

// 액션 타입 정의
type UserActions =
  | { type: 'FETCH_USERS_REQUEST' }
  | { type: 'FETCH_USERS_SUCCESS'; payload: UserDomain.User[] }
  | { type: 'FETCH_USERS_FAILURE'; payload: string }
  | { type: 'SELECT_USER'; payload: string }
  | { type: 'UPDATE_USER_REQUEST'; payload: { id: string; updates: Partial<UserDomain.User> } }
  | { type: 'UPDATE_USER_SUCCESS'; payload: UserDomain.User }
  | { type: 'UPDATE_USER_FAILURE'; payload: string };

// 상태 타입 정의
interface UserState {
  users: UserDomain.User[];
  selectedUserId: string | null;
  loading: boolean;
  error: string | null;
}

// 타입 안전한 리듀서
function userReducer(state: UserState, action: UserActions): UserState {
  switch (action.type) {
    case 'FETCH_USERS_REQUEST':
      return { ...state, loading: true, error: null };

    case 'FETCH_USERS_SUCCESS':
      return { ...state, loading: false, users: action.payload };

    case 'FETCH_USERS_FAILURE':
      return { ...state, loading: false, error: action.payload };

    case 'SELECT_USER':
      return { ...state, selectedUserId: action.payload };

    case 'UPDATE_USER_SUCCESS':
      return {
        ...state,
        users: state.users.map(user =>
          user.id === action.payload.id ? action.payload : user
        )
      };

    default:
      return state;
  }
}

// 액션 생성자 함수 (타입 안전)
const userActions = {
  fetchUsersRequest: (): UserActions => ({ type: 'FETCH_USERS_REQUEST' }),

  fetchUsersSuccess: (users: UserDomain.User[]): UserActions => ({
    type: 'FETCH_USERS_SUCCESS',
    payload: users
  }),

  selectUser: (userId: string): UserActions => ({
    type: 'SELECT_USER',
    payload: userId
  })
};

// 타입 가드 유틸리티
function isString(value: unknown): value is string {
  return typeof value === 'string';
}

function isNumber(value: unknown): value is number {
  return typeof value === 'number' && !isNaN(value);
}

function isObject(value: unknown): value is Record<string, unknown> {
  return value !== null && typeof value === 'object' && !Array.isArray(value);
}

// 복합 타입 가드
function isUser(value: unknown): value is UserDomain.User {
  if (!isObject(value)) return false;

  return (
    isString(value.id) &&
    isString(value.email) &&
    isString(value.username) &&
    isObject(value.profile) &&
    isUserProfile(value.profile) &&
    isObject(value.preferences) &&
    isUserPreferences(value.preferences)
  );
}

function isUserProfile(value: unknown): value is UserDomain.UserProfile {
  if (!isObject(value)) return false;

  return (
    isString(value.firstName) &&
    isString(value.lastName) &&
    (value.avatar === undefined || isString(value.avatar)) &&
    (value.bio === undefined || isString(value.bio))
  );
}

function isUserPreferences(value: unknown): value is UserDomain.UserPreferences {
  if (!isObject(value)) return false;

  return (
    ['light', 'dark', 'system'].includes(value.theme as string) &&
    ['ko', 'en', 'ja'].includes(value.language as string) &&
    isObject(value.notifications)
  );
}

// 런타임 검증 함수
function validateApiResponse<T>(
  data: unknown,
  validator: (value: unknown) => value is T
): T {
  if (!validator(data)) {
    throw new Error('Invalid API response format');
  }
  return data;
}

// 사용 예시
async function fetchUserSafely(id: string): Promise<UserDomain.User> {
  const response = await fetch(`/api/users/${id}`);
  const json = await response.json();

  // 런타임에서 타입 안전성 보장
  const apiResponse = validateApiResponse(json, (value): value is ApiResponse<UserDomain.User> => {
    if (!isObject(value)) return false;
    return (
      typeof value.success === 'boolean' &&
      isUser(value.data) &&
      isString(value.message) &&
      isString(value.timestamp)
    );
  });

  if (!apiResponse.success) {
    throw new Error(apiResponse.message);
  }

  return apiResponse.data;
}

// 깊은 부분 타입
type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};

// 깊은 읽기 전용 타입
type DeepReadonly<T> = {
  readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
};

// 키 경로 타입
type KeyPath<T> = {
  [K in keyof T]: T[K] extends object
    ? K | `${K & string}.${KeyPath<T[K]> & string}`
    : K;
}[keyof T];

// 중첩된 값 타입 추출
type GetValueByPath<T, P extends string> = P extends `${infer K}.${infer Rest}`
  ? K extends keyof T
    ? GetValueByPath<T[K], Rest>
    : never
  : P extends keyof T
    ? T[P]
    : never;

// 실무 활용 예시
type UserKeyPath = KeyPath<UserDomain.User>;
// 결과: "id" | "email" | "username" | "profile" | "profile.firstName" | "profile.lastName" | ...

type FirstNameType = GetValueByPath<UserDomain.User, 'profile.firstName'>;
// 결과: string

// 폼 핸들링을 위한 유틸리티
function getNestedValue<T, P extends KeyPath<T>>(
  obj: T,
  path: P
): GetValueByPath<T, P> {
  const keys = (path as string).split('.');
  let result: any = obj;

  for (const key of keys) {
    result = result?.[key];
  }

  return result;
}

function setNestedValue<T, P extends KeyPath<T>>(
  obj: T,
  path: P,
  value: GetValueByPath<T, P>
): T {
  const keys = (path as string).split('.');
  const newObj = JSON.parse(JSON.stringify(obj)); // Deep clone
  let current: any = newObj;

  for (let i = 0; i < keys.length - 1; i++) {
    current = current[keys[i]];
  }

  current[keys[keys.length - 1]] = value;
  return newObj;
}

// 사용 예시
const user: UserDomain.User = {
  id: 'user-1',
  email: 'test@example.com',
  username: 'testuser',
  profile: {
    firstName: 'John',
    lastName: 'Doe'
  },
  preferences: {
    theme: 'dark',
    language: 'ko',
    notifications: {
      email: true,
      push: false,
      sms: false
    }
  },
  createdAt: new Date(),
  updatedAt: new Date()
};

// 타입 안전한 중첩 값 접근
const firstName = getNestedValue(user, 'profile.firstName'); // string
const emailNotifications = getNestedValue(user, 'preferences.notifications.email'); // boolean

// 타입 안전한 중첩 값 설정
const updatedUser = setNestedValue(user, 'profile.firstName', 'Jane');

// 1단계: 타입 정의 파일 생성 (*.d.ts)
// legacy/user.d.ts - 기존 JavaScript 모듈에 대한 타입 정의
declare module 'legacy-user-module' {
  export interface LegacyUser {
    id: number;
    name: string;
    email: string;
  }

  export function getLegacyUser(id: number): Promise<LegacyUser>;
  export function updateLegacyUser(id: number, data: Partial<LegacyUser>): Promise<LegacyUser>;
}

// 2단계: 어댑터 패턴으로 기존 코드 감싸기
import { LegacyUser, getLegacyUser as legacyGetUser } from 'legacy-user-module';

// 새로운 타입 시스템에 맞게 변환
function adaptLegacyUser(legacyUser: LegacyUser): UserDomain.User {
  return {
    id: String(legacyUser.id), // number -> string 변환
    email: legacyUser.email,
    username: legacyUser.name,
    profile: {
      firstName: legacyUser.name.split(' ')[0] || '',
      lastName: legacyUser.name.split(' ')[1] || '',
    },
    preferences: {
      theme: 'system', // 기본값 설정
      language: 'ko',
      notifications: {
        email: true,
        push: true,
        sms: false
      }
    },
    createdAt: new Date(), // 기본값
    updatedAt: new Date()
  };
}

// 3단계: 타입 안전한 래퍼 함수 생성
export async function getUser(id: string): Promise<UserDomain.User> {
  try {
    const legacyUser = await legacyGetUser(Number(id));
    return adaptLegacyUser(legacyUser);
  } catch (error) {
    console.error('Failed to fetch user:', error);
    throw new Error(`User with id ${id} not found`);
  }
}

// 기존 코드와 새 코드 간의 타입 호환성 보장
type LegacyCompatible<T> = {
  [K in keyof T]: T[K] extends string | number | boolean | null | undefined
    ? T[K]
    : T[K] extends Date
      ? Date | string | number  // Date는 다양한 형태로 받을 수 있게
      : T[K] extends object
        ? LegacyCompatible<T[K]> | any  // 객체는 점진적 적용
        : T[K] | any;  // 나머지는 any로 허용
};

// 마이그레이션 중인 컴포넌트를 위한 타입
interface TransitionUser extends LegacyCompatible<UserDomain.User> {
  // 기존 코드에서 사용하던 필드들도 선택적으로 허용
  name?: string;  // profile.firstName + profile.lastName 대신
  displayName?: string;
}

// 점진적 타입 체크 함수
function isFullyTypedUser(user: TransitionUser): user is UserDomain.User {
  return (
    typeof user.id === 'string' &&
    typeof user.email === 'string' &&
    typeof user.username === 'string' &&
    typeof user.profile === 'object' &&
    typeof user.preferences === 'object'
  );
}

// 마이그레이션 상태에 따른 다른 처리
function handleUser(user: TransitionUser): void {
  if (isFullyTypedUser(user)) {
    // 완전히 타입화된 사용자는 새로운 로직 사용
    console.log(`Welcome, ${user.profile.firstName}!`);
  } else {
    // 레거시 사용자는 기존 로직 사용
    console.log(`Welcome, ${user.name || user.username}!`);
  }
}

// 마이그레이션 완료 검증을 위한 체크리스트 타입
interface MigrationChecklist {
  // 파일 단위 체크
  fileExtension: '.ts' | '.tsx';  // .js/.jsx -> .ts/.tsx 변환 완료
  noImplicitAny: boolean;         // any 타입 명시적 선언
  strictNullChecks: boolean;      // null/undefined 엄격 체크
  noUnusedLocals: boolean;        // 사용하지 않는 변수 제거

  // 타입 정의 체크
  interfacesDefined: boolean;     // 모든 객체에 인터페이스 정의
  typeGuardsImplemented: boolean; // 런타임 타입 검증 구현
  errorHandlingTyped: boolean;    // 에러 처리 타입 정의

  // 테스트 커버리지
  typeTestsCovered: boolean;      // 타입 관련 테스트 작성
  integrationTestsPassed: boolean; // 통합 테스트 통과
}

// 마이그레이션 진행 상태 추적
function trackMigrationProgress(checklist: MigrationChecklist): number {
  const completedItems = Object.values(checklist).filter(Boolean).length;
  const totalItems = Object.keys(checklist).length;
  return Math.round((completedItems / totalItems) * 100);
}

// ✅ 권장하는 타입 네이밍 규칙

// 인터페이스: PascalCase + 명확한 의미
interface UserProfile { }        // ✅ 좋음
interface IUserProfile { }       // ❌ I 접두사 불필요
interface userProfile { }        // ❌ camelCase 사용 금지

// 타입 별칭: PascalCase + Type 접미사 (구분이 필요한 경우)
type UserActionType = 'create' | 'update' | 'delete';  // ✅ 좋음
type UserAction = 'create' | 'update' | 'delete';      // ✅ 더 좋음
type userActionType = 'create' | 'update' | 'delete';  // ❌ camelCase 금지

// 제네릭: 의미 있는 이름 사용
interface ApiResponse<TData> { }     // ✅ 좋음 - 데이터 타입임을 명시
interface Repository<TEntity> { }    // ✅ 좋음 - 엔티티임을 명시
interface ApiResponse<T> { }         // ❌ 의미 불명확

// 상수 타입: UPPER_SNAKE_CASE + as const
const USER_ROLES = ['admin', 'user', 'guest'] as const;  // ✅ 좋음
type UserRole = typeof USER_ROLES[number];                // ✅ 타입 추출

// 네임스페이스: PascalCase + Domain 접미사
namespace UserDomain { }    // ✅ 좋음
namespace ApiDomain { }     // ✅ 좋음
namespace userDomain { }    // ❌ camelCase 금지

// types/domains/user.ts - 도메인별 타입 모음
export namespace UserDomain {
  export interface User {
    id: string;
    email: string;
    profile: UserProfile;
  }

  export interface UserProfile {
    firstName: string;
    lastName: string;
  }

  export type UserRole = 'admin' | 'user' | 'guest';
  export type UserStatus = 'active' | 'inactive' | 'pending';
}

// types/api/index.ts - API 관련 타입 통합
export interface ApiResponse<TData> {
  success: boolean;
  data: TData;
  message: string;
}

export interface PaginatedResponse<TData> extends ApiResponse<TData[]> {
  pagination: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
  };
}

// types/index.ts - 전체 타입 재export
export * from './domains/user';
export * from './domains/product';
export * from './api';

// 사용하는 곳에서는 깔끔하게 import
import { UserDomain, ApiResponse } from '@/types';

// .eslintrc.js - 팀 TypeScript 린트 규칙
{
  "extends": [
    "@typescript-eslint/recommended",
    "@typescript-eslint/recommended-requiring-type-checking"
  ],
  "rules": {
    // 타입 관련 규칙
    "@typescript-eslint/no-any": "error",
    "@typescript-eslint/no-explicit-any": "error",
    "@typescript-eslint/prefer-nullish-coalescing": "error",
    "@typescript-eslint/prefer-optional-chain": "error",

    // 네이밍 규칙
    "@typescript-eslint/naming-convention": [
      "error",
      {
        "selector": "interface",
        "format": ["PascalCase"]
      },
      {
        "selector": "typeAlias",
        "format": ["PascalCase"]
      },
      {
        "selector": "enum",
        "format": ["PascalCase"]
      }
    ],

    // 임포트 규칙
    "@typescript-eslint/consistent-type-imports": [
      "error",
      { "prefer": "type-imports" }
    ]
  }
}

// tsconfig.json - 엄격한 TypeScript 설정
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "noImplicitReturns": true,
    "noImplicitThis": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "exactOptionalPropertyTypes": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

// 코드 리뷰 시 확인해야 할 TypeScript 체크포인트

// ✅ 좋은 예시
interface CreateUserRequest {
  email: string;
  password: string;
  profile: {
    firstName: string;
    lastName: string;
  };
}

function createUser(request: CreateUserRequest): Promise<UserDomain.User> {
  // 타입이 명확하고 의도가 분명함
  return apiClient.request('POST /api/users', { body: request });
}

// ❌ 리뷰에서 개선 요청할 예시
function createUser(data: any): Promise<any> {  // any 사용 금지
  return fetch('/api/users', {
    method: 'POST',
    body: JSON.stringify(data)
  }).then(res => res.json());  // 타입 체크 없음
}

// 리뷰 코멘트 템플릿
const reviewComments = {
  anyType: "any 타입 사용을 피하고 구체적인 타입을 정의해주세요.",
  missingInterface: "매개변수 객체에 대한 인터페이스를 정의해주세요.",
  noTypeGuard: "외부 데이터를 사용할 때는 타입 가드를 추가해주세요.",
  inconsistentNaming: "팀 네이밍 컨벤션에 맞게 수정해주세요.",
  missingGeneric: "재사용성을 위해 제네릭 사용을 고려해보세요."
};

// user-service.js (Before - JavaScript)
class UserService {
  constructor(apiClient) {
    this.apiClient = apiClient;
    this.cache = new Map();
  }

  async getUser(id) {
    if (this.cache.has(id)) {
      return this.cache.get(id);
    }

    try {
      const response = await this.apiClient.get(`/users/${id}`);
      const user = response.data;

      // 런타임에 에러 발생 가능한 부분들
      if (user && user.profile) {
        user.displayName = user.profile.firstName + ' ' + user.profile.lastName;
      }

      this.cache.set(id, user);
      return user;
    } catch (error) {
      console.error('Failed to fetch user:', error);
      return null;  // null 반환으로 인한 잠재적 에러
    }
  }

  async updateUser(id, updates) {
    try {
      // updates 객체의 구조를 알 수 없음
      const response = await this.apiClient.put(`/users/${id}`, updates);
      const updatedUser = response.data;

      this.cache.set(id, updatedUser);
      return updatedUser;
    } catch (error) {
      throw error;  // 에러 타입 불명확
    }
  }

  // 배열 조작에서 타입 에러 발생 위험
  filterActiveUsers(users) {
    return users.filter(user => user.status === 'active');
  }
}

// user-service.ts (After - TypeScript)
import type { UserDomain, ApiResponse } from '@/types';

interface UserServiceError {
  code: 'USER_NOT_FOUND' | 'NETWORK_ERROR' | 'VALIDATION_ERROR';
  message: string;
  originalError?: Error;
}

class UserServiceError extends Error {
  constructor(
    public code: UserServiceError['code'],
    message: string,
    public originalError?: Error
  ) {
    super(message);
    this.name = 'UserServiceError';
  }
}

interface UserServiceConfig {
  cacheEnabled: boolean;
  cacheTTL: number; // milliseconds
}

class UserService {
  private cache = new Map<string, { user: UserDomain.User; timestamp: number }>();
  private config: UserServiceConfig;

  constructor(
    private apiClient: TypedApiClient,
    config: Partial<UserServiceConfig> = {}
  ) {
    this.config = {
      cacheEnabled: true,
      cacheTTL: 5 * 60 * 1000, // 5분
      ...config
    };
  }

  async getUser(id: string): Promise<UserDomain.User> {
    // 캐시 확인 (타입 안전)
    if (this.config.cacheEnabled && this.isCacheValid(id)) {
      const cached = this.cache.get(id)!;
      return cached.user;
    }

    try {
      const response = await this.apiClient.request('GET /api/users/:id', {
        params: { id }
      });

      if (!response.success) {
        throw new UserServiceError('USER_NOT_FOUND', response.message);
      }

      const user = response.data;

      // 타입 안전한 속성 접근
      const displayName = this.createDisplayName(user.profile);
      const enrichedUser: UserDomain.User = {
        ...user,
        // 계산된 속성 추가 (타입 안전)
        displayName
      };

      // 캐시 저장
      if (this.config.cacheEnabled) {
        this.cache.set(id, {
          user: enrichedUser,
          timestamp: Date.now()
        });
      }

      return enrichedUser;
    } catch (error) {
      if (error instanceof UserServiceError) {
        throw error;
      }

      throw new UserServiceError(
        'NETWORK_ERROR',
        `Failed to fetch user ${id}`,
        error instanceof Error ? error : new Error(String(error))
      );
    }
  }

  async updateUser(
    id: string,
    updates: Partial<Omit<UserDomain.User, 'id' | 'createdAt' | 'updatedAt'>>
  ): Promise<UserDomain.User> {
    try {
      const response = await this.apiClient.request('PUT /api/users/:id', {
        params: { id },
        body: updates
      });

      if (!response.success) {
        throw new UserServiceError('VALIDATION_ERROR', response.message);
      }

      const updatedUser = response.data;

      // 캐시 업데이트
      if (this.config.cacheEnabled) {
        this.cache.set(id, {
          user: updatedUser,
          timestamp: Date.now()
        });
      }

      return updatedUser;
    } catch (error) {
      if (error instanceof UserServiceError) {
        throw error;
      }

      throw new UserServiceError(
        'NETWORK_ERROR',
        `Failed to update user ${id}`,
        error instanceof Error ? error : new Error(String(error))
      );
    }
  }

  // 타입 안전한 필터링
  filterActiveUsers(users: UserDomain.User[]): UserDomain.User[] {
    return users.filter((user): user is UserDomain.User => {
      return user.status === 'active';
    });
  }

  // 타입 안전한 유틸리티 메서드들
  private createDisplayName(profile: UserDomain.UserProfile): string {
    const { firstName, lastName } = profile;
    return `${firstName} ${lastName}`.trim();
  }

  private isCacheValid(id: string): boolean {
    const cached = this.cache.get(id);
    if (!cached) return false;

    const now = Date.now();
    return (now - cached.timestamp) < this.config.cacheTTL;
  }

  // 캐시 관리
  clearCache(): void {
    this.cache.clear();
  }

  removeCacheEntry(id: string): boolean {
    return this.cache.delete(id);
  }
}

// 타입 안전한 팩토리 함수
export function createUserService(
  apiClient: TypedApiClient,
  config?: Partial<UserServiceConfig>
): UserService {
  return new UserService(apiClient, config);
}

// 타입 정의 export
export type { UserServiceError, UserServiceConfig };

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",

    // 성능 최적화 옵션
    "incremental": true,                    // 증분 컴파일 활성화
    "tsBuildInfoFile": ".tsbuildinfo",     // 빌드 정보 캐시 파일
    "skipLibCheck": true,                  // 라이브러리 타입 체크 스킵
    "skipDefaultLibCheck": true,           // 기본 라이브러리 체크 스킵

    // 타입 체크 최적화
    "noEmit": true,                        // 개발 시 JS 파일 생성 안함
    "isolatedModules": true,               // 파일별 독립적 컴파일
    "useDefineForClassFields": true,       // 클래스 필드 최적화

    // 경로 별칭으로 import 속도 향상
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@/components/*": ["src/components/*"],
      "@/types/*": ["src/types/*"],
      "@/utils/*": ["src/utils/*"]
    }
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx"
  ],
  "exclude": [
    "node_modules",
    "dist",
    "build",
    "**/*.test.ts",        // 테스트 파일 제외 (별도 설정)
    "**/*.spec.ts"
  ]
}

// packages/shared/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "composite": true,              // 프로젝트 레퍼런스 활성화
    "declaration": true,            // .d.ts 파일 생성
    "declarationMap": true,         // 선언 파일 소스맵
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src/**/*"]
}

// packages/frontend/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": true
  },
  "references": [
    { "path": "../shared" }         // 공유 패키지 참조
  ],
  "include": ["src/**/*"]
}

// 루트 tsconfig.json
{
  "files": [],
  "references": [
    { "path": "./packages/shared" },
    { "path": "./packages/frontend" },
    { "path": "./packages/backend" }
  ]
}

// ✅ 성능이 좋은 타입 패턴

// 1. 유니온 타입보다는 enum 사용 (작은 집합의 경우)
enum UserStatus {
  ACTIVE = 'active',
  INACTIVE = 'inactive',
  PENDING = 'pending'
}
// vs
type UserStatus = 'active' | 'inactive' | 'pending'; // 큰 유니온은 느릴 수 있음

// 2. 깊은 객체보다는 플랫한 구조 선호
interface OptimizedUser {
  id: string;
  email: string;
  firstName: string;
  lastName: string;
  theme: string;
  language: string;
}
// vs
interface DeepUser {
  id: string;
  email: string;
  profile: {
    personal: {
      name: {
        first: string;
        last: string;
      };
    };
    preferences: {
      ui: {
        theme: string;
        language: string;
      };
    };
  };
}

// 3. 조건부 타입 사용 최소화 (필요한 경우만)
// 복잡한 조건부 타입은 컴파일 시간을 증가시킴
type SimpleMapping<T> = T extends string ? string[] : T[];
// vs
type ComplexMapping<T> = T extends string
  ? T extends `${infer Start}-${infer End}`
    ? Start extends 'user'
      ? UserMapping<End>
      : DefaultMapping<End>
    : StringMapping<T>
  : T extends number
    ? NumberMapping<T>
    : DefaultMapping<T>;

// 타입 가드 최적화
// ❌ 매번 타입 체크하는 비효율적인 방법
function processUsers(users: unknown[]): UserDomain.User[] {
  return users
    .filter(isUser)  // 모든 요소를 체크
    .map(user => ({
      ...user,
      displayName: createDisplayName(user.profile)
    }));
}

// ✅ 한 번만 체크하는 효율적인 방법
function processUsersOptimized(users: unknown[]): UserDomain.User[] {
  const validUsers: UserDomain.User[] = [];

  for (const user of users) {
    if (isUser(user)) {
      validUsers.push({
        ...user,
        displayName: createDisplayName(user.profile)
      });
    }
  }

  return validUsers;
}

// 메모이제이션으로 반복 계산 방지
const memoizedDisplayName = (() => {
  const cache = new Map<string, string>();

  return (profile: UserDomain.UserProfile): string => {
    const key = `${profile.firstName}-${profile.lastName}`;

    if (cache.has(key)) {
      return cache.get(key)!;
    }

    const displayName = `${profile.firstName} ${profile.lastName}`.trim();
    cache.set(key, displayName);
    return displayName;
  };
})();