`.d.ts` 선언 파일: JavaScript의 타입 표면 설명하기

"선언 파일은 구현이 아니라, 이미 존재하는 JavaScript를 TypeScript가 이해하도록 적는 계약서야."

실행 코드는 없고 타입만 있다

.d.ts 파일에는 함수, 클래스, 모듈의 공개 모양을 선언하지만 실제 구현을 넣지 않아. 패키지 소비자는 이 정보를 바탕으로 자동 완성과 타입 검사를 받고, 실행할 코드는 별도의 JavaScript에서 가져와.

그래서 선언이 런타임보다 넓거나 틀리면 컴파일은 통과해도 실행 중에 깨져. declare function parse(input: string): Result라고 적었다면 실제 모듈도 그 이름과 동작을 제공해야 해. 선언 파일은 안전을 만들어 내는 것이 아니라 현실을 정확히 기술할 때만 안전을 전달해.

손으로 선언할 때의 원칙

타입이 없는 JavaScript 모듈을 설명할 때는 실제 사용 사례와 런타임 소스를 근거로 최소 계약부터 작성해. 모르는 값을 편하게 any로 덮으면 소비자 전체에 불확실성이 퍼져. 차라리 unknown과 좁히기 지점을 드러내는 편이 정직해.

DefinitelyTyped의 @types/*도 같은 역할을 하지만 라이브러리 버전과 선언 버전이 맞아야 해. 패키지가 자체 타입을 제공한다면 중복된 @types가 충돌하지 않는지도 확인해.

Array, Map, Promise, fetch, document 등의 타입은 node_modules/typescript/lib/ 아래 lib.es5.d.ts, lib.dom.d.ts, lib.es2022.d.ts 같은 선언 파일에 있어. tsconfig의 lib 옵션이 어떤 선언을 불러올지 정해.

직접 선언을 쓸 때

타입 없는 custom-lib를 설명하려면 declare module 'custom-lib' 안에 실제로 쓰는 내보내기부터 적어. 선언 파일이 프로젝트의 include나 typeRoots 범위에 들어오는지 확인하고, npm 패키지라면 루트의 types 필드가 선언 진입점을 가리키게 해.

좋은 .d.ts는 JavaScript 현실과 일치하는 작고 안정된 공개 표면이야. 선언 생성 성공만 보지 말고 실제 소비 프로젝트에서 import와 실행을 함께 시험해.

Code

타입 안 붙은 module 의 .d.ts 쓰기·typescript

// my-lib.d.ts — 타입 안 붙은 module 선언.
declare module 'untyped-lib' {
  export function add(a: number, b: number): number;
  export const VERSION: string;
  export default class Thing {
    constructor(name: string);
    getName(): string;
  }
}

// consumer.ts — 이제 타입 붙은 module 사용.
import Thing, { add, VERSION } from 'untyped-lib';

add(1, 2);            // ✅ 타입 붙음
Thing;                // ✅ class
VERSION;              // ✅ string

// Declaration 파일이 global 도 선언 가능.
declare global {
  interface Window {
    appConfig: { apiBase: string };
  }
}
window.appConfig.apiBase;   // ✅ — 이제 어디서나 타입 붙음

Exercise

타입이 없는 작은 JavaScript 라이브러리를 가정하고 함수 둘과 상수 하나를 설명하는 .d.ts를 작성해. TypeScript에서 가져와 자동 완성과 실제 실행이 모두 맞는지 확인해.

Hint

declare module 블록은 해당 모듈이 제공하는 내보내기 모양만 설명해. 함수 본문은 넣지 말고 실제 JavaScript 구현과 맞는 시그니처를 적어.

실행 코드는 없고 타입만 있다

손으로 선언할 때의 원칙

직접 선언을 쓸 때

Code

External links

Exercise

Progress

댓글 0