# 機能設計書 32-@jest/get-type

## 概要

本ドキュメントは、@jest/get-typeパッケージの機能設計を記載する。@jest/get-typeは、JavaScriptの値の型を正確に判定するためのユーティリティ関数を提供する。標準のtypeof演算子では区別できないnull、配列、RegExpなどの型を正確に識別できる。

### 本機能の処理概要

@jest/get-typeは、JavaScriptの値に対して詳細な型判定を行い、型名を文字列として返すユーティリティパッケージである。

**業務上の目的・背景**：JavaScriptの`typeof`演算子は、`null`を`"object"`と返したり、配列も`"object"`と返すなど、正確な型判定には不十分である。Jestのバリデーション機能やアサーション機能において、値の型を正確に判定する必要があり、この共通ユーティリティが必要とされた。

**機能の利用シーン**：
- jest-validateでの設定オプションの型検証
- expectマッチャーでのアサーション時の型比較
- pretty-formatでの値のフォーマット方式決定
- jest-diffでの差分比較時の型判定

**主要な処理内容**：
1. getType関数による詳細な型判定（undefined, null, array, boolean, function, number, string, bigint, regexp, map, set, date, object, symbol）
2. isPrimitive関数によるプリミティブ値の判定

**関連システム・外部連携**：
- 依存パッケージなし（純粋なTypeScript実装）
- 他のJestパッケージから広く利用される基盤ユーティリティ

**権限による制御**：特になし（ユーティリティ関数のため権限制御は不要）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面に直接関連しないユーティリティパッケージ |

## 機能種別

ユーティリティ / 型判定

## 入力仕様

### 入力パラメータ

#### getType関数

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| value | unknown | Yes | 型を判定する対象の値 | - |

#### isPrimitive関数

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| value | unknown | Yes | プリミティブ判定する対象の値 | - |

### 入力データソース

任意のJavaScript値（他のJestパッケージから渡される）

## 出力仕様

### 出力データ

#### getType関数

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | ValueType | 型名を表す文字列（'array', 'bigint', 'boolean', 'function', 'null', 'number', 'object', 'regexp', 'map', 'set', 'date', 'string', 'symbol', 'undefined'のいずれか） |

#### isPrimitive関数

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | boolean | プリミティブ値の場合true、オブジェクト値の場合false |

### 出力先

関数の戻り値として返却

## 処理フロー

### 処理シーケンス

```
1. getType関数の呼び出し
   └─ 任意の値を受け取る
2. undefined チェック
   └─ value === undefinedの場合、'undefined'を返す
3. null チェック
   └─ value === nullの場合、'null'を返す
4. 配列チェック
   └─ Array.isArray(value)の場合、'array'を返す
5. typeofによる基本型チェック
   └─ boolean, function, number, string, bigintをそれぞれ判定
6. オブジェクト型の詳細チェック
   └─ constructorプロパティで RegExp, Map, Set, Date を判定
   └─ それ以外は'object'を返す
7. シンボルチェック
   └─ typeof value === 'symbol'の場合、'symbol'を返す
8. 例外処理
   └─ 上記いずれにも該当しない場合はErrorをスロー
```

### フローチャート

