TypeScript 型アサーション

型アサーション(Type Assertion)は、コンパイラに「この値の型はあなたよりも私の方がよく知っている」と伝える仕組みです。これにより開発者は TypeScript の型推論結果を手動で上書きできます。他の言語の型変換に似ていますが、コンパイル時にのみ有効で、実行時のコードは生成されません。。


2つの構文形式

型アサーションには2つの書き方があります。統一してas構文を使用することをお勧めします。山括弧構文は JSX ファイル内でタグ構文と衝突します。

実例

// ① 山括弧構文(非推奨。.tsx ファイルでは使用不可)
const str1: any = "hello";
const len1: number = (<string>str1).length;

// ② as 構文(推奨)
const str2: any = "world";
const len2: number = (str2 as string).length;

console.log(len1);  // 5
console.log(len2);  // 5

実行結果:

5
5

注意:React の.tsxファイルでは、山括弧の書き方は JSX タグと衝突するため、必ずas構文を使用しなければなりません。


よくある使用シーン

1. any / unknown 型の処理

外部APIやJSONパースなどの場面で取得したデータは通常 any/unknown になり、anyアサーションによって型ヒントを復元できます。

実例

const response: any = { name: "Alice", age: 25 };

// 具体的な型にアサーションして、型ヒントを得る
const user = response as { name: string; age: number };

console.log(user.name);  // Alice
console.log(user.age);   // 25

実行結果:

Alice
25

2. ユニオン型の絞り込み

ユニオン型の具体的な分岐が分かっているが、コンパイラが自動的に判断できない場合、アサーションを使用して型を明確にできます。

実例

type Shape =
    | { kind: "circle"; radius: number }
    | { kind: "rect"; width: number; height: number };

function getArea(shape: Shape): number {
    if (shape.kind === "circle") {
        return Math.PI * (shape as { kind: "circle"; radius: number }).radius ** 2;
    }
    const rect = shape as { kind: "rect"; width: number; height: number };
    return rect.width * rect.height;
}

console.log(getArea({ kind: "circle", radius: 5 }).toFixed(2));  // 78.54
console.log(getArea({ kind: "rect", width: 4, height: 6 }));     // 24

実行結果:

78.54
24

ヒント:優先的に型ガード(typeof / instanceof/ 判別プロパティ)で型を絞り込み、ガードがカバーできない場合にのみアサーションを使用します。

3. DOM 要素の操作

document.querySelector返されるのは Element | nullElement | nullで、具体的な要素型にアサーションして初めて、その専用プロパティにアクセスできます。

実例

// querySelector は Element | null を返す
const input = document.querySelector("#username") as HTMLInputElement;

// アサーション後、HTMLInputElement の専用プロパティにアクセス可能
// console.log(input.value);

// より安全な書き方:nullチェックをしてからアサーションする
const btn = document.querySelector("#submit");
if (btn) {
    (btn as HTMLButtonElement).disabled = true;
}

非nullアサーション !

値の後に!を付けると、コンパイラにその値が null/undefined ではないことを伝え、null 或 undefined非nullを確信できるがコンパイラが推論できない場合に有効です。

実例

function printLength(str?: string) {
    // ! を使用して str に値があるとアサーション
    console.log(str!.length);
}

// 正常に動作
printLength("hello");  // 5

// 実行時エラー:Cannot read properties of undefined
// printLength();

実行結果:

5

警告:非nullアサーションはコンパイラのnullチェックを迂回します。実際の値がnull / undefinednull/undefined の場合、実行時にもエラーが発生します。条件が許せば、オプショナルチェーン?.を優先的に使用してください。


定数アサーション as const

as constリテラルを最も狭い読み取り専用リテラル型として推論します。列挙値、設定定数、タプルの定義によく使われます。

実例

// 通常の宣言:string[] と推論され、要素は変更可能
const colors1 = ["red", "green", "blue"];
colors1.push("yellow");  // 許可される

// as const:readonly ["red", "green", "blue"] と推論され、要素と長さはどちらも変更不可
const colors2 = ["red", "green", "blue"] as const;
// colors2.push("yellow"); // エラー:読み取り専用配列には push できない

// オブジェクトも同様:すべてのプロパティが readonly リテラル型になる
const config = {
    host: "localhost",
    port: 3000
} as const;
// config.port = 8080; // エラー:読み取り専用プロパティは変更できない

console.log(colors2);         // ['red', 'green', 'blue']
console.log(config.host);     // localhost
console.log(config.port);     // 3000

実行結果:

['red', 'green', 'blue']
localhost
3000

アサーションは型変換ではない

型アサーションはコンパイラの型チェックにのみ影響し、コンパイル後に変換コードは生成されません。string を"42"number にアサーションしても、number実行時にはそれは依然として文字列です。

実例

const strNum: any = "42";

// number にアサーションしても、実行時は string のまま
const wrongNum = strNum as number;
console.log(typeof wrongNum);    // string(number ではありません!)
console.log(wrongNum + 1);       // 421(文字列連結であり、数値の加算ではありません)

// 本当の型変換には変換関数を使用する必要があります
const realNum = Number(strNum);
console.log(typeof realNum);     // number
console.log(realNum + 1);        // 43

実行結果:

string
421
number
43

二重アサーション

2つの型の間に重なりがない場合、TypeScript は直接アサーションを拒否します。このとき、unknownunknown を中間として利用できますが、これは危険な操作なので極力避けるべきです。

実例

const num = 42;

// 直接アサーション:number と string に重なりがないため、コンパイラがエラーを報告
// const str = num as string;

// 二重アサーション:まず unknown にアサーションし、次に対象の型にアサーションする
const str = num as unknown as string;

console.log(str);          // 42
console.log(typeof str);   // number(実行時の型は変わらない。アサーションはコンパイル時にのみ有効)

実行結果:

42
number

警告:二重アサーションは TypeScript の型システムを完全に迂回するため、実行時エラーを引き起こしやすくなります。サードパーティライブラリの型が不正確な場合などの特別な状況でのみ使用し、コード内に理由を明記してください。


アサーション方式の比較

アサーション方式 構文 典型的なシナリオ リスク
as アサーションvalue as Typeany から具体的な型への変換、DOM 操作低い(重なりチェックあり)
非nullアサーションvalue!null/undefined でないことの確認中(nullチェックをスキップ)
定数アサーションvalue as constリテラル定数、列挙値无
二重アサーションvalue as unknown as T型に重なりがない場合の強制変換高い(チェックを完全に迂回)

まとめ

  • 構文の選択:統一してas構文を使用し、JSX では山括弧の書き方を避けてください。
  • アサーション vs 変換:アサーションはコンパイル時の型にのみ影響し、実行時コードは生成しません。実際の値の変換にはNumber()、String()などの関数を使用する必要があります。
  • 非nullアサーション:使用する!前に、値が本当に非nullであることを確認してください。そうしないと実行時エラーが発生します。条件が許せば優先的に?.
  • 定数アサーション:as const安全で実用的なアサーションです。設定オブジェクトや定数配列に推奨されます。
  • 二重アサーション:最後の手段です。使用する際はコメントで理由を説明する必要があります。

その他の拡張