【ITニュース解説】API extractor usage in tldraw codebase.

システムエンジニアを目指す初心者がソフトウェア開発の世界へ足を踏み入れる際、特に「ライブラリ」の開発や利用において、避けては通れない重要な概念がいくつかある。ここで取り上げるAPI Extractorというツールは、TypeScriptというプログラミング言語で書かれたライブラリを開発する際に、非常に役立つ存在である。

まず、TypeScriptについて簡単に触れておく。TypeScriptはJavaScriptに「型」の概念を導入した言語で、大規模なアプリケーション開発においてコードの品質を高め、エラーを未然に防ぐのに貢献する。多くのライブラリがTypeScriptで開発されており、その結果として、ライブラリの利用者も型の恩恵を受けることができる。

しかし、TypeScriptでライブラリを開発する際には、いくつか特有の課題がある。例えば、ある会社が「awesome-widgets」というNPMパッケージ（JavaScriptのライブラリを公開・管理するための仕組み）を公開していると仮定しよう。このライブラリには多くのクラスやインターフェースが含まれており、多くの開発者が利用している。

最初の課題は「意図しないAPIの破壊」だ。ライブラリの提供元が「マイナーな更新」だと思ってリリースしたにもかかわらず、その更新によって、ライブラリを利用している他の開発者のコードがコンパイルできなくなったり、正しく動作しなくなったりする問題が発生することがある。これは、ライブラリの外部から利用される部分（API契約）が、意図せず変更されてしまったために起こる。このような変更を一つ一つ手動でチェックするのは非常に困難であり、現実的ではない。API Extractorは、このようなAPI契約の変更を自動的に検出し、開発チームにレビューを促すことで、意図しない破壊を防ぐ手助けをする。これにより、重要な変更にのみ注意を集中させることができるようになる。

次に、「エクスポート漏れ」という課題がある。例えば、AwesomeButton.draw()というAPI関数が、DrawStyleという特定の型のパラメータを必要とするとしよう。しかし、ライブラリの開発者がDrawStyleという型そのものを外部にエクスポートするのを忘れてしまった場合、ライブラリの利用者はこの関数を呼び出す際に、DrawStyleを指定する方法がなくて困ってしまう。API Extractorは、このように外部に公開されるべきだがエクスポートされていない型や関数を自動的に検出し、警告してくれるため、このような見落としを防ぐことができる。

反対に「意図しないエクスポート」という問題もある。開発者が内部でのみ使用する目的で作成したDrawHelperというクラスが、誤って外部に公開されてしまうことがある。一度公開されてしまうと、そのクラスに依存する利用者が現れるため、後から削除しようとしても「使っているから削除しないでほしい」という声が上がることがある。API Extractorは、内部利用を意図したものが外部に公開されていないかをチェックし、意図しないエクスポートを防ぐことで、将来的な問題を回避する。

さらに、ライブラリのAPIには「アルファ版」「ベータ版」「公開版」といった段階がある場合がある。新しい機能やAPIを導入する際、すぐに安定した公開版として提供するのではなく、まずはテスト的な「アルファ版」として、次に少し安定度を上げた「ベータ版」としてリリースし、十分に成熟してから「公開版」としてリリースしたいというニーズがある。しかし、これらの段階ごとにバージョン番号を大きく変更していては、利用者に混乱を招いてしまう。API Extractorは、APIの各要素をアルファ、ベータ、パブリックといった品質レベルで分類し、利用者にそのステータスを明確に伝えることを可能にする。また、「公開版の関数がベータ版の結果を返してはいけない」といった、スコープに関する矛盾も検出して警告してくれる。

また、「.d.tsファイルのロールアップ」も重要な機能の一つだ。TypeScriptプロジェクトでは、型定義ファイルである.d.tsファイルが多数生成されることがある。これらのファイルをそのまま公開すると、ライブラリの利用者は多くのプライベートな定義まで見ることになり、混乱を招く可能性がある。API Extractorは、これらの.d.tsファイルを一つにまとめ、さらに、ライブラリのリリースタイプ（例えば、開発者向けの完全版か、製品利用向けの公開版か）に応じて、内部的な定義やベータ版の定義を自動的に削除（トリミング）して、必要な情報だけを含むクリーンな.d.tsファイルを生成する。これにより、Visual Studio Codeなどの開発環境で、利用者が関心のない内部情報が表示されてしまうのを防ぎ、より快適な開発体験を提供する。

最後に、「オンラインドキュメントの生成」という機能もある。開発者がTypeScriptコードにTSDocという形式で丁寧にコメントを記述した場合、API Extractorはそのコメントを解析し、整形されたAPIリファレンスドキュメントの元となるデータを出力できる。このデータは、さまざまなドキュメント生成ツールと連携し、美しいオンラインドキュメントを簡単に作成するために利用できる。

これらの課題に対して、API Extractorは統合されたプロフェッショナルな品質の解決策を提供する。このツールは、ビルドプロセスの中で自動的に実行され、TypeScriptコンパイラの強力な解析エンジンを利用して、プロジェクトから外部に公開されるAPIの構造を正確に検出し、そのAPI契約を簡潔なレポートとして記録する。これにより、APIの変更点や潜在的な問題を容易にレビューできるようになる。また、エクスポート漏れや可視性の一貫性の欠如といった一般的な間違いについても警告を発する。さらに、リリースタイプに応じた.d.tsファイルの生成とトリミングを行い、オンラインドキュメント作成のためのポータブルな形式でAPIドキュメントを出力する。

実際に、人気のあるオープンソースプロジェクトであるtldrawのコードベースでもAPI Extractorが活用されている。tldrawは、インタラクティブな描画アプリケーションを構築するためのライブラリで、その内部にはAPI Extractorの設定ファイルであるapi-extractor.jsonが存在する。例えば、tldraw/internal/config/api-extractor.jsonや、editorパッケージ内にも同様の設定ファイルが見られる。これらの設定ファイルによって、tldrawプロジェクトはAPI Extractorの機能を活用し、そのライブラリのAPIの安定性、正確性、そして利用者への提供品質を高いレベルで維持していると考えられる。

システムエンジニアとしてライブラリ開発に携わるなら、API Extractorのようなツールは、開発の効率と品質を大きく向上させる強力な味方となる。これは、単にコードを書くだけでなく、そのコードが他の開発者によってどのように利用され、どのように維持されていくかを考える上で、非常に重要な視点を提供するものだ。