TypeScriptの型定義管理ツールTypingsについて

tsdが非推奨になったということで新しく推奨されているTypeScript型定義管理ツールの「typings」に関して調べたのでその備忘録。

Typingsとは

tsdと同じくTypeScriptの型定義ファイルを管理するツールです。

GitHubから型定義を取得してくるしかなかったtsdと違って、npmやbower、githubプロジェクト、ローカルファイルシステムやhttp経由で型定義ファイルを取ってこれるのが特長です。DefinitelyTypedもサポートしているので、tsdから移行して困ることはありません。

また、tsdと違ってGitHubのAPIを叩かないので、GitHubAPIのrate limitに引っかかって落ちるということもありません。 ¹

インストール方法

npm install -g typings

基本的な使い方

tsdコマンドを置き換えるだけならすごく簡単です。

プロジェクトの初期化

Typingsはプロジェクトディレクトリのtypings.jsonファイル（tsdでいうところのtsd.json）にそのプロジェクトが利用している型定義一覧を保存するので、以下コマンドでtypings.jsonを作っておきます。

typings-sample-projectというディレクトリを新しく作ってプロジェクトディレクトリとして試してみる場合は以下のような感じ。

mkdir typings-sample-project
cd typings-sample-project
typings init

何か型定義を新しくインストールする

typings install jquery --save --ambient

プロジェクトディレクトリのtypings/ディレクトリに型定義がインストールされます。
実際にはtypings/main.d.tsをreference pathに追加して使ったりします。

プロジェクトが利用している型定義をインストールする

cloneしてきたプロジェクトにtypings.jsonがある場合は、以下コマンドで必要な型定義をインストールできます。

typings install

型定義を探す

typings search jquery --ambient

ambientオプション

Typingsでは何かにつけて--ambientというオプションを付けるというか大体のコマンドは付けないと利用できないんですが、意味としてはそのままTypeScriptの「アンビエント宣言(実装のないインターフェースだけの宣言)」のことらしいですね。

Typingsでは、このdeclare moduleを直接取り込む際に--ambientを指定させるようです。

例えば、Typingsではローカルファイルから型定義をインストールできるので以下のように.d.tsファイルを用意してみます。

sample.greeting.d.ts

declare module Greeting {
  export interface Hello {
    message: string;
  }
}

declare module "sample.greeting" { export = Greeting }

で、このファイルから型定義をTypingsで取り込むため以下のコマンドを実行してみます。

typings install file:sample.greeting.d.ts --name "greeting"

すると以下のようなエラーが出るはずです。

typings ERR! message Attempted to compile "greeting" as a dependency, but it contains some ambient module declarations ("sample.greeting").

このように、アンビエント宣言から型定義を取り込む場合は以下のように--ambientオプションを指定する必要があるようです。

typings install file:sample.d.ts --name "greeting" --ambient

なお、TypingsではDefinitelyTypedはアンビエント宣言のリポジトリのうちの一つという位置づけで、次のようにモジュール名を指定してアンビエント宣言を検索するとDefinitelyTypedが使用されます(sourceがdtとなっているもの)。

% typings search redux --ambient
Showing 13 results...

NAME                        SOURCE  HOMEPAGE                                               DESCRIPTION
react-redux                 dt      https://github.com/rackt/react-redux                              
react-router-redux          dt      https://github.com/rackt/react-router-redux                       
redux                       dt      https://github.com/rackt/redux                                    
redux                       ambient                                                                   
redux-actions               dt      https://github.com/acdlite/redux-actions                          
redux-action-utils          dt      https://github.com/insin/redux-action-utils                       
redux-devtools              dt      https://github.com/gaearon/redux-devtools                  

Typingsが正規で利用できるモジュール

Typingsが正規の(--ambientオプションなしで)利用できるのは、以下の場合のようです。

• typings.jsonが含まれたnpm、bower、githubなどのプロジェクト
  • 後ほど簡単に紹介しますが、Typingsではnpm、bowerから型定義をインストールできます。
• 公式リポジトリである、 https://github.com/typings/registry に登録された型定義

現在の所 https://github.com/typings/registry にあんまり数がなくて基本的にDefinitelyTypedなどからアンビエント宣言を取り込むことが多いので、--ambientオプションが必須みたいになっていますが、Typingsが普及してくれば--ambientオプションの出番も減るかもしれないですね。

便利な使い方

npmから型定義ファイルをインストールする

npmから型定義を取得できます。といいつつ、実際にはプロジェクトのnode_modulesディレクトリから型定義をコピーしてくるだけです。
つまり、前もってnpm installで型定義を取得したいモジュールをインストールしておく必要があります。

typings install npm:<npmのモジュール名>/<モジュール内の.d.tsファイルへのパス> --name <適当な型定義名> --ambient

例えば、RxJSはnpmモジュールに型定義が同梱されているのでこの機能を利用して以下のように型定義をインストールできます。

cd typings-sample-project
npm install rx --save
typings install npm:rx/ts/rx.all.d.ts --save --name rx --ambient

また、前述のように、対象となるモジュールがTypingsを使用していてtypings.jsonが含まれる場合、--ambientオプションを外して簡単にインストールできます。Typingsの公式ページではpopsicle²の例が紹介されています。

typings install npm:popsicle --save

nodeの他、webpackやbrowserifyを利用している場合に便利かもしれません。

bowerから型定義ファイルをインストールする

bowerから型定義を取得できます。といいつつ、実際にはプロジェクトのbower_componentsディレクトリから(ry
前もってbower installで型定義を取得したいモジュールを取得しておく必要があります。

typings install bower:<bowerのモジュール名>/<モジュール内の.d.tsファイルへのパス> --name <適当な型定義名> --ambient

RxJSはbowerモジュールにも型定義が同梱されているのでこの機能を利用できます。

cd typings-sample-project
bower install rxjs --save
typings install bower:rxjs/ts/rx.all.d.ts --save --name rxjs --ambient

bowerを利用している場合に便利かもしれません。

gulpと組み合わせてみる

以下のような感じでgulpタスクに組み込んでtypings installを実行できます。

typings.coffee

gulp = require('gulp')
typings = require('typings')

gulp.task 'typings', ->
  typingsInstallOption = {
    ambient: true
    cwd: process.cwd()
    save: false
  }
  typings.install(typingsInstallOption)

別にnpm-scriptsでtypings install && gulp buildとやってもいいんですけどね。

とりあえず

いろいろできるんですが、tsdからの移行から始めるのがいいんじゃないでしょうか。

1. ただ、代わりに型定義の検索(search)、新規インストール時(install xxx)には https://api.typings.org/ という謎APIを叩いているようです。このAPIがどれだけ信頼性のあるものなのかは不明ですが、プロジェクトにtypings.jsonさえあれば、そこからtypings installコマンドで型定義を取得する分にはこのAPIは利用しないようなので問題になるケースは少ないかもしれません。 ↩

2. 作者がTypingsの中の人 ↩