# 機能設計書 66-DefaultMap

## 概要

本ドキュメントは、Tailwind CSSにおけるDefaultMapクラスの機能設計を記述する。DefaultMapはJavaScript標準のMapを拡張し、存在しないキーに対してファクトリ関数によりデフォルト値を自動生成する機能を提供する。生成された値はMapに自動保存され、再計算を回避するメモ化（memoization）パターンを実現する。

### 本機能の処理概要

**業務上の目的・背景**：Tailwind CSSの内部処理では、候補パース結果のキャッシュ、バリアント処理結果のキャッシュ、ユーティリティ生成結果のキャッシュなど、多数の場面でキー→値のマッピングとメモ化が必要になる。DefaultMapは「キーが存在すれば値を返し、存在しなければファクトリ関数で生成して保存する」という共通パターンを汎用的に提供し、コードの簡潔化と計算コストの削減を両立する。PythonのdefaultdictやRubyのHash.newに相当する機能である。

**機能の利用シーン**：Tailwind CSS内部の極めて多くのモジュールから利用される最も基本的なユーティリティの一つ。候補パーサー（candidate.ts）、バリアント管理（variants.ts）、ユーティリティ管理（utilities.ts）、デザインシステム構築（design-system.ts）、AST操作（ast.ts）、候補正規化（canonicalize-candidates.ts）、@apply処理（apply.ts）、IntelliSense（intellisense.ts）、ソースマップ生成（source-map.ts）、v3互換レイヤー（plugin-api.ts, plugin-functions.ts）など、合計14以上のモジュールで使用されている。

**主要な処理内容**：
1. コンストラクタでファクトリ関数を受け取りMapを初期化する
2. get(key)メソッドをオーバーライドし、キーが未登録の場合はファクトリ関数を呼び出して値を生成・保存する
3. 生成された値はMapに保存されるため、同じキーへの2回目以降のアクセスではファクトリ関数は呼ばれない

**関連システム・外部連携**：外部システムとの連携はない。

**権限による制御**：権限による制御はない。

## 関連画面

本機能は内部ユーティリティクラスであり、画面に直接関連しない。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | 補助機能 | 各種キャッシュ・メモ化機構として間接的に全画面のCSS生成パフォーマンスに寄与 |

## 機能種別

計算処理（データ構造・キャッシュ）

## 入力仕様

### 入力パラメータ

#### コンストラクタ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| factory | (key: T, self: DefaultMap<T, V>) => V | Yes | キーが存在しない場合にデフォルト値を生成するファクトリ関数 | 任意の関数 |

#### get メソッド

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| key | T | Yes | 取得するキー | 任意の値（Mapのキーとして有効な値） |

### 入力データソース

呼び出し元モジュールからのメソッド呼び出しとして入力される。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| get戻り値 | V | キーに対応する値。存在しない場合はファクトリ関数で生成された値 |

### 出力先

呼び出し元への戻り値として返却される。

## 処理フロー

### 処理シーケンス

```
1. get(key)呼び出し
   ├─ 1a. super.get(key)でMapから値を取得
   ├─ 1b. 値がundefinedの場合
   │      ├─ factory(key, this)を呼び出してデフォルト値を生成
   │      ├─ this.set(key, value)でMapに保存
   │      └─ 生成された値を返却
   └─ 1c. 値がundefinedでない場合
          └─ 既存の値を返却
```

### フローチャート

