【TypeScript】ジェネリクスの使い方!基本から型制約まで解説

【TypeScript】ジェネリクスの使い方!基本から型制約まで解説

PR Amazonのアソシエイトとして、ITナレッジライフは適格販売により収入を得ています。

記事の文字数:5,870

TypeScriptのジェネリクス(Generics)の使い方を基礎から徹底解説。型引数Tの基本構文やアロー関数・インターフェース・クラスでの定義方法、extendsとkeyofによる型制約、デフォルト型引数、APIレスポンス型などの実務パターンまでコード例付きで分かりやすく紹介します。

ITエンジニアにお勧めの本 ↗

おすすめ

エンジニアが知っておきたい思考の整理術 複雑な情報を【理解する】【伝える】テクニック

難易度
実用性
図解

思考の整理というテーマを、実務ですぐに使える具体的な「技術」として落とし込んだ一冊です。

ベストセラー

世界一流エンジニアの思考法

難易度
実用性
思考法

技術スキル以上に大切な「考え方」をアップデートできる。世界基準の効率的な仕事術が学べます。

文系社会人のためのIT資格の歩き方: 文系のあなたに最適な道をご提案します (YKcreate kiki)

難易度
実用性
キャリア度

ロードマップが非常に明確。キャリアプランを見据えた、無駄のない学習順序を提案してくれます。

エンジニアを説明上手にする本 相手に応じた技術情報や知識の伝え方

難易度
実用性
コミュ力

「伝える技術」もエンジニアの重要なスキル。相手の視点に立った、具体的な説明のコツが満載です。

技術広報入門 ー テックブログから始めるエンジニアカルチャーのつくり方

難易度
実用性
独自性

テックブログを入口にエンジニア組織の文化をどう設計し、育てていくかという実践論が学べます。

TypeScriptTypeScript [タイプスクリプト]JavaScriptに型システムを追加した言語でアプリケーションを開発していると、「引数の型に応じて戻り値の型も連動させたい」「扱うデータの型が違っても、共通の関数やデータ構造を使い回したい」という場面に頻繁に遭遇します。

このとき any 型を使ってしまうとコンパイル時の型チェックが無効化され、逆に型ごとに別の関数やインターフェースを定義するとコードの重複が増えて保守性が低下してしまいます。

こうした課題を解決するのが ジェネリクス(Generics) です。本記事では、TypeScriptにおけるジェネリクスの基本構文から、インターフェースやクラスでの定義方法、extends と keyof を組み合わせた型制約、デフォルト型引数、さらに実務で頻出する活用パターンまで、実機検証済みのコード例を交えて詳しく解説します。

TypeScriptのジェネリクス(Generics)とは?

ジェネリクスとは、関数やインターフェース、クラスなどを定義する時点では具体的な型を固定せず、 実際に呼び出す(利用する)時点で型をパラメータ(型引数)として受け取る仕組み です。

値を受け取る通常の関数が「仮引数 (x)」を持つのと同じように、ジェネリクスは「型を受け取る仮引数 <T>」を持つイメージと捉えると理解しやすくなります。

なぜジェネリクスが必要なのか?(any型やunknown型との違い)

ジェネリクスを使う最大のメリットは、 汎用的なコードの再利用性と、コンパイル時の厳密な型安全性を両立できる点 にあります。

具体例として、「配列の先頭要素を取り出して返す関数」を考えてみましょう。もしジェネリクスを使わずに any 型や unknown 型で定義すると、以下のような問題が発生します。

// ❌ any型を使った場合: 戻り値も any になり、型チェックや補完が一切効かなくなる
function getFirstAny(items: any[]): any {
return items[0];
}
const val1 = getFirstAny(["TypeScript", "JavaScript"]);
// val1.toFixed(); // 文字列なのに数値メソッドを呼んでもコンパイルエラーにならず、実行時エラーになる
// ⚠️ unknown型を使った場合: 安全だが、呼び出し側で毎回型ガードや型アサーションが必要になる
function getFirstUnknown(items: unknown[]): unknown {
return items[0];
}
const val2 = getFirstUnknown(["TypeScript", "JavaScript"]);
// console.log(val2.toUpperCase()); // コンパイルエラー: 'val2' is of type 'unknown'.
// ⭕ ジェネリクスを使った場合: 渡した配列の要素型がそのまま戻り値の型として引き継がれる
function getFirstElement<T>(items: T[]): T | undefined {
return items[0];
}
const val3 = getFirstElement(["TypeScript", "JavaScript"]);
// val3 は string | undefined 型と推論されるため、安全にメソッドを呼び出せる
console.log(val3?.toUpperCase()); // 出力: TYPESCRIPT

