.d.ts 파일 작성법

자바스크립트 라이브러리 사용: jQuery, Lodash, React 등 수많은 자바스크립트 라이브러리들은 .js 파일 형태로 배포됩니다.

자체 선언이나 별도 타입 정보가 없다면 설정에 따라 any가 되거나 선언 누락 오류가 납니다. JavaScript를 분석 대상으로 포함하면 JSDoc과 코드에서 타입 정보를 얻을 수도 있습니다.

레거시 자바스크립트 코드 연동: 기존에 작성된 자바스크립트 코드를 타입스크립트 프로젝트에 통합할 때, 명시적인 타입 정보를 제공하여 타입 안전성을 확보합니다.

타입스크립트 라이브러리 배포: 타입스크립트 라이브러리에서 declaration 생성을 설정하면 JavaScript 구현과 함께 .d.ts를 배포할 수 있습니다.

사용자는 .js 파일(실제 구현)과 .d.ts 파일(타입 정보)을 함께 받아 타입스크립트 환경에서 라이브러리를 안전하게 사용할 수 있습니다.

전역 변수/객체 선언: 브라우저 환경에서 window, document와 같이 전역 스코프에 존재하는 객체나 변수의 타입을 명시할 때 사용됩니다.

declare var / declare let / declare const: 전역 변수를 선언합니다.

declare const MY_GLOBAL_CONFIG: {
  apiUrl: string;
  timeout: number;
};

declare let globalCounter: number;

declare function: 전역 함수를 선언합니다.

declare function customLog(message: string): void;
declare function calculateSum(...numbers: number[]): number;

declare class: 클래스를 선언합니다.

declare class MyEventEmitter<T> {
  on(eventName: string, listener: (data: T) => void): void;
  emit(eventName: string, data: T): void;
}

declare enum: 다른 곳에서 제공하는 열거형 값의 타입을 설명합니다. 아래 일반 ambient enum은 멤버에 접근할 런타임 객체가 따로 필요하며 const enum과 같지 않습니다.

declare enum StatusCode {
  Success = 200,
  NotFound = 404,
  ServerError = 500
}

declare namespace: 관련된 전역 변수, 함수, 클래스 등을 하나의 논리적인 그룹으로 묶습니다. (7장 3절 "네임스페이스" 참조)

declare namespace jQuery {
  interface Event {
    // ...
  }
  function ajax(url: string, settings?: any): JQueryPromise<any>;
  const version: string;
}

declare var $: typeof jQuery; // $도 jQuery 네임스페이스와 동일한 타입을 가짐

이 예시처럼 .d.ts 파일에서 declare namespace는 전역 스코프에 특정 이름을 가진 객체가 존재하며 그 안에 멤버들이 있음을 선언합니다.

declare module: 특정 경로 또는 모듈 이름을 가진 자바스크립트 모듈의 타입을 선언합니다.

• ES 모듈/CommonJS 모듈의 타입 선언

  declare module 'my-custom-module' {
    export interface Options {
      debug: boolean;
      port: number;
    }
    export function init(options: Options): void;
    export const version: string;
    export default class Client { // default export
      constructor(apiUrl: string);
      getData(): Promise<any>;
    }
  }

  이 선언이 프로젝트에 포함되면 해당 import의 타입을 검사할 수 있습니다. 실제 실행에는 같은 이름과 export를 제공하는 모듈 구현이 별도로 필요합니다.

• 파일 확장자를 위한 모듈 선언: 웹팩과 같은 번들러를 사용할 때 .css, .png 등 자바스크립트가 아닌 파일을 import하는 경우가 있습니다. 이들에 대한 타입을 선언할 때도 declare module을 사용합니다.

  declare module '*.png' {
    const content: string; // 이미지 파일은 URL 문자열로 로드된다고 가정
    export default content;
  }
  
  declare module '*.svg' {
    import * as React from 'react';
    export const ReactComponent: React.FunctionComponent<React.SVGProps<SVGSVGElement> & { title?: string }>;
    const src: string;
    export default src;
  }

  선언이 포함되면 이미지 import의 타입을 설명할 수 있습니다. PNG의 URL과 SVG의 ReactComponent를 실제로 제공하는 번들러·loader 설정은 별도로 필요합니다.

필요한 타입만 선언: .d.ts 파일은 실제 구현 코드를 포함하지 않으므로, 자바스크립트 코드가 외부에 노출하는 멤버들만 선언하면 됩니다.

내부적으로만 사용되는 변수나 함수는 선언할 필요가 없습니다.

가능한 한 구체적인 타입 사용: any 타입을 남용하지 않고, 가능한 한 정확하고 구체적인 타입을 사용하여 타입 안전성을 극대화해야 합니다.

제네릭, 유니온 타입, 인터섹션 타입 등을 적극적으로 활용하세요.

불필요한 export 피하기: .d.ts 파일이 모듈이 아닌 전역 타입 선언을 목적으로 한다면, 최상위 레벨에서 export를 사용하지 않아야 합니다.

export를 사용하면 해당 .d.ts 파일은 모듈로 간주됩니다.

• 전역 선언: declare var $, declare function jQuery()
• 모듈 선언: declare module 'lodash' { export function ... }

자동 생성 활용: tsc --declaration 또는 tsc -d 옵션을 사용하면 타입스크립트 소스 코드로부터 .d.ts 파일을 자동으로 생성할 수 있습니다.

자동 생성한 선언을 수정해야 한다면 원본 TypeScript API나 생성 설정을 고친 뒤 다시 생성합니다. JavaScript용으로 직접 작성한 선언은 실제 구현과 함께 갱신합니다.

DefinitelyTyped 참조: 널리 사용되는 자바스크립트 라이브러리들은 DefinitelyTyped 프로젝트에서 타입 정의를 제공하며, 이는 @types/ 접두사가 붙은 npm 패키지로 배포됩니다 (예: npm install @types/lodash).

새롭게 .d.ts 파일을 작성하기 전에, 사용할 라이브러리 타입 정의가 이미 존재하는지 먼저 확인하는 것이 좋습니다.