TypeScriptの型の絞り込み（Narrowing）と制御フロー分析

型の絞り込み（narrowing）とは、それまでにコードが行ったチェックに基づいて、TypeScriptがコードのある地点での値の型をより具体的に割り出すことです。string | number 型の引数は、if (typeof x === "string") の中では string に、else の中では number になります。

function pad(value: string | number): string {
  if (typeof value === "number") {
    // value: number
    return value.toFixed(2).padStart(8);
  }
  // value: string (number was handled above)
  return value.padStart(8);
}

console.log(`[${pad(3.14159)}]`); // [    3.14]
console.log(`[${pad("abc")}]`);   // [     abc]

チェックの前に value.toFixed(2) を呼ぶとコンパイルエラーになります。string には toFixed がないからです。チェックは実行時に動く普通のJavaScriptで、絞り込みはコンパイラーがそれを読んで型を調整することです。余分なコードは何も出力されません。

制御フロー分析

TypeScriptは関数の中のすべての経路をたどります。if/else、早期の return と throw、switch、ループ、そして短絡評価の演算子 &&、||、??、?: です。各地点での変数の型は、そこでまだありうる型です。

function firstWord(text: string | null | undefined): string {
  if (text == null) return "(none)";   // removes null and undefined
  // text: string
  const trimmed = text.trim();
  const space = trimmed.indexOf(" ");
  return space === -1 ? trimmed : trimmed.slice(0, space);
}

function lengthOrZero(list?: string[]): number {
  return list && list.length > 0 ? list.length : 0; // list: string[] after &&
}

console.log(firstWord("  hello typed world")); // hello
console.log(firstWord(undefined));             // (none)
console.log(lengthOrZero(["a", "b"]), lengthOrZero()); // 2 0

早期 return のスタイル（ガード節）は、いちばん読みやすい絞り込み方です。特殊なケースを先に処理すれば、関数の残りはきれいな型で書けます。

絞り込みの方法一覧

最後の3つは型ガードと判別可能なユニオン型のページで扱います。残りは以下で説明します。

truthiness による絞り込み

if (x) は null と undefined（と、リテラル型の false、0、""）を取り除きます。短く書けますが、典型的な落とし穴が1つあります。0 と "" は falsy なので、正しい値が「ない」ものとして扱われてしまいます。

function describeCount(count: number | undefined): string {
  if (!count) return "unknown";   // bug: 0 is falsy too
  return `${count} items`;
}

function describeCountFixed(count: number | undefined): string {
  if (count === undefined) return "unknown";
  return `${count} items`;
}

console.log(describeCount(0));      // unknown
console.log(describeCountFixed(0)); // 0 items

数値と文字列は、undefined や null と明示的に比較しましょう（または ?? を使います）。オブジェクト、配列、関数は falsy になることがないので、truthiness で問題ありません。

等価比較による絞り込み

===、!==、==、!= は両辺を絞り込みます。リテラルと比較するとそのリテラルに絞り込まれます。== null（緩い等価比較）は1回のチェックで null と undefined の両方に一致し、緩い等価比較が慣用的に使われる唯一の場所です。

type Status = "active" | "paused" | "deleted";

function label(status: Status, note: string | null | undefined): string {
  if (status === "deleted") return "gone";
  // status: "active" | "paused"
  const suffix = note != null ? ` (${note})` : ""; // note: string in the true branch
  return status.toUpperCase() + suffix;
}

console.log(label("paused", "until Monday")); // PAUSED (until Monday)
console.log(label("active", undefined));      // ACTIVE
console.log(label("deleted", null));          // gone

2つの変数を比較すると、両方が共通して取りうる型に絞り込まれます。a: string | number と b: string | boolean が a === b を満たすなら、if の中ではどちらも string です。

in 演算子

"key" in obj は、オブジェクト型のユニオンを、そのプロパティを持つ（または持つかもしれない）メンバーに絞り込みます。

type Fish = { name: string; swim: () => string };
type Bird = { name: string; fly: () => string };

function move(pet: Fish | Bird): string {
  if ("swim" in pet) {
    return pet.swim(); // pet: Fish
  }
  return pet.fly();    // pet: Bird
}

console.log(move({ name: "Nemo", swim: () => "splash" })); // splash
console.log(move({ name: "Tweety", fly: () => "flap" }));  // flap

in はオブジェクトであることがわかれば unknown にも使えます。typeof v === "object" && v !== null && "id" in v のあとでは、v が unknown 型の id プロパティを持つことをTypeScriptは知っています。自分で設計するユニオン型なら、メソッドの有無を調べるよりも共通のタグプロパティ（kind: "fish"）を使うほうがわかりやすくなります。このパターンを判別可能なユニオン型といいます。

代入による絞り込み

変数には宣言された型と、代入に応じて変わる絞り込まれた型があります。値を代入すると、宣言された型の範囲内で、その値の型に絞り込まれます。

let id: string | number = "a-17";
console.log(id.toUpperCase()); // id: string here, so string methods work

id = 42;
console.log(id.toFixed(1));    // id: number now

// id = true; would be an error: the declared type is still string | number

絞り込みが外れる場面

絞り込みは局所的で慎重です。次のような場面では絞り込みがリセットされます:

• 別の式。 obj.name をチェックすると obj.name（と obj["name"]）は絞り込まれますが、key がリテラルではなく string 型の変数の場合の obj[key] や、チェックの前に作ったコピーは絞り込まれません。
• コールバックと再代入。 コールバックの中では、絞り込まれた let は、コールバックを作ったあとに再代入されない場合にだけ絞り込みが保たれます。const や再代入されない引数は絞り込まれたままです。
• ヘルパーに隠れたチェック。 isString(x: unknown): boolean という関数はコンパイラーに何も伝えません。戻り値の型を型述語 x is string にすれば、その呼び出しは typeof と同じように絞り込みます。

// This does not compile: x is reassigned after the callback, so the callback loses the narrowing.
function run(flag: boolean): void {
  let x: string | undefined = flag ? "ready" : undefined;
  if (x !== undefined) {
    [1, 2].forEach(() => console.log(x.length));
  }
  x = undefined;
}

run(true);

コンパイラーは index.ts(5,38): error TS18048: 'x' is possibly 'undefined'. を報告します。コールバックは x = undefined のあとで実行されるかもしれないからです。最後の代入を消せば（または if の中で値を const にコピーすれば）コンパイルでき、5 が2回出力されます。

boolean を返すヘルパーは、それが何を保証するかを宣言すれば直せます。それが型ガードです:

function isString(value: unknown): value is string {
  return typeof value === "string";
}

TypeScript 5.5 以降、コンパイラーは単純なアロー関数からこうした型述語を推論します。list.filter((x) => x !== undefined) が undefined を含まない配列を返すようになったのはこのためです。