TypeScript の型安全性を破壊する NG コード＆その回避策 10 選

2025年8月10日

TypeScript

TypeScript を学び始めた皆さん、コンパイルエラーが出ないからといって安心していませんか？実は、TypeScript の型安全性を知らず知らずのうちに破壊してしまっているコードを書いている可能性があります。

型安全性の破壊は、開発時には気づかず、本番環境で予期しないエラーを引き起こす原因となります。今回は初心者の方でもわかりやすく、よくある NG パターンとその回避策をレベル別にご紹介いたします。

背景

TypeScript の型安全性とは

TypeScript の最大の魅力は「型安全性」です。コンパイル時に型の不整合を検出し、実行時エラーを未然に防ぐことができます。

型安全性がもたらすメリットは以下の通りです：

#	メリット	説明
1	エラーの早期発見	コンパイル時に型の不整合を検出
2	コードの可読性向上	型情報が仕様書の役割を果たす
3	リファクタリングの安全性	IDE のサポートで安全な変更が可能
4	チーム開発の効率化	API の仕様が型で明確になる

なぜ型安全性が重要なのか

JavaScript では実行時まで型エラーが分からないため、本番環境での予期しないエラーが発生しやすくなります。

以下のような問題が起こりがちです：

javascript// JavaScript の例：実行時エラー
function greet(user) {
    return "Hello, " + user.name; // user が null の場合エラー
}

greet(null); // TypeError: Cannot read property 'name' of null

TypeScript では、このような問題をコンパイル時に検出できます：

typescript// TypeScript の例：コンパイル時エラー
interface User {
    name: string;
}

function greet(user: User) {
    return "Hello, " + user.name;
}

greet(null); // コンパイルエラー：Argument of type 'null' is not assignable to parameter of type 'User'

課題

型安全性を破壊する代表的な NG パターンは、レベル別に分類すると以下のようになります：

レベル	対象者	問題の種類	パターン数
1	初心者	基本的な型安全性違反	4 選
2	中級者	よく陥りがちな問題	3 選
3	上級者	見落としやすい罠	3 選

これらの問題を理解し、適切な回避策を身につけることで、より安全で保守性の高いコードを書けるようになります。

解決策

レベル 1: 基本的な型安全性違反（4 選）

1. any 型の乱用

NG パターン

any 型を使うとすべての型チェックが無効になってしまいます。

typescript// NG: any 型の乱用
function processData(data: any) {
    return data.user.profile.name; // 実行時エラーの可能性
}

const result = processData("invalid data"); // コンパイルエラーにならない

問題点

型チェックが完全に無効になる
IDE の補完機能が働かない
リファクタリング時に問題を検出できない

回避策

具体的な型を定義するか、unknown 型を使用しましょう。

typescript// OK: 具体的な型定義
interface UserData {
    user: {
        profile: {
            name: string;
        };
    };
}

function processData(data: UserData) {
    return data.user.profile.name; // 型安全
}

未知の型の場合は unknown を使用します：

typescript// OK: unknown 型と型ガードの組み合わせ
function processData(data: unknown) {
    if (isUserData(data)) {
        return data.user.profile.name; // 型ガード後は安全
    }
    throw new Error("Invalid data format");
}

function isUserData(data: unknown): data is UserData {
    return (
        typeof data === "object" &&
        data !== null &&
        "user" in data
    );
}

2. 型アサーション（as）の誤用

NG パターン

型アサーションを根拠なく使用すると、型安全性が破壊されます。

typescript// NG: 根拠のない型アサーション
function getUser(id: string) {
    const response = fetch(`/api/users/${id}`);
    return response.json() as User; // 実際の型が保証されない
}

問題点

実際のデータ構造と型定義が一致しない可能性
実行時エラーの原因となる
TypeScript の型チェックを強制的に回避している

回避策

型ガードやスキーマ検証を使用しましょう。

