선언 파일

기존 JavaScript 유틸리티에 타입을 붙이는 네 지점

.d.ts 파일은 구현을 다시 쓰는 파일이 아니라, 이미 존재하는 .js 모듈의 공개 API를 타입 시그니처로 설명하는 계약서다.

파일 배치

구현 StringUtils.js가 실제 함수를 내보낸다.

선언 StringUtils.d.ts가 함수 이름과 타입만 적는다.

사용 app.ts는 선언을 읽어 잘못된 호출을 컴파일 전에 잡는다.

구현 파일에서 컴파일 오류까지

순서	확인 지점	작성 내용	타입스크립트가 얻는 정보
01	JS API 표면 내보내는 함수와 인자 의미를 확인한다.	capitalize, isEmpty 이름을 고정한다.	어떤 식별자를 import할 수 있는지 알게 된다.
02	모듈 경로 사용 코드의 import 문자열과 맞춘다.	declare module './StringUtils'	해당 JS 파일에 붙일 타입 선언을 찾는다.
03	함수 시그니처 입력과 반환 타입을 실제 동작에 맞춘다.	export function capitalize(str: string): string;	인자 타입과 반환 타입을 IDE와 컴파일러가 함께 사용한다.
04	널 허용 범위 빈 값 처리 함수의 입력 폭을 정한다.	string \| null \| undefined	허용되는 빈 값과 잘못된 인자를 구분한다.
05	소비 코드 타입 선언이 적용되는 호출을 확인한다.	import { capitalize, isEmpty }	capitalize(123) 같은 호출을 오류로 표시한다.

실행 없음 .d.ts에는 구현 코드가 아니라 타입 설명만 둔다.

API 계약 함수 이름, 매개변수, 반환 타입, export 방식을 외부 사용자에게 알려 준다.

도구 지원 자동 완성, 툴팁, 잘못된 인자 검사를 타입 정보로 제공한다.

타입 없음 선언 파일이 없으면 JS 모듈이 any처럼 흘러가 실수를 놓치기 쉽다.

타입 있음 선언이 있으면 잘못된 인자와 반환값 오해가 컴파일 단계에서 드러난다.

주의 선언은 실제 JS 동작을 검증하지 않으므로, 타입 시그니처가 구현과 어긋나지 않게 관리해야 한다.