1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@DaokFrontier

TypeScriptでランタイムエラーを防ぐ！堅牢な型設計5つの実践

1
Posted at

多くのTypeScript開発者が陥る落とし穴をご存知でしょうか？それは、コンパイル時には型エラーが出ないのに、実行時に予期せぬエラーが発生するという「ランタイム型安全性のギャップ」です。外部からの入力データ、APIレスポンス、あるいは安易なany型の使用が、アプリケーションをクラッシュさせる原因となりかねません。

この記事では、TypeScriptの強力な型システムを最大限に活用し、このランタイム型安全性のギャップを埋めるための具体的な5つの実践を解説します。Zodなどのバリデーションライブラリ活用から、型ガードの徹底、そして堅牢な型設計のベストプラクティスまで、実務で頻発するランタイムエラーを未然に防ぎ、TypeScriptアプリケーションの信頼性を飛躍的に向上させる方法を学びましょう。

TypeScriptにおけるランタイム安全性の重要性

TypeScriptは静的型付け言語であり、コンパイル時に多くの型関連エラーを検出できます。しかし、JavaScriptにコンパイルされて実行される以上、以下の要因でランタイムエラーが発生する可能性があります。

  • 外部からの入力: ユーザー入力、ファイル読み込み、環境変数など、TypeScriptの型チェックが及ばないデータソース。
  • APIレスポンス: サーバーからのデータは、定義したインターフェースと異なる可能性があります。
  • JavaScriptライブラリとの連携: 型定義がない、あるいは不正確なJavaScriptライブラリを使用する場合。
  • 型アサーションの誤用: 開発者がコンパイラに「この型は正しい」と強制した場合。

これらのギャップを埋め、アプリケーションの堅牢性を高めることが、TypeScriptにおけるランタイム安全性の追求です。本記事では、この課題に取り組むための具体的な手法を紹介します。
記事執筆時点（2026年6月）のTypeScriptは、安定版がTypeScript 6.0、リリース候補版がTypeScript 7.0です。本記事では主にTypeScript 5.x以降で利用可能な機能と概念を中心に解説します。

1. unknown 型と型ガードによる安全な型絞り込み

このセクションでは、unknown型を使って型が不明な値を安全に扱い、型ガードで厳密に型を絞り込む方法を解説します。

any型は非常に便利ですが、TypeScriptの型チェックを完全に無効にしてしまうため、ランタイムエラーの温床となります。代わりに、TypeScript 3.0で導入されたunknown型を積極的に使用しましょう。unknown型はあらゆる型の値を受け入れますが、その値を直接操作する前に必ず型チェックを強制します。これにより、型が不明な値を安全に扱えるようになります。

unknown 型の基本

unknown型は、値の型が不明であることを示します。anyと異なり、unknown型の変数に対してプロパティアクセスやメソッド呼び出しを直接行うことはできません。

function processInput(input: unknown) {
  // input.toUpperCase(); // コンパイルエラー: 'input' の型は 'unknown' です。
  // input.toFixed(2);    // コンパイルエラー: 'input' の型は 'unknown' です。

  if (typeof input === 'string') {
    // ここでは input は string 型として扱える
    console.log(input.toUpperCase()); // 安全にtoUpperCaseを呼び出し
  } else if (typeof input === 'number') {
    // ここでは input は number 型として扱える
    console.log(input.toFixed(2)); // 安全にtoFixedを呼び出し
  } else {
    console.log("Unknown type of input.");
  }
}

processInput("hello");     // 出力: HELLO
processInput(123.456);     // 出力: 123.46
processInput(true);        // 出力: Unknown type of input.

この例では、processInput関数の引数inputがunknown型であるため、if文によるtypeofチェック（型ガード）を行わない限り、inputのメソッドを呼び出すことはできません。これにより、意図しない型でのメソッド呼び出しを防ぎ、ランタイムエラーの発生を抑制します。

ユーザー定義型ガードの活用

