TypeScript 開発ルール

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ならクラス検討

  // 関数とinterface
  interface UserService { create(data: UserData): User }
  const userService: UserService = { create: (data) => {...} }
  

関数設計

• 引数は0-2個まで: 3個以上はオブジェクト化

  // オブジェクト引数
  function createUser({ name, email, role }: CreateUserParams) {}