typescript-refactor

TypeScript リファクタリングのベストプラクティス

TypeScript のリファクタリングとモダナイゼーションに関する 8 カテゴリ、43 のルールを、影響度の高い順にまとめています。自動リファクタリング、コードレビュー、コード生成の指針としてご活用ください。

適用する場面

• 型安全性と保守性を高めるために TypeScript コードをリファクタリングする場合
• 型アーキテクチャ（判別可能なユニオン、ブランド型、ジェネリクス）を設計する場合
• 型を絞り込んで安全でない as キャストをなくす場合
• 最新の TypeScript 4.x-5.x の機能（satisfies、using、const 型パラメーター）を導入する場合
• 大規模なコードベースでコンパイラーのパフォーマンスを最適化する場合
• 型安全なエラー処理パターンを実装する場合
• TypeScript 特有の挙動や落とし穴を考慮してコードをレビューする場合

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	型アーキテクチャ	CRITICAL	arch-
2	型の絞り込みとガード	CRITICAL	narrow-
3	最新の TypeScript	HIGH	modern-
4	ジェネリックパターン	HIGH	generic-
5	コンパイラーのパフォーマンス	MEDIUM-HIGH	compile-
6	エラー安全性	MEDIUM	error-
7	実行時パターン	MEDIUM	perf-
8	特有の挙動と落とし穴	LOW-MEDIUM	quirk-

クイックリファレンス

1. 型アーキテクチャ（CRITICAL）

• arch-discriminated-unions — 網羅的なパターンマッチングには、文字列列挙型ではなく判別可能なユニオンを使用します
• arch-branded-types — 値の取り違えを防ぐため、ドメイン識別子にはブランド型を使用します
• arch-satisfies-over-annotation — リテラル型を保持するため、設定オブジェクトには satisfies を使用します
• arch-interfaces-over-intersections — エラーメッセージを改善するため、型を交差させるのではなくインターフェースを拡張します
• arch-const-assertion — 不変のリテラル型を推論するために as const を使用します
• arch-readonly-by-default — 関数の引数と戻り値には、デフォルトで読み取り専用の型を使用します
• arch-avoid-partial-abuse — ビルダーパターンで Partial<T> を乱用しないようにします

2. 型の絞り込みとガード（CRITICAL）

• narrow-custom-type-guards — 型アサーションの代わりにカスタム型ガードを記述します
• narrow-assertion-functions — 前提条件のチェックにはアサーション関数を使用します
• narrow-exhaustive-switch — never を使って switch 文の網羅性を保証します
• narrow-in-operator — インターフェースのユニオン型を絞り込むには in 演算子を使用します
• narrow-eliminate-as-casts — 適切な絞り込みの連鎖によって as キャストをなくします
• narrow-typeof-chains — プロパティにアクセスする前に typeof で型を絞り込みます

3. 最新の TypeScript（HIGH）

• modern-using-keyword — リソースのクリーンアップには using キーワードを使用します
• modern-const-type-parameters — リテラル型を推論するために const 型パラメーターを使用します
• modern-template-literal-types — 文字列パターンにはテンプレートリテラル型を使用します
• modern-noinfer-utility — 型パラメーターの推論を制御するには NoInfer を使用します
• modern-accessor-keyword — 自動生成されるゲッターとセッターには accessor を使用します
• modern-verbatim-module-syntax — インポートする型を明示するには verbatimModuleSyntax を有効にします

4. ジェネリックの一般的なパターン（HIGH）

• generic-infer-over-annotate — 明示的な型注釈ではなく、TypeScript の型推論を活用します
• generic-constrain-dont-overconstrain — ジェネリック型には必要最小限の制約を指定します
• generic-avoid-distributive-surprises — 分配条件型を制御します
• generic-mapped-type-utilities — 繰り返し行う変換用にカスタムのマップ型を作成します
• generic-return-type-inference — ジェネリック関数の戻り値の型推論を維持します

5. コンパイラーのパフォーマンス（MEDIUM-HIGH）

• compile-explicit-return-types — エクスポートする関数に明示的な戻り値の型を追加します
• compile-avoid-deep-recursion — 深く再帰する型定義を避けます
• compile-project-references — モノレポのビルドにはプロジェクト参照を使用します
• compile-base-types-over-unions — 大きなユニオン型ではなく、基底型を使用します

6. エラー安全性（MEDIUM）

• error-result-type — スローされる例外ではなく、Result 型を使用します
• error-exhaustive-error-handling — 型付きエラーのバリアントには網羅的なチェックを使用します
• error-typed-catch — catch 節の変数を unknown として型付けします
• error-never-for-unreachable — 到達不能なコードパスを示すために never を使用します
• error-discriminated-error-unions — ドメインエラーを判別可能なユニオンとしてモデル化します

7. ランタイムのパターン（MEDIUM）

• perf-union-literals-over-enums — enum ではなく、ユニオンリテラルを使用します
• perf-avoid-delete-operator — オブジェクトに対する delete 演算子の使用を避けます
• perf-object-freeze-const — 真の不変性を実現するため、as const と Object.freeze を併用します
• perf-object-keys-narrowing — Object.keys による型の拡大を避けます
• perf-map-set-over-object — 動的なコレクションにはプレーンオブジェクトではなく、Map と Set を使用します

8. 特有の挙動と落とし穴（LOW-MEDIUM）

• quirk-excess-property-checks — オブジェクトリテラルに対する余分なプロパティチェックについて理解します
• quirk-empty-object-type — {} 型は nullish でない値を意味するため、使用を避けます
• quirk-type-widening-let — let 宣言による型の拡大を防ぎます
• quirk-variance-annotations — ジェネリックインターフェースには変性注釈を使用します
• quirk-structural-typing-escapes — 構造的部分型付けの抜け道に対するガードを設けます

使用方法

詳しい説明とコード例については、個々のリファレンスファイルを参照してください。

• セクションの定義 — カテゴリー構成と影響度
• ルールのテンプレート — 新しいルールを追加するためのテンプレート

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート