# 機能設計書 12-@babel/runtime

## 概要

本ドキュメントは、Babelの@babel/runtimeパッケージの機能設計を記述する。@babel/runtimeは、Babelによって変換されたコードで使用されるランタイムヘルパー関数のコレクションである。

### 本機能の処理概要

@babel/runtimeは、Babelが生成する変換済みコードで必要となるヘルパー関数をモジュール化して提供する。これにより、同一のヘルパーコードが複数ファイルで重複することを防ぎ、バンドルサイズの最適化を実現する。

**業務上の目的・背景**：Babelはモダンなjavascript構文（クラス、アロー関数、分割代入など）を古いブラウザでも動作するコードに変換する。この変換処理には、ランタイムで必要となるヘルパー関数（例：クラスの継承を実現する`_inherits`、分割代入を実現する`_slicedToArray`など）が含まれる。従来、これらのヘルパーは各ファイルにインライン展開されていたが、大規模プロジェクトではコードの重複が深刻な問題となっていた。@babel/runtimeはこれらのヘルパーを外部モジュールとして提供し、@babel/plugin-transform-runtimeと組み合わせることで重複を排除する。

**機能の利用シーン**：ライブラリやアプリケーションのビルド時に@babel/plugin-transform-runtimeと併用される。特に、npmパッケージとして配布するライブラリでは、グローバルスコープを汚染しないために必須となる。

**主要な処理内容**：
1. 70以上のランタイムヘルパー関数を提供
2. CommonJS形式（helpers/）とESM形式（helpers/esm/）の両方でエクスポート
3. クラス関連ヘルパー（継承、プロパティ定義など）
4. イテレーション関連ヘルパー（for-of、スプレッド演算子など）
5. 非同期処理関連ヘルパー（async/await、ジェネレータなど）
6. プライベートフィールド関連ヘルパー
7. 明示的リソース管理（using宣言）関連ヘルパー

**関連システム・外部連携**：@babel/plugin-transform-runtimeプラグインがヘルパーのインライン展開を@babel/runtimeからのimportに置き換える。

**権限による制御**：本機能に権限制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | なし | - | ランタイムライブラリとして利用 |

## 機能種別

ユーティリティ / ランタイムヘルパーライブラリ

## 入力仕様

### 入力パラメータ

各ヘルパー関数は独立したモジュールであり、関数ごとに入力パラメータが異なる。代表的なヘルパーのパラメータを以下に示す。

| ヘルパー名 | パラメータ | 説明 |
|-----------|-----------|------|
| classCallCheck | instance, Constructor | クラスがnewで呼び出されたか検証 |
| inherits | subClass, superClass | クラス継承のプロトタイプチェーンを設定 |
| createClass | Constructor, protoProps, staticProps | クラスメソッドを定義 |
| asyncToGenerator | fn | async関数をジェネレータに変換 |
| slicedToArray | arr, i | 配列分割代入の実装 |
| objectSpread2 | target, ...sources | オブジェクトスプレッドの実装 |
| typeof | obj | Symbolを考慮したtypeof実装 |

### 入力データソース

Babelによって変換されたJavaScriptコードからimport/require経由で参照される。

## 出力仕様

### 出力データ

各ヘルパー関数は、変換後のJavaScriptコードを正しく動作させるための補助機能を提供する。

| ヘルパーカテゴリ | 出力/効果 |
|-----------------|----------|
| クラス関連 | 継承関係の設定、メソッド定義、インスタンスチェック |
| イテレーション関連 | 配列・イテラブルの変換、スプレッド展開 |
| 非同期関連 | Promise・ジェネレータの連携 |
| 型チェック関連 | 正確な型判定 |

### 出力先

ランタイムで実行され、変換済みコードの動作に必要な処理を実行する。

## 処理フロー

### 処理シーケンス

```
1. ビルド時：@babel/plugin-transform-runtime
   └─ インラインヘルパーを@babel/runtimeからのimportに置換

2. 実行時：ヘルパー関数の呼び出し
   └─ require/importでヘルパーをロード
   └─ 変換コードからヘルパー関数を実行

例：クラス変換の場合
class A extends B {}
  ↓ Babel変換
import _inherits from "@babel/runtime/helpers/inherits";
import _classCallCheck from "@babel/runtime/helpers/classCallCheck";
function A() {
  _classCallCheck(this, A);
  // ...
}
_inherits(A, B);
```

### フローチャート

