TypeScriptのDeclaration Merging（宣言の結合）とは？interfaceの同名定義がマージされる仕組みと注意点

TypeScriptの開発において、複数の場所で同じ名前の型を定義した際、それらが自動的に統合される挙動に驚いたことはないでしょうか。

これを「Declaration Merging（宣言の結合）」と呼び、TypeScriptが言語仕様として備えている強力な機能の一つです。

特にインターフェース（interface）においては、この機能が日常的に活用されており、外部ライブラリの拡張や型定義の整理において重要な役割を果たしています。

本記事では、このDeclaration Mergingの仕組みから、実践的な活用方法、そして利用時の注意点までを詳しく整理してお伝えします。

Declaration Merging（宣言の結合）の基本概念

Declaration Mergingとは、コンパイラが「同じ名前で宣言された2つ以上の個別の宣言」を、1つの定義として統合するプロセスを指します。

通常、多くのプログラミング言語では、同じスコープ内で同じ名前を変数や型に割り当てることは禁止されています。

しかし、TypeScriptでは特定の条件下において、同名の宣言を許容し、それらを賢くマージする仕組みを持っています。

この機能の主な目的は、既存の型定義を壊さずに、後から新しいプロパティやメソッドを追加することにあります。

Declaration Mergingは、インターフェースだけでなく、名前空間（Namespace）やクラス、列挙型（Enum）の間でも発生します。

その中でも、最も頻繁に利用され、かつ理解が不可欠なのが「インターフェースの結合」です。

interfaceにおける同名定義のマージ

TypeScriptのインターフェースは、「オープン」な性質を持っています。

これは、一度定義したインターフェースに対して、後から同じ名前で宣言を追加できることを意味します。

基本的なマージの仕組み

まずは、最もシンプルなマージの例を見てみましょう。

interface User {
  name: string;
}

interface User {
  age: number;
}

const user: User = {
  name: "田中太郎",
  age: 25
};

上記のコードでは、Userという名前のインターフェースが2回宣言されています。

TypeScriptコンパイラはこれらを統合し、最終的に以下のような1つの型として扱います。

interface User {
  name: string;
  age: number;
}

このように、異なる場所で定義されたプロパティが、あたかも最初から1つのインターフェースに記述されていたかのように振る舞います。

非関数メンバーの重複に関するルール

インターフェースをマージする際、非関数メンバー（プロパティ）の名称が重複している場合は注意が必要です。

同名のプロパティが存在する場合、それらは「全く同じ型」でなければなりません。

interface Person {
  id: number;
}

interface Person {
  // エラー：後続のプロパティ宣言は同じ型である必要があります
  id: string; 
}

もし上記のように、同じ名前で異なる型を指定しようとすると、コンパイルエラーが発生します。

Declaration Mergingはあくまで「追加」を行うものであり、「上書き」を許可するものではないという点を覚えておきましょう。

メソッド（関数メンバー）のマージとオーバーロード

関数メンバー、すなわちメソッドが同名で定義された場合は、プロパティとは異なる挙動を示します。

同じ名前のメソッドが複数存在する場合、それらは「関数のオーバーロード」として扱われます。

interface Document {
  createElement(tagName: any): Element;
}

interface Document {
  createElement(tagName: "div"): HTMLDivElement;
  createElement(tagName: "span"): HTMLSpanElement;
}

この場合、後の宣言が優先順位の高いオーバーロードとして登録されます。

ただし、特定の文字列リテラル型を持つシグネチャがある場合、それらはリストの先頭に配置されるという特殊なルールがあります。

なぜDeclaration Mergingが必要なのか

この機能がなぜ存在するのか、その主な理由は「外部ライブラリの型拡張」にあります。

グローバルオブジェクトの拡張

例えば、ブラウザ環境で動作するJavaScriptにおいて、windowオブジェクトに独自のプロパティを追加したい場合があります。

標準のTypeScript定義では、windowには独自のプロパティは含まれていません。

interface Window {
  myCustomProperty: string;
}

// これでエラーにならずにアクセス可能になる
window.myCustomProperty = "Hello";

