# 帳票設計書 3-to json

## 概要

本ドキュメントは、Nushellの`to json`コマンドに関する設計書である。`to json`コマンドは、任意のNushellデータをJSON (JavaScript Object Notation) 形式のテキストに変換するデータ変換コマンドである。

### 本帳票の処理概要

`to json`コマンドは、Nushellのパイプラインで流れてくるあらゆるデータ型をJSON形式のテキストに変換する。レコード、リスト、プリミティブ値など、多様なデータ構造に対応している。

**業務上の目的・背景**：JSONは現代のWeb APIやデータ交換で最も広く使用されているフォーマットであり、システム間連携、設定ファイル、データ保存など多様な用途で必要とされる。Nushellで処理したデータを外部システムやWebサービスで利用可能な形式に変換する需要に応える。

**帳票の利用シーン**：
- REST APIへのデータ送信準備
- 設定ファイルの生成
- データのシリアライズと保存
- 他プログラミング言語との連携
- デバッグ用データ出力

**主要な出力内容**：
1. JSONオブジェクト（レコードから変換）
2. JSON配列（リストから変換）
3. JSONプリミティブ値（文字列、数値、真偽値など）

**帳票の出力タイミング**：パイプライン処理において`to json`コマンドが実行されたとき

**帳票の利用者**：Nushellユーザー、Web開発者、システムエンジニア、データエンジニア

## 帳票種別

データ変換出力（テキスト形式）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | Nushell CLI | コマンドライン | `to json` コマンド実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | JSON (テキスト) |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | パイプラインで`save`コマンドと組み合わせて指定 |
| 出力方法 | 標準出力またはファイル保存 |
| 文字コード | UTF-8 |

### 出力オプション

| オプション | 短縮形 | 説明 | デフォルト値 |
|-----------|--------|------|-------------|
| --raw | -r | 空白と末尾改行を削除（コンパクト出力） | false |
| --indent | -i | インデント幅を指定（スペース数） | 2 |
| --tabs | -t | インデントにタブを使用（タブ数） | なし |
| --serialize | -s | デシリアライズ不可能なNushell型をシリアライズ | false |

## 帳票レイアウト

### レイアウト概要

JSON出力は以下の構造を持つ：

```
┌─────────────────────────────────────┐
│  JSON構造（インデント付き）          │
│  {                                  │
│    "key1": "value1",                │
│    "key2": [1, 2, 3],               │
│    "key3": {                        │
│      "nested": true                 │
│    }                                │
│  }                                  │
└─────────────────────────────────────┘
```

### 型変換マッピング

| No | Nushell型 | JSON型 | 備考 |
|----|-----------|--------|------|
| 1 | Bool | boolean | 真偽値 |
| 2 | Int | number (I64) | 整数 |
| 3 | Float | number (F64) | 浮動小数点 |
| 4 | String | string | 文字列 |
| 5 | Date | string | ISO形式文字列 |
| 6 | Duration | number (I64) | ナノ秒 |
| 7 | Filesize | number (I64) | バイト数 |
| 8 | Nothing | null | null値 |
| 9 | List | array | 配列 |
| 10 | Record | object | オブジェクト |
| 11 | Binary | array | バイト配列 |
| 12 | CellPath | array | パス要素配列 |
| 13 | Closure | string/error | --serialize時のみ文字列変換 |

## 出力条件

### 入力条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| 入力データ型 | Any（任意の型） | Yes |

### 制約条件

| 条件名 | 説明 |
|-------|------|
| Closure | --serialize未指定時はエラー |
| Range | null出力 |
| Error | エラー伝播 |

## データベース参照仕様

### 参照テーブル一覧

本コマンドはデータベースを直接参照しない。パイプラインから受け取るデータを処理する。

## 計算仕様

### 計算項目一覧

