Declaration merging은 TypeScript가 같은 이름을 가진 여러 선언을 하나의 정의로 결합하는 것입니다. Interface, namespace, 그리고 일부 다른 구문이 자동으로 병합됩니다.
interface Box { width: number; }
interface Box { height: number; }
// Box는 이제 { width: number; height: number } — 둘이 병합됨
이것이 소유하지 않은 라이브러리나 전역에 타입을 추가하는 방법입니다:
// Express의 Request에 커스텀 프로퍼티 추가
declare global {
namespace Express {
interface Request { user?: { id: string }; } // Express.Request에 병합됨
}
}
request.user; // ✅ 이제 어디서나 타입이 지정됨
// 모듈 보강
declare module "some-lib" {
interface Options { newOption: boolean; }
}
라이브러리의 Request/Options가 interface이기 때문에, 당신의 선언은 충돌하는 대신 그 안으로 병합됩니다 — 편집할 수 없는 타입을 안전하게 확장하게 해줍니다.
function greet() {}
namespace greet { export const version = "1.0"; }
greet.version; // "1.0" — namespace가 함수에 병합됨
type은 왜 이것을 못하나type A = { x: number };
type A = { y: number }; // ❌ 오류: 중복된 식별자
Type alias는 고유합니다. 오직 interface(와 namespace)만 병합됩니다 — 확장 가능한 공개 API shape에 interface를 사용하는 핵심 이유입니다.
Declaration merging은 **모듈 보강(module augmentation)**을 떠받치는 메커니즘입니다 — Express request 확장, window에 추가, 라이브러리 타입 커스터마이징, 테마 시스템 등입니다.
제어할 수 없는 타입을 포크하지 않고 적응시켜야 하는 실제 앱을 타이핑하는 데 필수적인 지식입니다.