typescript// OK: 型ガードを使用
function getUser(id: string): Promise<User> {
    return fetch(`/api/users/${id}`)
        .then(response => response.json())
        .then(data => {
            if (isUser(data)) {
                return data;
            }
            throw new Error("Invalid user data");
        });
}

function isUser(data: unknown): data is User {
    return (
        typeof data === "object" &&
        data !== null &&
        "id" in data &&
        "name" in data &&
        typeof (data as any).id === "string" &&
        typeof (data as any).name === "string"
    );
}

ライブラリを使用した検証も有効です：

typescript// OK: Zod を使用したスキーマ検証
import { z } from "zod";

const UserSchema = z.object({
    id: z.string(),
    name: z.string(),
    email: z.string().email(),
});

type User = z.infer<typeof UserSchema>;

function getUser(id: string): Promise<User> {
    return fetch(`/api/users/${id}`)
        .then(response => response.json())
        .then(data => UserSchema.parse(data)); // 検証付きパース
}

3. unknown への不適切なキャスト

NG パターン

unknown 型を適切な型チェックなしに使用する例です。

typescript// NG: unknown の不適切な使用
function handleApiResponse(response: unknown) {
    const data = response as ApiResponse; // 危険
    return data.result.items[0]; // 実行時エラーの可能性
}

問題点

unknown の安全性が活かされない
型チェックを回避している
any 型と同等の危険性を持つ

回避策

unknown 型は必ず型ガードと組み合わせて使用します。

typescript// OK: 型ガードとの組み合わせ
interface ApiResponse {
    result: {
        items: string[];
    };
}

function handleApiResponse(response: unknown) {
    if (!isApiResponse(response)) {
        throw new Error("Invalid API response");
    }
    
    return response.result.items[0]; // 型安全
}

function isApiResponse(data: unknown): data is ApiResponse {
    return (
        typeof data === "object" &&
        data !== null &&
        "result" in data &&
        typeof (data as any).result === "object" &&
        "items" in (data as any).result &&
        Array.isArray((data as any).result.items)
    );
}

段階的な型チェックも効果的です：

typescript// OK: 段階的な型チェック
function handleApiResponse(response: unknown) {
    // Step 1: オブジェクト型チェック
    if (typeof response !== "object" || response === null) {
        throw new Error("Response is not an object");
    }
    
    // Step 2: result プロパティのチェック
    if (!("result" in response)) {
        throw new Error("Response missing result property");
    }
    
    const result = (response as any).result;
    
    // Step 3: items プロパティのチェック
    if (typeof result !== "object" || !("items" in result)) {
        throw new Error("Result missing items property");
    }
    
    // Step 4: items が配列かチェック
    if (!Array.isArray(result.items)) {
        throw new Error("Items is not an array");
    }
    
    return result.items[0];
}

4. 配列の型チェック不足

NG パターン

配列の要素に対する型チェックが不十分な例です。

typescript// NG: 配列要素の型チェック不足
function processItems(items: any[]) {
    return items.map(item => {
        return {
            id: item.id,
            name: item.name.toUpperCase(), // item.name が undefined の可能性
        };
    });
}

問題点

配列の要素が期待する型でない可能性
実行時エラーが発生しやすい
型の恩恵を受けられない

回避策

配列の要素に対して適切な型定義を行います。

typescript// OK: 適切な型定義
interface Item {
    id: string;
    name: string;
}

function processItems(items: Item[]) {
    return items.map(item => {
        return {
            id: item.id,
            name: item.name.toUpperCase(), // 型安全
        };
    });
}

実行時の型チェックも組み合わせます：

typescript// OK: 実行時型チェック付き
function processItems(items: unknown[]): ProcessedItem[] {
    return items
        .filter(isItem) // 型ガードでフィルタリング
        .map(item => ({
            id: item.id,
            name: item.name.toUpperCase(),
        }));
}

