Global .d.ts 템플릿

Global .d.ts 템플릿 (전역 라이브러리)

전역 라이브러리는 어떤 형태의 import도 사용하지 않고 전역 스코프에서 접근할 수 있는 라이브러리예요. 많은 라이브러리가 사용을 위해 하나 이상의 전역 변수를 그냥 노출합니다. 예를 들어 jQuery를 쓴다면 $ 변수를 그냥 참조해서 사용할 수 있죠.

$(() => {
  console.log("hello!");
});

전역 라이브러리 문서에서는 HTML script 태그에서 라이브러리를 사용하는 방법을 안내하는 걸 보통 볼 수 있어요.

<script src="http://a.great.cdn.for/someLib.js"></script>

오늘날 가장 인기 있는 전역 접근 라이브러리들은 사실 UMD 라이브러리로 작성되어 있어요(아래 참조). UMD 라이브러리 문서는 전역 라이브러리 문서와 구분하기 어렵습니다. 전역 선언 파일을 작성하기 전에 그 라이브러리가 사실은 UMD가 아닌지 꼭 확인하세요.

출처: TypeScript 핸드북

코드에서 전역 라이브러리 식별하기

전역 라이브러리 코드는 보통 아주 단순해요. 전역 "Hello, world" 라이브러리는 이렇게 생겼을 거예요.

function createGreeting(s) {
  return "Hello, " + s;
}

또는 이렇게요.

window.createGreeting = function (s) {
  return "Hello, " + s;
};

전역 라이브러리의 코드를 보면 보통 다음을 볼 수 있어요.

최상위 var 문 또는 function 선언
window.someName에 대한 하나 이상의 할당
document나 window 같은 DOM 기본 요소가 존재한다는 가정

다음은 보이지 않을 거예요.

require나 define 같은 모듈 로더의 검사 또는 사용
var fs = require("fs"); 형태의 CommonJS/Node.js 방식 import
define(...) 호출
라이브러리를 require하거나 import하는 방법을 설명하는 문서

전역 라이브러리의 예시

전역 라이브러리를 UMD 라이브러리로 바꾸는 게 보통 쉬워서, 여전히 전역 스타일로 작성된 인기 라이브러리는 거의 없어요. 하지만 작고 DOM이 필요하거나(혹은 의존성이 없는) 라이브러리는 여전히 전역일 수 있습니다.

전역 라이브러리 템플릿

아래에서 DTS 예시를 볼 수 있어요.

// Type definitions for [~THE LIBRARY NAME~] [~OPTIONAL VERSION NUMBER~]
// Project: [~THE PROJECT NAME~]
// Definitions by: [~YOUR NAME~] <[~A URL FOR YOU~]>

/*~ If this library is callable (e.g. can be invoked as myLib(3)),
 *~ include those call signatures here.
 *~ Otherwise, delete this section.
 */
declare function myLib(a: string): string;
declare function myLib(a: number): number;

/*~ If you want the name of this library to be a valid type name,
 *~ you can do so here.
 *~
 *~ For example, this allows us to write 'var x: myLib';
 *~ Be sure this actually makes sense! If it doesn't, just
 *~ delete this declaration and add types inside the namespace below.
 */
interface myLib {
  name: string;
  length: number;
  extras?: string[];
}

/*~ If your library has properties exposed on a global variable,
 *~ place them here.
 *~ You should also place types (interfaces and type alias) here.
 */
declare namespace myLib {
  //~ We can write 'myLib.timeout = 50;'
  let timeout: number;

  //~ We can access 'myLib.version', but not change it
  const version: string;

  //~ There's some class we can create via 'let c = new myLib.Cat(42)'
  //~ Or reference e.g. 'function f(c: myLib.Cat) { ... }
  class Cat {
    constructor(n: number);

    //~ We can read 'c.age' from a 'Cat' instance
    readonly age: number;

    //~ We can invoke 'c.purr()' from a 'Cat' instance
    purr(): void;
  }

  //~ We can declare a variable as
  //~   'var s: myLib.CatSettings = { weight: 5, name: "Maru" };'
  interface CatSettings {
    weight: number;
    name: string;
    tailLength?: number;
  }

  //~ We can write 'const v: myLib.VetID = 42;'
  //~  or 'const v: myLib.VetID = "bob";'
  type VetID = string | number;

  //~ We can invoke 'myLib.checkCat(c)' or 'myLib.checkCat(c, v);'
  function checkCat(c: Cat, s?: VetID);
}

Global .d.ts 템플릿