より複雑なオブジェクトの型チェックには、ユーザー定義型ガードが有効です。value is Typeという戻り値の型アノテーションを持つ関数を定義することで、TypeScriptコンパイラに「この関数がtrueを返せば、valueは指定したTypeである」と伝えることができます。

interface User {
  id: number;
  name: string;
  isAdmin: boolean;
}

/**
 * unknownな値がUserインターフェースを満たしているかチェックするユーザー定義型ガード
 * @param value チェック対象の値
 * @returns valueがUser型であればtrue、そうでなければfalse
 */
function isUser(value: unknown): value is User {
  // valueがnullでないオブジェクトであることを確認
  if (typeof value !== 'object' || value === null) {
    return false;
  }
  // プロパティの存在と型をチェック
  // NOTE: ここで一度Record<string, unknown>に型アサーションするのは、
  // unknown型では直接プロパティアクセスができないため。あくまでチェックのための一時的なアサーション。
  const asUser = value as Record<string, unknown>; 
  return (
    'id' in asUser && typeof asUser.id === 'number' &&
    'name' in asUser && typeof asUser.name === 'string' &&
    'isAdmin' in asUser && typeof asUser.isAdmin === 'boolean'
  );
}

const data: unknown = JSON.parse('{ "id": 1, "name": "Alice", "isAdmin": false }');
const invalidData: unknown = JSON.parse('{ "id": "2", "name": "Bob" }'); // idがstring型で不正

if (isUser(data)) {
  console.log(`User Name: ${data.name}, Admin: ${data.isAdmin}`); // 出力: User Name: Alice, Admin: false
} else {
  console.log("Data is not a User type.");
}

if (isUser(invalidData)) {
  console.log(`User Name: ${invalidData.name}, Admin: ${invalidData.isAdmin}`);
} else {
  console.log("Invalid data is not a User type."); // 出力: Invalid data is not a User type.
}

ユーザー定義型ガードは、外部からのJSONデータなど、実行時まで型が確定しないデータを扱う際に非常に強力なツールとなります。

2. Zodなどのバリデーションライブラリによるランタイムバリデーション

このセクションでは、外部からの入力データに対するランタイム型安全性を確保するため、Zodのようなスキーマバリデーションライブラリの活用方法を解説します。

TypeScriptの型システムはコンパイル時に機能しますが、外部からのデータ（APIレスポンス、ユーザー入力、ファイル内容など）は、アプリケーションの型定義と一致しない可能性があります。このような外部からの入力データの型不整合は、ランタイムエラーの主要な原因の一つです。
Zodのようなバリデーションライブラリは、実行時にデータの構造と型を検証し、同時にTypeScriptの型定義を生成することで、このギャップを埋めます。

Zodを用いたランタイムバリデーションと型生成

ZodはTypeScriptファーストで設計されており、非常に直感的なAPIでスキーマを定義できます。

まず、Zodをインストールします。

npm install zod

次に、Zodでスキーマを定義し、それを使ってデータのバリデーションとTypeScriptの型生成を行います。

import { z } from 'zod';

// Zodスキーマの定義
// このスキーマが、データの構造とバリデーションルールを定義します。
const UserSchema = z.object({
  id: z.number().int().positive(), // number型、整数、かつ正の数であること
  name: z.string().min(1, { message: "名前は1文字以上である必要があります。" }), // string型、かつ1文字以上であること
  email: z.string().email().optional(), // string型、email形式、任意項目
});

// ZodスキーマからTypeScriptの型を自動生成
// これにより、スキーマと型定義の二重管理が不要になり、常に同期が保たれます。
type User = z.infer<typeof UserSchema>;

const validUserData = { id: 1, name: "Alice", email: "alice@example.com" };
const invalidUserData = { id: -1, name: "", email: "invalid-email" }; // 不正なデータ

// 正常なデータのバリデーション
try {
  const user1: User = UserSchema.parse(validUserData);
  console.log("Valid User:", user1);
  // 出力: Valid User: { id: 1, name: 'Alice', email: 'alice@example.com' }
} catch (error) {
  console.error("Validation Error for user1:", error);
}