function isItem(item: unknown): item is Item {
    return (
        typeof item === "object" &&
        item !== null &&
        "id" in item &&
        "name" in item &&
        typeof (item as any).id === "string" &&
        typeof (item as any).name === "string"
    );
}

interface ProcessedItem {
    id: string;
    name: string;
}

レベル 2: 中級者が陥りがちな問題（3 選）

5. オブジェクトのプロパティアクセス

NG パターン

動的なプロパティアクセスで型安全性を失う例です。

typescript// NG: 動的プロパティアクセスの型安全性不足
function getProperty(obj: any, key: string) {
    return obj[key]; // 存在しないプロパティでも undefined が返される
}

const user = { name: "Alice", age: 30 };
const email = getProperty(user, "email"); // undefined だが型エラーにならない

問題点

存在しないプロパティへのアクセスを検出できない
戻り値の型が不明確
タイポによるバグを防げない

回避策

keyof 演算子とジェネリクスを使用します。

typescript// OK: keyof とジェネリクスを使用
function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
    return obj[key];
}

const user = { name: "Alice", age: 30 };
const name = getProperty(user, "name"); // string 型
const age = getProperty(user, "age");   // number 型
// const email = getProperty(user, "email"); // コンパイルエラー

オプショナルプロパティの場合は、適切な型定義を行います：

typescript// OK: オプショナルプロパティの適切な処理
interface User {
    name: string;
    age: number;
    email?: string; // オプショナル
}

function getProperty<T, K extends keyof T>(
    obj: T, 
    key: K
): T[K] {
    return obj[key];
}

function getUserEmail(user: User): string {
    const email = getProperty(user, "email");
    // email は string | undefined 型
    return email ?? "No email provided";
}

6. 関数の引数型チェック不備

NG パターン

関数の引数に対する型チェックが不十分な例です。

typescript// NG: 引数の型チェック不備
function calculateTotal(items: any) {
    let total = 0;
    for (const item of items) { // items が配列でない場合エラー
        total += item.price * item.quantity;
    }
    return total;
}

問題点

引数が期待する型でない場合の処理が不十分
実行時エラーが発生しやすい
関数の契約が明確でない

回避策

明確な型定義と引数検証を行います。

typescript// OK: 明確な型定義
interface CartItem {
    price: number;
    quantity: number;
    name: string;
}

function calculateTotal(items: CartItem[]): number {
    return items.reduce((total, item) => {
        return total + (item.price * item.quantity);
    }, 0);
}

実行時の引数検証も追加します：

typescript// OK: 実行時検証付き
function calculateTotal(items: unknown): number {
    if (!Array.isArray(items)) {
        throw new Error("Items must be an array");
    }
    
    const validItems = items.filter(isCartItem);
    
    if (validItems.length !== items.length) {
        throw new Error("All items must have valid price and quantity");
    }
    
    return validItems.reduce((total, item) => {
        return total + (item.price * item.quantity);
    }, 0);
}

function isCartItem(item: unknown): item is CartItem {
    return (
        typeof item === "object" &&
        item !== null &&
        "price" in item &&
        "quantity" in item &&
        "name" in item &&
        typeof (item as any).price === "number" &&
        typeof (item as any).quantity === "number" &&
        typeof (item as any).name === "string" &&
        (item as any).price >= 0 &&
        (item as any).quantity >= 0
    );
}

7. 非同期処理での型情報の欠如

NG パターン

Promise の型情報が不十分な例です。

typescript// NG: Promise の型情報不足
async function fetchUserData(id: string) {
    const response = await fetch(`/api/users/${id}`);
    return response.json(); // any 型が返される
}

// 使用例
async function displayUser(id: string) {
    const user = await fetchUserData(id); // user は any 型
    console.log(user.name); // 型チェックされない
}

問題点

Promise の解決値の型が不明
非同期処理のエラーハンドリングが不十分
型の恩恵を受けられない

回避策

Promise の型パラメータを明確に指定します。

