Featured image of post TypeScriptのsatisfies演算子を使いこなす Featured image of post TypeScriptのsatisfies演算子を使いこなす
TypeScript

TypeScriptのsatisfies演算子を使いこなす

TypeScriptのsatisfies演算子を徹底解説。型安全性を維持しながらオブジェクトのリテラルタイプを柔軟に推論させる仕組みを、従来の型注釈（Type Annotation）や型アサーション（as Type）との違いを交えて解説。実践的なユースケースとともに使いこなし方を学びます。

English
  1. ホーム
  2. web
  3. TypeScriptのsatisfies演算子を使いこなす

はじめに

TypeScript 4.9で導入された satisfies 演算子 は、コードの型安全性を向上させつつ、開発中の「推論の自由度」を維持するための非常に強力な機能です。

しかし、従来の「型注釈（Type Annotation：: Type）」や「型アサーション（Type Assertion：as Type）」との違いが分かりづらく、実際のコードでどのように使い分ければよいのか迷うケースが多々あります。

本記事では、satisfies 演算子の仕組みと、なぜこれが重要なのかを、具体的なユースケースを交えて分かりやすく解説します。

1. 型注釈（:）の問題点

まず、従来の型注釈（型のアノテーション）が持つ課題をおさらいしましょう。

例えば、Webサイトのカラーパレットを定義するオブジェクトを作成するとします。一部のカラーはRGB形式の配列、一部は単純なカラーネーム（文字列）で定義したいとします。

type Color = string | [number, number, number];

// パレットの型定義
type Palette = {
  primary: Color;
  secondary: Color;
  danger: Color;
};

// 型注釈を使ってオブジェクトを作成する
const themePalette: Palette = {
  primary: "blue",
  secondary: [0, 128, 0], // 緑 (RGB)
  danger: "red"
};

ここまでは問題ありません。しかし、このオブジェクトのプロパティを呼び出して、文字列特有のメソッド（toUpperCase() など）を使おうとすると問題が発生します。

// エラー！ 'Color' 型に 'toUpperCase' は存在しません。
// プロパティ 'toUpperCase' は '[number, number, number]' 型に存在しません。
themePalette.primary.toUpperCase();

なぜエラーになるのか？

変数 themePalette に対して : Palette と明示的に型アノテーションを施したため、TypeScriptは themePalette.primary の型を「string または [number, number, number]」のユニオン型として認識します。

たとえ値として "blue"（確実に文字列）を代入していたとしても、定義された型情報によって具体的な推論が上書きされ、コンパイラは「文字列かどうか確定していない」と判断してしまいます。

これを避けるためには、これまで as const を使ったり、利用側でいちいち typeof による型ガード（Type Guard）を挟む必要がありました。

2. satisfies演算子による解決

ここで登場するのが satisfies 演算子です。 satisfies は、**「オブジェクトが指定された型を満たしている（satisfies）かチェックするが、オブジェクト自身の具体的な値の推論はそのまま維持する」**という動作をします。

satisfies を使った書き方

const themePalette = {
  primary: "blue",
  secondary: [0, 128, 0],
  danger: "red"
} satisfies Palette; // 型チェックのみを行い、具体的な型推論を維持する

この記述に変更すると、以下のメリットが得られます。

メリット1: 具体的な型推論の維持

// エラーにならない！ 
// TypeScriptは themePalette.primary が 'string' であることを知っているため
themePalette.primary.toUpperCase();

// こちらもエラーにならない！ 
// themePalette.secondary が 3つの要素の数値配列であることを知っているため
themePalette.secondary.map(v => v * 2);

メリット2: タイプミスの検知（型チェックの機能）

当然、Palette 型に定義されていないプロパティを指定したり、指定外の型を代入しようとすると、ビルド時にエラーを検知してくれます。

const badPalette = {
  primary: "blue",
  secondary: [0, 128, 0],
  danger: 12345, // エラー！数値型は Color に代入できません
  warning: "orange" // エラー！Palette型に warning は定義されていません
} satisfies Palette;

3. 実践ユースケース：レコード型（Record）とキーの保護

もう一つの強力なユースケースは、Record 型とオブジェクトのキー（Key）を組み合わせる場面です。

例えば、ユーザーの権限設定などのマッピングオブジェクトを定義する場合を考えます。

type UserRole = "admin" | "editor" | "viewer";

// 全てのロールに対して、編集権限があるかどうかのマップを定義したい
const rolePermissions = {
  admin: true,
  editor: true,
  viewer: false
} satisfies Record<UserRole, boolean>;

このコードにより、

  1. UserRole に定義されているロールの記述漏れ（例: viewer の書き忘れ）をコンパイラがチェックしてくれます。
  2. さらに、rolePermissions のプロパティにアクセスする際、キーが単なる string に広がらず、具体的な admin や editor として推論されるため、入力補完（オートコンプリート）が完璧に動作します。

まとめ：使い分けの基準

TypeScriptにおける型定義の記述は、以下の基準で使い分けるのがベストプラクティスです。

  1. 型注釈 (: Type): 関数の引数・戻り値や、意図的に型を広い定義（ユニオン型など）に固定し、それ以外のプロパティへのアクセスを制限したい場合に使用する。
  2. 型アサーション (as Type): APIレスポンスのパース時など、型システムが型を特定できないが、開発者側で型が絶対に正しいと保証できる場合に「強制的に型を上書き」する（※乱用はバグを招くため避ける）。
  3. satisfies 演算子 (satisfies Type): オブジェクトや設定マップを定義する際、構造が型定義を満たしているかを厳格に検証しつつ、オブジェクト固有のプロパティ値の推論（文字列リテラルや配列長など）を利用側へ引き継ぎたい場合に使用する。

satisfies を導入することで、無駄な型キャストや型ガードコードを減らし、安全で補完の効きやすいクリーンなTypeScriptコードを書くことができます。ぜひ試してみてください。

© 2022 - 2026 たかおの解説