// 不正なデータのバリデーション
try {
  const user2: User = UserSchema.parse(invalidUserData);
  console.log("Valid User:", user2);
} catch (error) {
  console.error("Validation Error for user2:", error);
  // 出力例: Validation Error for user2: ZodError: [
  //   { "code": "too_small", "minimum": 0, "type": "number", "inclusive": false, "exact": false, "message": "Number must be greater than 0", "path": ["id"] },
  //   { "code": "too_small", "minimum": 1, "type": "string", "inclusive": true, "exact": false, "message": "名前は1文字以上である必要があります。", "path": ["name"] },
  //   { "validation": "email", "code": "invalid_string", "message": "Invalid email", "path": ["email"] }
  // ]
}

UserSchema.parse()メソッドは、データがスキーマに合致しない場合にZodErrorをスローします。これにより、不正なデータがアプリケーションのロジックに到達する前にエラーとして捕捉できます。

その他のバリデーションライブラリ

  • io-ts: 関数型プログラミングのアプローチを取り、より厳密な型安全性と表現力豊かな型定義が可能です。学習コストはZodより高い傾向にあります。
  • Yup: React Hook Formなどのフォームライブラリとの連携が強力で、シンプルなスキーマ定義が特徴です。

プロジェクトの特性やチームの習熟度に応じて、適切なライブラリを選択しましょう。

3. never 型による網羅性チェック

このセクションでは、TypeScriptのnever型を利用して、スイッチ文や条件分岐の網羅性を保証し、予期せぬ状態によるランタイムエラーを防ぐ方法を解説します。

never型は「到達し得ない」ことを表す型です。主に以下の状況で利用されます。

  • 例外を常に投げる関数や無限ループ関数。
  • 型の網羅性チェック (Exhaustiveness Checking): 特にユニオン型を扱うスイッチ文などで、全てのケースが処理されていることをコンパイラに強制させます。

never 型を用いた網羅性チェックの具体例

ユニオン型に対してスイッチ文を使用する場合、新しいメンバーがユニオン型に追加された際に、そのケースがスイッチ文で処理されていないと、コンパイルエラーとして検出できます。

type TrafficLight = "red" | "yellow" | "green";

function getAction(light: TrafficLight): string {
  switch (light) {
    case "red":
      return "Stop";
    case "yellow":
      return "Caution";
    case "green":
      return "Go";
    default:
      // ここに到達することは通常ないはず。
      // もし新しいリテラル型がTrafficLightに追加され、defaultケースが処理しない場合、
      // lightの型はneverではなくなり、exhaustiveCheckへの代入でコンパイルエラーが発生する。
      const exhaustiveCheck: never = light; // ここでコンパイルエラーが発生する
      throw new Error(`Unknown traffic light: ${exhaustiveCheck}`);
  }
}

console.log(getAction("red")); // 出力: Stop
// console.log(getAction("blue")); // コンパイルエラー: 型 '"blue"' の引数を型 'TrafficLight' のパラメーターに割り当てることはできません。

// 例えば、将来的に TrafficLight に "flashing" が追加された場合:
// type TrafficLight = "red" | "yellow" | "green" | "flashing";
// この時、getAction関数は "flashing" ケースを処理していないため、
// defaultブロックの `const exhaustiveCheck: never = light;` の行で
// 「'TrafficLight' 型を 'never' 型に割り当てることはできません。」というコンパイルエラーが発生します。
// これにより、実装漏れを早期に発見し、ランタイムエラーを防ぐことができます。

このアプローチにより、ユニオン型に新しいケースが追加された際に、関連するロジックの更新漏れをコンパイル時に検出し、デプロイ後のランタイムエラーを防ぐことができます。

4. よくあるランタイムエラーの落とし穴と回避策