それぞれの手法の違いを整理すると、以下のようになります。

アプローチ型安全性呼び出し側の利便性主な特徴
any 型低い(型チェック無効)高い(何でも呼べるが危険)戻り値の型情報が失われ、実行時エラーの原因になる
unknown 型高い低い(毎回型の絞り込みが必要)値の型を特定するまでプロパティやメソッドにアクセスできない
ジェネリクス <T>高い高い(自動推論・型補完が効く)入力された型と出力される型の関連性を維持できる

このように、ジェネリクスを活用することで「どんな型の配列でも受け取れる汎用性」と「取り出した要素の型を正確に保持する安全性」を同時に実現できます。

型引数(T, U, K, V)の命名慣習

型引数の名前には任意の識別子を指定できますが、TypeScriptでは慣習として以下のアルファベット1文字がよく使われます。

  • T: Type(最も基本的な第1の型引数)
  • U: 2番目の型引数(アルファベット順で T に続く文字。3番目以降は V、W と続けることもある)
  • K: Key(オブジェクトのキーやプロパティ名を表す型)
  • V: Value(オブジェクトやMapなどの値を表す型)
  • E: Element / Error(配列の要素やエラーオブジェクトを表す型)

なお、型引数が複数あり役割を明確にしたい場合は、TData や TError、TParams のように先頭に T を付けた分かりやすい名前を付けるのも実務でよく使われる手法です。

スポンサーリンク

ジェネリクスの基本的な使い方(関数・インターフェース・クラス)

ここからは、関数・アロー関数・インターフェース・クラスにおけるジェネリクスの具体的な記述方法を確認していきましょう。

1. 関数宣言と型推論の仕組み

通常の関数宣言でジェネリクスを使う場合は、関数名の直後に <T> を記述します。

function getFirstElement<T>(items: T[]): T | undefined {
return items[0];
}
// 1. 型引数を明示的に指定して呼び出す方法
const firstStr = getFirstElement<string>(["TypeScript", "JavaScript", "Python"]);
console.log(firstStr?.toUpperCase()); // 出力: TYPESCRIPT
// 2. 引数からの型推論に任せて呼び出す方法(実務で一般的)
const firstNum = getFirstElement([10, 20, 30]);
console.log(firstNum?.toFixed(1)); // 出力: 10.0

TypeScriptのコンパイラは、渡された実引数 [10, 20, 30] から型引数 T が number であることを自動的に推論します。そのため、日常的な開発では <string> のような明示的な指定を省略し、型推論に任せてシンプルに呼び出すケースが大半です。

ただし、空配列 [] を渡す場合や、戻り値の型だけで T が決まる関数(APIAPI [エーピーアイ]Application Programming Interface。異なるソフトウェア間の接続口レスポンスの取得など)では推論材料が足りないため、呼び出し時に <Type> を明示的に指定します。

2. アロー関数での記述方法(JSX / TSX での注意点)

アロー関数でジェネリクスを定義する場合は、引数リスト (...) の直前に <T> を配置します。

// 通常の .ts ファイルでのアロー関数定義
const wrapInArray = <T>(value: T): T[] => {
return [value];
};
// Reactなどの .tsx ファイル(JSX構文有効時)での定義:末尾にカンマを付ける
const wrapInArrayTsx = <T,>(value: T): T[] => {
return [value];
};
console.log(wrapInArray("Hello")); // 出力: [ 'Hello' ]
console.log(wrapInArray(42)); // 出力: [ 42 ]

