TypeScript宣言マージの深淵：コンパイラをハックするプラグインアーキテクチャの真髄
多くのエンジニアが「Interfaceの宣言マージは便利だ」と語る。しかし、それは表面をなぞっただけの理解に過ぎない。TypeScriptコンパイラ（`tsc`）がシンボルテーブルをどう構築し、`Program`オブジェクトがいかにして複数のソースファイルを統合されたAST（抽象構文木）へと昇華させるか。このプロセスを理解すれば、宣言マージは単なる機能ではなく、ランタイムを侵食し拡張するための強力な「アーキテクチャ・ベクター」となる。
今回は、コアを一切汚染せずに、型安全性とバイナリサイズを両立させるプラグインシステムの構築手法を、コンパイラ内部の挙動から紐解く。
—
1. 宣言マージの真実：シンボル結合の裏側
TypeScriptにおいて、`interface`が同名の宣言をマージする理由は、`tsc`が名前空間ごとに`Symbol`を管理しているからだ。宣言の重複が検出されると、コンパイラは既存のシンボルテーブルにプロパティを「追加」する（`MergeDeclaration`処理）。
これは単なる型チェックではない。この特性を逆手に取れば、「コアモジュールが何者であるかを知らないまま、外部からそのアイデンティティを書き換える」ことが可能になる。
実装パターン：プラグインによるコアの侵食
例えば、`CoreConfig`という単一のコンフィグオブジェクトを想定する。通常、プラグインには型を拡張する権限がない。しかし、`interface`を用いることでこれを突破する。
// @core/config.ts
export interface PluginRegistry {
// 拡張ポイントを空のインターフェースとして定義
}
export interface CoreConfig {
version: string;
plugins: PluginRegistry; // ここを拡張のゲートウェイにする
}
// ユーザーが作成するプラグイン（別モジュール）
declare module “@core/config” {
interface PluginRegistry {
// 宣言マージにより、型システム上でコアが再構成される
auth: { token: string; ttl: number };
}
}
この手法の肝は、`PluginRegistry`が「存在しないはずのプロパティ」を後付けで受け入れられる点にある。コンパイラは型検査の段階でこのマージを解決するため、最終的なEmit（JS出力）には型情報は一切含まれず、ランタイムコストはゼロだ。
—
2. メモリ最適化と型評価のコスト：なぜ`Type Alias`ではなく`Interface`なのか
シニアエンジニアなら知っているはずだが、`Type Alias`には宣言マージが存在しない。なぜか？ `Type Alias`は「型の別名」であり、シンボルテーブル上で新しい型名を作ることを目的としている。一方、`Interface`は「型宣言の積集合」を構築できる。
- メモリ効率: `Interface`は名前ベースの型システム（Nominal-like）として処理され、コンパイラ内での比較コストが `Type Alias`（構造的型システム）よりもわずかに低い。
- 再帰的評価: 大規模なプラグインシステムを組む場合、`Type Alias`の複雑な`Mapped Types`はコンパイラの再帰深さを圧迫し、`Type instantiation is excessively deep`エラーを誘発する。`Interface`の宣言マージは、純粋なプロパティの結合であるため、コンパイラの計算量（Big O）の観点から非常に安定的だ。
—
3. ランタイムへの橋渡し：イベントループの制御
型システムは静的な防壁だが、ランタイムは動的だ。TypeScriptの宣言マージで拡張したプロパティが、実際に実行時に確実に注入されていることを保証するにはどうすべきか？
ここで、「ブランド付き型（Branded Types）」と組み合わせることで、プラグインのロード順序を型レベルで固定する戦略をとる。
// プラグインのライフサイクルを強制する型定義
interface PluginHook
onInit: (config: T) => void;
}
// 宣言マージにより、プラグインが自身を登録する場所を生成
declare module “@core/hooks” {
interface HookRegistry {
auth: PluginHook<{ token: string }>;
}
}
イベントループを意識した実行戦略
JavaScriptのイベントループにおいて、`Promise.resolve().then()`によるマイクロタスクキューの消費は、プラグインのロード順に影響を与える。
1. 初期化フェーズ: `Core`は`HookRegistry`の各キーを走査する。
2. 実行フェーズ: `Object.keys()`で取得したプラグイン名に対し、非同期処理をキューに積む。
ここで重要なのは、「型定義はランタイムのプロパティ順序を保証しない」という点だ。したがって、プラグインの依存関係が必要な場合は、型定義に依存関係を埋め込む（`type Deps = ‘auth’ | ‘logger’`）ことで、ソートアルゴリズムを型安全に実装する必要がある。
—
4. セキュリティ：型による「シャドーイング」の防止
宣言マージは強力だが、悪意ある（あるいは意図しない）重複定義はコアロジックを破壊する。
- 防御的アプローチ: `Object.freeze()`や`Proxy`を用いて、コアの構成オブジェクトを保護せよ。
- コンパイラ設定: `declarationMap`と`composite`を有効にし、プラグインの型定義がどこから来ているかをトレーサビリティとして確保する。これがないと、巨大なプロジェクトでどのモジュールがコアを汚染したのか特定不能になる。
—
結論：型を「コード」ではなく「メタデータ」として扱う
TypeScriptの宣言マージを使いこなすということは、コンパイラの「型解決プロセス」という魔法を理解することと同義だ。
あなたが構築するのは、単なる「設定ファイル」ではない。コンパイル時のシンボルテーブルを動的に書き換え、実行時には存在しないはずの型を、実在するデータ構造へと変換する「アーキテクチャの骨格」だ。
型システムはただのチェックツールではない。それは、実行時の複雑性をコンパイル時に抽象化し、解決するための最も洗練されたツールである。この「型による抽象化」を極限まで押し進めた先にこそ、真に拡張性の高い、伝説的なアーキテクチャが存在する。
次回の執筆では、`Conditional Types`を用いた、プラグインの静的検証エンジンについて深掘りしよう。型システムがチューリング完全である以上、コンパイラをあなたの「忠実なランタイム・コンパニオン」に変えることは可能だ。