このセクションでは、TypeScriptプロジェクトで頻繁に遭遇するランタイムエラーのパターンと、それらを回避するための実践的なアドバイスを提供します。

4.1. any 型の乱用

  • ハマりどころ: any型はTypeScriptの型チェックを無効にするため、コンパイル時にはエラーが出なくても、実行時に存在しないプロパティにアクセスしたり、不正な型の値を渡したりすることでランタイムエラーを引き起こします。特に、外部ライブラリの型定義がない場合や、JavaScriptからの移行時に安易にanyを使用すると、TypeScriptの恩恵が失われます。
  • 回避策:
    • unknown型を積極的に使用する: 型が不明な場合はanyではなくunknownを使用し、必要な箇所で型ガードによる厳密な型チェックを行います。
    • @types/パッケージの導入: 外部ライブラリには、コミュニティが提供する型定義パッケージ（@types/library-name）の導入を検討します。
    • anyは最小限に: どうしてもanyが必要な場合は、その理由をコメントで明記し、スコープを最小限に留めます。ESLintの@typescript-eslint/no-explicit-anyルールでanyの使用を制限することも有効です。

4.2. 型アサーション (as Type) の誤用

  • ハマりどころ: 型アサーションはコンパイラに「開発者が型を保証する」と伝える強力な機能です。しかし、実際には型が一致しない場合にランタイムエラーを引き起こす可能性があります。例えば、document.getElementById('id') as HTMLInputElementとしたにも関わらず、実際にはidを持つ要素がdivだった場合、valueプロパティへのアクセスはundefinedとなり、エラーに繋がります。
  • 回避策:
    • 型アサーションは最終手段と考える: 可能な限り型ガードやZod/io-tsのようなバリデーションライブラリを使用して、実行時に型を検証します。
    • 確信がある場合のみ使用: 型アサーションを使用する場合は、その型が本当に正しいという強い確信がある場合に限定し、コメントなどでその根拠を明記することが推奨されます。例えば、DOM要素の取得では、if (element instanceof HTMLInputElement)のようなチェックを挟むことで安全性が高まります。

4.3. 外部からの入力データの型不整合

  • ハマりどころ: APIレスポンスやユーザー入力など、外部から来るデータはTypeScriptの静的型チェックの範囲外であり、定義した型と実際のデータ構造が異なる場合にランタイムエラーが発生します。これは、サーバーサイドの変更やフロントエンドの古い定義が原因で起こりやすい問題です。
  • 回避策:
    • ランタイムバリデーションの導入: Zodやio-tsなどのライブラリを導入し、外部からの入力データをアプリケーション内部で使用する前に厳密に検証します。これにより、不正なデータがアプリケーションのロジックに到達するのを防ぎます。
    • APIスキーマの共有: バックエンドとフロントエンドでAPIのスキーマ定義を共有し、自動生成ツール（OpenAPI Generatorなど）を利用することも有効です。

5. 堅牢なTypeScriptアプリケーションのための型設計ベストプラクティス

このセクションでは、ランタイム安全性を考慮したTypeScriptの型設計におけるベストプラクティスと、設計上のトレードオフについて解説します。

5.1. 設計上のトレードオフ

堅牢な型設計は重要ですが、常に完璧を目指すことが最善とは限りません。プロジェクトの規模やフェーズに応じてバランスを考慮する必要があります。

  • 型安全性の追求と開発速度: 厳密な型定義やランタイムバリデーションを徹底することは、コードの堅牢性を高めますが、初期開発コストやコード量が増加する可能性があります。特に小規模なプロジェクトやプロトタイプ開発では、このバランスを考慮する必要があります。
  • パフォーマンスとランタイムチェック: ランタイム型チェックは、実行時に追加の処理を伴うため、パフォーマンスに影響を与える可能性があります。特に高頻度で呼び出される関数や大量のデータを処理する場面では、パフォーマンスへの影響を評価し、必要に応じて最適化を検討する必要があります。
  • 柔軟性と厳密性: any型は柔軟性を提供しますが、型安全性を犠牲にします。unknown型は安全性を高めますが、使用前に型チェックが必要なため、コードが冗長になる可能性があります。プロジェクトの要件に応じて、適切な厳密性のレベルを選択することが重要です。