ReactReact [リアクト]Meta開発のUIライブラリなどのJSX構文が有効な .tsx ファイルでは、単なる <T> と書くとJSXの開始タグとして解釈され、構文エラーが発生することがあります。.tsx ファイル内でジェネリックなアロー関数を定義する際は、 <T,> のように末尾にカンマを入れる か、<T extends unknown> と記述することでJSXタグとの衝突を回避できます。

3. 複数の型引数を受け取る関数

2つ以上の異なる型を同時に扱いたい場合は、カンマ区切りで <T, U> のように複数の型引数を定義できます。

function createPair<T, U>(first: T, second: U): [T, U] {
return [first, second];
}
// [string, number] のタプル型として推論される
const pairResult = createPair("userId", 1001);
console.log(pairResult); // 出力: [ 'userId', 1001 ]

第1引数と第2引数にそれぞれ異なる型を渡しても、それぞれの型情報が失われることなくタプル型 [string, number] として正確に推論されます。

4. インターフェース(interface)と型エイリアス(type)でのジェネリクス

オブジェクトの構造を定義する interface や type でも、型引数を受け取って柔軟なデータ構造を表現できます。

// ジェネリックなインターフェース
interface Box<T> {
value: T;
label: string;
}
const stringBox: Box<string> = {
value: "設定データ",
label: "Config",
};
// ジェネリックな型エイリアス(成功時の値 T と失敗時のエラー E を持つ Result 型)
type Result<T, E> =
| { ok: true; value: T }
| { ok: false; error: E };
const successResult: Result<number, string> = {
ok: true,
value: 200,
};

インターフェースや型エイリアスを変数注釈として使う際は、関数の引数推論とは異なり、Box<string> のように型引数を明示的に渡す必要があります(後述するデフォルト型引数を設定している場合を除く)。

5. クラス(class)でのジェネリクス

クラス名の後ろに <T> を宣言することで、クラス内のフィールド(プロパティ)やメソッドの引数・戻り値全体で一貫した型を扱えるようになります。

class DataStore<T> {
private items: T[] = [];
add(item: T): void {
this.items.push(item);
}
getAll(): readonly T[] {
return this.items;
}
}
// number型専用のデータストアとしてインスタンス化
const numberStore = new DataStore<number>();
numberStore.add(1);
numberStore.add(2);
// numberStore.add("文字列"); // コンパイルエラー: Argument of type 'string' is not assignable to parameter of type 'number'.
console.log(numberStore.getAll()); // 出力: [ 1, 2 ]

一度 new DataStore<number>() として生成すれば、そのインスタンスに対して誤って文字列などを追加しようとした際にコンパイルエラーで検知できます。

ここまで紹介した定義対象の構文を整理すると、以下のようになります。

定義対象構文例型推論の可否
関数宣言function fn<T>(arg: T): T実引数から自動推論される
アロー関数(.ts)const fn = <T>(arg: T): T => arg実引数から自動推論される
アロー関数(.tsx)const fn = <T,>(arg: T): T => arg実引数から自動推論される
インターフェースinterface Box<T> { value: T }原則として型引数の明示が必要
型エイリアスtype Result<T, E> = ...原則として型引数の明示が必要
クラスclass Store<T> { ... }コンストラクタ引数があれば推論可能

extends と keyof を使った型制約(Type Constraints)

ジェネリクスで受け入れる型引数に一定の条件(制約)を課したい場合は、extends キーワードによる 型制約(Type Constraints) を使用します。

制約のない基本的なジェネリクス <T> は、あらゆる型を受け入れられる反面、関数内部で「特定のプロパティが存在すること」を前提とした処理が書けません。例えば、渡された値の文字数や要素数を出力しようとして item.length にアクセスすると、T に number や boolean が渡される可能性を考慮して以下のコンパイルエラーが発生します。

function logLengthBroken<T>(item: T): number {
// コンパイルエラー
// error TS2339: Property 'length' does not exist on type 'T'.
return item.length;
}

このような場面で extends を使うと、特定のプロパティや構造を持つ型だけを受け入れるように安全に制限できます。

extends で特定の構造を持つ型に制限する

<T extends 制約となる型> と記述することで、「指定した型の構造を満たす型だけを受け入れる」という型制約を設定できます。