```mermaid
flowchart TD
    A[ソースコード: class構文] --> B[Babel変換]
    B --> C{@babel/plugin-transform-runtime?}
    C -->|有効| D[ヘルパーをimport文に変換]
    C -->|無効| E[ヘルパーをインライン展開]
    D --> F[出力コード: import from @babel/runtime]
    E --> G[出力コード: インラインヘルパー]
    F --> H[実行時: @babel/runtimeから読み込み]
    G --> I[実行時: インラインで実行]
    H --> J[ヘルパー関数実行]
    I --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | モジュール形式対応 | CommonJSとESMの両形式でヘルパーを提供 | 常時 |
| BR-02 | グローバル非汚染 | グローバルスコープを変更しない | 常時 |
| BR-03 | 後方互換性 | 古いBabelバージョンとの互換性維持 | 常時 |
| BR-04 | 依存関係最小化 | 各ヘルパーは独立してimport可能 | 常時 |

### 計算ロジック

ヘルパー関数の実装例：

**typeof ヘルパー**:
```javascript
function _typeof(o) {
  return typeof Symbol === "function" && typeof Symbol.iterator === "symbol"
    ? (o) => typeof o
    : (o) => o && typeof Symbol === "function" && o.constructor === Symbol && o !== Symbol.prototype
      ? "symbol"
      : typeof o;
}
```

**possibleConstructorReturn ヘルパー**:
```javascript
function _possibleConstructorReturn(self, call) {
  if (call && (typeof call === "object" || typeof call === "function")) {
    return call;
  }
  if (call !== void 0) {
    throw new TypeError("Derived constructors may only return object or undefined");
  }
  return _assertThisInitialized(self);
}
```

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| TypeError | classCallCheckエラー | クラスをnew無しで呼び出し | クラスはnewで呼び出す |
| TypeError | possibleConstructorReturn | 派生コンストラクタが無効な値を返却 | objectまたはundefinedを返す |
| TypeError | readOnlyError | 読み取り専用プロパティへの書き込み | コードを修正 |

### リトライ仕様

本機能にリトライ処理は存在しない。

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

本機能はトランザクション処理を行わない。

## パフォーマンス要件

- 各ヘルパーは軽量に実装され、実行時オーバーヘッドを最小化
- tree-shaking対応により、未使用ヘルパーはバンドルから除外可能
- ESM形式はモジュールバンドラーによる最適化に対応

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

- プロトタイプ汚染攻撃への対策として、Object.createやObject.definePropertyを適切に使用
- 信頼されたBabel変換コードからの呼び出しを前提

## 備考

- Node.js v20.19.0以上またはv22.12.0以上が必要
- sideEffects: falseによりtree-shakingが有効
- 72種類以上のヘルパー関数を提供

---

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

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

### 推奨読解順序

#### Step 1: パッケージ構成を理解する

まず、パッケージの構造とエクスポート設定を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | package.json | `packages/babel-runtime/package.json` | exportsフィールドで各ヘルパーのエントリーポイントを定義 |

**読解のコツ**:
- **17-482行目**: exportsフィールドで各ヘルパーのCommonJS/ESMパスを定義
- **node/import/default**: 環境に応じた適切なファイルを提供

#### Step 2: 代表的なヘルパーを理解する

クラス関連ヘルパーを例に実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | classCallCheck.js | `packages/babel-runtime/helpers/classCallCheck.js` | クラス呼び出し検証 |
| 2-2 | inherits.js | `packages/babel-runtime/helpers/inherits.js` | クラス継承 |
| 2-3 | createClass.js | `packages/babel-runtime/helpers/createClass.js` | メソッド定義 |

#### Step 3: 型関連ヘルパーを理解する

typeof演算子の拡張実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | typeof.js | `packages/babel-runtime/helpers/typeof.js` | Symbol対応typeof |

**主要処理フロー**:
- **1-9行目**: Symbolの存在チェックと適切なtypeof実装の選択
- **4-7行目**: Symbol.iteratorの存在に基づく分岐

#### Step 4: 非同期処理ヘルパーを理解する

async/await変換のためのヘルパーを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | asyncToGenerator.js | `packages/babel-runtime/helpers/asyncToGenerator.js` | async関数変換 |
| 4-2 | wrapAsyncGenerator.js | `packages/babel-runtime/helpers/wrapAsyncGenerator.js` | 非同期ジェネレータ |

#### Step 5: 最新機能のヘルパーを理解する

明示的リソース管理（using宣言）のヘルパーを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | dispose.js | `packages/babel-runtime/helpers/dispose.js` | リソース破棄 |
| 5-2 | usingCtx.js | `packages/babel-runtime/helpers/usingCtx.js` | using文脈管理 |

**主要処理フロー**:
- **1-11行目**: SuppressedErrorのポリフィル
- **12-27行目**: リソーススタックの順次破棄処理

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

```
@babel/plugin-transform-runtime
    │
    └─ 変換時にimport文を生成
           │
           └─ @babel/runtime/helpers/{helper}
                  │
                  ├─ helpers/{helper}.js (CommonJS)
                  │      └─ 他ヘルパーをrequire
                  │
                  └─ helpers/esm/{helper}.js (ESM)
                         └─ 他ヘルパーをimport

例：possibleConstructorReturn
    ├─ typeof
    └─ assertThisInitialized
```

### データフロー図

```
[ビルド時]
ソースコード(ES6+) ──> Babel変換 ──> import文 + 変換コード

[実行時]
import "@babel/runtime/helpers/X"
       │
       └──> helpers/X.js または helpers/esm/X.js
                 │
                 └──> ヘルパー関数実行 ──> 変換ロジックの実現
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| package.json | `packages/babel-runtime/package.json` | 設定 | パッケージ定義、exports設定 |
| classCallCheck.js | `packages/babel-runtime/helpers/classCallCheck.js` | ヘルパー | クラス呼び出し検証 |
| inherits.js | `packages/babel-runtime/helpers/inherits.js` | ヘルパー | クラス継承設定 |
| createClass.js | `packages/babel-runtime/helpers/createClass.js` | ヘルパー | メソッド定義 |
| typeof.js | `packages/babel-runtime/helpers/typeof.js` | ヘルパー | Symbol対応typeof |
| possibleConstructorReturn.js | `packages/babel-runtime/helpers/possibleConstructorReturn.js` | ヘルパー | 派生コンストラクタ戻り値 |
| asyncToGenerator.js | `packages/babel-runtime/helpers/asyncToGenerator.js` | ヘルパー | async変換 |
| slicedToArray.js | `packages/babel-runtime/helpers/slicedToArray.js` | ヘルパー | 配列分割代入 |
| objectSpread2.js | `packages/babel-runtime/helpers/objectSpread2.js` | ヘルパー | オブジェクトスプレッド |
| dispose.js | `packages/babel-runtime/helpers/dispose.js` | ヘルパー | リソース破棄 |
| esm/*.js | `packages/babel-runtime/helpers/esm/` | ヘルパー | ESM形式ヘルパー |
