できない.dev

TypeScript の satisfies 演算子で型が広がる・narrowing が効かない

satisfies は値が型に適合することを検査しつつ値の具体的な型は保持する演算子。
as と違って型を広げないため narrowing も保たれるが、変数の型注釈や const アサーションと併用する位置を誤ると効果が消える。

公開: 更新:

症状できない · exit 2
npx tsc
src/bad.ts(11,15): error TS2339: Property 'toUpperCase' does not exist on type 'Color | [number, number, number]'.
  Property 'toUpperCase' does not exist on type '[number, number, number]'.
src/bad.ts(13,16): error TS2339: Property 'toFixed' does not exist on type 'string | number'.
  Property 'toFixed' does not exist on type 'string'.
解決後できた · exit 0
npx tsc

2026-10-28 に node:20(TypeScript 5.9.3 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細

要約

satisfies 演算子は 「この値はこの型に適合するか」を検査しつつ、値の具体的な型はそのまま保持 する。
as のように型を強制的に広げないため narrowing が効くが、変数に型注釈を付けると宣言型側が優先されて狭い型情報が失われる。
修正するときは、変数の型注釈を外し、値の式末尾に satisfies を置く。

実行例

node:20 環境で上記の手順を動かすと、型注釈を残したままの bad.ts では、toUpperCase と toFixed の呼び出しの両方に TS2339 エラーが出た(tsc 終了コード 2)。
型注釈を外して satisfies に一本化した修正版は終了コード 0 で通り、narrowing が保たれた。

$ npx tsc --version
Version 5.9.3
$ npx tsc
src/bad.ts(11,15): error TS2339: Property 'toUpperCase' does not exist on type 'Color | [number, number, number]'.
  Property 'toUpperCase' does not exist on type '[number, number, number]'.
src/bad.ts(13,16): error TS2339: Property 'toFixed' does not exist on type 'string | number'.
  Property 'toFixed' does not exist on type 'string'.
$ echo $?
2
$ npx tsc
$ echo $?
0

— 2026-10-28 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-10-28 検証(ほか 2 件)
検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5
  • TypeScript 5.9.3

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. 型注釈を外し satisfies に一本化

type Color = "red" | "green" | "blue";
type Palette = Record<string, Color | [number, number, number]>;
 
const palette = {
  red: [255, 0, 0],
  green: "green",
  blue: [0, 0, 255],
} satisfies Palette;
 
palette.green.toUpperCase();
palette.red[0].toFixed();

palette.green は "green" リテラルとして narrowing され、palette.red は [number, number, number] のタプルのままになる。

2. as const と組み合わせるなら順序に注意

const routes = {
  home: "/",
  login: "/login",
} as const satisfies Record<string, `/${string}`>;

as const で全プロパティをリテラル化したうえで、satisfies でテンプレートリテラル型のキー仕様を検査する。
順序を逆にすると型が広がる。

3. 値の具体型を再利用したい場合

const config = {
  port: 3000,
  host: "localhost",
} satisfies { port: number; host: string };
 
type Config = typeof config;

typeof config で narrowing 結果の具体型を取り出せる。
type Config = { port: number; host: string } を別に書くと narrowing が失われるので避ける。

4. バージョン確認

npx tsc --version
# 4.9 以上であること

旧バージョンを使っているプロジェクトでは package.json の typescript を 4.9 以降に上げる。

よくある原因

  1. 型注釈と二重に指定している。
    const config: Config = { ... } satisfies Config と書くと const config の型は Config(広い側)になり、リテラル narrowing が消える。
  2. as const との順序を誤っている。
    { ... } satisfies Config as const は意味が逆になるので、as const satisfies Config の順序にする。
  3. TypeScript が古い。
    satisfies は TypeScript 4.9(新しいタブで開く) で導入されたので、4.8 以前ではパースエラーになる。
  4. 検査対象の型が緩い。
    satisfies Record<string, unknown> のような広い型では、narrowing が効かない。