interface HasLength {
length: number;
}
// length プロパティ(number型)を持つ型だけに制限する
function logLength<T extends HasLength>(item: T): number {
console.log(`長さ: ${item.length}`);
return item.length;
}
logLength("TypeScript"); // 出力: 長さ: 10(string は length を持つためOK)
logLength([1, 2, 3, 4]); // 出力: 長さ: 4(配列も length を持つためOK)
logLength({ length: 10, name: "カスタム要素" }); // 出力: 長さ: 10(length プロパティを持つオブジェクトもOK)
// length を持たない数値を渡すとコンパイルエラーになる
// error TS2345: Argument of type 'number' is not assignable to parameter of type 'HasLength'.
// logLength(123);

単に引数型を item: HasLength とした場合との違いは、ジェネリクス <T extends HasLength> を使えば 引数として渡した元の具体的な型 T を戻り値の型などにもそのまま保持できる 点にあります。

keyof と組み合わせてオブジェクトのキーを安全に指定する

実務で非常によく使われるのが、オブジェクトのキー一覧をユニオン型として取得する keyof 演算子と extends の組み合わせです。

K extends keyof T と記述することで、「第2引数 key には、第1引数のオブジェクト obj に実在するプロパティ名しか渡せない」という厳密な制約を実現できます。

function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
return obj[key];
}
const user = {
id: "u_001",
name: "佐藤花子",
age: 28,
};
// 存在するキーを指定すると、対応するプロパティの型(T[K])が正確に推論される
const userName = getProperty(user, "name"); // string 型(値: "佐藤花子")
const userAge = getProperty(user, "age"); // number 型(値: 28)
console.log(userName, userAge); // 出力: 佐藤花子 28
// 存在しないキーを指定するとコンパイルエラーで即座に検知できる
// error TS2345: Argument of type '"email"' is not assignable to parameter of type '"name" | "id" | "age"'.
// getProperty(user, "email");

戻り値の型に指定している T[K] は インデックスアクセス型(Indexed Access Type) と呼ばれ、user["name"] なら string、user["age"] なら number のように、指定されたキーに応じた正確な型を返してくれます。

スポンサーリンク

デフォルト型引数(Default Type Parameters)の使い方

関数の仮引数にデフォルト値を設定できるのと同様に、ジェネリクスの型引数にも = を使って デフォルト型引数 を設定できます。

型引数が省略された場合にはデフォルトの型が適用され、明示的に型引数が渡された場合にはその型で上書きされます。

// デフォルト型として unknown を指定
interface ApiResponse<T = unknown> {
status: number;
message: string;
data: T;
}
// 1. 型引数を省略した場合: data は自動的に unknown 型になる
const emptyResponse: ApiResponse = {
status: 204,
message: "No Content",
data: null,
};
// 2. 型引数を明示した場合: data は指定した UserDto 型になる
interface UserDto {
id: string;
name: string;
}
const userResponse: ApiResponse<UserDto> = {
status: 200,
message: "OK",
data: { id: "u_001", name: "佐藤花子" },
};
console.log(userResponse.data.name); // 出力: 佐藤花子

また、<T extends HTMLElement = HTMLDivElement> のように、extends による型制約とデフォルト型引数を同時に組み合わせて記述することも可能です。

実務で役立つジェネリクスの活用パターン

ここからは、実際のWebアプリケーション開発でよく登場するジェネリクスの実践パターンを3つ紹介します。

パターン1:APIレスポンスの共通ラッパー型

バックエンドAPIとの通信では、エンドポイントごとに返却されるデータの中身(ユーザー情報、商品一覧、記事詳細など)は異なるものの、レスポンス全体の外枠(ステータスコード、データ本体、ページネーション情報など)は共通しているケースが多くあります。

このような場合、外枠をジェネリックなインターフェースとして切り出すことで、型定義の重複をなくすことができます。

