typescript-rules

# TypeScript 開発ルール ## 前提条件の検出 プロジェクト規約を適用する前に、`tsconfig`、ランタイム・フレームワーク設定、lint・format設定、パスエイリアス、package scripts、代表的なモジュールを確認する。設定または確立済みのパターンに裏付けられたルールだけをプロジェクト固有として扱う。限られたパターンから導いた結論には推測であることを明記する。競合する規約によって公開契約、ランタイムの振る舞い、エラー境界が変わる場合は作業を止め、必要な情報源またはユーザー判断を具体的に示す。 ## Backend実装における型安全性 **データフローでの型安全性** 入力層（`unknown`） → 型ガード → ビジネス層（型保証） → 出力層（シリアライズ） **Backend固有の型シナリオ**: - **API通信**: レスポンスは`unknown`で受け、型ガードで検証 - **フォーム入力**: 外部入力は`unknown`、バリデーション後に型確定 - **レガシー統合**: レガシーとの境界では`unknown`として受け取り、根拠のある型アサーションが必要な場合は、その境界を所有するアダプター内に限定する - **テストコード**: 設定済みのテストハーネスでモックの入出力型を定義する。意図的に一部だけを持つfixtureには`Partial<T>`を使用し、Vitestが設定されている場合にのみ型付きの`vi.fn<[Args], Return>()`を使用する ## コーディング規約 **クラス使用の判断基準** - **推奨：関数とinterfaceでの実装** - 背景: テスタビリティと関数合成の柔軟性が向上 - **クラス使用を許可**: - フレームワーク要求時（NestJSのController/Service、TypeORMのEntity等） - カスタムエラークラス定義時 - 状態とビジネスロジックが密結合している場合（例: ShoppingCart、Session、StateMachine） - **判断基準**: 「このデータは振る舞いを持つか？」がYesならクラス検討 ```typescript // 関数とinterface interface UserService { create(data: UserData): User } const userService: UserService = { create: (data) => {...} } ``` **関数設計** - **引数は0-2個まで**: 3個以上はオブジェクト化 ```typescript // オブジェクト引数 function createUser({ name, email, role }: CreateUserParams) {} ``` **依存性注入** - **外部依存は引数で注入**: テスト可能性とモジュール性確保 ```typescript // 依存性を引数で受け取る function createService(repository: Repository) { return {...} } ``` **非同期処理** - Promise処理: リポジトリで確立済みのスタイルに従う。処理順序とエラー伝播を明確にできる場合は`async/await`を使用する - エラーハンドリング: 現在の層で失敗の変換、情報付加、復旧、記録ができる場合に`try-catch`を追加する。それ以外は、所有する境界までPromiseのrejectionを伝播させる - 型定義: 戻り値の型は明示的に定義（例: `Promise<Result>`） **フォーマット規則** - セミコロンの扱いを含め、リポジトリで設定されたformatterに従う - 型は`PascalCase`、変数・関数は`camelCase` - 絶対importは`tsconfig`または設定済みのビルドツールで宣言されたaliasを通じて使用する。それ以外は相対importを使用する **クリーンコード原則** - 今回の変更範囲にある未使用コードを削除する - デバッグ用`console.log()`は削除 - 実行可能なソースにはコメントアウトしたコードを残さない。削除した実装の履歴はバージョン管理で保持する - コメントは「なぜ」を説明（「何」ではなく） ## エラーハンドリング **エラー結果のルール**: すべての失敗に対して、型付きの想定内エラーを返す、明記された要件に従って復旧する、診断情報を付加して伝播する、のいずれか1つを選ぶ。同じ失敗を重複して記録しないよう、ログ出力を担う境界で記録する。 **Fail-Fast原則**: エラー時は速やかに失敗させ、不正な状態での処理継続を防ぐ ```typescript // 無効: 呼び出し元が必要とする失敗をフォールバックで隠している catch (error) { return defaultValue // エラーを隠蔽 } // 情報を付加して明示的に伝播する catch (error) { throw new Error('処理失敗', { cause: error }) } ``` **Result型パターン**: エラーを型で表現し、明示的に処理 ```typescript type Result<T, E> = { ok: true; value: T } | { ok: false; error: E } // 使用例：エラーの可能性を型で表現 function parseUser(data: unknown): Result<User, ValidationError> { if (!isValid(data)) return { ok: false, error: new ValidationError() } return { ok: true, value: data as User } } ``` **カスタムエラークラス** ```typescript export class AppError extends Error { constructor(message: string, public readonly code: string, public readonly statusCode = 500) { super(message) this.name = this.constructor.name } } // 用途別: ValidationError(400), BusinessRuleError(400), DatabaseError(500), ExternalServiceError(502) ``` **層別エラー処理** - API層: HTTPレスポンスに変換、機密情報を除外してログ出力 - サービス層: ビジネスルール違反を検出、AppErrorはそのまま伝播 - リポジトリ層: 技術的エラーをドメインエラーに変換 **構造化ログと機密情報保護** 現在の信頼境界で許可されたフィールドだけをログに含める。認証情報、トークン、シークレット、決済情報、個人データはログ出力前に除去する。 **非同期エラーハンドリング** - ランタイムが`unhandledRejection`や`uncaughtException`を公開する場合は、アプリケーションのentry pointでランタイムレベルのhandlerを設定する。ライブラリではプロセスレベルの方針をhostに委ねる - 非同期の失敗は、型付きの結果、復旧、診断情報のいずれかを付加できる層でcatchする - その層での復旧を要件が明記している場合を除き、情報を付加した失敗は伝播させる ## パフォーマンス最適化 - ストリーミング処理: 計測した入力サイズが利用可能なメモリ予算を超える場合、または要件で逐次出力が必要な場合は、ストリーミングまたは上限付きbatchを使用し、判断の根拠となった計測値または制約を記録する - リソースのライフタイム: timer、subscription、handle、保持している参照は、そのライフサイクルを所有する境界で解放する