TypeScriptの型ガードで起こりやすいエラーと対処法を徹底解説！初心者でも理解できる型安全の考え方

1. 型ガードとは？基本の理解から始めよう

1. 型ガードとは？基本の理解から始めよう

TypeScriptの型ガードとは、変数の型を条件分岐によって絞り込み、特定の型として安全に扱えるようにする仕組みです。例えば、ある変数が文字列なのか数値なのかで処理を分けたい場合、型ガードを使うことでエラーを防ぎながら正しい処理を実行できます。

型ガードはユニオン型（複数の型を許可する型）を扱うときに特に重要です。例えば、値が入力フォームから取得される場合、文字列や数値として扱い方が変わるため、型の判定が欠かせません。

2. よくあるエラー：プロパティが存在しないと言われる

2. よくあるエラー：プロパティが存在しないと言われる

ユニオン型の値に対してプロパティへ直接アクセスすると、TypeScriptは安全性を確認できず、エラーが発生します。これは、含まれる型すべてがそのプロパティを持っているとは限らないためです。

type User = { name: string };
type Admin = { name: string; role: string };

function printRole(person: User | Admin) {
    console.log(person.role); // エラー
}

上記の例では、User型にはroleが存在しないため、TypeScriptは安全なコードであると言えません。この問題を解決するには、型ガードを用いて型を判定します。

function printRole(person: User | Admin) {
    if ("role" in person) {
        console.log(person.role);
    }
}

3. typeof で判定できる型とできない型を理解する

3. typeof で判定できる型とできない型を理解する

typeofは便利な型ガードですが、判定できる型には制限があります。たとえば、numberやstringやbooleanなど基本的な型は判定できますが、オブジェクトの中身を判定することはできません。

function checkValue(value: string | number) {
    if (typeof value === "string") {
        console.log(value.toUpperCase());
    }
}

逆に、ユーザー定義型の場合にはtypeofは使えません。例えば、次のようなケースです。

type Cat = { meow: () => void };
type Dog = { bark: () => void };

function speak(animal: Cat | Dog) {
    if (typeof animal === "Cat") { // エラー
    }
}

このような場合は、in演算子を使って判定します。

function speak(animal: Cat | Dog) {
    if ("meow" in animal) {
        animal.meow();
    } else {
        animal.bark();
    }
}

4. カスタム型ガードの書き方を理解する

4. カスタム型ガードの書き方を理解する

複雑な型を判定するためには、カスタム型ガードを使う方法があります。これは、自作の関数で型を判断し、その結果をTypeScriptに伝える仕組みです。

type Car = { drive: () => void };
type Bike = { ride: () => void };

function isCar(v: Car | Bike): v is Car {
    return "drive" in v;
}

function move(v: Car | Bike) {
    if (isCar(v)) {
        v.drive();
    } else {
        v.ride();
    }
}

このように型ガード関数を作ると、条件分岐後の型が確実に判定されているとTypeScriptが理解してくれます。

5. never 型のエラーの理解と対処法

5. never 型のエラーの理解と対処法

型ガードを使っていると、neverという型が登場することがあります。これは、「絶対に起こらない型」を意味しており、型の分岐が完全に網羅されていないと発生します。

type Shape = { kind: "circle"; radius: number }
           | { kind: "square"; size: number };

function area(shape: Shape) {
    switch (shape.kind) {
        case "circle":
            return Math.PI * shape.radius * shape.radius;
        case "square":
            return shape.size * shape.size;
        default:
            const _exhaustive: never = shape; // エラー
            return _exhaustive;
    }
}

これは型の条件をすべて網羅することで解決できます。

まとめ

まとめ

型ガードで起こりやすいエラーを正しく理解することが型安全への第一歩

ここまで、TypeScriptの型ガードで初心者がつまずきやすいエラーと、その具体的な対処法について詳しく解説してきました。 型ガードは「TypeScriptで安全にプログラムを書くための土台」とも言える重要な仕組みですが、 使い方を誤るとエラーが増え、かえって不安になってしまうことがあります。 しかし、エラーの意味と理由を一つずつ理解していくことで、 型ガードは非常に心強い味方へと変わります。

特に多いのが、「プロパティが存在しない」というエラーです。 これはTypeScriptが「すべての型にそのプロパティがあるとは限らない」と判断しているために発生します。 ユニオン型を扱う以上、このエラーは避けて通れませんが、 in演算子やカスタム型ガードを使うことで、確実に解消できます。 これはTypeScriptが型安全を守ろうとしている証拠でもあり、 エラーは決して悪いものではありません。

typeof・in・カスタム型ガードの正しい使い分け

型ガードにはいくつかの方法があり、それぞれに役割があります。 typeofは文字列や数値などの基本型を判定するのに向いていますが、 オブジェクトの詳細な構造までは判定できません。 一方、in演算子は「そのプロパティを持っているかどうか」を調べることで、 オブジェクト型の判定に力を発揮します。

さらに複雑なケースでは、カスタム型ガードを作ることで、 処理を安全かつ読みやすくまとめることができます。 カスタム型ガードは一度作ってしまえば何度も再利用できるため、 実務では特に重宝されます。 型ガードの書き方に慣れてくると、「どこでどの型ガードを使うべきか」が自然と分かるようになります。

never型エラーは設計を見直すチャンス

初心者にとって分かりにくい存在がnever型です。 しかし、never型は「想定していない状態が存在する」ことを教えてくれる、 とても親切な仕組みでもあります。 switch文などでnever型が出てきた場合は、 「分岐がすべて網羅されているか？」を見直すサインだと考えましょう。

このチェックを行うことで、後から型が追加された場合でも、 対応漏れにすぐ気づけるようになります。 型ガードとnever型を組み合わせることで、 将来の変更にも強い、堅牢なコードを書くことができます。

型ガードを使った安全な分岐のサンプル

type Member = { name: string };
type Staff = { name: string; department: string };

function isStaff(person: Member | Staff): person is Staff {
    return "department" in person;
}

function showInfo(person: Member | Staff) {
    if (isStaff(person)) {
        console.log(person.department);
    } else {
        console.log(person.name);
    }
}

このように型ガードを使えば、条件分岐の中で安全にプロパティへアクセスできます。 TypeScriptが自動で型を絞り込んでくれるため、 エラーを恐れずに処理を書けるようになります。

型ガードのエラーを恐れず、理解して使いこなそう

型ガードで発生するエラーは、TypeScriptが「安全ではない可能性」を教えてくれている合図です。 エラーを無理に消すのではなく、 「なぜこのエラーが出ているのか？」を考えることが、型安全への近道になります。 型ガードの考え方を身につけることで、 TypeScriptらしい堅牢で読みやすいコードが書けるようになるでしょう。