```mermaid
flowchart TD
    A["get(key)"] --> B["value = super.get(key)"]
    B --> C{value === undefined?}
    C -->|Yes| D["value = factory(key, self)"]
    D --> E["this.set(key, value)"]
    E --> F[return value]
    C -->|No| F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-66-01 | 遅延生成 | デフォルト値はget時に初めて生成される（遅延初期化） | キーが未登録の場合 |
| BR-66-02 | 自動保存 | 生成されたデフォルト値は自動的にMapに保存される | ファクトリ関数実行後 |
| BR-66-03 | 再計算回避 | 同じキーへの2回目以降のアクセスではファクトリ関数は呼ばれない | キーが既に登録済みの場合 |
| BR-66-04 | 自己参照可能 | ファクトリ関数は第2引数でDefaultMapインスタンス自身を受け取れる | 常時 |
| BR-66-05 | undefined判定 | undefined値を明示的にsetした場合、get時にファクトリ関数が再実行される | value === undefined |

### 計算ロジック

ファクトリ関数の呼び出し: `this.factory(key, this)` - 第1引数はアクセスされたキー、第2引数はDefaultMapインスタンス自身。自己参照により、ファクトリ関数内で他のキーの値にアクセス（連鎖的な遅延生成）が可能。

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

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

データベース操作はない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | ファクトリ関数がエラーをスローした場合 | エラーはそのまま伝播する。値はMapに保存されない |

### リトライ仕様

リトライ処理はない。

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

トランザクション管理はない。

## パフォーマンス要件

- get操作はO(1)（MapのO(1)取得 + ファクトリ関数のコスト）
- 2回目以降のアクセスはMapの純粋なO(1)取得
- メモリ使用量はアクセスされたキーの数に比例

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

セキュリティ上の考慮事項はない。

## 備考

- TypeScriptジェネリクス `<T = string, V = any>` により任意のキー型・値型に対応
- デフォルトの型パラメータは `T = string, V = any`
- Mapの他のメソッド（set, has, delete, clear, forEach, entries等）は変更なくそのまま使用可能
- undefinedを値としてsetした場合の挙動に注意（ファクトリ関数が再実行される）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | default-map.ts | `packages/tailwindcss/src/utils/default-map.ts` | **5行目**: `DefaultMap<T = string, V = any> extends Map<T, V>` - MapのサブクラスでT(キー型)とV(値型)のジェネリクス |

**読解のコツ**: `extends Map<T, V>`によりMapの全機能を継承している。追加されるのはコンストラクタのfactoryパラメータとgetメソッドのオーバーライドのみ。

#### Step 2: 実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | default-map.ts | `packages/tailwindcss/src/utils/default-map.ts` | **1-20行目**: DefaultMapクラスの全体実装（わずか20行） |

**主要処理フロー**:
1. **1-4行目**: JSDocコメント。デフォルト値の自動生成と再計算回避の説明
2. **5行目**: クラス宣言。Map<T, V>を継承
3. **6-8行目**: コンストラクタ。private factoryフィールドとsuper()呼び出し
4. **10行目**: get(key: T): V - getメソッドのオーバーライド
5. **11行目**: super.get(key)で既存値を取得
6. **13-15行目**: undefinedの場合、factoryで生成してsetし保存
7. **18行目**: 値を返却

#### Step 3: 利用箇所を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | candidate.ts | `packages/tailwindcss/src/candidate.ts` | 候補パース結果のキャッシュ |
| 3-2 | variants.ts | `packages/tailwindcss/src/variants.ts` | バリアント処理結果のキャッシュ |
| 3-3 | utilities.ts | `packages/tailwindcss/src/utilities.ts` | ユーティリティ生成結果のキャッシュ |
| 3-4 | design-system.ts | `packages/tailwindcss/src/design-system.ts` | デザインシステム内部のキャッシュ |
| 3-5 | ast.ts | `packages/tailwindcss/src/ast.ts` | AST操作のキャッシュ |

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

```
DefaultMap (extends Map)
    │
    ├─ constructor(factory)
    │      └─ super() + factoryフィールド保存
    │
    └─ get(key)
           ├─ super.get(key)  ── 既存値の取得
           ├─ factory(key, self)  ── デフォルト値の生成
           └─ this.set(key, value)  ── 生成値の保存

[利用元（14+モジュール）]
    │
    ├─ candidate.ts
    │      └─ new DefaultMap((key) => parseCandidate(key))
    │
    ├─ variants.ts
    │      └─ new DefaultMap((key) => ...)
    │
    ├─ utilities.ts
    │      └─ new DefaultMap((key) => ...)
    │
    ├─ design-system.ts
    │      └─ new DefaultMap((key) => ...)
    │
    ├─ ast.ts
    │      └─ new DefaultMap((key) => ...)
    │
    ├─ canonicalize-candidates.ts
    │      └─ new DefaultMap((key) => ...)
    │
    ├─ apply.ts
    │      └─ new DefaultMap((key) => ...)
    │
    ├─ intellisense.ts
    │      └─ new DefaultMap((key) => ...)
    │
    ├─ source-map.ts
    │      └─ new DefaultMap((key) => ...)
    │
    └─ compat/ (plugin-api.ts, plugin-functions.ts)
           └─ new DefaultMap((key) => ...)
```

### データフロー図

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

key ──────────────▶ defaultMap.get(key)
                          │
                          ├─ Map内にkeyが存在
                          │    └─ 既存値を返却 ───────────────▶ V (cached)
                          │
                          └─ Map内にkeyが不在
                               ├─ factory(key, self) 実行
                               ├─ Map に set
                               └─ 生成値を返却 ──────────────▶ V (new)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| default-map.ts | `packages/tailwindcss/src/utils/default-map.ts` | ソース | DefaultMapクラスの実装 |
| candidate.ts | `packages/tailwindcss/src/candidate.ts` | ソース | 候補パース結果のキャッシュで利用 |
| variants.ts | `packages/tailwindcss/src/variants.ts` | ソース | バリアント処理のキャッシュで利用 |
| utilities.ts | `packages/tailwindcss/src/utilities.ts` | ソース | ユーティリティ生成のキャッシュで利用 |
| design-system.ts | `packages/tailwindcss/src/design-system.ts` | ソース | デザインシステム内部のキャッシュで利用 |
| ast.ts | `packages/tailwindcss/src/ast.ts` | ソース | AST操作のキャッシュで利用 |
| canonicalize-candidates.ts | `packages/tailwindcss/src/canonicalize-candidates.ts` | ソース | 候補正規化のキャッシュで利用 |
| apply.ts | `packages/tailwindcss/src/apply.ts` | ソース | @apply処理のキャッシュで利用 |
| intellisense.ts | `packages/tailwindcss/src/intellisense.ts` | ソース | IntelliSenseのキャッシュで利用 |
| source-map.ts | `packages/tailwindcss/src/source-maps/source-map.ts` | ソース | ソースマップ生成のキャッシュで利用 |
| plugin-api.ts | `packages/tailwindcss/src/compat/plugin-api.ts` | ソース | v3互換APIのキャッシュで利用 |
| plugin-functions.ts | `packages/tailwindcss/src/compat/plugin-functions.ts` | ソース | v3互換関数のキャッシュで利用 |
| dimensions.ts | `packages/tailwindcss/src/utils/dimensions.ts` | ソース | 寸法ユーティリティのキャッシュで利用 |