```mermaid
flowchart TD
    A[getType開始] --> B{value === undefined?}
    B -->|Yes| C[return 'undefined']
    B -->|No| D{value === null?}
    D -->|Yes| E[return 'null']
    D -->|No| F{Array.isArray?}
    F -->|Yes| G[return 'array']
    F -->|No| H{typeof判定}
    H -->|boolean| I[return 'boolean']
    H -->|function| J[return 'function']
    H -->|number| K[return 'number']
    H -->|string| L[return 'string']
    H -->|bigint| M[return 'bigint']
    H -->|object| N{constructor判定}
    H -->|symbol| O[return 'symbol']
    N -->|RegExp| P[return 'regexp']
    N -->|Map| Q[return 'map']
    N -->|Set| R[return 'set']
    N -->|Date| S[return 'date']
    N -->|その他| T[return 'object']
    H -->|その他| U[throw Error]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | null判定 | nullはtypeofで'object'となるが、'null'として返す | value === null |
| BR-02 | 配列判定 | 配列はtypeofで'object'となるが、'array'として返す | Array.isArray(value) |
| BR-03 | 組み込みオブジェクト判定 | RegExp, Map, Set, Dateはconstructorで個別に判定 | typeof value === 'object' |
| BR-04 | プリミティブ判定 | Object(value) !== valueでプリミティブを判定 | isPrimitive関数 |

### 計算ロジック

**isPrimitive判定**：
```typescript
Object(value) !== value
```
- オブジェクトラッパーを生成し、元の値と比較
- プリミティブ値は新しいオブジェクトが生成されるため不一致
- オブジェクト値は同じ参照が返されるため一致

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

該当なし（純粋な関数型ユーティリティ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Error | 未知の型の値が渡された場合 | 通常のJavaScript値では発生しない |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 同期的に即座に結果を返すこと
- typeof演算子と同等のパフォーマンス

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

該当なし（値の型判定のみで副作用なし）

## 備考

- ValueType型は14種類の型名リテラルのユニオン型として定義
- 外部依存がなく、軽量なユーティリティパッケージ

---

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

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

### 推奨読解順序

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

型定義から理解を始める。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/jest-get-type/src/index.ts` | ValueType型の定義（8-22行目） |

**読解のコツ**:
- ValueTypeはリテラル型のユニオンとして定義されている
- 14種類の型名（'array', 'bigint', 'boolean', 'function', 'null', 'number', 'object', 'regexp', 'map', 'set', 'date', 'string', 'symbol', 'undefined'）

#### Step 2: メイン関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/jest-get-type/src/index.ts` | getType関数の実装（26-59行目） |

**主要処理フロー**:
1. **27-28行目**: undefinedチェック
2. **29-30行目**: nullチェック
3. **31-32行目**: 配列チェック（Array.isArray）
4. **33-42行目**: typeof演算子による基本型チェック
5. **43-53行目**: オブジェクト型の詳細判定（constructor比較）
6. **54-55行目**: シンボルチェック
7. **58行目**: 未知の型の場合はErrorをスロー

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/jest-get-type/src/index.ts` | isPrimitive関数の実装（61-64行目） |

**主要処理フロー**:
- **61-64行目**: `Object(value) !== value`でプリミティブ判定
- TypeScriptの型ガードとして実装（戻り値型`value is ...`）

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

```
getType (index.ts)
    │
    ├─ === undefined (直接比較)
    ├─ === null (直接比較)
    ├─ Array.isArray() (組み込み関数)
    ├─ typeof演算子 (言語機能)
    └─ constructor比較 (プロパティアクセス)

isPrimitive (index.ts)
    │
    └─ Object() (組み込みコンストラクタ)
```

### データフロー図

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

任意の値 ─────────▶ getType() ──────────────▶ ValueType文字列
                        │
                        ├─ undefined? ────▶ 'undefined'
                        ├─ null? ─────────▶ 'null'
                        ├─ array? ────────▶ 'array'
                        ├─ boolean? ──────▶ 'boolean'
                        ├─ function? ─────▶ 'function'
                        ├─ number? ───────▶ 'number'
                        ├─ string? ───────▶ 'string'
                        ├─ bigint? ───────▶ 'bigint'
                        ├─ RegExp? ───────▶ 'regexp'
                        ├─ Map? ──────────▶ 'map'
                        ├─ Set? ──────────▶ 'set'
                        ├─ Date? ─────────▶ 'date'
                        ├─ object? ───────▶ 'object'
                        └─ symbol? ───────▶ 'symbol'


任意の値 ─────────▶ isPrimitive() ──────────▶ boolean
                        │
                        └─ Object(value) !== value
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/jest-get-type/src/index.ts` | ソース | getType、isPrimitive関数の実装 |
| package.json | `packages/jest-get-type/package.json` | 設定 | パッケージ定義 |
| getType.test.ts | `packages/jest-get-type/src/__tests__/getType.test.ts` | テスト | getType関数のテスト |
| isPrimitive.test.ts | `packages/jest-get-type/src/__tests__/isPrimitive.test.ts` | テスト | isPrimitive関数のテスト |
