# 機能設計書 32-Result型

## 概要

本ドキュメントは、F#コアライブラリにおけるResult型およびその操作関数群の機能設計を記述する。Result型は成功（Ok）と失敗（Error）の両方を型安全に表現するための判別共用体であり、例外を使わないエラーハンドリングを実現する重要な機能である。

### 本機能の処理概要

**業務上の目的・背景**：従来のエラーハンドリングでは例外を使用することが一般的であったが、例外は制御フローを複雑にし、どのような例外が発生しうるかが型シグネチャから判断できないという問題があった。Result型は「成功値（Ok 'T）」か「エラー値（Error 'TError）」かを型レベルで明示的に表現することで、コンパイル時にエラーハンドリングの漏れを検出でき、より堅牢なプログラミングを可能にする。Railway Oriented Programming（鉄道指向プログラミング）パターンの実装基盤として機能する。

**機能の利用シーン**：ファイルI/O操作でファイルが存在しない可能性がある場合、ユーザー入力のバリデーションで複数種類のエラーを返す必要がある場合、APIリクエストの結果が成功/失敗を明確に区別する必要がある場合、ビジネスロジックで複数のエラー条件を型安全に扱う必要がある場合など。

**主要な処理内容**：
1. 成功/失敗の状態を判定する関数（isOk、isError）の提供
2. 値を安全に取り出す関数（defaultValue、defaultWith）の提供
3. 関数型プログラミングのためのコンビネータ関数（map、mapError、bind）の提供
4. Result型から他の型（Option、ValueOption）への変換関数の提供
5. コレクション操作との互換性を持つ関数（toList、toArray、iter、exists、forall、count、fold）の提供

**関連システム・外部連携**：Option型およびValueOption型との相互変換機能を提供。C#との相互運用時にはResult<'T, 'TError>型として公開される。

**権限による制御**：本機能はライブラリ関数群であり、権限による制御は行わない。

## 関連画面

該当なし（コアライブラリ機能であり、画面は持たない）

## 機能種別

計算処理 / データ変換 / エラーハンドリング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| result | Result<'T, 'TError> | Yes | 操作対象のResult値 | - |
| value | 'T | No | デフォルト値 | - |
| mapping | 'T -> 'U | No | 成功値の変換関数 | - |
| errorMapping | 'TError -> 'U | No | エラー値の変換関数 | - |
| binder | 'T -> Result<'U, 'TError> | No | 束縛関数 | - |
| predicate | 'T -> bool | No | 述語関数 | - |
| folder | 'State -> 'T -> 'State | No | 畳み込み関数 | - |
| action | 'T -> unit | No | 副作用関数 | - |
| defThunk | 'TError -> 'T | No | エラー値からデフォルト値を生成する関数 | - |

### 入力データソース

F#プログラム内で生成されるResult型の値、または他の関数からの戻り値として受け取る。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 結果 | Result<'U, 'TError> / 'T / bool / int / 'T option / 'T voption / 'T list / 'T array | 各関数に応じた戻り値 |

### 出力先

関数の戻り値としてプログラムに返却。

## 処理フロー

### 処理シーケンス

```
1. Result値の受け取り
   └─ パターンマッチングでOk/Errorを判定
2. 各操作に応じた処理実行
   └─ Ok(x)の場合: 成功値xに対して処理を適用
   └─ Error(e)の場合: エラー値eに対して処理を適用またはエラーを伝播
3. 結果の返却
   └─ 新しいResult値、変換後の値、または集約結果
```

### フローチャート

