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`を使用する - エラーハンドリン...