// ページネーション付きAPIレスポンスの共通型
interface PaginatedResponse<T> {
items: T[];
totalCount: number;
currentPage: number;
hasNextPage: boolean;
}
interface ArticleSummary {
slug: string;
title: string;
}
// 記事一覧APIのレスポンス型として再利用
const articleListResponse: PaginatedResponse<ArticleSummary> = {
items: [
{ slug: "typescript-generics", title: "ジェネリクスの使い方" },
{ slug: "typescript-utility-types", title: "ユーティリティ型の使い方" },
],
totalCount: 2,
currentPage: 1,
hasNextPage: false,
};

パターン2:汎用的な非同期データ取得関数(fetchラッパー)

fetch APIを使ってJSONJSON [ジェイソン]JavaScript Object Notation。軽量データ交換フォーマットデータを取得する共通関数にジェネリクスを導入すると、呼び出し側で期待するレスポンス型をスマートに指定できます。

async function fetchJson<T>(url: string): Promise<T> {
const response = await fetch(url);
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return (await response.json()) as T;
}
// 呼び出し例: 戻り値が Promise<ArticleSummary> として扱われる
// const article = await fetchJson<ArticleSummary>("/api/articles/typescript-generics");

なお、response.json() の結果を as T で型付けするだけでは、実行時に想定外のデータ構造が返ってきた場合までは防げません。外部APIのレスポンスをより安全に扱いたい場合は、 【TypeScript】型ガードの使い方と型の絞り込み完全ガイド で解説しているユーザー定義型ガードや、Zodなどのスキーマ検証ライブラリと組み合わせるのが効果的です。

パターン3:標準ユーティリティ型との連携

TypeScriptに標準搭載されている Partial<T> や Pick<T, K>、Omit<T, K>、Record<K, T> といったユーティリティ型も、すべてジェネリクスの仕組みを使って実装されています。

自前のジェネリック関数の中でこれらのユーティリティ型を組み合わせると、より柔軟な関数を定義できます。以下は、任意のオブジェクト T に対して一部のプロパティだけを上書き更新する汎用関数の例です。

function mergeChanges<T extends object>(original: T, changes: Partial<T>): T {
return { ...original, ...changes };
}
const currentProfile = {
id: "u_001",
name: "佐藤花子",
age: 28,
};
// 第2引数には currentProfile のプロパティの一部だけを安全に渡せる
const updatedProfile = mergeChanges(currentProfile, { age: 29 });
console.log(updatedProfile);
// 出力: { id: 'u_001', name: '佐藤花子', age: 29 }

Partial<T> をはじめとする標準ユーティリティ型の詳しい使い分けについては、 【TypeScript】ユーティリティ型の使い方!実務で役立つ頻出型一覧 もあわせて参照してください。

スポンサーリンク

ジェネリクスを使うときの注意点とアンチパターン

ジェネリクスは強力な機能ですが、使い方を誤るとかえってコードを読みづらくしてしまうことがあります。実務で意識しておきたい3つの注意点を押さえておきましょう。

1. 1箇所でしか使わない不要な型引数を作らない

関数シグネチャの中で、型引数 T が 引数の1箇所にしか登場せず、他の引数や戻り値の型と一切関連していない場合 は、ジェネリクスを使う必要がないケースが大半です。

// ❌ アンチパターン: 型引数 T が引数 arg の1箇所でしか使われていない
function printMessageBad<T extends { text: string }>(arg: T): void {
console.log(arg.text);
}
// ⭕ 改善例: 直接インターフェースやオブジェクト型を引数に指定する
function printMessageGood(arg: { text: string }): void {
console.log(arg.text);
}

ジェネリクスは「複数の場所(引数と戻り値、あるいは第1引数と第2引数など)の型を連動させたいとき」に使うのが原則です。

2. 実行時(Runtime)には型引数 T の情報は消去される

TypeScriptの型情報はコンパイル時のみ存在し、JavaScriptへトランスパイルされた時点ですべて消去(Type Erasure)されます。そのため、関数の処理内部で型引数 T を値として参照することはできません。

function createInstanceBroken<T>() {
// ❌ コンパイルエラー: 'T' only refers to a type, but is being used as a value here.
// return new T();
// if (typeof val === T) { ... }
}

実行時にクラスのインスタンスを生成したり型判定を行ったりする必要がある場合は、コンストラクタ関数(ctor: new () => T)や検証用の型ガード関数を通常の引数として受け取る設計にしましょう。

