TypeScriptのsatisfies演算子: 型注釈・asとの違い

value satisfies Type は、value が Type に合っているかをコンパイル時にチェックし、値自身のより正確な型はそのままにします。型注釈ならその正確な型を Type に置き換えてしまいますが、satisfies は型を広げずに検証します。

type ColorName = "red" | "green" | "blue";
type Color = string | [number, number, number];

const palette = {
  red: [255, 0, 0],
  green: "#00ff00",
  blue: [0, 0, 255],
} satisfies Record<ColorName, Color>;

// Checked against the Record, yet every property keeps its own type:
console.log(palette.green.toUpperCase());      // #00FF00 (green: string)
console.log(palette.red.map((c) => c / 255));  // [ 1, 0, 0 ] (red: [number, number, number])

チェックはきちんと行われます。色が足りない、bleu のようにキーを打ち間違える、true のような値を書くと、その行でコンパイルエラーになります。TypeScript 4.9 から使え、ほかの型注釈と同じように出力されるJavaScriptからは取り除かれます。

satisfies が解決する問題

型注釈を付けると、変数の型は注釈の型そのものになります。コンパイラーはリテラルで見たものを忘れてしまいます。次の例では同じパレットに型注釈を付けていて、TypeScriptは green が文字列であることをもう知りません:

// This does not compile: the annotation widens every property to Color.
type ColorName = "red" | "green" | "blue";
type Color = string | [number, number, number];

const palette: Record<ColorName, Color> = {
  red: [255, 0, 0],
  green: "#00ff00",
  blue: [0, 0, 255],
};

console.log(palette.green.toUpperCase());

コンパイラーは次のエラーを報告します:

index.ts(11,27): error TS2339: Property 'toUpperCase' does not exist on type 'Color'.
  Property 'toUpperCase' does not exist on type '[number, number, number]'.

TypeScript 4.9 より前の選択肢は、型注釈を付けてあちこちで手作業で絞り込む（typeof palette.green === "string"）か、注釈をやめてチェックを失うかのどちらかでした。satisfies なら両方が手に入ります。: Record<ColorName, Color> を、閉じかっこのあとの satisfies Record<ColorName, Color> に変えれば実行できます。

satisfies、型注釈、as の比較

同じ設定オブジェクトを3通りに書いてみます:

type Settings = {
  theme: "light" | "dark";
  fontSize: number;
  lang: string;
};

const annotated: Settings = { theme: "dark", fontSize: 14, lang: "en" };
const asserted = { theme: "dark", fontSize: 14 } as Settings; // lang is missing!
const satisfied = { theme: "dark", fontSize: 14, lang: "en" } satisfies Settings;

// annotated.theme: "light" | "dark"   (the annotation's type)
// satisfied.theme: "dark"             (what was actually written)
const isDark: "dark" = satisfied.theme; // fine; annotated.theme would be rejected

console.log(annotated.lang, asserted.lang, satisfied.lang); // en undefined en
console.log(isDark);                                         // dark

as は足りない lang を通してしまい、asserted.lang は型が string なのに実行時には undefined です。ほかの2行から lang を消すと、どちらも TS2741 Property 'lang' is missing in type ... で失敗します。

目安として、変数に宣言した型を持たせたいとき（再代入する値、公開API）は型注釈を使い、チェックはしたいが値自身の型のほうが役に立つときは satisfies を使います。

オブジェクトリテラルの間違いを捕まえる

satisfies は余分なプロパティのチェックを含む代入可能性のチェックを完全に行うので、キーの打ち間違いはエラーになります:

type Route = { path: string; method: "GET" | "POST" };

const home = { path: "/", metod: "GET" } satisfies Route;
// error TS2561: Object literal may only specify known properties, but 'metod' does not exist in type 'Route'. Did you mean to write 'method'?

このチェックは、型注釈と同じようにリテラルに文脈上の型も与えます。これには2つの意味があります。対象の型がリテラル型を期待していれば、文字列リテラルはリテラル型のまま保たれます。{ path: "/", method: "GET" } satisfies Route は method: "GET" を持ちますが、同じオブジェクトを型注釈なしで書くと method: string と推論されます。そして、コールバックの引数の型が対象の型から推論されます:

type Handlers = {
  onSave: (doc: { id: number; title: string }) => string;
  onDelete: (id: number) => boolean;
};

const handlers = {
  onSave: (doc) => `saved #${doc.id}: ${doc.title}`, // doc is typed from Handlers
  onDelete: (id) => id > 0,
} satisfies Handlers;

