typescriptの定義ファイル(d.ts)を実際にDefinitelyTypedにPullRequestしてみた

このエントリーをはてなブックマークに追加

最近はもっぱらNodeJSとAngularJSに興味深々な日々です。
Javascriptは今までただのコピペ職人だったのですが、最近は真面目に勉強しています。Javascriptの(本当に)基本的な概念を理解したところで、普段の仕事でC#とVisualStudioを使っている私としては静的型付け言語であるTypescriptに挑戦してみたくなりました。
IDEは普段macbook proを使っているのでVMWareにWindowsを放り込んでVisualStudio Community Editionでも入れようかと思ったのですが重すぎて断念しました。ということで結局Webstormを購入してそれとなく使っています。
Typescriptの静的型付けの性質を活かしてC#同様にIntellisense(コード補完, CodeCompletion)がとても便利。ただしサードパーティーのJavascriptライブラリを使おうと思ったとたんTypescript版を用意してくれてるライブラリなんてそうそう無いのでIntellisenseも何もあったもんじゃありません。しかもJavascript(他の言語もそうですけど)はサードパーティー製のライブラリって頻繁に使うので割と早々にこの問題に直面するかと思います。
そこで登場するのがd.ts拡張子の「定義ファイル」。typescript側でこのファイルを参照することで、サードパーティーのライブラリでもIntellisenseがしっかりと効きます。ではこの「定義ファイル」がどこから登場するかと言うと、これがなかなか原始的で、個々人が自力で書いているだけなのです。「既存のjavascriptから定義ファイルを作ってくれるツールがあるんでしょ?」って思うかと思いますが、残念ながら現時点では無さそうです。↓参照

Generating typescript declaration files from javascript

既存のTypescriptから定義ファイルは生成できますけど、そんなものが必要になるシチュエーションが私はまだあまりわかっていません。

話がそれましたが、その「定義ファイル」をまとめられているリポジトリがあります。その名も「DefinitelyTyped」。「みんなで頑張って定義ファイル作ろう!」っていうそんな感じなプロジェクトだと思います。Githubで公開されていて「Fork→定義ファイル作成→PullRequest→本家にマージ」してもらうというそんな流れ。

非常に申し訳ないのですが、ここまでの説明はQiitaのこの記事にvvakameさんがとてもわかりやすく説明しています。これを参考に実際に私の方でも定義ファイルを作ってPullRequestを発行してみてマージされるところまでを備忘録もかねて記録しておきたいと思います。(意外と技術書とかで出てくるライブラリの定義ファイルがまだDefinitelyTypedに公開されていなかったりするので、結構自分で書かないといけないことが多いです)

今回Typescriptで欲しかった定義ファイルは「angular-local-storage」というlocalStorageをいい感じに使わせてくれるangularjsのモジュールです。

1.まずはGithubのDefinitelyTypedに行き、右上の「Fork」を押してForkしましょう

スクリーンショット 2014-12-18 21.24.50

2.ForkしたリポジトリをローカルにGit Cloneしてきてまずはライブラリ名のbranchを作成しましょう(今回ならangular-local-storageブランチ)。次にライブラリ名(angular-local-storage)と一致するフォルダを作成します。

スクリーンショット 2014-12-18 21.25.45

3.作成したフォルダに定義ファイルを作成します(angular-local-storage.d.ts)

スクリーンショット 2014-12-18 21.26.19
4.DefinitelyTypedに投稿する定義ファイルには以下のようにヘッダ情報を入力

// Type definitions for [ライブラリ名(バージョンがわかればバージョンも)]
// Project: [ライブラリのURL] 
// Definitions by: [作った人(自分)] <[自分のURL]> 
// Definitions: https://github.com/borisyankov/DefinitelyTyped

スクリーンショット 2014-12-18 21.34.34

今回はv0.1.5が対象だったのでヘッダ情報にも書いておきました。
スクリーンショット 2014-12-18 21.26.55

5.さて、次のキャプチャではもう定義ファイルは概ね完成しています。作り方とかはTypeScriptの仕様とかが絡んでくる話なので割愛。これはとにかく対象となるライブラリのAPIを読みながら作っていくしかないと思います。コメントとかも概ね流用したものをそのまま定義ファイルに使っています。
スクリーンショット 2014-12-18 22.53.45

6.定義ファイルが完成したところで次に必ず作らないといけないのが、その定義ファイルを使ったテストコードです。「ライブラリ名-tests.ts」を作りましょう(今回ならangular-local-storage-tests.ts)

スクリーンショット 2014-12-18 22.54.48

 

