できない.dev

型の絞り込み (Narrowing)

別名: Narrowing / 型ガード / ナローイング / type guard

TypeScript が if や instanceof、typeof、in などの条件から、ユニオン型をより具体的な型へ自動的に絞り込む仕組み。
unknown や null を安全に扱う土台になる。

公開: 更新:

定義

型の絞り込み(Narrowing) は、TypeScript が制御フロー上の条件式から変数の型をより具体的な型へ狭めていく機能である。
if (typeof x === "string") や if (e instanceof Error)、if (v != null) などの分岐の内側で、コンパイラが自動的に型を絞る。

詳細

string | number のようなユニオン型や、unknown / null | undefined を含む型は、そのままではプロパティアクセスできない。
typeof / instanceof / in / 等価比較・早期 return などで分岐すると、その先のスコープで型が確定する。
v is T を返す ユーザー定義型ガード関数 を書けば、複雑な判定を再利用しつつ絞り込みを効かせられる。

よくある誤解

  • 型の絞り込みは、型アサーション(as)とは違う。
    as は検査せずに型を上書きするだけである。
    Narrowing は、実行時のチェックに基づいて安全に型を絞り込む。
  • 絞り込みは関数をまたいでは保たれない。
    別の関数に値を渡すと絞り込みは失われるので、型ガード関数にして対処する。

関連

null 系は Object is possibly 'null'、catch の unknown は Object is of type 'unknown' を参照する。