[typescript] 선언 합침, 외부 선언

1. 선언 합침 (Declaration Merging)

선언 합침이란, 동일한 이름을 가진 인터페이스, 클래스, enum 등이 여러 번 선언되었을 때 TypeScript 컴파일러가 이 선언들을 하나로 병합하는 기능입니다.

// 첫 번째 선언
interface User {
  name: string;
}

// 두 번째 선언
interface User {
  age: number;
}

// 최종적으로 병합된 User는 { name: string, age: number } 입니다.
const user: User = { name: 'Alice', age: 30 };

왜 사용할까?

• 기존 인터페이스에 새 속성을 추가하여 확장할 수 있습니다.
• 외부 라이브러리를 직접 수정하지 않고 원하는 기능이나 타입을 추가할 수 있습니다.

2. 외부 선언 (Ambient Declaration)

declare 키워드를 사용하여 TypeScript에게 외부 환경(브라우저, Node.js 등)에 이미 존재하거나, 다른 모듈에 정의된 타입을 보완하거나 확장하는 방법입니다.

주요 사용법

(1) 전역 스코프 확장 (declare global)

전역 스코프에 타입이나 변수를 추가할 때 사용합니다.

export {};

declare global {
  type Maybe<T> = T | null | undefined;
}

// 이제 Maybe<string>과 같은 타입을 모든 파일에서 별도 import 없이 사용 가능합니다.
const name: Maybe<string> = 'Alice';

• export {}는 파일을 모듈 스코프로 만들어, 다른 전역 선언과 충돌을 방지합니다.
• 자주 쓰이는 타입을 전역으로 선언하면 코드량이 줄고 효율성이 높아집니다.

(2) 모듈 확장 (Module Augmentation)

기존 모듈의 인터페이스에 새로운 속성을 추가할 때 사용합니다.

declare module "#app" {
  interface PageMeta {
    pageType?: string;
  }
}

// 이제 PageMeta에 pageType 속성을 사용할 수 있습니다.

Nuxt 3 등 가상 모듈을 사용하는 환경에서도 매우 유용합니다.

3. 선언 합침의 작동 원리

TypeScript는 동일한 이름의 인터페이스 선언들을 발견하면, 각 선언의 속성들을 하나로 합쳐줍니다.

interface Foo { a: string; }
interface Foo { b: number; }

// 최종 Foo 타입은 { a: string, b: number }

이를 통해 필요한 속성을 점진적으로 추가하며 인터페이스를 확장할 수 있습니다.

4. 외부 선언의 주요 구문

• declare global { ... }: 전역 타입이나 변수를 선언할 때 사용합니다.
  • 브라우저 또는 Node.js 같은 환경 전역에서 사용될 타입을 선언합니다.
• declare module "..." { ... }: 특정 모듈의 타입을 확장하거나 보완할 때 사용합니다.
  • Vue, React, Express와 같은 외부 라이브러리에 커스텀 타입을 추가할 때 주로 활용됩니다.

이외에도 declare namespace, declare class, declare function 등의 키워드를 통해 외부 선언을 할 수 있습니다.

5. 실무 활용 예시

라이브러리 타입 확장

React 또는 Express의 타입 정의에 커스텀 속성을 추가할 때 유용합니다.

declare module 'express' {
  interface Request {
    user?: User;
  }
}

// 이제 Request 객체에서 user를 사용할 수 있습니다.

프로젝트 전역 타입 정의

프로젝트에서 공통적으로 사용하는 타입을 전역으로 선언하여 편리하게 활용할 수 있습니다.

// types/global.d.ts
declare global {
  interface ApiResponse<T> {
    data: T;
    error?: string;
  }
}

export {};

특정 환경에서만 존재하는 API 선언

특정 런타임 환경에만 존재하는 전역 API를 TypeScript에 알려줍니다.

declare global {
  interface Window {
    customAnalytics?: Analytics;
  }
}

6. 사용 시 주의할 점

• 이름 충돌 방지: 다른 라이브러리와 겹치지 않도록 명확하고 구체적인 이름을 사용합니다.
• tsconfig.json 설정 확인: 선언 파일이 컴파일에 포함되도록 include, files, typeRoots 설정을 확인합니다.
• 모듈 스코프 관리: 전역 선언 파일은 export {} 구문을 넣어 모듈로 만들어 다른 전역 선언과 충돌을 방지합니다.
• 팀 컨벤션 확립: 전역 선언을 과도하게 사용하면 코드 이해를 어렵게 할 수 있습니다. 팀 내에서 명확한 컨벤션을 정하고 사용하는 것이 중요합니다.