typescript// OK: Promise の型を明確に指定
interface User {
    id: string;
    name: string;
    email: string;
}

async function fetchUserData(id: string): Promise<User> {
    const response = await fetch(`/api/users/${id}`);
    
    if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    const data = await response.json();
    
    if (!isUser(data)) {
        throw new Error("Invalid user data received");
    }
    
    return data;
}

function isUser(data: unknown): data is User {
    return (
        typeof data === "object" &&
        data !== null &&
        "id" in data &&
        "name" in data &&
        "email" in data &&
        typeof (data as any).id === "string" &&
        typeof (data as any).name === "string" &&
        typeof (data as any).email === "string"
    );
}

エラーハンドリングも含めた包括的な型定義を行います：

typescript// OK: エラーハンドリング付きの型安全な非同期処理
type Result<T> = {
    success: true;
    data: T;
} | {
    success: false;
    error: string;
};

async function fetchUserData(id: string): Promise<Result<User>> {
    try {
        const response = await fetch(`/api/users/${id}`);
        
        if (!response.ok) {
            return {
                success: false,
                error: `HTTP error! status: ${response.status}`
            };
        }
        
        const data = await response.json();
        
        if (!isUser(data)) {
            return {
                success: false,
                error: "Invalid user data received"
            };
        }
        
        return {
            success: true,
            data
        };
    } catch (error) {
        return {
            success: false,
            error: error instanceof Error ? error.message : "Unknown error"
        };
    }
}

// 使用例
async function displayUser(id: string): Promise<void> {
    const result = await fetchUserData(id);
    
    if (result.success) {
        console.log(result.data.name); // 型安全
    } else {
        console.error("Failed to fetch user:", result.error);
    }
}

レベル 3: 上級者向けの罠（3 選）

8. ジェネリクスの制約不足

NG パターン

ジェネリクスに適切な制約を設けていない例です。

typescript// NG: ジェネリクス制約不足
function merge<T, U>(obj1: T, obj2: U) {
    return { ...obj1, ...obj2 }; // プリミティブ値でも動作してしまう
}

const result1 = merge("hello", 42); // 意味のない結果
const result2 = merge(null, undefined); // 危険な操作

問題点

不適切な型でも関数が呼び出せる
実行時エラーの可能性
関数の意図が明確でない

回避策

適切な制約を設けます。

typescript// OK: 適切なジェネリクス制約
function merge<T extends object, U extends object>(
    obj1: T, 
    obj2: U
): T & U {
    if (obj1 === null || obj2 === null) {
        throw new Error("Cannot merge null objects");
    }
    
    return { ...obj1, ...obj2 };
}

// 使用例
const user = { name: "Alice", age: 30 };
const profile = { bio: "Developer", location: "Tokyo" };
const merged = merge(user, profile); // 型安全
// const invalid = merge("hello", 42); // コンパイルエラー

より細かい制約も可能です：

typescript// OK: より具体的な制約
interface Identifiable {
    id: string;
}

function mergeWithId<T extends Identifiable, U extends object>(
    obj1: T, 
    obj2: U
): T & U {
    return { ...obj1, ...obj2 };
}

// 使用例
const userWithId = { id: "123", name: "Alice" };
const profile = { bio: "Developer" };
const merged = mergeWithId(userWithId, profile);
// const invalid = mergeWithId({ name: "Alice" }, profile); // id がないためエラー

9. 条件付き型の誤用

NG パターン

条件付き型が複雑になりすぎて理解困難になる例です。

typescript// NG: 複雑すぎる条件付き型
type ComplexType<T> = T extends string
    ? T extends `${infer P}:${infer R}`
        ? R extends "number"
            ? number
            : R extends "boolean"
                ? boolean
                : string
        : never
    : T extends number
        ? string
        : never;

// 使用が困難で意図が不明
type Result = ComplexType<"value:number">; // 何が返されるか分からない

問題点

可読性が低い
メンテナンスが困難
デバッグが難しい

回避策

