typescript-functions

関数

現在のタスクにおいて、TypeScript スタイルガイドの関数に関する規約を適用します。

ワークフロー

1. 利用側リポジトリの規約と設定を確認します。
2. 明示的なリポジトリの規約がある場合は、この独自の指針より優先します。
3. タスクに関連する指針のみを適用、確認、または説明します。
4. 適切な設計が状況や判断に左右される場合は、重要なトレードオフを示します。

範囲

• 自動的に強制できるチェックは、TypeScript と ESLint に任せます。
• このスキルが有効だからといって、無関係な TypeScript スタイルガイドの規約を持ち込まないでください。

関連する指針

関数の引数

相互排他的な関数の引数に関する詳しい指針については、利用可能であれば typescript-discriminated-unions を使用してください。

関数

関数に関する規約は、できる限り従ってください（基本的な関数型プログラミングの概念に由来するものもあります）。

一般

次のような関数を優先してください。

• 単一の責務を持つ。
• 引数を通じて依存関係を明示する。
• データを計算または変換する場合は値を返す。
• 実用上可能な限り、副作用を避ける。

ステートレス関数は、呼び出しの間にデータを保持しません。決定的関数は、同じ入力に対して常に同じ結果を返します。純粋関数は決定的で、観測可能な副作用もないため、理解、テスト、再利用が容易になります。

すべての関数を純粋にできるわけではありません。ネットワークリクエスト、ストレージ、ログ記録、UI の更新には副作用が必要です。こうした関数は小さく保ち、副作用を純粋なビジネスロジックから分離してください。

単一オブジェクト引数

複数の関連するパラメーターを受け取る関数では、単一のオブジェクト引数を優先してください。名前付きプロパティを使うと、呼び出し側で意図が理解しやすくなり、引数の順序に依存せずに関数の API を変更できます。

意味と順序が明確な場合や、isNumber(value) のように慣例的なシグネチャのほうが明瞭な場合（コールバックなど）は、位置引数を使ってください。

// ❌ Multiple arguments make this call difficult to understand
transformUserInput('client', false, 60, 120, null, true, 2000);

// ✅ An object makes each argument explicit
transformUserInput({
  method: 'client',
  isValidated: false,
  minLines: 60,
  maxLines: 120,
  defaultInput: null,
  shouldLog: true,
  timeout: 2000,
});

必須引数と省略可能な引数

引数の大半を必須にし、省略可能な引数は必要最小限にすることを目指してください。
関数が複雑になりすぎた場合は、より小さな関数に分割するべきです。
極端な例ですが、必須引数を5つ持つ専用の関数を10個実装するほうが、省略可能な引数を50個持つ「何でもこなす」関数を1つ実装するより望ましいです。

関数の引数が相互排他的なケースを表す場合は、判別共用体を使用してください。

戻り値の型

戻り値の型を明示することで、安全性が高まり、エラーを早期に検出でき、長期的な保守性も向上します。ただし、厳格にしすぎると開発が遅くなり、不要な冗長さが加わる可能性があります。

目安として、外側は明示し、内側は暗黙にします。たとえば、API やライブラリを構築するときは、意図しない互換性のない変更を防ぐため、すべての型を常に明示します。内部ロジックでは、TypeScript の型推論に任せることで、冗長さを増やさずに強い型安全性を確保できます。

関数の戻り値の型を明示的に定義する利点を考えてみましょう。

• 可読性が向上します：関数が返す値の型を明確に指定できるため、関数を呼び出す側がコードを理解しやすくなります。
• 誤用を防ぎます：戻り値を意図しない場合に、呼び出し側のコードが誤って未定義の値を使用しようとするのを防ぎます。
• 型エラーを早期に検出できます：特に、コードの変更によって戻り値の型が意図せず変わった場合に、開発中に潜在的な型エラーを検出しやすくなります。
• リファクタリングが簡単になります：関数の戻り値が代入される変数の型が正しいことを保証できるため、より安全かつ効率的にリファクタリングできます。
• 設計についての議論を促します：テスト駆動開発（TDD）と同様に、関数の引数と戻り値の型を明示的に定義することで、実装に先立って関数の機能やインターフェースについての議論が促されます。
• コンパイルのパフォーマンスが向上する場合があります：戻り値の型を明示すると、特に推論される型が複雑な場合に、TypeScript が行う処理を減らせることがあります。

状況に応じて、明確さと安全性が高まる場合は戻り値の型を明示してください。

<Rule prefix="モジュール境界では戻り値の型を明示する" href="https://typescript-eslint.io/rules/explicit-module-boundary-types/"

{"@typescript-eslint/explicit-module-boundary-types": "error"}