# 機能設計書 63-@babel/plugin-proposal-throw-expressions

## 概要

本ドキュメントは、Babelのthrow式（throw expressions）を変換する提案プラグイン `@babel/plugin-proposal-throw-expressions` の機能設計を定義する。

### 本機能の処理概要

本プラグインは、TC39で提案されているthrow式をES5互換のコードに変換する機能を提供する。throw式は、従来の文としてのthrowを式として使用可能にし、論理演算子やアロー関数など式が期待される場所でエラーをスローできるようにする。

**業務上の目的・背景**：JavaScriptでは`throw`は文であり、式コンテキストでは使用できない。例えば `const x = value || throw new Error()` のような記述は通常のJavaScriptでは不可能である。throw式を使用することで、デフォルト値の設定時やnullチェック時に簡潔にエラーをスローできる。

**機能の利用シーン**：
- 論理OR演算子でのデフォルト値設定時のエラースロー: `value || throw new Error('Required')`
- nullish coalescing でのフォールバック: `value ?? throw new Error()`
- 三項演算子での条件付きスロー: `cond ? value : throw new Error()`

**主要な処理内容**：
1. UnaryExpressionで演算子が`throw`のノードを検出
2. throw文をラップする即時実行関数式（IIFE）を生成
3. 元のthrow式を関数呼び出しに置換

**関連システム・外部連携**：`@babel/core`のAST変換機能を利用する。パーサープラグイン`throwExpressions`を有効化する。

**権限による制御**：特にロールや権限による制御はない。Babel設定ファイルでのプラグイン有効化により機能する。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はCLIツールまたはビルドプロセスで使用され、GUI画面との関連はない |

## 機能種別

コード変換処理（AST変換）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| - | - | - | 本プラグインにはオプションパラメータはない | - |

### 入力データソース

- ソースコードからのASTノード（UnaryExpressionノード、演算子が`throw`のもの）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| transformedAST | AST Node | 変換後のAST（CallExpression） |

### 出力先

- 変換後のJavaScriptコード（Babelのパイプライン出力）

## 処理フロー

### 処理シーケンス

```
1. UnaryExpression訪問
   └─ 演算子がthrowでない場合は処理スキップ
2. ラッパー関数の生成
   └─ function(e) { throw e; } を作成
3. 元のthrow式を関数呼び出しに置換
   └─ throw expr → (function(e) { throw e; })(expr)
```

### フローチャート

```mermaid
flowchart TD
    A[UnaryExpression検出] --> B{演算子が throw ?}
    B -->|No| Z[処理スキップ]
    B -->|Yes| C[ラッパー関数生成]
    C --> D[function式作成]
    D --> E[パラメータe定義]
    E --> F[throw文をbodyに設定]
    F --> G[CallExpression生成]
    G --> H[元のthrow引数を引数として渡す]
    H --> I[path.replaceWith実行]
    I --> J[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | throw演算子判定 | UnaryExpressionのoperatorが"throw"の場合のみ変換 | 常時 |
| BR-02 | IIFE変換 | throw式を即時実行関数呼び出しに変換 | throw式検出時 |
| BR-03 | 引数保持 | throw式の引数は関数呼び出しの引数として保持 | 常時 |

### 計算ロジック

- 変換パターン: `throw expr` → `(function(e) { throw e; })(expr)`
- 論理式での使用例: `a || throw b` → `a || (function(e) { throw e; })(b)`

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

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 構文エラー | throw式の構文が不正 | ソースコードを修正する |

### リトライ仕様

リトライ処理は不要（コンパイル時のエラーはリトライ対象外）

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

トランザクション管理は不要（ファイル変換処理のため）

## パフォーマンス要件

- 単純な変換処理のため、パフォーマンス上の懸念は少ない
- 大規模コードベースでも数秒以内で変換完了すること

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

- ソースコード変換のため、実行時のセキュリティリスクは限定的
- 生成されるIIFEはオリジナルと同等のセキュリティ特性を持つ

## 備考

- TC39 Stage 2 提案
- 非常にシンプルな変換ロジック
- 変換後のコードサイズは若干増加する

---

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

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

### 推奨読解順序

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

throw式の変換では、UnaryExpressionノード（throw演算子）が主要なデータ構造となる。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-plugin-proposal-throw-expressions/src/index.ts` | 全体構造（27行のみの簡潔なプラグイン） |

**読解のコツ**: 非常に短いコードなので、全体を一度に読み通せる。`@babel/types`の関数（functionExpression、blockStatement、throwStatement等）の使い方に注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-plugin-proposal-throw-expressions/src/index.ts` | UnaryExpressionのvisitor |

**主要処理フロー**:
1. **9行目**: manipulateOptionsでthrowExpressionsパーサープラグインを追加
2. **12-14行目**: UnaryExpressionのoperatorがthrowかチェック
3. **16-19行目**: ラッパー関数の生成（function(e) { throw e; }）
4. **21行目**: CallExpressionに置換

#### Step 3: AST生成パターンを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/babel-plugin-proposal-throw-expressions/src/index.ts` | t.functionExpression、t.callExpression の使い方 |

**コード解説**:
```javascript
// 16-19行目のラッパー関数生成
const arrow = t.functionExpression(
  null,                                          // 関数名（無名）
  [t.identifier("e")],                          // パラメータ
  t.blockStatement([t.throwStatement(t.identifier("e"))])  // 本体
);
```

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

```
@babel/core (transform)
    │
    └─ @babel/plugin-proposal-throw-expressions/src/index.ts
           │
           └─ UnaryExpression visitor
                  │
                  ├─ 演算子チェック (operator === "throw")
                  │
                  ├─ t.functionExpression (ラッパー関数生成)
                  │      └─ t.blockStatement
                  │             └─ t.throwStatement
                  │
                  └─ t.callExpression (関数呼び出し生成)
                         └─ path.replaceWith
```

### データフロー図

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

UnaryExpression            ラッパー関数生成                  CallExpression
throw expr        ───▶     function(e) { throw e; }  ───▶   (function(e){throw e})(expr)
                           CallExpression生成
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-plugin-proposal-throw-expressions/src/index.ts` | ソース | プラグインエントリーポイント、変換ロジック |
| package.json | `packages/babel-plugin-proposal-throw-expressions/package.json` | 設定 | パッケージ定義・依存関係 |
