【ITニュース解説】Managing private TypeScript types: beyond DefinitelyTyped

TypeScriptは、プログラム内で扱うデータの種類、つまり「型」を明確にすることで、開発の早い段階で間違いを見つけやすくし、より信頼性の高いソフトウェアを作るための強力な機能を提供する。多くの広く使われている公開ライブラリには、「DefinitelyTyped」というプロジェクトがあり、そこに用意された型定義ファイルを利用することで、TypeScriptの型安全性の恩恵を簡単に受けられる。

しかし、実際の開発現場では、社内で独自に開発したライブラリを使ったり、外部のJavaScriptライブラリをCDN（Contents Delivery Network）経由でウェブページに読み込んだりするケースが頻繁にある。このような場合、DefinitelyTypedでは対応できないため、型に関する問題が発生しやすくなる。例えば、NPM（Node Package Manager）を通じてライブラリをインストールする場合、通常はそのパッケージに型定義ファイルが同梱されており、TypeScriptはそれを自動で認識する。しかし、CDN経由で読み込まれたスクリプトについては、TypeScriptはそれがどのような機能を提供しているかを自動で判断できない。

このため、開発者はCDN経由のライブラリを使う際に、そのライブラリの型を自分で定義する必要がある。例えば、DailymotionのウェブSDKをCDNから読み込むと、window.dailymotionというグローバルなオブジェクトを通じてその機能が利用できるようになる。開発者は、declare globalという特別な構文を使って、このdailymotionオブジェクトが持つ関数（メソッド）やデータ（プロパティ）の型を手動で宣言する。しかし、複数のチームやプロジェクトがそれぞれDailymotion SDKを利用し、各自でこの型定義を作成すると、定義の内容が異なったり、一部が重複したりする可能性が生じる。これらのプロジェクトを後で統合しようとすると、TypeScriptはどちらの型定義を優先すべきか判断できなくなり、「プロパティの再宣言は同じ型を持つ必要があります」といったエラー（TS2717）が発生することがある。これは、個々のプロジェクトが独自の定義を作り、それらが互いに矛盾するために起こる典型的な問題だ。

このような問題を解決し、特に大規模な組織での開発を効率化するためには、「集中型の社内TypeScript型リポジトリ」を構築することが非常に有効である。これは、公開ライブラリ向けのDefinitelyTypedのように、社内で利用するすべてのライブラリやCDN経由のライブラリに関する型定義を一箇所に集約して管理する仕組みだと考えると良いだろう。

この集中型リポジトリの導入には、いくつかの明確な利点がある。まず、社内のすべてのプロジェクトが同じ型定義を使用するため、定義の不一致や矛盾がなくなり、コード全体で「一貫性」が保たれる。次に、一度作成された型定義はリポジトリに公開され、社内のどのプロジェクトからでも再利用できるため、開発者は同じ型定義を繰り返し書く手間が省け、「再利用性」が向上する。さらに、プロジェクト間で型が合わないという問題が解消されるため、コンパイル時や実行時の予期せぬエラーが減り、全体的な「型安全性」が向上する。最後に、型定義に修正が必要になった場合、一箇所だけを直せば、その型を利用しているすべてのプロジェクトに更新が反映されるため、「メンテナンス性」が大幅に向上する。

具体的な実装方法としては、「モノレポ」と呼ばれる単一のリポジトリで複数のプロジェクトやパッケージを管理する構造を採用するのが一般的だ。このモノレポ内に、それぞれのライブラリの型定義を独立したパッケージとして配置する。例えば、リポジトリのルートにpackage.jsonを置き、typesというディレクトリを作成し、その中にdailymotion、custom-loggerといった形で各型定義のパッケージディレクトリを設ける。

各型パッケージのディレクトリ（例: types/dailymotion/）内には、そのパッケージに関する情報が記述されたpackage.jsonファイルと、実際の型定義が書かれたindex.d.tsファイル、そして説明文のREADME.mdなどが含まれる。package.jsonでは、その型パッケージの名前（例: @prime-types/dailymotion）やバージョン、そして型定義ファイルがindex.d.tsであることを指定する。index.d.tsファイルの中には、declare global構文を使ってDailymotion SDKが提供するグローバルオブジェクトwindow.dailymotionの型を定義する。この際、TypeScriptがこのファイルをモジュールとして正しく認識し、型解決を行えるように、ファイルの末尾にexport {}という記述を追加することが重要である。

プロジェクトでこれらの集中型リポジトリの型定義を利用するには、まずNPMを使って対象の型パッケージをインストールする。例えば、npm install @prime-types/dailymotionを実行する。次に、TypeScriptがこの型定義ファイルをプロジェクト全体で参照できるように、tsconfig.jsonファイルを修正する必要がある。TypeScriptはデフォルトでnode_modules/@typesのパスにある型定義を探すが、自作の型パッケージは別のパスにインストールされる可能性があるため、includeオプションに型パッケージが置かれるパス、例えば"./node_modules/@prime-types"を追加する。これにより、TypeScriptはそのパスにある型定義も探し出し、プロジェクト内で利用可能になる。

複数のプロジェクトが同じ型パッケージを利用する際に、それぞれ異なるバージョンに依存してしまうという問題が発生することがある。例えば、プロジェクトAが型パッケージのバージョン1.0.0を使い、プロジェクトBがバージョン1.1.0を使うといった状況だ。この問題を防ぐためには、型パッケージをプロジェクトのdependencies（通常の依存関係）ではなく、peerDependencies（ピア依存関係）としてpackage.jsonに宣言する方法が効果的である。peerDependenciesに指定されたパッケージは、それをインストールするプロジェクトの最上位レベルに単一のバージョンがインストールされるようNPMが調整してくれるため、全てのプロジェクトが同じバージョンの型定義を使うことになり、型の不整合による衝突を避けることができる。

小規模なチームであれば、すべての型定義を一つの大きなパッケージにまとめるという、より単純な方法も選択肢として考えられる。このアプローチはセットアップやデプロイが簡単で、一度のインストールで必要なすべての型が手に入るといったメリットがある。しかし、個々の型のバージョンを独立して管理することが難しくなったり、パッケージのサイズが不必要に大きくなったりする可能性もあるため、長期的な視点やプロジェクトの規模を考えると、モノレポで個別の型パッケージとして管理する方が、拡張性とメンテナンス性に優れていることが多い。

まとめると、DefinitelyTypedがオープンソースプロジェクトの型管理に非常に役立つ一方で、社内プロジェクトやCDN経由のライブラリの型定義には独自の解決策が求められる。集中型のTypeScript型リポジトリを構築することは、型定義の重複や衝突を排除し、社内の複数のプロジェクト間で一貫した型安全性を確保するための重要な手段となる。これにより、開発の効率と品質が向上し、信頼できる唯一の型情報の源泉を確立できるのである。