typescript

TypeScript のベストプラクティス

コンパイラー設定、型システムのパフォーマンス、非同期コード、モジュール、安全性、測定に基づくランタイム最適化を網羅した、8 カテゴリーにわたる 44 のルールを紹介する、TypeScript 7 対応の包括的なガイドです。

適用するタイミング

次の場合に、これらのガイドラインを参照してください。

• 新規または既存のプロジェクトで tsconfig.json を設定するとき
• 複雑な型定義やジェネリクスを記述するとき
• async/await パターンやデータ取得を最適化するとき
• モジュールを整理し、インポートを管理するとき
• コンパイルやランタイムのパフォーマンスについてコードをレビューするとき

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

優先度	カテゴリー	影響度	プレフィックス
1	型システムのパフォーマンス	CRITICAL	type-
2	コンパイラー設定	CRITICAL	tscfg-
3	非同期パターン	HIGH	async-
4	モジュール構成	HIGH	module-
5	型安全性のパターン	MEDIUM-HIGH	safety-
6	メモリー管理	MEDIUM	mem-
7	ランタイム最適化	LOW-MEDIUM	runtime-
8	高度なパターン	LOW	advanced-

目次

1. 型システムのパフォーマンス — CRITICAL
   • 1.1 エクスポートされた関数に明示的な戻り値の型を追加する — CRITICAL（宣言ファイルの出力を高速化）
   • 1.2 深くネストしたジェネリック型を避ける — CRITICAL（インスタンス化コストの指数的な増大を防止）
   • 1.3 大きなユニオン型を避ける — CRITICAL（比較コストが二次関数的に O(n²) で増加するのを防止）
   • 1.4 条件型を名前付きエイリアスに切り出す — CRITICAL（コンパイラーのキャッシュを有効にし、再評価を防止）
   • 1.5 型の再帰深度を制限する — CRITICAL（型の指数的な展開を防止）
   • 1.6 型の交差よりインターフェースを優先する — CRITICAL（型解決を高速化）
   • 1.7 複雑なマップ型を簡素化する — CRITICAL（型の計算量を削減）
2. コンパイラー設定 — CRITICAL
   • 2.1 include と exclude を適切に設定する — CRITICAL（不要なファイルを何千件もスキャンするのを防止）
   • 2.2 インクリメンタルコンパイルを有効にする — CRITICAL（再ビルドを高速化）
   • 2.3 skipLibCheck を意図的に選択する — CRITICAL（コンパイルを高速化）
   • 2.4 型の安全な関数割り当てのために strictFunctionTypes を有効にする — CRITICAL（最適化された変性チェックを有効化）
   • 2.5 単一ファイルのトランスパイラーで isolatedModules を使用する — CRITICAL（バンドラーを使ったトランスパイルを高速化）
   • 2.6 大規模なコードベースでプロジェクト参照を使用する — CRITICAL（インクリメンタルビルドを高速化）
   • 2.7 TypeScript 7 の設定へ意図的に移行する — CRITICAL
3. 非同期パターン — HIGH
   • 3.1 非同期関数の戻り値の型を注釈する — HIGH（実行時エラーを防止し、型推論を改善）
   • 3.2 ループ内で await を使わない — HIGH（反復回数に比例してスケール）
   • 3.3 不要な async/await を避ける — HIGH（マイクロタスクキューのオーバーヘッドを排除）
   • 3.4 値が必要になるまで await を遅らせる — HIGH（暗黙的な並列化を可能にする）
   • 3.5 独立した処理には Promise.all を使用する — HIGH（I/O 待ちが発生するコードの性能を改善）
4. モジュール構成 — HIGH
   • 4.1 バレルファイルからのインポートを避ける — HIGH（インポートのコストとバンドルサイズの増大を抑制）
   • 4.2 循環依存を避ける — HIGH（実行時の未定義エラーとコンパイルの遅延を防止）
   • 4.3 @types パッケージの読み込みを制御する — HIGH（型の競合を防ぎ、メモリ使用量を削減）
   • 4.4 大きなモジュールには動的インポートを使用する — HIGH（初期バンドルを縮小）
   • 4.5 型には型専用インポートを使用する — HIGH（型情報のための実行時インポートを排除）
5. 型安全性のパターン — MEDIUM-HIGH
   • 5.1 strictNullChecks を有効にする — MEDIUM-HIGH
   • 5.2 any より unknown を優先する — MEDIUM-HIGH
   • 5.3 検証にはアサーション関数を使用する — MEDIUM-HIGH
   • 5.4 リテラル型には const アサーションを使用する — MEDIUM-HIGH
   • 5.5 ユニオン型には網羅性チェックを使用する — MEDIUM-HIGH
   • 5.6 実行時の型チェックには型ガードを使用する — MEDIUM-HIGH
6. メモリ管理 — MEDIUM
   • 6.1 クロージャによるメモリリークを避ける — MEDIUM（長時間存続するコールバック内で参照が保持されるのを防止）
   • 6.2 グローバル状態の蓄積を避ける — MEDIUM（メモリが無制限に増加するのを防止）
   • 6.3 イベントリスナーをクリーンアップする — MEDIUM（メモリが無制限に増加するのを防止）
   • 6.4 タイマーとインターバルをクリアする — MEDIUM（コールバックの保持と繰り返し実行を防止）
   • 6.5 オブジェクトのメタデータには WeakMap を使用する — MEDIUM（メモリリークを防ぎ、自動クリーンアップを可能にする）
7. 実行時の最適化 — LOW-MEDIUM
   • 7.1 ホットループ内でオブジェクトスプレッドを避ける — LOW-MEDIUM
   • 7.2 計測で特定したホットパスでは、ループ不変の処理をループの外に移動する — LOW-MEDIUM
   • 7.3 Lodash よりネイティブの配列メソッドを優先する — LOW-MEDIUM
   • 7.4 単純な反復には for-of を使用する — LOW-MEDIUM
   • 7.5 最新の文字列メソッドを使用する — LOW-MEDIUM
   • 7.6 O(1) の検索には Set/Map を使用する — LOW-MEDIUM
8. 高度なパターン — LOW
   • 8.1 型安全な ID にはブランド型を使用する — LOW（互換性のない ID 型の混同を防止）
   • 8.2 型推論を維持した型検証には satisfies を使用する — LOW（プロパティアクセスエラーを防ぎ、信頼性の高い自動補完を可能にする）
   • 8.3 文字列パターンにはテンプレートリテラル型を使用する — LOW（コンパイル時に文字列形式のエラーを防止）

使用方法

まずプロジェクトのルートで実行します：

npx -y @pymodel/react-frontend-skills detect                   # installed vs. targeted versions
npx -y @pymodel/react-frontend-skills scan --skill typescript  # deprecated APIs → rule IDs

タスクに該当する上記の各ルールと、scan の各検出結果について、references/<rule-id>.md を読み、重要な理由と誤ったコードと正しいコードを確認します。

参考資料

1. https://github.com/microsoft/TypeScript/wiki/Performance
2. https://www.typescriptlang.org/docs/handbook/
3. https://v8.dev/blog
4. https://nodejs.org/en/learn/diagnostics/memory