TypeScriptの型ガード: オブジェクトの型をチェックする

型ガードとは、TypeScriptが理解できる実行時のチェックです。チェックしたブランチの中で型が絞り込まれます。typeof、instanceof、in は組み込みの型ガードです。それ以外のチェックには、戻り値の型が型述語 value is Type である関数を書きます。

interface User {
  name: string;
  age: number;
}

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" && value !== null &&
    "name" in value && typeof value.name === "string" &&
    "age" in value && typeof value.age === "number"
  );
}

const inputs: unknown[] = [{ name: "Ada", age: 36 }, { name: "Bob" }, "Ada", null];

for (const input of inputs) {
  if (isUser(input)) {
    console.log(`${input.name} is ${input.age}`); // input: User
  } else {
    console.log("not a user:", input);
  }
}

isUser は実行時には普通の boolean を返します。戻り値の型 value is User が、true という結果が何を保証するかをコンパイラーに伝えるので、if (isUser(x)) のたびに x が User に絞り込まれます。

組み込みの型ガード

次のチェックは、ヘルパー関数なしで型を絞り込みます:

どれも普通のJavaScriptとして実行されます。TypeScriptが加えるのは絞り込みです。チェックを読んで、各ブランチの型を調整します。形の一覧は 型の絞り込み のページにあります。自作の型ガードは、1つの式に収まらないチェックや、再利用したいチェックのためのものです。

型述語を書く

型述語は parameterName is Type という形で、戻り値の型の boolean の代わりに書きます。絞り込みは両方向に働きます。true なら Type に絞り込まれ、false ならユニオン型から Type が取り除かれます。

type Cat = { kind: "cat"; meow: () => string };
type Dog = { kind: "dog"; bark: () => string };
type Pet = Cat | Dog;

function isCat(pet: Pet): pet is Cat {
  return pet.kind === "cat";
}

function speak(pet: Pet): string {
  if (isCat(pet)) {
    return pet.meow(); // pet: Cat
  }
  return pet.bark();   // pet: Dog (Cat was ruled out)
}

const pets: Pet[] = [
  { kind: "cat", meow: () => "meow" },
  { kind: "dog", bark: () => "woof" },
];

console.log(pets.map(speak));             // [ 'meow', 'woof' ]
console.log(pets.filter(isCat).length);   // 1 (and the result is typed Cat[])

型ガードを filter に渡すと、正しく型付けされた配列が得られます。TypeScript 5.5 以降は単純なアロー関数からも型述語が推論されるので、名前付きの型ガードがなくても pets.filter((p) => p.kind === "cat") は Cat[] を返します。

型述語の型は引数の型に収まっている必要があります。function f(x: string): x is number はエラー TS2677 A type predicate's type must be assignable to its parameter's type. です。

コンパイラーは型ガードを信用する

TypeScriptは型ガードが boolean を返すことはチェックしますが、その boolean が正しいかはチェックしません。間違った値に true を返す型ガードは型に嘘をつかせ、コンパイルエラーなしに実行時にプログラムが失敗します。

interface Product {
  title: string;
  price: number;
}

// Wrong: only checks title, never price
function isProduct(value: unknown): value is Product {
  return typeof value === "object" && value !== null && "title" in value;
}

const data: unknown = { title: "Lamp" };

if (isProduct(data)) {
  console.log(data.title); // Lamp
  try {
    console.log(data.price.toFixed(2)); // compiles, but throws at run time
  } catch (e) {
    console.log(e instanceof Error ? e.message : e);
    // Cannot read properties of undefined (reading 'toFixed')
  }
}

data.price.toFixed(2) は実行時に TypeError: Cannot read properties of undefined (reading 'toFixed') を投げます。型ガードがそう言ったので、コンパイラーは data.price を number として受け入れました。残りのコードが頼るプロパティはすべてチェックし、型ガードは小さく、テストされた状態で、表す型の近くに置きましょう。

オブジェクトがある型かどうかをチェックする

自作の型ガードの多くはこの疑問から生まれます。データが unknown として（JSON.parse、fetch、localStorage、メッセージから）届き、それがインターフェースに一致するかを知る必要がある場合です。手順は次のとおりです:

1. typeof value === "object" && value !== null（null ではないオブジェクト）。
2. 必須プロパティごとに "prop" in value。unknown に対して in を使うと、そのプロパティが unknown 型として型に追加されます。
3. 各プロパティの型について typeof value.prop === "..."（またはネストした型ガード）。
4. 配列には Array.isArray(value.items) && value.items.every(isItem)。

interface Order {
  id: string;
  lines: { sku: string; qty: number }[];
}

function isLine(v: unknown): v is Order["lines"][number] {
  return typeof v === "object" && v !== null &&
    "sku" in v && typeof v.sku === "string" &&
    "qty" in v && typeof v.qty === "number" && Number.isInteger(v.qty);
}

function isOrder(v: unknown): v is Order {
  return typeof v === "object" && v !== null &&
    "id" in v && typeof v.id === "string" &&
    "lines" in v && Array.isArray(v.lines) && v.lines.every(isLine);
}

const good: unknown = JSON.parse('{"id":"A1","lines":[{"sku":"pen","qty":2}]}');
const bad: unknown = JSON.parse('{"id":"A2","lines":[{"sku":"pen","qty":"2"}]}');

console.log(isOrder(good), isOrder(bad)); // true false
if (isOrder(good)) console.log(good.lines[0].qty * 3); // 6

大きな形や深くネストした形では、手書きは面倒になります。Zod や Valibot のようなスキーマライブラリを使えば、形を一度記述するだけで、実行時のチェックとTypeScriptの型の両方が得られます。

アサーション関数: asserts value is Type

アサーション関数は、チェックに失敗すると例外を投げ、成功すれば普通に戻ります。戻り値の型は asserts value is Type（または asserts condition）で、呼び出しのあとのすべてが if なしで絞り込まれます。

function assertIsString(value: unknown, name: string): asserts value is string {
  if (typeof value !== "string") {
    throw new TypeError(`${name} must be a string, got ${typeof value}`);
  }
}

function assert(condition: unknown, message: string): asserts condition {
  if (!condition) throw new Error(message);
}

function greet(input: unknown, count: number | null): string {
  assertIsString(input, "input");
  assert(count !== null, "count is required");
  // input: string, count: number
  return input.toUpperCase().repeat(count);
}

console.log(greet("hi", 2)); // HIHI

try {
  greet(42, 1);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // input must be a string, got number
}

つまずきやすいルールが1つあります。アサーション関数は、明示的な型を持つ名前を通して呼び出す必要があります。型注釈のない const のアロー関数 const check = (v: unknown): asserts v is string => {...} は、呼び出し箇所でエラー TS2775 Assertions require every name in the call target to be declared with an explicit type annotation. になります。function 宣言を使うか、定数に関数型の注釈を付けましょう。

型ガード、アサーション関数、キャストの比較

型アサーション（as）は何もチェックせずに型を変えます。外部からデータが入ってくる境界では、型ガードやアサーション関数が同じ考え方の安全な版です。

クラスでの this を使った型ガード

メソッドは this is Type で、呼び出し元のオブジェクトを絞り込めます。クラスの階層で便利です:

class FileNode {
  constructor(public name: string) {}
  isDirectory(): this is DirectoryNode {
    return this instanceof DirectoryNode;
  }
}

class DirectoryNode extends FileNode {
  children: FileNode[] = [];
}

function count(node: FileNode): number {
  return node.isDirectory() ? node.children.length : 0; // node: DirectoryNode in the true branch
}