段階的な型定義で理解しやすくします。

typescript// OK: 段階的な条件付き型
// Step 1: 基本的な解析
type ParseKeyValue<T extends string> = T extends `${infer K}:${infer V}` 
    ? { key: K; value: V } 
    : never;

// Step 2: 値の型変換
type ParseValueType<T extends string> = T extends "number"
    ? number
    : T extends "boolean"
        ? boolean
        : string;

// Step 3: 組み合わせ
type TypedKeyValue<T extends string> = ParseKeyValue<T> extends { 
    key: infer K; 
    value: infer V 
}
    ? V extends string
        ? { key: K; value: ParseValueType<V> }
        : never
    : never;

// 使用例
type NumberValue = TypedKeyValue<"age:number">; // { key: "age"; value: number }
type BooleanValue = TypedKeyValue<"active:boolean">; // { key: "active"; value: boolean }

実用的なユーティリティ型として活用します：

typescript// OK: 実用的な条件付き型
type NonNullable<T> = T extends null | undefined ? never : T;

type DeepReadonly<T> = {
    readonly [P in keyof T]: T[P] extends object 
        ? DeepReadonly<T[P]> 
        : T[P];
};

// 使用例
interface Config {
    database: {
        host: string;
        port: number;
    };
    api: {
        endpoint: string;
    };
}

type ReadonlyConfig = DeepReadonly<Config>;
// すべてのプロパティが readonly になる

10. モジュール境界での型情報の喪失

NG パターン

モジュール間で型情報が失われる例です。

typescript// utils.ts - NG: 型情報が不十分
export function processData(data: any) {
    return {
        processed: true,
        result: data.items.map((item: any) => item.name)
    };
}

// main.ts - NG: 型情報が失われている
import { processData } from "./utils";

const result = processData(someData); // result の型が不明
console.log(result.result[0]); // 型チェックされない

問題点

モジュール間での型情報の連携不足
API の契約が不明確
リファクタリング時の影響範囲が不明

回避策

明確な型定義をエクスポートします。

typescript// types.ts - 共通型定義
export interface DataItem {
    id: string;
    name: string;
}

export interface InputData {
    items: DataItem[];
}

export interface ProcessedResult {
    processed: boolean;
    result: string[];
}

型定義を活用したモジュールを作成します：

typescript// utils.ts - OK: 明確な型定義
import { InputData, ProcessedResult } from "./types";

export function processData(data: InputData): ProcessedResult {
    return {
        processed: true,
        result: data.items.map(item => item.name)
    };
}

// 型ガード関数もエクスポート
export function isInputData(data: unknown): data is InputData {
    return (
        typeof data === "object" &&
        data !== null &&
        "items" in data &&
        Array.isArray((data as any).items)
    );
}

型安全な使用例：

typescript// main.ts - OK: 型安全な使用
import { processData, isInputData } from "./utils";
import { ProcessedResult } from "./types";

function handleData(someData: unknown): ProcessedResult | null {
    if (!isInputData(someData)) {
        console.error("Invalid input data format");
        return null;
    }
    
    const result = processData(someData); // 型安全
    console.log(result.result[0]); // string 型として推論される
    return result;
}

具体例

実際のプロジェクトでの改善例

以下は、実際のプロジェクトで見つかった問題と改善方法の例です。

改善前のコード

typescript// API レスポンス処理（改善前）
class UserService {
    async getUser(id: string) {
        const response = await fetch(`/api/users/${id}`);
        const data = await response.json();
        return data; // any 型
    }
    
    async updateUser(id: string, updates: any) {
        const user = await this.getUser(id);
        const updatedUser = { ...user, ...updates }; // 型安全性なし
        
        const response = await fetch(`/api/users/${id}`, {
            method: 'PUT',
            body: JSON.stringify(updatedUser)
        });
        
        return response.json(); // any 型
    }
}

改善後のコード

typescript// API レスポンス処理（改善後）
import { z } from "zod";