console.log(handlers.onSave({ id: 7, title: "Notes" })); // saved #7: Notes
console.log(handlers.onDelete(-1));                      // false

Record のキーがわかったままになる

よくある使い方はルックアップテーブルです。Record<string, T> と型注釈を付けると、どんな文字列も正しいキーになり、打ち間違いもコンパイルできて、実行時に undefined が返ります。satisfies なら値は T と照らし合わせてチェックされつつ、変数の型には書いたキーだけが並びます:

type Endpoint = { url: string; timeoutMs: number };

const loose: Record<string, Endpoint> = {
  users: { url: "/api/users", timeoutMs: 3000 },
};

const endpoints = {
  users: { url: "/api/users", timeoutMs: 3000 },
  orders: { url: "/api/orders", timeoutMs: 8000 },
} satisfies Record<string, Endpoint>;

console.log(loose.userz?.url); // undefined: the typo compiles
console.log(endpoints.orders.timeoutMs); // 8000

type EndpointName = keyof typeof endpoints; // "users" | "orders"
const endpointName: EndpointName = "users";
console.log(endpoints[endpointName].url); // /api/users

// @ts-expect-error: TS2551 Property 'userz' does not exist on type ... Did you mean 'users'?
endpoints.userz;

keyof typeof endpoints が役に立つのは、キーが残っているからです。型注釈ならただの string になります。

決まったキーの集合を必須にするには、ユニオン型をキーにした Record を満たすようにします。satisfies Record<"dev" | "prod", string> なら、足りない prod は TS2741 で、知らない staging は TS2353 で報告されます。

as const satisfies

as const と satisfies は組み合わせられます。as const を先に書きます。値を奥まで readonly のリテラル型にし、そのあと satisfies がその正確な値をチェックします。

type Route = { path: string; method: "GET" | "POST"; auth: boolean };

const routes = [
  { path: "/", method: "GET", auth: false },
  { path: "/login", method: "POST", auth: false },
  { path: "/account", method: "GET", auth: true },
] as const satisfies readonly Route[];

type Path = (typeof routes)[number]["path"]; // "/" | "/login" | "/account"

function link(path: Path): string {
  return `<a href="${path}">`;
}

console.log(link("/account"));                           // <a href="/account">
console.log(routes.filter((r) => r.auth).map((r) => r.path)); // [ '/account' ]

各ルートは Route と照らし合わせてチェックされ（method: "PUT" ならエラー）、リテラル型のタプルはそのまま使えるので、Path は実際のパスのユニオン型になります。as const の配列は readonly なので、対象の型には readonly Route[]（または ReadonlyArray<Route>）を使います。

設定オブジェクト

satisfies がいちばん力を発揮するのは設定です。形は正しくなければならず、ほかの場所のコードは正確な値を必要とします。

type Env = "development" | "production";

type AppConfig = {
  port: number;
  logLevel: "debug" | "info" | "warn";
  features: Record<string, boolean>;
};

const configs = {
  development: { port: 3000, logLevel: "debug", features: { newCheckout: true } },
  production: { port: 8080, logLevel: "warn", features: { newCheckout: false } },
} satisfies Record<Env, AppConfig>;

function start(env: Env): string {
  const c = configs[env];
  return `${env}: port ${c.port}, log ${c.logLevel}, newCheckout=${c.features.newCheckout}`;
}

console.log(start("development")); // development: port 3000, log debug, newCheckout=true
console.log(start("production"));  // production: port 8080, log warn, newCheckout=false

production のエントリーを忘れる、logLevel を打ち間違える、logLevel: "verbose" と書く、といった間違いはコンパイラーが正確な行を指摘します。同じパターンは *.config.ts ファイルにも向いています。export default { ... } satisfies SomeConfig と書けばファイル全体がチェックされ、export したオブジェクトはリテラルの値を保ちます。

satisfies を使わないほうがよい場面

• 変数を再代入する。 let cfg = { port: 3000 } satisfies { port: number | string } とすると cfg の型は { port: number } になるので、あとの cfg = { port: "80" } は失敗します（TS2322）。変更するつもりの変数には型注釈を付けましょう。
• あえて宣言した型にしたい。 関数の戻り値や、APIの一部である export した定数では、型注釈の型が約束です。正確なリテラル型が外に漏れると、あとの変更が破壊的変更になりかねません。
• 値がリテラルではない。 satisfies が役立つのはオブジェクトリテラルと配列リテラルです。変数や呼び出しの結果に使っても普通の代入可能性のチェックになるだけで、それなら型注釈で十分です。