11장 선언파일

11.1 선언파일

• 타입스크립트 선언 파일 d.ts 는 타입스크립트 코드의 타입 추론을 돕는 파일입니다
• 타입 선언은 파일 이름이 .d .ts 확장자로 끝나는 선언파일에 작성됩니다.

// types.d.ts
export interface Character {
  catchpharase?: string;
  name: string;

11.2 런타임 값 선언

• declare로 변수를 선언하면 초깃값이 허용되지 않는다는 점을 제외하고 일반적인 변수 선언과 동일한 구문을 사용합니다.

declare let declared: string // Ok

declared let initializer: string = 'Wanda';
//Error : Initailizers are not allowed on ambient contexts.

• 타입 선언만 가능하다(?) -> 본문 설정이 불가능하다

11.2.1 전역 변수

• import 또는 export 문이 없는 타입스크립트 파일은 전역으로 사용된다.

// globals.d.ts
declare const version: string;

// version.ts
export function logVersion() {
  console.log('Version: ${version}'); // Ok
}

11.2.2 전역 인터페이스 병합

• 인터페이스 병합을 이용하면 types/www.d.ts와 같은 파일에서 Window 타입의 전역 window 변수에 존재하는 변수를 선언할수 있게 허용한다.

<script type='text/javascript'>
window.myVersion= '3.1.1';
</script>

interface Window {
  myVersion: string;
}

// index.ts
export function logWindowVersion() {
  console.log('Window version is: ${window.myVersion}');
  window.alert('Built-in window types still work! Hooray!')
}

11.2.3 전역 확장

• 경우에 따라 모듈 파일에 선언된 타입이 전역으로 사용될수 있다.

// types.d.ts
// (모듈 컨텍스트)
declare global {
  // (전역 컨텍스트)
}
// (모듈 컨텍스트)

• types/data.d.ts 파일은 Data 인터페이스를 내보내고 나중에 types/globals.d.ts와 런타임 index.ts 파일에서 이 인터페이스를 가져옴

// types/data.d.ts
export interface Data {
  version: string;
}

• types/global.d.ts 파일에서만 사용할 수 있는 변수와 Data 타입 변수를 declare global 블록 내에 전역으로 선언함.

// types/global.d.ts
import {Data} from "./data";

declare global {
  const globallyDeclared: Data;
}

declare const locallyDeclared: Data;

• 후에 index.ts는 import문 없이 globallyDeclared 변수에 접근할 수 있고, Data를 가져와야 함.

// index.ts
import {Data} from "./data";

function logData(data: Data) {
  console.log('Data version is: ${data.version}');
}

logData(globallyDeclared);
logData(locallyDeclared);
//Error: Cannot find name'locallyDeclared'.

11.3 내장된 선언

11.3.1 라이브러리 선언

• 모던 자바스크립트 런타임에 존재하는 Array, Function 같은 내장된 전역 객체는 lib.[target].d.ts 파일이름으로 선언됩니다.
• 237페이지 Go to Definition 클릭시 결과로 lib.es5.d.ts 파일이 열림
• 타입스크립트는 target으로 지정한 자바스크립트 버전의 모든 최소 버전 lib파일을 포함한다.
• target과 같은 컴파일러 옵션은 13장 '구성 옵션'에서 상세히 다룸.

// lib.es5.d.ts

interface Array<T> {
  length: number;
}

11.3.2 DOM 선언

• DOM 타입이라고 하는 웹 브라우저 타입은 localStorage와 같은 API와 웹 브라우저에서 주로 사용하는 HTMLElement와 같은 형대를 다룹니다.
• DOM 타입은 lib.d.ts 파일과 다른 lib.*.d.ts 선언파일에도 저장됩니다.

//lib.dom.d.ts

interface Storage {
  readOnly length: number;
  clear(): void;
  getItem(key: string): string | null;
}

• lib 컴파일러 옵션을 재정의하지 않은 타입스크립트 프로젝트는 DOM 타입을 기본으로 포함한다.

11.4 모듈 선언

• 선언 파일의 또 다른 중요한 기능은 모듈의 상태를 설명하는 기능입니다.
• 모듈의 문자열 이름 앞에 declare 키워드를 사용하면 모듈의 내용을 타입 시스템에 알릴 수 있다.

// module.d.ts
declare module "my-example-lib" {
  export const value: string;
}

// index.ts
import {value} from "my-example-lib";

console.log(value); // OK

11.4.1 와일드카드 모듈 선언

• 모듈 선언은 자바스크립트와 타입스크립트 파일 확장자가 아닌 특정 파일의 내용을 코드로 가져올 수 있음을 웹 애플리케이션에 알리기 위해 사용합니다.
• 모듈 선언으로 하나의 * 와일드카드를 포함해 해당 패턴과 일치하는 모든 모듈을 나타낼 수 있습니다.

// styles.d.ts
declare module "*module.css" {
  const styles: { [i: string]: string };
  export default styles;
}

// component.ts
import styles form "./styles.module.css";

styles.anyClassName; // 타입: string

11.5 패캐지 타입

11.5.1 선언

• 타입스크립트는 입력된 파일에 대한 .d.ts 출력 파일과 자바스크립트 출력 파일을 함께 생성하는 선언 옵션을 제공합니다.

// index.ts
export const greet = (text: string) => {{
  console.log('Hello, ${text}!');
};

• module은 es2015, target은 es2015인 선언 옵션을 사용해 다음 출력 파일을 생성합니다.

// index.d.ts
export declare const greet: (text: string) => void;

11.5.2 패키지 타입 의존성

• 타입스크립트는 프로젝트의 node_modules 의존성 내부에서 번들로 제공되는 .d.ts 파일을 감지하고 활용함.
• jest와 같은 인기있는 프레임워크는 타입스크립트로 작성되었으며 jest 패키지 내에 자체 번들 .d.ts 파일을 제공한다.
• descript와 it 같은 함수를 제공하는 @jest/globals 패키지에 대한 의존성을 가지며 jest는 전역으로 사용할 수 있다.

https://jestjs.io/

11.5.3 패키지 타입 노출

• 프로젝트가 npm에 배포되고 사용자를 위한 타입을 제공하려면 패키지의 package.json 파일에 types 필드를 추가해 루트 선언 파일을 가리킵니다.
• types 필드는 .js 확장자 대신 .d.ts 확장자를 사용합니다.

11.6 DefinitelyTyped

• DT(DefinitelyTyped)는 깃허브의 활발한 저장소 중 하나입니다.
• DT 패키지는 타입을 제공하는 패키지와 동일한 이름으로 npm에 @types 범위로 게시됩니다.

11.6.1 타입 사용 가능성

• 자바스크립트 패키지는 자체 타이칭과 함께 제공되거나 DefinitelyTyped를 통해 타이핑할 수 있습니다.
• 아직 사용 가능한 타입이 없는 캐피지에서 타입을 얻는 일반적인 세 가지 옵션은 다음과 같습니다.
• 1. @types/ 패키지를 생성하기 위해 DefinitelyTyped에 풀 리퀘스트를 보냅니다.
• 2. 앞서 소개한 declare module 구문얼 사용해 프로젝트 내에서 타입을 작성합니다.
• 3. 13장 '구성 옵션'에서 다루게 될 noImplicitAny 옵션을 비활성하고 강력하게 경고합니다.