@aiquants/duckdb-helper 1.4.0 → 1.5.0

package/docs/specs/2026.04.11 [AI] 00-overview.md

@@ -0,0 +1,177 @@
+# @aiquants/duckdb-helper 設計書 - 全体概要
+
+## 1. パッケージ概要
+
+| 項目 | 内容 |
+|------|------|
+| パッケージ名 | `@aiquants/duckdb-helper` |
+| バージョン | 1.4.1 |
+| ライセンス | MIT |
+| 目的 | ブラウザ上で DuckDB-WASM を簡単に利用するためのヘルパーライブラリ |
+| 主な利用者 | React ベースの Web アプリケーション開発者 |
+
+## 2. このパッケージが解決する課題
+
+DuckDB-WASM をブラウザで使う場合、以下のような複雑な手順が必要になる。
+
+1. WASM バンドルの取得とブラウザ互換バンドルの選択
+2. Web Worker の作成と DuckDB インスタンスの初期化
+3. コネクション管理（作成・再利用・破棄）
+4. クエリ結果（Apache Arrow Table）の JavaScript 配列への変換
+5. React コンポーネントでの状態管理（初期化中・準備完了・エラー）
+
+このパッケージは上記すべてをラップし、**数行のコードで DuckDB を利用可能**にする。
+
+## 3. アーキテクチャ図
+
+```mermaid
+graph TD
+    subgraph App["利用側アプリケーション"]
+        direction TB
+        subgraph Hooks["React Hooks"]
+            useDuckDB["useDuckDB"]
+            useDuckDBQuery["useDuckDBQuery"]
+        end
+        subgraph Service["サービス層（シングルトン）"]
+            DuckDBService["DuckDBService"]
+        end
+        subgraph Utils["ユーティリティ層"]
+            Logger["Logger"]
+            helpers["helpers"]
+            types["types"]
+        end
+        useDuckDB --> DuckDBService
+        useDuckDBQuery --> DuckDBService
+        DuckDBService --> Logger
+        DuckDBService --> helpers
+        DuckDBService --> types
+    end
+    DuckDBService --> duckdb_wasm["@duckdb/duckdb-wasm\n（外部依存）"]
+    duckdb_wasm --> Worker["Web Worker\n（WASM / ブラウザランタイム）"]
+```
+
+## 4. ディレクトリ構成
+
+```
+packages/duckdb-helper/
+├── src/
+│   ├── index.ts                  # エントリーポイント（公開 API の定義）
+│   ├── hooks/
+│   │   └── useDuckDB.ts          # React Hooks（useDuckDB, useDuckDBQuery）
+│   ├── services/
+│   │   └── duckdb.ts             # DuckDBService クラス（シングルトン）
+│   ├── types/
+│   │   └── duckdb.ts             # 型定義（DuckDBQueryResult, DuckDBRow）
+│   └── utils/
+│       ├── duckdb-helpers.ts     # ヘルパー関数群
+│       └── simple-logger.ts      # ログユーティリティ
+├── tests/
+│   └── integration/
+│       └── dummy.test.ts         # テスト（Vitest）
+├── docs/
+│   ├── spec/                     # 設計仕様書
+│   ├── guides/                   # ガイド（入門・開発）
+│   └── useDuckDB.md              # API リファレンス
+├── dist/                         # ビルド成果物（自動生成）
+├── package.json
+├── tsconfig.json
+└── tsup.config.ts                # ビルド設定
+```
+
+## 5. 公開 API 一覧
+
+`src/index.ts` で公開されるすべてのエクスポート:
+
+| カテゴリ | エクスポート名 | 種別 | 説明 |
+|----------|---------------|------|------|
+| Hooks | `useDuckDB` | 関数 | DuckDB の状態管理と操作を提供する React Hook |
+| Hooks | `useDuckDBQuery` | 関数 | SQL クエリの実行と結果管理を行う React Hook |
+| Service | `DuckDBService` | クラス | DuckDB 操作のシングルトンサービス（名前付きエクスポート） |
+| Service | `duckDBService` | インスタンス | `DuckDBService.getInstance()` の名前付きエクスポート（`services/duckdb.ts` のデフォルトエクスポートを re-export） |
+| Types | `UseDuckDBResult` | 型 | `useDuckDB` の戻り値の型 |
+| Types | `DuckDBQueryResult` | 型 | クエリ結果のインターフェース |
+| Types | `DuckDBRow` | 型 | 行データのヘルパー型 |
+| Utils | `duckdbTableToArray` | 関数 | クエリ結果を型付き配列に変換 |
+| Utils | `getDuckDBRowCount` | 関数 | 結果の行数を取得 |
+| Utils | `getDuckDBColumnCount` | 関数 | 結果の列数を取得 |
+| Utils | `isDuckDBTable` | 関数 | 結果が有効な DuckDB テーブルか判定（型ガード） |
+
+## 6. 依存関係
+
+### 本番依存（dependencies）
+
+| パッケージ | バージョン | 用途 |
+|-----------|-----------|------|
+| `@duckdb/duckdb-wasm` | ^1.30.0 | DuckDB の WASM 実装本体 |
+
+### ピア依存（peerDependencies）- オプション
+
+| パッケージ | バージョン | 用途 |
+|-----------|-----------|------|
+| `react` | >=18.0.0 | React Hooks を使う場合に必要 |
+| `react-dom` | >=18.0.0 | React Hooks を使う場合に必要 |
+
+> **ポイント**: React はオプショナルなピア依存。Hooks を使わずサービス層のみ利用する場合、React は不要。
+
+## 7. データフロー
+
+### 初期化フロー
+
+```mermaid
+flowchart TD
+    A["useDuckDB(autoInitialize=true)"] --> B["マウント時に initialize() を呼び出し"]
+    B --> C["DuckDBService.initialize()"]
+    C --> D{workerInstance が存在?}
+    D -- Yes --> E["workerInstance を返す"]
+    D -- No --> F{初期化中?}
+    F -- Yes --> G["既存の initPromise を返す（重複防止）"]
+    F -- No --> H["1. jsDelivr CDN からバンドル一覧を取得"]
+    H --> I["2. ブラウザ互換バンドルを自動選択"]
+    I --> J["3. Blob URL で Web Worker を作成"]
+    J --> K["4. AsyncDuckDB インスタンスを作成"]
+    K --> L["5. WASM モジュールをインスタンス化"]
+    L --> M["6. splink_udfs 拡張をインストール・ロード\n（失敗しても初期化は続行）"]
+    M --> N["7. Blob URL を解放"]
+    N --> O{結果}
+    O -- 成功 --> P["status: ready"]
+    O -- 失敗 --> Q["status: error"]
+```
+
+### クエリ実行フロー
+
+```mermaid
+flowchart TD
+    A["executeQuery(sql)"] --> B["getConnection()"]
+    B --> C{コネクションが存在?}
+    C -- No --> D["initialize() → connect()"]
+    C -- Yes --> E["既存コネクションを返す"]
+    D --> F["connection.query(sql) を実行"]
+    E --> F
+    F --> G["60秒タイムアウトで Promise.race"]
+    G --> H["Apache Arrow Table を返す"]
+```
+
+## 8. 設計上の重要な判断
+
+| 判断事項 | 採用方針 | 理由 |
+|---------|---------|------|
+| シングルトンパターン | 採用 | アプリ全体で WASM インスタンスを1つだけ保持し、メモリを節約 |
+| CDN からのバンドル取得 | jsDelivr を使用 | `@duckdb/duckdb-wasm` 公式推奨の配布方法 |
+| Blob URL による Worker 作成 | 採用 | CORS 制約を回避し、CDN の Worker スクリプトをロード |
+| splink_udfs 拡張の自動ロード | 初期化時に実行 | 名寄せ（レコードリンケージ）機能を標準提供 |
+| 初期化タイムアウト | 120秒 | WASM ダウンロードを考慮した長めの設定 |
+| クエリタイムアウト | 60秒 | 長時間クエリによる UI フリーズを防止 |
+| バッチインサート | 1000行単位 | 大量データ投入時のメモリ効率とパフォーマンスのバランス |
+
+## 9. 関連ドキュメント
+
+| ドキュメント | パス | 内容 |
+|-------------|------|------|
+| 型定義仕様書 | [01-types.md](./2026.04.11%20%5BAI%5D%2001-types.md) | 型定義の詳細 |
+| サービス仕様書 | [02-service.md](./2026.04.11%20%5BAI%5D%2002-service.md) | DuckDBService の全メソッド仕様 |
+| Hooks 仕様書 | [03-hooks.md](./2026.04.11%20%5BAI%5D%2003-hooks.md) | useDuckDB / useDuckDBQuery の仕様 |
+| ユーティリティ仕様書 | [04-utils.md](./2026.04.11%20%5BAI%5D%2004-utils.md) | ヘルパー関数の仕様 |
+| Logger 仕様書 | [05-logger.md](./2026.04.11%20%5BAI%5D%2005-logger.md) | ログユーティリティの仕様 |
+| ビルド設定仕様書 | [06-build-config.md](./2026.04.11%20%5BAI%5D%2006-build-config.md) | tsup / TypeScript 設定の詳細 |
+| 入門ガイド | [getting-started.md](../guides/2026.04.11%20%5BAI%5D%20getting-started.md) | 初めて使う人向けガイド |
+| 開発ガイド | [development.md](../guides/2026.04.11%20%5BAI%5D%20development.md) | 開発・保守作業向けガイド |

