noisejs の TypeScript 型定義ファイルを作成し Contribute してみた
なぜしたか
Create.js を TypeScript で書くことがあったのですが、その中で perlin/simplex noise を使いたくなり、それももちろん TypeScript で書きたいなーとなりました。
bower/npm で手に入る perlin/simplex noise の javascript 実装として GitHub - xixixao/noisejs: Javascript 2D Perlin & Simplex noise functions がありますが、意外にも型定義ファイルがありませんでした。なので作成しました。(コンストラクタ含め関数6つだったので^^)
最近 TypeScript にぞっこんなので、愛を示すためにコントリビュートしてみたくなりました。
完成品はこちら
以下のコマンドで取ってこれます(感動)
$ tsd install noisejs --save
.d.ts ファイルの作り方調査
まずは vvakame さんのこの記事を参考に。 vvakame さんの溢れる人徳により、とても気軽にコントリビュートできそうな気がしてきます。
また、具体的な作業も含めてまとめて下さっている方もいました。こちらも大変参考になりました
typescriptの定義ファイル(d.ts)を実際にDefinitelyTypedにPullRequestしてみた – 押入れ工房 – Oscillate Cobalt
他の型定義ファイルを参考にする
具体的なコードの書き方は、よくお世話になっていて使い方を知っており、コード量もあまり長くない、以下の二つを参考にしてみました。
- DefinitelyTyped/victor/victor.d.ts - 2d ベクトル計算のライブラリ
- DefinitelyTyped/stats/stats.d.ts - jsのfps計測ユーティリティ
jsdoc 対応
/** * [function description] * @param {number} x [description] * @return {number} [description] */
の形式の説明を、クラス/関数毎につけておきます。 atom.io エディタを使っているのですが、 docblockr を使うとお手軽でした。
テストコード
先の vvakame さんの記事中に
hoge.d.tsという型定義ファイルを作った場合、hoge-tests.tsというファイルを作成し、hoge.d.tsの利用例を書いてください。
hoge-tests.tsが"動作"するコードである必要はありません。コンパイルが通ることが確認できればよいです。
ようするに、pull request出す前に tsc --noImplicitAny hoge/hoge.d.ts と tsc --noImplicitAny hoge/hoge-tests.ts が通ることを確認しましょう。
とあります。先ほどの二つのライブラリの -tests.ts ファイルを見てみたところ、関数を順に呼ぶだけのシンプルなテストコードとなっていたので、それに準ずることとします→こちら
実際にテストしてみる
/// <reference path="./typings/noisejs/noisejd.d.ts/>
を各 .ts
ファイルのヘッダに入れることで定義ファイルが使える様になるのはもちろん確認した上で、恥ずかしくないようしっかりとテストをしておきたいです。
DefinitelyTyped プロジェクトのテストスクリプト実行 (怪しい)
# プロジェクトに移動 $ cd DefinitelyTyped # テスト等に必要なパッケージをインストール $ npm install # テスト実行 $ npm test
これをやってみたところ、
----------------------------------------------------------------------------- Queued for testing ----------------------------------------------------------------------------- noisejs/noisejs-tests.ts noisejs/noisejs.d.ts # 中略 ----------------------------------------------------------------------------- Total ----------------------------------------------------------------------------- Elapsed time : ~3.526 seconds (3.526s) Syntax error : 0.00% (0/1) Failed tests : 0.00% (0/1) Invalid header : 0.00% (0/1) Without tests : 0.00% (0/1) -----------------------------------------------------------------------------
という感じの出力で、問題がなさそうです。
いや、本当か?と思って、わざと .d.ts コードに間違いを仕込んで見たりしたのですが、やはり問題無くテストが通った風になります。私のやり方が間違っている気がします。
node.js の require で確認する
CommonJS の module の仕組みがよくわからないまま .d.ts を書いていて不安なので、一応確認しておこうかな、と。
npm から noisejs を引っ張ってきて、
$ npm install noisejs
実際にnode.jsのスクリプト中で呼び出してみます
import noisejs = require('noirejs'); // 中略 var noisejs: Noise = new noisejs(Math.random()); // 後略
的なコードを node で実行したところ、ちゃんと動いたので、大丈夫そうです。とりあえずこれで CommonJS 的には OK っぽいので、良いことにします。
プルリクエストを出してみる
- GitHub 上で DefinitelyTyped/DefinitelyTyped を Fork して
- ローカルに clone し、
- 上で作成した
noisejs.d.ts
noisels-tests.ts
を含むnoisejs
フォルダを追加して - commitし、
- 自分のリモート(GitHub) に Push して
- そこで "New pull request" をクリック
- わかりやすいコメントを書いて、pull request を作成
Pull request 後のやりとりはこちらに。なんとも軽快。
これでコントリビュートが完了し、他の型定義ファイルと同様、 tsd install noisejs --save
コマンドで取ってこれるようになりました。やったー。
オープンソースへのコミットはこれが初体験でした。結構責任が生じるので緊張しましたが、恥ずかしいことにならないよう勉強が出来たので良かったです。
Deprecate TSD
この記事を書き始めて色々調べているうちに気がついたのですが、型定義ファイルを管理する tsd コマンドが非推奨になり、新しい型定義管理ツールとして typings というのが始まっているようです。
DefinitelyTyped の一つのリポジトリに、すべてのライブラリの .d.ts
ファイルを集合させる仕組みでは無くなるらしく、おそらくそちらの方がいい気がします。今回は旧来の手法にのっとってコントリビュートしてみましたが、次は typings の手法でコントリビュートしてみたいです。