// スキーマ定義
const UserSchema = z.object({
    id: z.string(),
    name: z.string(),
    email: z.string().email(),
    age: z.number().min(0),
    createdAt: z.string().datetime(),
});

const UserUpdateSchema = UserSchema.partial().omit({ id: true, createdAt: true });

type User = z.infer<typeof UserSchema>;
type UserUpdate = z.infer<typeof UserUpdateSchema>;

// エラー型定義
type ApiResult<T> = {
    success: true;
    data: T;
} | {
    success: false;
    error: string;
    code: string;
};

class UserService {
    async getUser(id: string): Promise<ApiResult<User>> {
        try {
            const response = await fetch(`/api/users/${id}`);
            
            if (!response.ok) {
                return {
                    success: false,
                    error: `User not found`,
                    code: response.status.toString()
                };
            }
            
            const data = await response.json();
            const user = UserSchema.parse(data); // 検証付きパース
            
            return {
                success: true,
                data: user
            };
        } catch (error) {
            return {
                success: false,
                error: error instanceof Error ? error.message : "Unknown error",
                code: "PARSE_ERROR"
            };
        }
    }
    
    async updateUser(
        id: string, 
        updates: UserUpdate
    ): Promise<ApiResult<User>> {
        // 入力検証
        try {
            UserUpdateSchema.parse(updates);
        } catch (error) {
            return {
                success: false,
                error: "Invalid update data",
                code: "VALIDATION_ERROR"
            };
        }
        
        // 現在のユーザー取得
        const currentUserResult = await this.getUser(id);
        if (!currentUserResult.success) {
            return currentUserResult;
        }
        
        const updatedUser = { ...currentUserResult.data, ...updates };
        
        try {
            const response = await fetch(`/api/users/${id}`, {
                method: 'PUT',
                headers: {
                    'Content-Type': 'application/json',
                },
                body: JSON.stringify(updatedUser)
            });
            
            if (!response.ok) {
                return {
                    success: false,
                    error: `Update failed`,
                    code: response.status.toString()
                };
            }
            
            const data = await response.json();
            const user = UserSchema.parse(data);
            
            return {
                success: true,
                data: user
            };
        } catch (error) {
            return {
                success: false,
                error: error instanceof Error ? error.message : "Unknown error",
                code: "UPDATE_ERROR"
            };
        }
    }
}

使用例での比較

改善前の使用方法

typescript// 改善前：型安全性なし
const userService = new UserService();

async function displayUser(id: string) {
    const user = await userService.getUser(id); // any 型
    console.log(user.name); // 実行時エラーの可能性
    
    // 更新処理
    await userService.updateUser(id, {
        invalidField: "value" // コンパイルエラーにならない
    });
}

改善後の使用方法

typescript// 改善後：完全に型安全
const userService = new UserService();

async function displayUser(id: string): Promise<void> {
    const userResult = await userService.getUser(id);
    
    if (userResult.success) {
        console.log(userResult.data.name); // 型安全
        
        // 更新処理
        const updateResult = await userService.updateUser(id, {
            name: "New Name",
            age: 25
            // invalidField: "value" // コンパイルエラー
        });
        
        if (updateResult.success) {
            console.log("Updated:", updateResult.data);
        } else {
            console.error("Update failed:", updateResult.error);
        }
    } else {
        console.error("User not found:", userResult.error);
    }
}

まとめ

TypeScript の型安全性を保つためには、以下のポイントを押さえることが重要です。

レベル	ポイント	対策
基本	any 型を避ける	具体的な型定義を行う
基本	型アサーションの乱用を避ける	型ガードを使用する
中級	動的アクセスでの型安全性	keyof 演算子を活用する
中級	非同期処理の型情報	Promise の型パラメータを明確にする
上級	ジェネリクスの適切な制約	extends キーワードで制約を設ける
上級	モジュール間の型連携	型定義ファイルを共有する