7.本家の「Contribution guide」にもテストコードは対象のライブラリのサンプルコードとかを書いとけばいいよみたいなことが書いてあるので、とりあえずGithubのReadmeに載っているサンプルコードをTypescriptで書きました。以下でコンパイルが通れば多分OK。

tsc --noImplicitAny angular-local-storage/angular-local-storage-tests.ts

サンプルコードはこんな感じ↓
スクリーンショット 2014-12-18 23.35.32

8.ひと通り完成したところで「npm test」を走らせてテストがちゃんと通ることを確認します。

以下、確認結果。

mbp:DefinitelyTyped hoge$ npm test

> DefinitelyTyped@0.0.1 test /Users/hoge/Projects/Fork/DefinitelyTyped
> node ./_infrastructure/runner.js --changes

=============================================================================
DefinitelyTyped Diff Detector 0.1.0
=============================================================================
All changes
-----------------------------------------------------------------------------
angular-local-storage/angular-local-storage-tests.ts
angular-local-storage/angular-local-storage.d.ts
rest/rest-tests.ts
rest/rest.d.ts
-----------------------------------------------------------------------------
Removed files
-----------------------------------------------------------------------------
no files listed here
-----------------------------------------------------------------------------
Interesting files
-----------------------------------------------------------------------------
angular-local-storage/angular-local-storage-tests.ts
angular-local-storage/angular-local-storage.d.ts
rest/rest-tests.ts
rest/rest.d.ts
not mapped? -> /Users/hoge/Projects/Fork/DefinitelyTyped/when/when
-----------------------------------------------------------------------------
Queued for testing
-----------------------------------------------------------------------------
angular-local-storage/angular-local-storage-tests.ts
angular-local-storage/angular-local-storage.d.ts
rest/rest-tests.ts
rest/rest.d.ts
=============================================================================
DefinitelyTyped Test Runner 0.5.0
=============================================================================
Typescript version: 1.3.0
Typings : 2
Tests : 2
TypeScript files : 4
Total Memory : 16384 mb
Free Memory : 3650 mb
Cores : 4
Concurrent : 3
============================== Syntax checking ==============================
..
-----------------------------------------------------------------------------
Elapsed time : ~0.827 seconds (0.827s)
Successful : 100.00% (2/2)
Failure : 0.00% (0/2)
=============================== Typing tests ================================
..
-----------------------------------------------------------------------------
Elapsed time : ~0.862 seconds (0.862s)
Successful : 100.00% (2/2)
Failure : 0.00% (0/2)
=============================== Header format ===============================
..
-----------------------------------------------------------------------------
Elapsed time : ~0.002 seconds (0.002s)
Successful : 100.00% (2/2)
Failure : 0.00% (0/2)
-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
Total
-----------------------------------------------------------------------------
Elapsed time : ~2.452 seconds (2.452s)
Syntax error : 0.00% (0/2)
Failed tests : 0.00% (0/2)
Invalid header : 0.00% (0/2)
Without tests : 0.00% (0/2)
-----------------------------------------------------------------------------

9.とりあえずなんとなくテストが通ってそうな予感がしたところで、Forkしたリポジトリにコミット&プッシュしちゃいます。

スクリーンショット 2014-12-18 23.41.00

10.Pushが完了したところでGithubの自分のForkしたリポジトリを見ると以下のように「Compare & pull request」という項目が増えているのがわかります。

 スクリーンショット 2014-12-18 23.42.17

 

11.迷わす「Compare & pull request」をクリックしてタイトルを「add ライブラリ名 definition file」みたいな感じでpull requestを作成しましょう。
スクリーンショット 2014-12-18 23.42.31

12.pull requestが完了したところで本家の「pull request」一覧を観に行くと、ちゃんとpull requestが作成されていることがわかります。右側の印はTravis CIにてビルドがちゃんと通ったかどうかを教えてくれます。アクセスするのが早過ぎると下の画面みたいに「ビルド中…」のマークがつきます。

スクリーンショット 2014-12-18 23.43.19

13.ちょっとしてからリロードするとちゃんとビルドが通っていることが確認できて一安心。後は本家にマージするのを待つだけです。
スクリーンショット 2014-12-18 23.43.26

 

14.何日かしたらvvakameさんからマージ完了のメールと共に「@kenfdev(私のユーザ名) thanks mate!」 みたいなメールを受け取ることができます。

15.上記全て完了するとTSDというTypescript Definition Managerで自分の作ったライブラリがインストールできるようになります。例えば以下のコマンドで今回の定義ファイルはインストールできます。

tsd query angular-local-storage --action install

Typescriptがこの先どんどん盛り上がっていくといいですね!
(もう盛り上がっているはず!)

Written on December 19, 2014
このエントリーをはてなブックマークに追加