# 機能設計書 111-jsheaders

## 概要

本ドキュメントは、Nim標準ライブラリの`jsheaders`モジュールの機能設計について記載する。このモジュールはJavaScriptターゲット専用のHTTP Headersオブジェクト操作APIを提供する。

### 本機能の処理概要

jsheadersモジュールは、Web APIの`Headers`インターフェースをNimから利用可能にするためのラッパーモジュールである。JavaScriptバックエンドでコンパイルされたNimコードにおいて、HTTP通信時のヘッダー操作を効率的に行うことができる。

**業務上の目的・背景**：Webブラウザ上で動作するNimアプリケーションにおいて、Fetch APIやXMLHttpRequestを使用したHTTP通信を行う際、リクエストヘッダーやレスポンスヘッダーを操作する必要がある。このモジュールは、Web標準のHeaders APIをNimの型システムで安全に利用できるようにし、JavaScript相互運用性を高める。

**機能の利用シーン**：
- Fetch APIを使用したHTTPリクエストのヘッダー設定
- サーバーからのレスポンスヘッダーの解析
- カスタムHTTPヘッダーの追加・削除・更新
- REST API呼び出し時の認証トークン設定

**主要な処理内容**：
1. `newHeaders()` - 新しいHeadersオブジェクトの生成
2. `add(key, value)` - ヘッダーの追加（重複キー許可）
3. `delete(key)` - ヘッダーの削除（重複キーも含めて全て削除）
4. `hasKey(key)` - キーの存在確認
5. `keys()` / `values()` / `entries()` - イテレーション
6. `[]` / `[]=` - インデックスアクセス（取得・設定）
7. `clear()` - 全ヘッダーのクリア
8. `len()` - ヘッダー数の取得

**関連システム・外部連携**：
- JavaScript Fetch API
- Web標準Headers API（MDN準拠）
- jsfetchモジュールとの連携

**権限による制御**：特になし（ブラウザのCORS制限はAPIレベルで適用される）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLIコンパイラまたはブラウザ実行環境で使用 |

## 機能種別

データ操作 / API連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| key | cstring | Yes | ヘッダー名 | 空文字チェックはなし |
| value | cstring | Yes | ヘッダー値 | 空文字チェックはなし |

### 入力データソース

プログラムコード内で直接指定、または他のAPIからの取得値

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Headers | ref object of JsRoot | HTTPヘッダーを管理するオブジェクト |
| keys | seq[cstring] | ヘッダー名の配列 |
| values | seq[cstring] | ヘッダー値の配列 |
| entries | seq[tuple[key, value: cstring]] | キーと値のペアの配列 |

### 出力先

メモリ上のJavaScriptオブジェクト

## 処理フロー

### 処理シーケンス

```
1. newHeaders()でHeadersオブジェクトを生成
   └─ JavaScriptの`new Headers()`を呼び出し

2. add()またはインデックス代入でヘッダーを追加
   └─ add(): 重複キーを許可（append相当）
   └─ []=: 重複キーを上書き（set相当）

3. 必要に応じてヘッダーを取得・削除
   └─ []: 全ての値をカンマ区切りで取得
   └─ delete(): 指定キーの全エントリを削除

4. イテレーションでヘッダー一覧を取得
   └─ keys(), values(), entries()
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[newHeaders]
    B --> C{操作種別}
    C -->|追加| D[add/set]
    C -->|取得| E[get/keys/values]
    C -->|削除| F[delete/clear]
    D --> G[Headersオブジェクト更新]
    E --> H[値を返却]
    F --> G
    G --> I[終了]
    H --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-111-01 | 重複キーの扱い | addは重複を許可、[]=は上書き | ヘッダー追加時 |
| BR-111-02 | 削除の範囲 | deleteは指定キーの全エントリを削除 | ヘッダー削除時 |
| BR-111-03 | 取得時の結合 | 同一キーの複数値はカンマ区切りで結合 | ヘッダー取得時 |

### 計算ロジック

特になし

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

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

該当なし（メモリ上のオブジェクト操作のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | コンパイルエラー | JavaScript以外のバックエンドで使用 | `{.fatal.}`でコンパイル停止 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

JavaScriptネイティブAPIを直接呼び出すため、オーバーヘッドは最小限

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

- ブラウザのCORS制限に従う
- 認証トークンなど機密情報を含む場合は適切な取り扱いが必要

## 備考

- JavaScriptターゲット専用（`when not defined(js)`でコンパイルエラー）
- MDN Web Docsの Headers API仕様に準拠

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | jsheaders.nim | `lib/std/jsheaders.nim` | Headers型の定義（5行目） |

**読解のコツ**: `ref object of JsRoot`はJavaScriptオブジェクトへの参照を表すNimの型表現である。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | jsheaders.nim | `lib/std/jsheaders.nim` | newHeaders関数（7-8行目） |

**主要処理フロー**:
1. **7-8行目**: `newHeaders()`がJavaScriptの`new Headers()`を呼び出し

#### Step 3: 各操作関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | jsheaders.nim | `lib/std/jsheaders.nim` | add関数（10-12行目） - append相当 |
| 3-2 | jsheaders.nim | `lib/std/jsheaders.nim` | delete関数（14-17行目） |
| 3-3 | jsheaders.nim | `lib/std/jsheaders.nim` | hasKey関数（19-20行目） |
| 3-4 | jsheaders.nim | `lib/std/jsheaders.nim` | keys/values/entries（22-28行目） |
| 3-5 | jsheaders.nim | `lib/std/jsheaders.nim` | インデックスアクセス（31-37行目） |
| 3-6 | jsheaders.nim | `lib/std/jsheaders.nim` | clear関数（39-41行目） |
| 3-7 | jsheaders.nim | `lib/std/jsheaders.nim` | ユーティリティ関数（43-48行目） |

**主要処理フロー**:
- **10-12行目**: `add`は`#.append(#, #)`にマップ
- **31-33行目**: `[]`は`#.get(#)`にマップ
- **35-37行目**: `[]=`は`#.set(#, #)`にマップ

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

```
Nimアプリケーション
    │
    ├─ newHeaders()
    │      └─ JavaScript: new Headers()
    │
    ├─ add(key, value)
    │      └─ JavaScript: Headers.append()
    │
    ├─ [key] / [key]=
    │      ├─ JavaScript: Headers.get()
    │      └─ JavaScript: Headers.set()
    │
    └─ keys() / values() / entries()
           └─ JavaScript: Array.from(Headers.keys/values/entries())
```

### データフロー図

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

key, value  ───▶ add/set ───▶ Headers Object
                    │
Headers Object ◀───┘
                    │
key ───────────▶ get/delete ───▶ cstring / void
                    │
Headers Object ───▶ keys/values/entries ───▶ seq[cstring]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| jsheaders.nim | `lib/std/jsheaders.nim` | ソース | HTTP Headers API実装 |
| jsfetch.nim | `lib/std/jsfetch.nim` | ソース | Fetch APIでHeadersを使用 |
| jsformdata.nim | `lib/std/jsformdata.nim` | ソース | 関連するFormData API |
