typescript-patterns

TypeScript のパターン

概要

型システムを使って実行時エラーを防ぐ、高度な TypeScript のパターンです。型推論、型の絞り込み、コンパイル時の検証を行う、strict モードの TypeScript に焦点を当てています。初心者向けのチュートリアルではありません。

使用する場面： 型安全な API の構築、複雑なデータ変換、ライブラリの作成、型による実行時エラーの防止、strict モードのフラグを使う場合。

使用しない場面： TypeScript の基本（プリミティブ型、インターフェース、クラス）の学習、JavaScript から TypeScript への移行ガイド、ツールのセットアップ、ビルド設定。

クイックリファレンス

パターン	API	主なポイント
ユーティリティ型	Pick<T, K>, Omit<T, K>	プロパティを抽出または除外します
Partial／Required	Partial<T>, Required<T>	プロパティを任意または必須にします
Record 型	Record<K, V>	キーが既知のオブジェクト
Awaited 型	Awaited<T>	Promise の戻り値の型を展開します
ReturnType／Parameters	ReturnType<F>, Parameters<F>	関数の型を抽出します
ジェネリック制約	<T extends Type>	ジェネリックパラメーターを制約します
型推論	type Inferred = typeof value	値から TypeScript に推論させます
型ガード	typeof, instanceof, in	実行時に型を絞り込みます
カスタム型ガード	(x): x is Type	ユーザー定義の型絞り込み関数
推論される型述語	(x) => x !== null	型述語を自動推論するフィルター
判別可能なユニオン	リテラル型の type プロパティを持つユニオン	網羅的なパターンマッチング
条件型	T extends U ? X : Y	型レベルの条件分岐
マップ型	{ [K in keyof T]: T[K] }	すべてのプロパティを変換します
テンプレートリテラル	`${A}-${B}`	文字列リテラル型を操作します
const アサーション	as const	最も狭いリテラル型
satisfies 演算子	value satisfies Type	型を拡大せずに型チェックします
NoInfer ユーティリティ	NoInfer<T>	ある位置からの推論を防ぎます
const 型パラメーター	<const T extends Type>	as const を使わずに推論を狭めます
インライン型インポート	import { type User }	型を明示的にインポートします
モジュール拡張	declare module 'lib' { ... }	サードパーティの型を拡張します
アサーション関数	function assert(x): asserts x is T	型ガードに失敗した場合に例外をスローします

よくある間違い

間違い	正しいパターン
正当な理由なく any を使う	unknown を使い、型ガードで絞り込みます
あちこちで手動の型アサーションを行う	型推論に任せ、関数の戻り値に型を指定します
型の絞り込み前に分割代入する	判別可能なユニオンではオブジェクトをそのまま使います
undefined を確認せずにインデックスアクセスする	noUncheckedIndexedAccess を有効にします
安全でない値を as Type でキャストする	絞り込まれた型を維持するために satisfies Type を使います
ジェネリクス内にオブジェクトをインラインで記述する	const または型エイリアスに切り出します
制約で extends を省略する	可能な場合は常にジェネリクスに制約を設定します
Parameters<typeof fn>[0] を使う	関数のパラメーターに直接型を指定します
ユニオンの網羅性を処理しない	switch／if-else で never チェックを使います
value as const satisfies Type を使う	satisfies Type を使い、必要であればその後に as const を使います

委任

• パターンの調査：Explore エージェントを使って、コードベース内の既存パターンを見つけます
• 型エラーのデバッグ：複数ステップにわたる型の解決には Task エージェントを使います
• コードレビュー：型安全性の監査を code-reviewer スキルに委任します

参考資料

• 型ユーティリティ（Pick、Omit、Partial、Required、Record、Extract、Exclude、ReturnType、Parameters、Awaited）
• ジェネリクス（制約、推論、デフォルトパラメーター、分散性）
• 型ガードと絞り込み（typeof、instanceof、in、カスタムガード、アサーション関数）
• 判別可能なユニオン（網羅的チェック、never 型、タグ付きユニオン）
• 条件型（分配条件型、infer キーワード、型レベルのロジック）
• マップ型（キーの再マッピング、テンプレートリテラル、修飾子）
• 厳格モードのパターン（noUncheckedIndexedAccess、exactOptionalPropertyTypes、const アサーション、satisfies）
• モジュールのパターン（インラインの型インポート、宣言ファイル、モジュール拡張、アンビエント型）
• モダンなイディオム（eslint-plugin-unicorn のパターン、モダンな配列／文字列／DOM API、ES モジュール）