package/docs/specs/2026.04.11 [AI] 01-types.md

@@ -0,0 +1,101 @@
+# 型定義仕様書
+
+> ソースファイル: `src/types/duckdb.ts`
+
+## 1. 概要
+
+このファイルは、DuckDB のクエリ結果を TypeScript で安全に扱うための型定義を提供する。
+DuckDB-WASM のクエリ結果は内部的に Apache Arrow Table 形式だが、このライブラリでは直接 Arrow に依存せず、必要最小限のインターフェースを定義している。
+
+## 2. 型定義一覧
+
+### 2.1 `DuckDBQueryResult<T>`
+
+```typescript
+export interface DuckDBQueryResult<T = unknown> {
+    toArray(): T[]
+    numRows: number
+    numCols: number
+}
+```
+
+| プロパティ/メソッド | 型 | 説明 |
+|-------------------|------|------|
+| `toArray()` | `T[]` | クエリ結果の全行を JavaScript 配列として返すメソッド |
+| `numRows` | `number` | 結果の行数 |
+| `numCols` | `number` | 結果の列数 |
+
+#### 設計意図
+
+- **なぜ独自インターフェースか**: `@duckdb/duckdb-wasm` が返す Apache Arrow Table の型を直接使うと、Arrow ライブラリへの強い依存が発生する。この最小インターフェースにより、利用側は Arrow の知識なしに結果を扱える。
+- **ジェネリクス `T`**: デフォルトは `unknown`。利用側が行の型を指定することで、`toArray()` の戻り値に型安全性を持たせられる。
+
+#### 使用例
+
+```typescript
+// 型パラメータなし（unknown[] が返る）
+const result: DuckDBQueryResult = await executeQuery("SELECT 1")
+const rows = result.toArray() // unknown[]
+
+// 型パラメータあり（型安全）
+interface User { id: number; name: string }
+const result: DuckDBQueryResult<User> = await executeQuery("SELECT * FROM users")
+const rows = result.toArray() // User[]
+```
+
+### 2.2 `DuckDBRow<T>`
+
+```typescript
+export type DuckDBRow<T> = T
+```
+
+| 項目 | 内容 |
+|------|------|
+| 定義 | ジェネリクス `T` をそのまま返すエイリアス型 |
+| 用途 | コード上の可読性向上。「この `T` は DuckDB の行データである」という意味を明示する |
+
+#### 設計意図
+
+機能的には `T` と同一だが、コード上で「この型は DuckDB テーブルの1行を表す」という意図を伝える**ドキュメンテーション型**として存在する。
+
+#### 使用例
+
+```typescript
+type UserRow = DuckDBRow<{
+    id: number
+    name: string
+    email: string | null
+}>
+
+// 以下は同じ意味だが、DuckDBRow を使うと「DuckDB の行データ」という意図が明確
+// type UserRow = { id: number; name: string; email: string | null }
+```
+
+## 3. 型の関係図
+
+```
+DuckDBQueryResult<T>
+  │
+  ├── toArray() → T[] (= DuckDBRow<T>[])
+  ├── numRows: number
+  └── numCols: number
+
+DuckDBRow<T> = T  ← ドキュメンテーション用エイリアス
+```
+
+## 4. 他モジュールとの関係
+
+| 参照元ファイル | 参照する型 | 使われ方 |
+|--------------|-----------|---------|
+| `index.ts` | `DuckDBQueryResult`, `DuckDBRow` | 公開 API として re-export（型のみ） |
+| `utils/duckdb-helpers.ts` | `DuckDBQueryResult` | `duckdbTableToArray` 内の型アサーション（`as DuckDBQueryResult<T>`）、`isDuckDBTable` の型ガード戻り値（`result is DuckDBQueryResult`）。なお `getDuckDBRowCount` / `getDuckDBColumnCount` は `DuckDBQueryResult` を参照せず、`unknown` 型の入力に対して `in` 演算子と `typeof` で直接プロパティを検査する |
+| `hooks/useDuckDB.ts` | （直接参照なし） | フック内部では `unknown` 型で結果を返す |
+| `services/duckdb.ts` | （直接参照なし） | `executeQuery` の戻り値は `Promise<unknown>`（独立して `unknown` を採用） |
+
+> **補足**: `DuckDBRow` は `index.ts` から re-export されているが、`src/` 内のどのモジュールでも実際には使用されていない。利用側アプリケーションでのドキュメンテーション用途を想定した型。
+
+## 5. 新人向けポイント
+
+1. **`DuckDBQueryResult` は「DuckDB の結果はこういう形ですよ」という約束事**。実際の結果は Apache Arrow Table だが、このインターフェースの3つのメンバーだけ知っていればOK。
+2. **`DuckDBRow` は使っても使わなくても動作は同じ**。ただしチーム内で「これは DuckDB の行データ」と分かりやすくするために使う。
+3. **型パラメータ `<T>` を指定すると、IDE の補完が効くようになる**。可能な限り具体的な型を指定しよう。

