선언 병합(Declaration Merging)이란 무엇이며 어떤 상황에서 유용한가요?

선언 병합은 같은 이름의 interface나 namespace 선언을 TypeScript가 하나로 합치는 기능입니다. 라이브러리 타입 보강이나 Express Request 확장처럼 기존 타입에 프로젝트 필드를 추가할 때 유용합니다.

핵심 개념

핵심 기준은 기존 타입 보강과 전역 확장의 위험입니다. 이 개념은 단순한 용어가 아니라, 실제 코드나 시스템에서 반복적으로 생기는 문제를 다루기 위해 등장했습니다.

TypeScript는 런타임 전에 실수를 발견하고 코드의 의도를 타입으로 문서화하기 위해 사용합니다. 좋은 타입은 자동완성, 리팩터링, 협업 안정성을 높여줍니다.

동작 흐름

1. 먼저 어떤 문제가 있는지 확인합니다.
2. 이 개념이 그 문제를 어떤 기준으로 나누거나 해결하는지 봅니다.
3. 실제 코드에서는 입력, 상태, 실행 순서, 비용이 어떻게 바뀌는지 확인합니다.
4. 마지막으로 한계와 부작용을 함께 점검합니다.

실제 예시

declare global {
  namespace Express {
    interface Request {
      user?: {
        id: string;
        role: "admin" | "member";
      };
    }
  }
}

app.get("/me", (req, res) => {
  // Request 타입에 user가 병합되어 안전하게 접근할 수 있습니다.
  res.json(req.user);
});

선언 병합은 기존 라이브러리 타입을 프로젝트 상황에 맞게 보강할 때 유용합니다. 다만 전역 타입을 바꾸는 일이므로 적용 범위와 의도를 명확히 남겨야 합니다.

실무에서 주의할 점

• 타입 단언으로 오류를 덮기보다 타입을 좁히는 코드를 먼저 고려합니다.
• 런타임 검증이 필요한 외부 입력은 타입만으로 안전해지지 않습니다.
• 공개 타입은 너무 구체적이어도, 너무 느슨해도 유지보수가 어려워집니다.

함께 연결해서 보면 좋은 키워드

TS, DeclarationMerging, Interface, 타입확장

정리

한 줄로 정리하면, 선언 병합은 같은 이름의 interface나 namespace 선언을 TypeScript가 하나로 합치는 기능입니다. 라이브러리 타입 보강이나 Express Request 확장처럼 기존 타입에 프로젝트 필드를 추가할 때 유용합니다. 실무에서는 개념을 적용하는 조건과 적용하지 않았을 때 생기는 문제까지 함께 이해하는 것이 중요합니다.

선언 병합이란?

Declaration Merging은 같은 이름의 interface나 namespace 선언이 하나로 합쳐지는 TypeScript 기능입니다.

interface Window {
  appVersion: string;
}

window.appVersion = '1.0.0';

브라우저 전역 객체, Express Request, 라이브러리 타입 확장처럼 기존 타입에 필드를 추가해야 할 때 유용합니다.

Express 예시

declare global {
  namespace Express {
    interface Request {
      user?: { id: string; role: 'admin' | 'user' };
    }
  }
}

이후 미들웨어가 req.user를 설정하고 라우터에서 타입 안전하게 사용할 수 있습니다.

주의사항

선언 병합은 전역적으로 영향을 주므로 남용하면 타입 출처를 추적하기 어렵습니다. 가능하면 확장 파일을 명확히 분리하고, 팀이 쉽게 찾을 수 있는 위치(types/express.d.ts 등)에 둡니다.