5.2. ベストプラクティス

これらのプラクティスは、TypeScriptプロジェクトのランタイム安全性を高め、保守性を向上させるために役立ちます。

  • strictモードの有効化: tsconfig.jsonでstrict: trueを設定し、TypeScriptの厳密な型チェックを最大限に活用します。これは新しいプロジェクトではデフォルトで有効になっていることが多いです。
  • any型の回避とunknown型の活用: 型が不明な場合はunknown型を使用し、型ガードで安全に型を絞り込みます。any型は最終手段として、その使用箇所を最小限に留め、理由を明記します。
  • ドメイン主導型設計 (Domain-First): 現実世界の意味構造を型に落とし込み、意味ベースで抽象化された型を設計します。例えば、単なるstringではなくEmailAddress型やUserId型を定義することで、誤った値の代入を防ぎやすくなります。
  • 入力・内部・出力型の分離: API層、アプリケーション層、DB層など、各レイヤーの責任に応じて型を明確に分離し、共通化を避けます。これにより、各層での変更が他の層に与える影響を最小限に抑えられます。特にAPIの入力と出力は、Zodなどでバリデーションされた内部表現とは異なる型として扱うべきです。
  • 不変性 (Immutability) のデフォルト化: 変更可能なオブジェクトはバグの温床となるため、readonly修飾子などを活用し、不変性をデフォルトとします。これにより、予期せぬ副作用を防ぎやすくなります。
  • Narrow Type の積極的活用: 文字列や数値に意味を持たせ、ユニオン型やリテラル型で型を狭めます。例えば、"pending" | "success" | "error" のようなステータス型は、不正なステータスの代入をコンパイル時に防ぎます。
  • ランタイムバリデーションの導入: 外部からの入力データに対しては、Zodやio-tsなどのライブラリを用いてランタイムバリデーションを徹底します。これにより、不正なデータがアプリケーションのロジックに到達するのを防ぎます。
  • エラーハンドリングの型付け: 非同期処理やエラーハンドリングにおいても、Promiseの型やレスポンスデータの型定義をしっかり行い、never型などを用いて網羅的なエラーチェックを実装します。
  • ESLintとPrettierの導入: コード品質を維持し、チーム開発での一貫性を保つために、ESLintとPrettierを導入し、型に関するルールも設定します。例えば、@typescript-eslint/no-explicit-anyルールでanyの使用を制限するなど。

まとめ

本記事では、TypeScriptにおけるランタイム安全性を確保するための5つの実践的なアプローチを解説しました。

  1. unknown 型と型ガードによる安全な型絞り込み: anyの代わりにunknownを使い、型ガードで厳密なチェックを行う。
  2. Zodなどのバリデーションライブラリによるランタイムバリデーション: 外部からの入力を実行時に検証し、型とスキーマの同期を保つ。
  3. never 型による網羅性チェック: ユニオン型を扱うスイッチ文などで、処理漏れをコンパイル時に検出する。
  4. よくあるランタイムエラーの落とし穴と回避策: anyの乱用、型アサーションの誤用、外部データの不整合といった一般的な問題への対処法。
  5. 堅牢なTypeScriptアプリケーションのための型設計ベストプラクティス: strictモード、ドメイン主導型設計、入力・内部・出力型の分離など、長期的な保守性を見据えた設計原則。

これらの実践を組み合わせることで、TypeScriptの静的型付けの恩恵を最大限に活かしつつ、JavaScriptの動的な性質に起因するランタイムエラーを大幅に削減し、より堅牢で信頼性の高いアプリケーションを構築できます。

TypeScriptの公式ドキュメントや各ライブラリのGitHubリポジトリも参考に、これらの知見を日々の開発にぜひ取り入れてみてください。

1
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?