package/docs/specs/2026.04.11 [AI] 02-service.md

@@ -0,0 +1,387 @@
+# DuckDBService 詳細仕様書
+
+> ソースファイル: `src/services/duckdb.ts`
+
+## 1. 概要
+
+`DuckDBService` は、ブラウザ上で DuckDB-WASM を操作するための**シングルトンサービスクラス**。
+Web Worker の初期化、コネクション管理、SQL クエリの実行、テーブル操作をすべて担当する。
+
+## 2. クラス設計
+
+### 2.1 デザインパターン
+
+- **シングルトンパターン**: `getInstance()` で唯一のインスタンスを取得する。アプリケーション全体で DuckDB Worker を1つだけ保持し、メモリとリソースを節約する。
+- **オブザーバーパターン**: `addStatusListener` / `removeStatusListener` でステータス変更を監視できる。React Hook (`useDuckDB`) がこれを利用している。
+
+### 2.2 プライベートプロパティ
+
+| プロパティ名 | 型 | 初期値 | 説明 |
+|-------------|------|--------|------|
+| `instance` | `DuckDBService \| null` | `null` | シングルトンインスタンス（static） |
+| `operationFlags` | `Map<string, boolean>` | 空の Map | テーブル作成の重複実行防止フラグ |
+| `workerInstance` | `AsyncDuckDB \| null` | `null` | DuckDB Worker インスタンス |
+| `connectionInstance` | `AsyncDuckDBConnection \| null` | `null` | DB コネクション（再利用される） |
+| `isInitializing` | `boolean` | `false` | 初期化中フラグ |
+| `initPromise` | `Promise<AsyncDuckDB> \| null` | `null` | 初期化 Promise（重複呼び出し防止用） |
+| `hasError` | `boolean` | `false` | エラー発生フラグ |
+| `listeners` | `Set<() => void>` | 空の Set | ステータス変更リスナー群 |
+
+## 3. メソッド仕様
+
+### 3.1 `getInstance(): DuckDBService` (static)
+
+```typescript
+public static getInstance(): DuckDBService
+```
+
+| 項目 | 内容 |
+|------|------|
+| 戻り値 | `DuckDBService` のシングルトンインスタンス |
+| 副作用 | インスタンスが未作成の場合、新規作成する |
+| スレッド安全性 | JavaScript はシングルスレッドなので問題なし |
+
+**処理フロー**:
+1. `instance` が `null` → 新しい `DuckDBService` を作成して `instance` に格納
+2. `instance` を返す
+
+---
+
+### 3.2 `getStatus(): string`
+
+```typescript
+public getStatus(): "not-initialized" | "initializing" | "ready" | "error"
+```
+
+| ステータス | 条件 | 意味 |
+|-----------|------|------|
+| `"error"` | `hasError === true` | 初期化に失敗した（最優先で判定） |
+| `"initializing"` | `isInitializing === true` | 初期化処理中 |
+| `"ready"` | `workerInstance !== null` | 利用可能 |
+| `"not-initialized"` | 上記いずれでもない | まだ初期化されていない |
+
+> **判定順序に注意**: `error` が最優先。`isInitializing` が `true` かつ `hasError` が `true` の場合は `"error"` になる。
+
+---
+
+### 3.3 `initialize(): Promise<AsyncDuckDB>`
+
+```typescript
+public async initialize(): Promise<duckdb.AsyncDuckDB>
+```
+
+| 項目 | 内容 |
+|------|------|
+| 戻り値 | 初期化された `AsyncDuckDB` インスタンス |
+| 例外 | 初期化失敗時（タイムアウト含む）に throw |
+| タイムアウト | 120秒（120,000ms） |
+
+**処理フロー**:
+
+```mermaid
+flowchart TD
+    A["initialize()"] --> B{workerInstance が存在?}
+    B -- Yes --> C["そのまま返す（高速パス）"]
+    B -- No --> D{既に初期化中?}
+    D -- Yes --> E["initPromise を返す（重複防止）"]
+    D -- No --> F["isInitializing = true, hasError = false\nリスナーに通知（status: initializing）"]
+    F --> G["Promise.race(\n  internalInitializeWorker(),\n  タイムアウト 120秒\n)"]
+    G -- 成功 --> H["isInitializing = false\nリスナーに通知（status: ready）\nAsyncDuckDB を返す"]
+    G -- 失敗 --> I["isInitializing = false, hasError = true\nリスナーに通知（status: error）\ninitPromise = null（リトライ可能）\nエラーを throw"]
+```
+
+**重複呼び出し防止の仕組み**:
+複数の箇所から同時に `initialize()` が呼ばれても、2回目以降は `initPromise` を返すため、Worker は1回だけ作成される。
+
+---
+
+### 3.4 `internalInitializeWorker(): Promise<AsyncDuckDB>` (private)
+
+```typescript
+private async internalInitializeWorker(): Promise<duckdb.AsyncDuckDB>
+```
+
+Worker の実際の初期化処理。以下のステップを順番に実行する。
+
+| ステップ | 処理内容 | 補足 |
+|---------|---------|------|
+| 1 | `duckdb.getJsDelivrBundles()` で CDN バンドル一覧を取得 | jsDelivr CDN を使用 |
+| 2 | `duckdb.selectBundle()` でブラウザ互換のバンドルを選択 | ブラウザの機能に応じて最適なものを選択 |
+| 3 | Blob URL を作成して Web Worker を生成 | `importScripts()` で Worker スクリプトを読み込む |
+| 4 | `new duckdb.AsyncDuckDB(logger, worker)` でインスタンス作成 | ConsoleLogger を使用 |
+| 5 | `workerInstance.instantiate()` で WASM モジュールを読み込み | メインモジュールと pthread Worker |
+| 6 | `splink_udfs` 拡張をインストール・ロード | **一時コネクション**を開き、`INSTALL` → `LOAD` を実行後、`finally` で close する。メインの `connectionInstance` とは別。失敗しても初期化は続行 |
+| 7 | Blob URL を `revokeObjectURL` で解放 | メモリリーク防止 |
+
+**splink_udfs について**:
+- 名寄せ（レコードリンケージ）用の UDF（ユーザー定義関数）
+- `INSTALL splink_udfs FROM community;` → `LOAD splink_udfs;`
+- インストール/ロードに失敗しても `warn` ログを出すだけで、初期化全体は失敗しない
+
+---
+
+### 3.5 `getConnection(): Promise<AsyncDuckDBConnection>`
+
+```typescript
+public async getConnection(): Promise<duckdb.AsyncDuckDBConnection>
+```
+
+| 項目 | 内容 |
+|------|------|
+| 戻り値 | DuckDB コネクション |
+| 動作 | コネクションが無ければ `initialize()` → `connect()` で作成。あれば再利用 |
+
+**注意**: コネクションは1つだけ保持・再利用される。並列クエリの実行には対応していない。
+
+---
+
+### 3.6 `executeQuery(sql: string): Promise<unknown>`
+
+```typescript
+public async executeQuery(sql: string): Promise<unknown>
+```
+
+| 項目 | 内容 |
+|------|------|
+| 引数 | `sql` - 実行する SQL 文字列 |
+| 戻り値 | クエリ結果（Apache Arrow Table）。型は `unknown` |
+| タイムアウト | 60秒（60,000ms） |
+| 例外 | クエリ失敗時・タイムアウト時に throw |
+
+**処理フロー**:
+1. `getConnection()` でコネクションを取得
+2. `connection.query(sql)` を実行
+3. 60秒のタイムアウトと `Promise.race` で競合
+4. 結果を返す（またはエラーを throw）
+
+---
+
+### 3.7 `executeQueries(queries: string[]): Promise<unknown[]>`
+
+```typescript
+public async executeQueries(queries: string[]): Promise<unknown[]>
+```
+
+| 項目 | 内容 |
+|------|------|
+| 引数 | `queries` - SQL 文字列の配列 |
+| 戻り値 | 各クエリの結果を順番に格納した配列 |
+| 実行方法 | **逐次実行**（並列ではない） |
+
+> **重要**: クエリは配列の順番通りに1つずつ実行される。CREATE TABLE → INSERT → SELECT のように依存関係があるクエリ列に適している。
+
+---
+
+### 3.8 `createTableFromData<T>(tableName, data, options): Promise<void>`
+
+```typescript
+public async createTableFromData<T extends Record<string, unknown>>(
+    tableName: string,
+    data: T[],
+    options: {
+        dropIfExists?: boolean
+        primaryKey?: string
+        verbose?: boolean
+    } = {},
+): Promise<void>
+```
+
+JavaScript の配列データから DuckDB テーブルを作成する高レベルメソッド。
+
+#### 引数
+
+| 引数名 | 型 | 必須 | 説明 |
+|--------|------|------|------|
+| `tableName` | `string` | Yes | 作成するテーブル名 |
+| `data` | `T[]` | Yes | テーブルに投入するデータ配列（1行以上必須） |
+| `options.dropIfExists` | `boolean` | No | `true` の場合、既存テーブルを削除してから作成 |
+| `options.primaryKey` | `string` | No | 主キーとして設定するカラム名 |
+| `options.verbose` | `boolean` | No | ログ出力の有無（デフォルト: `true`） |
+
+#### 処理フロー
+
+```mermaid
+flowchart TD
+    A["createTableFromData(tableName, data, options)"] --> B{data が空配列?}
+    B -- Yes --> C["Error を throw"]
+    B -- No --> D{operationFlags に\n同名テーブルが進行中?}
+    D -- Yes --> E["スキップして return"]
+    D -- No --> F["operationFlags にフラグをセット"]
+    F --> G{dropIfExists === true?}
+    G -- Yes --> H["DROP TABLE IF EXISTS を実行"]
+    G -- No --> I1["SHOW TABLES（作成前の確認ログ）"]
+    H --> I1
+    I1 --> I2["型推定（inferColumnTypes）\n先頭100行→関数内部で先頭10行を使用"]
+    I2 --> J["CREATE TABLE 文を生成・実行"]
+    J --> J1["SHOW TABLES + information_schema\n（作成後の検証ログ）"]
+    J1 --> K["データを1000行ずつバッチ INSERT\nformatValueForSQL で値を変換"]
+    K --> L["operationFlags からフラグを削除（finally）"]
+```
+
+> **注意**: `SHOW TABLES` と `information_schema` による検証ステップは `verbose` が `true`（デフォルト）の場合にログ出力される。検証自体が失敗しても処理は続行される（`try/catch` で `warn` ログのみ）。
+
+#### 型推定ルール（`inferColumnTypes`）
+
+`createTableFromData` は先頭100行を `inferColumnTypes` に渡すが、`inferColumnTypes` 内部でさらに `data.slice(0, Math.min(data.length, 10))` で先頭10行に絞り込む。したがって**実効的なサンプルサイズは最大10行**。
+
+| JavaScript の値 | 推定される DuckDB 型 | 条件 |
+|----------------|---------------------|------|
+| `number`（整数） | `INTEGER` | `Number.isInteger()` が true かつ 32bit 範囲内 |
+| `number`（整数、大きい） | `BIGINT` | `Number.isInteger()` が true かつ 32bit 範囲外 |
+| `number`（小数） | `DOUBLE` | 整数でない number |
+| `boolean` | `BOOLEAN` | typeof === "boolean" |
+| `Date` オブジェクト | `TIMESTAMP` | `instanceof Date` |
+| `string`（日付形式） | `TIMESTAMP` | `new Date(value)` が有効かつ "-" を含む |
+| `string`（その他） | `VARCHAR` | 上記以外 |
+| `null` / `undefined` のみ | `VARCHAR` | 値がすべて null/undefined の場合のフォールバック |
+
+#### SQL 値フォーマットルール（`formatValueForSQL`）
+
+| JavaScript の値 | SQL 出力 | 補足 |
+|----------------|---------|------|
+| `null` / `undefined` | `NULL` | |
+| `string` | `'エスケープ済み文字列'` | シングルクォートは `''` にエスケープ |
+| `Date` | `'2024-01-01T00:00:00.000Z'` | ISO 8601 形式 |
+| `boolean` | `TRUE` / `FALSE` | |
+| `number` | `123` / `45.67` | そのまま文字列化 |
+| その他 | `String(value)` | |
+
+---
+
+### 3.9 `getTableInfo(tableName: string): Promise<unknown>`
+
+```typescript
+public async getTableInfo(tableName: string): Promise<unknown>
+```
+
+| 項目 | 内容 |
+|------|------|
+| 実行 SQL | `DESCRIBE {tableName}` |
+| 戻り値 | テーブルのカラム情報（名前、型、NULL 可否など） |
+
+---
+
+### 3.10 `listTables(): Promise<unknown>`
+
+```typescript
+public async listTables(): Promise<unknown>
+```
+
+| 項目 | 内容 |
+|------|------|
+| 実行 SQL | `SHOW TABLES` |
+| 戻り値 | 現在のデータベースに存在するテーブル一覧 |
+
+---
+
+### 3.11 `isReady(): boolean`
+
+```typescript
+public isReady(): boolean
+```
+
+| 項目 | 内容 |
+|------|------|
+| 戻り値 | `workerInstance !== null` の場合 `true` |
+| 用途 | 同期的に初期化完了を確認したい場合 |
+
+---
+
+### 3.12 `cleanup(): Promise<void>`
+
+```typescript
+public async cleanup(): Promise<void>
+```
+
+リソースの完全な解放を行う。
+
+| ステップ | 処理 |
+|---------|------|
+| 1 | コネクションを close |
+| 2 | Worker を terminate |
+| 3 | すべての内部状態をリセット |
+| 4 | リスナーと operationFlags をクリア |
+
+> **注意**: cleanup 後に再度 `initialize()` を呼べば再初期化できる。
+
+---
+
+### 3.13 `resetInstance(): void` (static)
+
+```typescript
+public static resetInstance(): void
+```
+
+| 項目 | 内容 |
+|------|------|
+| 用途 | テスト時にシングルトンをリセットする |
+| 動作 | `cleanup()` を呼び出し（**await しない**）、直後に `instance = null` にする |
+
+> **注意**: `cleanup()` は `async` メソッドだが、`resetInstance()` は同期メソッド（`void`）であり `cleanup()` を await しない。コネクションの close や Worker の terminate が完了する前にインスタンスが `null` になる。テストで確実にリソースを解放したい場合は、`resetInstance()` の前に `await DuckDBService.getInstance().cleanup()` を明示的に呼ぶこと。
+
+---
+
+### 3.14 ステータスリスナー
+
+```typescript
+public addStatusListener(listener: () => void): void
+public removeStatusListener(listener: () => void): void
+```
+
+| メソッド | 説明 |
+|---------|------|
+| `addStatusListener` | ステータス変更時に呼ばれるコールバックを登録 |
+| `removeStatusListener` | 登録済みコールバックを削除 |
+
+リスナーが呼ばれるタイミング:
+- `initialize()` 開始時（→ `"initializing"`）
+- `initialize()` 成功時（→ `"ready"`）
+- `initialize()` 失敗時（→ `"error"`）
+
+## 4. エクスポート
+
+`services/duckdb.ts` のエクスポート:
+
+```typescript
+// 名前付きエクスポート（クラス本体）
+export { DuckDBService }
+
+// デフォルトエクスポート（シングルトンインスタンス）— services/duckdb.ts 内でのみ default
+export default DuckDBService.getInstance()
+```
+
+`index.ts` での re-export:
+
+```typescript
+export { DuckDBService, default as duckDBService } from "./services/duckdb"
+```
+
+> **注意**: `services/duckdb.ts` はデフォルトエクスポートを持つが、`index.ts` はそれを `duckDBService` という**名前付きエクスポート**として re-export する。パッケージ自体にデフォルトエクスポートは存在しない。
+
+| エクスポート | インポート方法 | 用途 |
+|------------|--------------|------|
+| `DuckDBService`（クラス） | `import { DuckDBService } from '...'` | `getInstance()` や `resetInstance()` を呼びたい場合 |
+| `duckDBService`（インスタンス） | `import { duckDBService } from '...'` | 通常利用。シングルトンインスタンスを直接使う |
+
+## 5. ステータス遷移図
+
+```mermaid
+stateDiagram-v2
+    state "not-initialized" as not_init
+    [*] --> not_init
+    not_init --> initializing : initialize()
+    initializing --> ready : 成功
+    initializing --> error : 失敗
+    ready --> not_init : cleanup()
+    error --> initializing : initialize()（リトライ）
+    error --> not_init : cleanup()
+```
+
+## 6. 新人向けポイント
+
+1. **`import { duckDBService } from '@aiquants/duckdb-helper'` が最も簡単な使い方**。シングルトンインスタンスがそのまま使える。
+2. **`initialize()` は何回呼んでも安全**。既に初期化済みならすぐ返る。初期化中なら同じ Promise を返す。
+3. **コネクションは自動で再利用される**。`getConnection()` を何度呼んでも、内部では1つのコネクションが使い回される。
+4. **`createTableFromData` が便利**。JavaScript の配列をそのまま DuckDB テーブルにできる。型推定も自動。
+5. **テスト時は `DuckDBService.resetInstance()` でリセット**できる。テスト間の状態汚染を防げる。
+6. **splink_udfs の失敗は無視される**。名寄せ機能が不要な環境でもエラーにならない。