本コマンドには計算処理は含まれない。型変換のみ実施。

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[入力データ受信] --> B[オプション解析]
    B --> C[Range展開]
    C --> D[Value取得]
    D --> E[value_to_json_value変換]
    E --> F{フォーマット選択}
    F -->|--raw| G[to_string_raw]
    F -->|--tabs| H[to_string_with_tab_indentation]
    F -->|--indent| I[to_string_with_indent]
    F -->|デフォルト| J[to_string]
    G --> K[Value::string作成]
    H --> K
    I --> K
    J --> K
    K --> L[メタデータ付与]
    L --> M[PipelineData返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| UnsupportedInput | Closureを--serializeなしで変換 | "closures are currently not deserializable (use --serialize to serialize as a string)" | --serializeオプションを使用 |
| CantConvert | JSON変換失敗 | "CantConvert to JSON" | 入力データを確認 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | メモリ制限内 |
| 目標出力時間 | データサイズに依存 |
| 同時出力数上限 | N/A |

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

- 入力データはそのまま出力されるため、センシティブな情報が含まれる場合は注意が必要
- JSONインジェクション対策として、nu_jsonクレートが適切なエスケープを行う

## 備考

- content_type メタデータは "application/json" として設定される
- nu_jsonクレートを使用してJSON変換を実施
- Closure型は--serializeオプションなしでは変換エラーとなる

---

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

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

### 推奨読解順序

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

まず、Nushellの各Value型とJSON型のマッピングを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | json.rs | `crates/nu-command/src/formats/to/json.rs` | value_to_json_value関数での型マッピング（114-177行目） |

**読解のコツ**: match文でValue型ごとにnu_json::Value型への変換を確認する。

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

`to json`コマンドの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | json.rs | `crates/nu-command/src/formats/to/json.rs` | ToJson構造体とCommandトレイト実装（5-112行目） |

**主要処理フロー**:
1. **12-38行目**: シグネチャ定義（--raw, --indent, --tabs, --serializeオプション）
2. **44-89行目**: runメソッドでオプション解析とJSON変換処理
3. **62-70行目**: フォーマット選択ロジック

#### Step 3: 値変換ロジックを理解する

各型の変換ロジックを詳細に確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | json.rs | `crates/nu-command/src/formats/to/json.rs` | value_to_json_value関数（114-177行目） |
| 3-2 | json.rs | `crates/nu-command/src/formats/to/json.rs` | json_list関数（179-197行目） |

**主要処理フロー**:
- **122-128行目**: プリミティブ型（Bool, Int, Float, String等）の変換
- **131-139行目**: CellPathの変換
- **141-143行目**: Listの再帰的変換
- **145-157行目**: Closureの変換（--serialize時）
- **162-171行目**: Recordの変換

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

```
ToJson::run (json.rs:44)
    │
    ├─ input.try_expand_range() (json.rs:58)
    │
    ├─ input.into_value() (json.rs:59)
    │
    └─ value_to_json_value (json.rs:60)
           │
           ├─ プリミティブ型変換 (json.rs:122-130)
           │
           ├─ CellPath変換 (json.rs:131-139)
           │
           ├─ List変換 (json.rs:141-143)
           │      │
           │      └─ json_list (json.rs:179)
           │             │
           │             └─ value_to_json_value (再帰)
           │
           ├─ Closure変換 (json.rs:145-157)
           │
           └─ Record変換 (json.rs:162-171)
                  │
                  └─ value_to_json_value (再帰)
```

### データフロー図

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

Value (Any型) ────────▶ ToJson::run ──────────────────▶ PipelineData::Value
                              │                              │
                              ▼                              ▼
                        Range展開                      JSON形式文字列
                              │                        "{ ... }"
                              ▼
                        value_to_json_value
                        (型別変換)
                              │
                              ▼
                        nu_json::to_string*
                        (フォーマット適用)
                              │
                              ▼
                        metadata付与
                        (application/json)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| json.rs | `crates/nu-command/src/formats/to/json.rs` | ソース | to jsonコマンドの実装 |
| mod.rs | `crates/nu-command/src/formats/to/mod.rs` | ソース | toモジュールの公開定義 |
| nu-json (crate) | 外部依存 | ライブラリ | JSON出力ライブラリ |