```mermaid
flowchart TD
    A[Result値を受け取る] --> B{Ok/Error判定}
    B -->|Ok x| C[成功値xを取得]
    C --> D[変換/述語/畳み込み等を適用]
    D --> E[結果を返却]
    B -->|Error e| F[エラー処理]
    F --> G{mapError?}
    G -->|Yes| H[エラー値を変換]
    H --> E
    G -->|No| I[エラーを伝播]
    I --> E
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-32-1 | Error伝播 | map、bind等の操作はErrorを保持して伝播する | 入力がErrorの場合 |
| BR-32-2 | mapError | mapError関数はOk値を保持しつつError値のみを変換 | 入力がErrorの場合に変換適用 |
| BR-32-3 | defaultWith | defaultWith関数はエラー値を引数として受け取りデフォルト値を生成 | 入力がErrorの場合 |

### 計算ロジック

- `count`: Okなら1、Errorなら0を返す
- `fold`: Okの場合のみfolderを適用、Errorの場合は初期状態をそのまま返す

## データベース操作仕様

該当なし（メモリ上のデータ操作のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | Result型自体がエラーを表現する型 | defaultValueやdefaultWithで値を取得 |

### リトライ仕様

該当なし（単純な同期関数のため）

## トランザクション仕様

該当なし（メモリ上の操作のみ）

## パフォーマンス要件

- すべての関数はO(1)の時間計算量
- インライン最適化（inline属性）により関数呼び出しオーバーヘッドを最小化
- InlineIfLambda属性によるラムダ式のインライン化

## セキュリティ考慮事項

特になし（純粋な値変換関数群）

## 備考

- Result型は判別共用体として実装されており、F#のパターンマッチングで安全にハンドリング可能
- エラー型`'TError`は任意の型を取ることができ、string、例外型、カスタムエラー型など柔軟に定義可能
- Railway Oriented Programmingでは、bind関数を使って処理をパイプライン化することで、エラーが発生した時点で処理を短絡させることができる

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

Result型は言語組み込みの判別共用体として定義されている。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | prim-types.fsi | `src/FSharp.Core/prim-types.fsi` | Result型のシグネチャ定義（Ok/Error判別共用体） |

**読解のコツ**: Result型は`type Result<'T, 'TError> = Ok of 'T | Error of 'TError`という2つの型パラメータを持つ判別共用体。

#### Step 2: エントリーポイントを理解する

Resultモジュールが提供する各関数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | result.fs | `src/FSharp.Core/result.fs` | Resultモジュールの全関数実装 |

**主要処理フロー**:
1. **8-12行目**: `map`関数 - Ok時に変換関数を適用、Errorはそのまま伝播
2. **14-18行目**: `mapError`関数 - Error時にエラー変換関数を適用、Okはそのまま伝播
3. **20-24行目**: `bind`関数 - Ok時にバインダー関数を適用（モナディック操作）
4. **26-36行目**: `isOk`/`isError`関数 - 状態判定
5. **38-48行目**: `defaultValue`/`defaultWith`関数 - デフォルト値の提供
6. **104-114行目**: `toOption`/`toValueOption`関数 - Option型への変換

### プログラム呼び出し階層図

```
ユーザーコード
    │
    ├─ Result.map mapping result
    │      └─ パターンマッチ: Ok x -> Ok (mapping x) | Error e -> Error e
    │
    ├─ Result.mapError mapping result
    │      └─ パターンマッチ: Error e -> Error (mapping e) | Ok x -> Ok x
    │
    ├─ Result.bind binder result
    │      └─ パターンマッチ: Ok x -> binder x | Error e -> Error e
    │
    └─ Result.defaultWith defThunk result
           └─ パターンマッチ: Ok v -> v | Error error -> defThunk error
```

### データフロー図

```
[入力]                        [処理]                              [出力]

Result<'T,'E>  ───────▶ パターンマッチング ───────────▶ Result<'U,'E> (map)
                              │
                              ├──▶ Ok x: 変換適用 → Ok (f x)
                              │
                              └──▶ Error e: 伝播 → Error e

Result<'T,'E>  ───────▶ パターンマッチング ───────────▶ Result<'T,'F> (mapError)
                              │
                              ├──▶ Ok x: 保持 → Ok x
                              │
                              └──▶ Error e: 変換 → Error (f e)

Result<'T,'E>  ───────▶ パターンマッチング ───────────▶ 'T option (toOption)
                              │
                              ├──▶ Ok x: Some x
                              │
                              └──▶ Error _: None
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| result.fs | `src/FSharp.Core/result.fs` | ソース | Resultモジュールの実装 |
| result.fsi | `src/FSharp.Core/result.fsi` | シグネチャ | Resultモジュールのシグネチャ定義 |
| prim-types.fsi | `src/FSharp.Core/prim-types.fsi` | シグネチャ | Result型の定義 |
| prim-types.fs | `src/FSharp.Core/prim-types.fs` | ソース | Result型の実装 |