3. 過度なネストや複雑な型パズルを避ける

1つの関数や型定義に <T, U, V, W, K> のように多数の型引数を並べたり、条件型(T extends U ? X : Y)を何重にもネストさせたりすると、エラーメッセージが難解になりチームメンバーが解読できなくなります。

型定義が複雑になってきた場合は、意味のある中間型(型エイリアス)に分割して名前を付けることで、可読性と保守性を高く保つことができます。また、定数オブジェクトや配列からリテラル型を抽出したい場合は、ジェネリクスだけでなく 【TypeScript】as constの使い方!型を固定する実務テクニック で紹介している as const と typeof を組み合わせる手法も有効です。

まとめ

本記事では、TypeScriptのジェネリクス(Generics)の基本から実践的な活用法までを解説しました。

  • ジェネリクスの役割: 型をパラメータ <T> として受け取ることで、コードの汎用性とコンパイル時の型安全性を両立できる
  • 基本構文: 関数・アロー関数(.tsx では <T,>)・インターフェース・クラスで幅広く定義でき、関数呼び出し時は引数からの自動推論も活用できる
  • 型制約(Constraints): T extends 型 で受け入れる型の構造を制限でき、K extends keyof T でオブジェクトに実在するキーのみを安全に指定できる
  • デフォルト型引数: <T = unknown> のように初期型を指定しておくことで、利用側の記述コストを減らせる
  • 実務でのポイント: APIレスポンスの共通型や Partial<T> 等のユーティリティ型との連携で威力を発揮する一方、1箇所でしか使わない不要な型引数や過度な複雑化は避ける

ジェネリクスを正しく使いこなせるようになると、TypeScriptでの設計の幅が大きく広がります。まずは共通のAPIレスポンス型や小さなユーティリティ関数から取り入れてみてください。

あわせて読みたい関連記事

TypeScriptの型システムや実務テクニックをさらに体系的に学びたい方は、以下の記事もあわせてご覧ください。

【TypeScript】ユーティリティ型の使い方!実務で役立つ頻出型一覧
ITナレッジライフ

【TypeScript】ユーティリティ型の使い方!実務で役立つ頻出型一覧

TypeScriptのユーティリティ型の使い方を徹底解説。PartialやRequired、Readonly、Pick、Omit、Recordなどのプロパティ操作から、Exclude、Extract、ReturnTypeの実践的な組み合わせパターンまでコード例付きで分かりやすく紹介します。

【TypeScript】型ガードの使い方と型の絞り込み完全ガイド
ITナレッジライフ

【TypeScript】型ガードの使い方と型の絞り込み完全ガイド

TypeScriptの型ガード(Type Guard)の使い方を初心者向けに解説。typeof・instanceof・in演算子による基本的な型の絞り込みから、型述語(is)を使ったユーザー定義型ガードの実装、assertsによるアサーション関数まで実例コードを交えて徹底解説します。

【TypeScript】as constの使い方!型を固定する実務テクニック
ITナレッジライフ

【TypeScript】as constの使い方!型を固定する実務テクニック

TypeScriptのas const(constアサーション)の使い方を徹底解説。リテラル型推論や再帰的なreadonly化の仕組み、オブジェクトや配列からユニオン型を自動生成する実務パターン、Object.freezeとの違いまでコード例付きで分かりやすく紹介します。


以上で本記事の解説を終わります。
よいITライフを!
スポンサーリンク
ITナレッジライフ 運営者
この記事を書いた人

Z (ITナレッジライフ)

現役のITエンジニア。Linux、プログラミング、IT用語など、日々の業務で得た「痒いところに手が届く」技術情報を発信しています。

プロフィールと編集ポリシーを見る →
スポンサーリンク

ITエンジニアにお勧めの本 ↗

おすすめ

エンジニアが知っておきたい思考の整理術 複雑な情報を【理解する】【伝える】テクニック

難易度
実用性
図解

思考の整理というテーマを、実務ですぐに使える具体的な「技術」として落とし込んだ一冊です。

スポンサーリンク

人気記事


記事を評価

Thanks!
目次
Scroll to Top