このように、既存のグローバルインターフェースにプロパティを注入できるのは、Declaration Mergingのおかげです。

モジュール拡張（Module Augmentation）

外部のnpmパッケージが提供している型を、自分のプロジェクトに合わせて拡張したいケースも多いでしょう。

例えば、Expressなどのフレームワークで、Requestオブジェクトにユーザー情報を格納するプロパティを追加する場合などに利用されます。

import "express";

declare module "express" {
  interface Request {
    currentUser?: {
      id: string;
      role: string;
    };
  }
}

これを「Module Augmentation（モジュール拡張）」と呼びます。

既存のライブラリのソースコードを直接編集することなく、安全に型定義を強化できる非常に強力な手法です。

インターフェース以外の結合パターン

Declaration Mergingはインターフェース同士だけでなく、異なる種類の宣言の間でも発生します。

クラスと名前空間の結合

クラスと同じ名前の名前空間を定義することで、クラスに静的な内部クラスのような構造を持たせることができます。

class Album {
  label: Album.AlbumLabel;
}

namespace Album {
  export class AlbumLabel { }
}

これにより、Album.AlbumLabelという形式で型を参照できるようになります。

関数と名前空間の結合

関数に対しても、名前空間をマージすることでプロパティを付与することが可能です。

function buildLabel(name: string): string {
  return buildLabel.prefix + name;
}

namespace buildLabel {
  export const prefix = "Label: ";
}

console.log(buildLabel("Sample"));

"Label: Sample"

JavaScriptにおける「関数はオブジェクトであり、プロパティを持てる」という性質を、TypeScript上で安全に表現する手段として機能します。

利用時の注意点とリスク

非常に便利なDeclaration Mergingですが、多用しすぎるとコードの可読性や保守性を損なう恐れがあります。

意図しないマージによる混乱

プロジェクト内で不用意に同じ名前のインターフェースを作成してしまうと、意図せず型がマージされてしまいます。

エラーが発生せずに新しいプロパティが追加されてしまうため、バグの発見が遅れる原因になりかねません。

特に大規模なプロジェクトでは、名前空間やモジュール分割を適切に行い、名前の衝突を避ける工夫が必要です。

型定義の隠蔽

マージされた型は、エディタ上での定義ジャンプが難しくなることがあります。

一つのインターフェースが複数のファイルに分かれて定義されている場合、全体の構造を把握するためにファイル間を行き来しなければなりません。

基本的には一つのファイルにまとまった定義を記述し、マージはライブラリ拡張などの「真に必要な場面」に限定するのがベストプラクティスです。

typeエイリアスとの違い

type（型エイリアス）は、Declaration Mergingをサポートしていません。

同じ名前でtypeを複数回宣言すると、コンパイルエラーとなります。

type User = {
  name: string;
};

// エラー：識別子 'User' が重複しています
type User = {
  age: number;
};

このため、後からの拡張性を考慮する必要がある定義にはinterfaceを使用し、拡張を許可したくない厳格な定義にはtypeを使用するという使い分けが推奨されます。

2026年におけるDeclaration Mergingの立ち位置

近年のTypeScript開発では、以前よりもtypeエイリアスが好まれる傾向にあります。

しかし、Declaration Mergingを基盤としたエコシステムの重要性は変わっていません。

特に、メタプログラミングに近い型定義の拡張や、型安全なプラグインシステムの構築において、この機能は不可欠です。

「なぜかプロパティが追加されている」「なぜか型が壊れている」といったトラブルに遭遇した際、このマージの仕組みを知っていることが解決の鍵となります。

まとめ

TypeScriptのDeclaration Mergingは、同名のインターフェースや宣言を一つに統合する、柔軟で強力な機能です。

インターフェースのプロパティは型が一致していればマージされ、メソッドはオーバーロードとして扱われます。

外部ライブラリの拡張やグローバルオブジェクトのカスタマイズにおいて、この機能は大きな威力を発揮します。

一方で、予期せぬマージはコードの複雑性を高めるため、名前の衝突には十分に注意しなければなりません。

インターフェースの「オープン」な性質を正しく理解し、型定義の設計をより洗練されたものにしていきましょう。