icon

.d.ts 파일 작성법

 .d.ts 파일은 타입스크립트에서 타입 선언을 위한 특별한 파일입니다.

 이 파일은 자바스크립트 코드의 타입 정보를 제공하여 타입스크립트의 타입 검사와 자동 완성 기능을 지원합니다.

.d.ts 파일의 목적과 중요성

  • 자바스크립트 라이브러리에 대한 타입 정보 제공
  • 코드 에디터의 인텔리센스 지원 강화
  • 타입 안정성 향상 및 런타임 오류 감소

기본 구조와 작성 규칙

 기본 구조

// example.d.ts
declare function myFunction(a: string): number;
declare const myConstant: number;
interface MyInterface {
    prop: string;
}

 작성 규칙

  • declare 키워드 사용하여 변수, 함수 등 선언
  • 실제 구현 코드는 포함하지 않음
  • 파일 확장자는 .d.ts로 지정

다양한 타입 선언 방법

  1. 인터페이스
interface User {
    id: number;
    name: string;
    email?: string;
}
  1. 타입 별칭
type Point = {
    x: number;
    y: number;
};
  1. 함수 시그니처
declare function calculateArea(width: number, height: number): number;

모듈에 대한 타입 선언

// myModule.d.ts
declare module "myModule" {
    export function someFunction(): void;
    export interface SomeInterface {
        prop: string;
    }
}

 사용 예

import { someFunction, SomeInterface } from "myModule";

고급 타입 기능 활용

  1. 제네릭 타입
interface Container<T> {
    value: T;
}
  1. 조건부 타입
type TypeName<T> = 
    T extends string ? "string" :
    T extends number ? "number" :
    T extends boolean ? "boolean" :
    "object";

전역 선언

 전역 변수, 함수, 클래스 선언

// globals.d.ts
declare const GlobalConfig: {
    apiUrl: string;
};
 
declare function globalFunction(): void;
 
declare class GlobalClass {
    static staticMethod(): void;
}

 주의사항

  • 전역 선언은 신중히 사용 (네임스페이스 오염 가능성)
  • 모듈 시스템 사용 시 전역 선언 대신 import/export 사용 권장

네임스페이스를 이용한 그룹화

// myNamespace.d.ts
declare namespace MyNamespace {
    interface MyInterface {
        prop: string;
    }
    function myFunction(): void;
}

 장점 : 관련 선언을 논리적으로 그룹화

 단점 : 모듈 시스템에 비해 유연성 부족

.d.ts 파일의 상속과 확장

 파일 간 참조

base.d.ts
interface BaseInterface {
    id: number;
}
extended.d.ts
/// <reference path="./base.d.ts" />
interface ExtendedInterface extends BaseInterface {
    name: string;
}

 의존성 관리

  • 명시적 참조 사용 (/// <reference />)
  • 모듈 시스템 활용 (import/export)

자동 생성 vs 수동 작성

 자동 생성

  • tsc --declaration 옵션으로 자동 생성
  • 타입스크립트 코드에서 직접 생성되어 정확성 높음

 수동 작성

  • 더 세밀한 타입 제어 가능
  • 자바스크립트 라이브러리에 대한 타입 정의 시 필요

 사용 시나리오

  • 자동 생성 : 타입스크립트 프로젝트의 API 정의
  • 수동 작성 : 써드파티 자바스크립트 라이브러리 타입 정의

Best Practices와 유지보수 전략

 1. 명확성 유지

  • 의미 있는 이름 사용
  • 복잡한 타입에 주석 추가
/**
 * 사용자 정보를 나타내는 인터페이스
 */
interface User {
    /** 고유 식별자 */
    id: number;
    /** 사용자 이름 */
    name: string;
}

 2. 버전 관리

  • 라이브러리 버전과 .d.ts 파일 버전 동기화
  • 주요 변경사항 문서화

 3. 모듈화

  • 관련 선언을 별도 파일로 분리
  • 필요한 경우에만 import/export 사용

 4. 테스트

  • 선언 파일에 대한 테스트 작성
  • DTSlint 등 도구 활용

 5. 확장성 고려

  • 제네릭 사용으로 재사용성 향상
  • 유니온 타입으로 유연성 확보
type Result<T> = {
    success: true;
    data: T;
} | {
    success: false;
    error: string;
};

 6. 라이브러리 특성 반영

  • 라이브러리의 API 스타일 존중
  • 오버로딩을 통한 다양한 사용 케이스 지원
declare function fetch(url: string): Promise<Response>;
declare function fetch(url: string, options: RequestInit): Promise<Response>;

 7. 불필요한 any 타입 지양

  • 가능한 구체적인 타입 사용
  • unknown 타입 활용 검토

 8. 네임스페이스 vs 모듈

  • 가능한 ES 모듈 문법 사용
  • 레거시 지원 시에만 네임스페이스 사용

 9. 조건부 타입 활용

  • 복잡한 타입 로직 구현에 활용
  • 타입 추론 개선

 10. 지속적인 업데이트

  • API 변경 시 즉시 .d.ts 파일 업데이트
  • 커뮤니티 피드백 반영

 .d.ts 파일은 타입스크립트 생태계에서 핵심적인 역할을 합니다.

 이 파일을 통해 자바스크립트 코드에 타입 안정성을 부여하고, 개발자 경험을 크게 향상시킬 수 있습니다.

 효과적인 .d.ts 파일 작성은 프로젝트의 품질과 생산성에 직접적인 영향을 미치므로, 위의 Best Practices를 고려하여 신중하게 접근해야 합니다.

 오픈 소스 라이브러리를 개발할 때, 잘 작성된 .d.ts 파일은 해당 라이브러리의 사용성과 채택률을 크게 높일 수 있습니다.

 .d.ts 파일 작성은 단순히 타입 정보를 제공하는 것 이상의 의미를 갖습니다.

 이는 API 설계의 명확성을 높이고, 코드의 의도를 문서화하며 타입 시스템을 통해 프로그래밍 오류를 사전에 방지하는 중요한 도구입니다.

이전으로다음으로