@aiquants/duckdb-helper 1.4.0 → 1.5.0

package/docs/specs/2026.04.11 [AI] 03-hooks.md

@@ -0,0 +1,298 @@
+# React Hooks 詳細仕様書
+
+> ソースファイル: `src/hooks/useDuckDB.ts`
+
+## 1. 概要
+
+React コンポーネントから DuckDB を利用するための2つのカスタムフックを提供する。
+
+| Hook 名 | 用途 | 難易度 |
+|---------|------|--------|
+| `useDuckDB` | DuckDB の初期化・状態管理・各種操作を提供する汎用フック | 中級 |
+| `useDuckDBQuery` | 単一 SQL クエリの実行と結果管理に特化した簡易フック | 初級 |
+
+## 2. `useDuckDB` フック
+
+### 2.1 シグネチャ
+
+```typescript
+export const useDuckDB = (autoInitialize = true): UseDuckDBResult
+```
+
+### 2.2 引数
+
+| 引数名 | 型 | デフォルト | 説明 |
+|--------|------|-----------|------|
+| `autoInitialize` | `boolean` | `true` | コンポーネントマウント時に自動で DuckDB を初期化するか |
+
+### 2.3 戻り値（`UseDuckDBResult`）
+
+```typescript
+export interface UseDuckDBResult {
+    status: "not-initialized" | "initializing" | "ready" | "error"
+    error: string | null
+    executeQuery: (sql: string) => Promise<unknown>
+    executeQueries: (queries: string[]) => Promise<unknown[]>
+    createTableFromData: <T extends Record<string, unknown>>(
+        tableName: string,
+        data: T[],
+        options?: {
+            dropIfExists?: boolean
+            primaryKey?: string
+            verbose?: boolean
+        },
+    ) => Promise<void>
+    getTableInfo: (tableName: string) => Promise<unknown>
+    listTables: () => Promise<unknown>
+    isReady: boolean
+    initialize: () => Promise<void>
+}
+```
+
+| プロパティ | 型 | 説明 |
+|-----------|------|------|
+| `status` | `string` | 現在の DuckDB ステータス（4種類） |
+| `error` | `string \| null` | エラーメッセージ。正常時は `null` |
+| `executeQuery` | `Function` | SQL を実行して結果を返す。`status !== "ready"` で throw |
+| `executeQueries` | `Function` | 複数 SQL を逐次実行。`status !== "ready"` で throw |
+| `createTableFromData` | `Function` | データ配列からテーブルを作成。`status !== "ready"` で throw |
+| `getTableInfo` | `Function` | テーブルの DESCRIBE 結果を返す。`status !== "ready"` で throw |
+| `listTables` | `Function` | SHOW TABLES の結果を返す。`status !== "ready"` で throw |
+| `isReady` | `boolean` | `status === "ready"` のショートカット |
+| `initialize` | `Function` | 手動で DuckDB を初期化する |
+
+### 2.4 内部動作の詳細
+
+#### ステータス同期の仕組み
+
+`useDuckDB` は2つの方法で `DuckDBService` のステータスを React の状態に同期する。
+
+**方法1: ステータスリスナー**
+```
+DuckDBService
+  ├── addStatusListener(updateStatus)  ← マウント時に登録
+  └── removeStatusListener(updateStatus) ← アンマウント時に解除
+```
+
+**方法2: ポーリング（フォールバック）**
+```
+setInterval(pollStatus, 1000)  ← 1秒ごとにステータスをチェック
+```
+
+> **なぜ2つの方法があるのか**: リスナーだけではステータス変更が漏れる可能性がある（例: 別のコンポーネントから直接サービスを操作した場合）。ポーリングは保険として機能する。
+
+**ポーリングのガード条件**（2つの条件を AND で結合）:
+```typescript
+if (currentStatus !== status && currentStatus !== "initializing") {
+    setStatus(currentStatus)
+}
+```
+1. `currentStatus !== status` — サービスの現在のステータスが React state と異なる場合のみ更新
+2. `currentStatus !== "initializing"` — サービスが `"initializing"` を返す場合は更新しない
+
+両方を満たした場合のみ React state が更新される。`"initializing"` への遷移はリスナー経由でのみ通知される。
+
+**SSR 環境での動作**: `typeof window === "undefined"` の場合（SSR / Node.js 環境）、`setInterval` は設定されず、`pollStatus` を1回だけ同期的に実行してから effect を終了する。ブラウザ環境でも `setInterval` 設定直後に `pollStatus()` が1回即時実行される。
+
+#### 自動初期化フロー
+
+```mermaid
+flowchart TD
+    A["コンポーネントマウント"] --> B{autoInitialize === true\nかつ status === 'not-initialized'?}
+    B -- Yes --> C["initialize() を呼び出し"]
+    C -- 成功 --> D["status が 'ready' に変わる"]
+    C -- 失敗 --> E["error にメッセージをセット"]
+    B -- No --> F["何もしない\n（手動で initialize() を呼ぶ必要がある）"]
+```
+
+#### 各操作関数の共通ガード
+
+`executeQuery`、`executeQueries`、`createTableFromData`、`getTableInfo`、`listTables` はすべて、実行前に以下のチェックを行う。
+
+```typescript
+if (status !== "ready") {
+    throw new Error("DuckDB is not ready. Please wait for initialization to complete.")
+}
+```
+
+> **重要**: `isReady` を確認してから操作関数を呼ぶのが安全なパターン。
+
+### 2.5 使用パターン
+
+#### パターン1: 自動初期化（推奨）
+
+```tsx
+const MyComponent = () => {
+    const { status, executeQuery, isReady, error } = useDuckDB()
+
+    if (error) return <p>Error: {error}</p>
+    if (!isReady) return <p>Loading DuckDB... ({status})</p>
+
+    return <button onClick={() => executeQuery("SELECT 1")}>Run</button>
+}
+```
+
+#### パターン2: 手動初期化
+
+```tsx
+const MyComponent = () => {
+    const { status, initialize, isReady } = useDuckDB(false)
+
+    const handleInit = async () => {
+        await initialize()
+    }
+
+    return (
+        <div>
+            <p>Status: {status}</p>
+            {!isReady && <button onClick={handleInit}>Initialize</button>}
+        </div>
+    )
+}
+```
+
+#### パターン3: テーブル作成
+
+```tsx
+const DataLoader = ({ data }: { data: Record<string, unknown>[] }) => {
+    const { createTableFromData, isReady } = useDuckDB()
+
+    useEffect(() => {
+        if (isReady && data.length > 0) {
+            createTableFromData("my_table", data, { dropIfExists: true })
+        }
+    }, [isReady, data, createTableFromData])
+
+    return <p>Loading data...</p>
+}
+```
+
+---
+
+## 3. `useDuckDBQuery` フック
+
+### 3.1 シグネチャ
+
+```typescript
+export const useDuckDBQuery = <T = unknown>(
+    sql: string,
+    dependencies: DependencyList = [],
+): {
+    data: T | null
+    loading: boolean
+    error: string | null
+    refetch: () => Promise<void>
+}
+```
+
+### 3.2 引数
+
+| 引数名 | 型 | デフォルト | 説明 |
+|--------|------|-----------|------|
+| `sql` | `string` | (必須) | 実行する SQL クエリ |
+| `dependencies` | `DependencyList` | `[]` | この配列の値が変わるとクエリが再実行される |
+
+### 3.3 戻り値
+
+| プロパティ | 型 | 説明 |
+|-----------|------|------|
+| `data` | `T \| null` | クエリ結果。未実行・エラー時は `null` |
+| `loading` | `boolean` | クエリ実行中は `true` |
+| `error` | `string \| null` | エラーメッセージ。正常時は `null` |
+| `refetch` | `() => Promise<void>` | クエリを手動で再実行する関数 |
+
+### 3.4 内部動作
+
+```mermaid
+flowchart TD
+    A["useDuckDBQuery(sql, dependencies)"] --> B["内部で useDuckDB() を呼び出し\n（自動初期化）"]
+    B --> C["refetch 関数を定義"]
+    C --> D{"!(isReady && sql.trim())\nガード条件（単一複合条件）"}
+    D -- "true\n(未準備 or 空SQL)" --> E["何もしない（return）"]
+    D -- "false\n(準備完了 かつ 有効SQL)" --> G["executeQuery(sql) を実行"]
+    G -- 成功 --> H["data にセット"]
+    G -- 失敗 --> I["error にメッセージをセット"]
+    C --> J["useEffect で refetch を自動実行\nトリガー: refetch参照変更 + dependencies変更"]
+```
+
+### 3.5 再実行のタイミング
+
+以下のいずれかが変わるとクエリが再実行される:
+
+1. `sql` 文字列が変更された
+2. `dependencies` 配列の要素が変更された
+3. `isReady` が `false` → `true` に変わった（初期化完了）
+4. `refetch()` を手動で呼んだ
+
+### 3.6 使用パターン
+
+#### パターン1: 基本的なデータ取得
+
+```tsx
+const UserList = () => {
+    const { data, loading, error } = useDuckDBQuery<UserTable>(
+        "SELECT * FROM users LIMIT 100"
+    )
+
+    if (loading) return <p>Loading...</p>
+    if (error) return <p>Error: {error}</p>
+    if (!data) return <p>No data</p>
+
+    const rows = duckdbTableToArray<User>(data)
+    return <ul>{rows.map(u => <li key={u.id}>{u.name}</li>)}</ul>
+}
+```
+
+#### パターン2: パラメータ付きクエリ
+
+```tsx
+const UserDetail = ({ userId }: { userId: number }) => {
+    const { data, loading, error } = useDuckDBQuery(
+        `SELECT * FROM users WHERE id = ${userId}`,
+        [userId]  // userId が変わるとクエリが再実行される
+    )
+
+    if (loading) return <p>Loading...</p>
+    if (error) return <p>Error: {error}</p>
+
+    return <pre>{JSON.stringify(data)}</pre>
+}
+```
+
+#### パターン3: 手動リフェッチ
+
+```tsx
+const Dashboard = () => {
+    const { data, loading, refetch } = useDuckDBQuery(
+        "SELECT COUNT(*) as total FROM orders"
+    )
+
+    return (
+        <div>
+            <p>Total: {JSON.stringify(data)}</p>
+            <button onClick={refetch} disabled={loading}>
+                Refresh
+            </button>
+        </div>
+    )
+}
+```
+
+## 4. 2つの Hook の使い分け
+
+| 判断基準 | `useDuckDB` | `useDuckDBQuery` |
+|---------|-------------|------------------|
+| 単一クエリの取得だけ | | 推奨 |
+| 複数クエリを実行したい | 推奨 | |
+| テーブルを作成したい | 推奨 | |
+| 初期化タイミングを制御したい | 推奨 | |
+| DuckDB のステータスを細かく監視 | 推奨 | |
+| 最もシンプルに使いたい | | 推奨 |
+
+## 5. 新人向けポイント
+
+1. **まずは `useDuckDBQuery` から試そう**。SQL を渡すだけで結果が `data` に入る。
+2. **`isReady` のチェックを忘れずに**。DuckDB の初期化には数秒かかるため、初期化前に操作すると例外が発生する。
+3. **`dependencies` は React の `useEffect` の依存配列と同じ考え方**。中の値が変われば再実行される。
+4. **`useDuckDB` の操作関数はすべて `useCallback` でメモ化されている**。子コンポーネントに props として渡してもパフォーマンス問題は起きにくい。
+5. **1つの画面で複数の `useDuckDB` を呼んでもOK**。内部では同一のシングルトンサービスを共有する。

package/docs/specs/2026.04.11 [AI] 04-utils.md

@@ -0,0 +1,220 @@
+# ユーティリティ関数仕様書
+
+> ソースファイル: `src/utils/duckdb-helpers.ts`
+
+## 1. 概要
+
+DuckDB のクエリ結果（Apache Arrow Table）を JavaScript で扱いやすい形に変換するためのユーティリティ関数群。
+すべての関数は `unknown` 型の入力を安全に処理し、不正な値に対してはデフォルト値を返す（例外を投げない）。
+
+## 2. 関数一覧
+
+| 関数名 | 戻り値 | 説明 |
+|--------|--------|------|
+| `duckdbTableToArray<T>` | `T[]` | クエリ結果を型付き配列に変換 |
+| `getDuckDBRowCount` | `number` | クエリ結果の行数を取得 |
+| `getDuckDBColumnCount` | `number` | クエリ結果の列数を取得 |
+| `isDuckDBTable` | `boolean` | 結果が有効な DuckDB テーブルか判定（型ガード） |
+
+## 3. 各関数の詳細仕様
+
+### 3.1 `duckdbTableToArray<T>(result: unknown): T[]`
+
+クエリ結果を JavaScript の型付き配列に変換する。
+
+#### シグネチャ
+
+```typescript
+export const duckdbTableToArray = <T>(result: unknown): T[]
+```
+
+#### 引数
+
+| 引数名 | 型 | 説明 |
+|--------|------|------|
+| `result` | `unknown` | `executeQuery()` の戻り値（Apache Arrow Table） |
+
+#### 戻り値
+
+| 条件 | 戻り値 |
+|------|--------|
+| `result` が null/undefined | `[]`（空配列） |
+| `result` がオブジェクトでない | `[]`（空配列） |
+| `result` に `toArray` メソッドがない | `[]`（空配列） |
+| `result` に `toArray` メソッドがある | `result.toArray()` の結果を `T[]` として返す |
+
+#### 処理フロー
+
+```mermaid
+flowchart TD
+    A["duckdbTableToArray(result)"] --> B{result が null/undefined?}
+    B -- Yes --> C["[] を返す"]
+    B -- No --> D{result が object?}
+    D -- No --> C
+    D -- Yes --> E{toArray メソッドがある?}
+    E -- No --> C
+    E -- Yes --> F["result.toArray() を T[] として返す"]
+```
+
+#### 使用例
+
+```typescript
+import { duckdbTableToArray, duckDBService } from '@aiquants/duckdb-helper'
+
+interface StockPrice {
+    ticker: string
+    price: number
+    date: string
+}
+
+const result = await duckDBService.executeQuery("SELECT * FROM stock_prices LIMIT 10")
+
+// 型パラメータを指定して安全に変換
+const rows: StockPrice[] = duckdbTableToArray<StockPrice>(result)
+
+// rows[0].ticker  ← IDE の補完が効く
+// rows[0].price   ← number 型として扱える
+```
+
+---
+
+### 3.2 `getDuckDBRowCount(result: unknown): number`
+
+クエリ結果の行数を取得する。
+
+#### シグネチャ
+
+```typescript
+export const getDuckDBRowCount = (result: unknown): number
+```
+
+#### 戻り値
+
+| 条件 | 戻り値 |
+|------|--------|
+| `result` が null/undefined | `0` |
+| `result` がオブジェクトでない | `0` |
+| `result` に `numRows` プロパティがない | `0` |
+| `result.numRows` が number でない | `0` |
+| 上記以外 | `result.numRows` の値 |
+
+#### 使用例
+
+```typescript
+import { getDuckDBRowCount, duckDBService } from '@aiquants/duckdb-helper'
+
+const result = await duckDBService.executeQuery("SELECT * FROM users")
+const count = getDuckDBRowCount(result) // 例: 42
+console.log(`${count} 件のデータがあります`)
+```
+
+---
+
+### 3.3 `getDuckDBColumnCount(result: unknown): number`
+
+クエリ結果の列数を取得する。
+
+#### シグネチャ
+
+```typescript
+export const getDuckDBColumnCount = (result: unknown): number
+```
+
+#### 戻り値
+
+| 条件 | 戻り値 |
+|------|--------|
+| `result` が null/undefined | `0` |
+| `result` がオブジェクトでない | `0` |
+| `result` に `numCols` プロパティがない | `0` |
+| `result.numCols` が number でない | `0` |
+| 上記以外 | `result.numCols` の値 |
+
+#### 使用例
+
+```typescript
+import { getDuckDBColumnCount, duckDBService } from '@aiquants/duckdb-helper'
+
+const result = await duckDBService.executeQuery("SELECT id, name, email FROM users")
+const cols = getDuckDBColumnCount(result) // 3
+```
+
+---
+
+### 3.4 `isDuckDBTable(result: unknown): result is DuckDBQueryResult`
+
+結果が有効な DuckDB テーブルかどうかを判定する **TypeScript 型ガード**関数。
+
+#### シグネチャ
+
+```typescript
+export const isDuckDBTable = (result: unknown): result is DuckDBQueryResult
+```
+
+#### 判定条件（すべて満たす必要がある）
+
+| 条件 | 説明 |
+|------|------|
+| `result` が null/undefined でない | |
+| `result` が object である | |
+| `result` に `toArray` キーが存在する | `"toArray" in result`（存在チェック） |
+| `result.toArray` が関数である | `typeof result.toArray === "function"`（型チェック） |
+| `result` に `numRows` キーが存在する | `"numRows" in result`（存在チェック） |
+| `result.numRows` が数値である | `typeof result.numRows === "number"`（型チェック） |
+
+> **注意**: `numCols` は判定条件に含まれない。`toArray` と `numRows` の2つのプロパティのみで判定する。
+
+#### 型ガードとしての効果
+
+```typescript
+import { isDuckDBTable, duckDBService } from '@aiquants/duckdb-helper'
+
+const result: unknown = await duckDBService.executeQuery("SELECT 1")
+
+if (isDuckDBTable(result)) {
+    // ここでは result の型が DuckDBQueryResult に絞り込まれる
+    const rows = result.toArray()    // OK: toArray() が使える（実行時に検証済み）
+    const count = result.numRows     // OK: numRows にアクセスできる（実行時に検証済み）
+    const cols = result.numCols      // 型定義上アクセス可能だが、isDuckDBTable は numCols を検証しない
+}
+```
+
+#### なぜ型ガードが必要か
+
+`DuckDBService.executeQuery()` の戻り値は `unknown` 型。TypeScript の型安全性を維持するため、使用前に型を絞り込む必要がある。`isDuckDBTable` を使うと `if` ブロック内で安全にプロパティにアクセスできる。
+
+## 4. 設計方針
+
+### 4.1 防御的プログラミング
+
+すべての関数は以下の方針で設計されている。
+
+1. **例外を投げない**: 不正な入力に対してはデフォルト値（`[]`, `0`, `false`）を返す
+2. **null/undefined 安全**: 最初に null チェックを行う
+3. **型チェック**: `typeof` と `in` 演算子で段階的に型を検証する
+
+### 4.2 なぜ `unknown` を受け取るのか
+
+`DuckDBService.executeQuery()` の戻り値が `unknown` なので、ヘルパー関数も `unknown` を受け取る設計になっている。これにより:
+
+- `executeQuery()` の結果をそのまま渡せる
+- キャストなしで安全に型変換できる
+- 不正な値が渡されてもランタイムエラーにならない
+
+## 5. 他モジュールとの関係
+
+```mermaid
+flowchart LR
+    A["executeQuery()"] -- "unknown" --> B["isDuckDBTable()\n型ガードで検証"]
+    A --> C["duckdbTableToArray&lt;T&gt;()\nT[] に変換"]
+    A --> D["getDuckDBRowCount()\n行数を取得"]
+    A --> E["getDuckDBColumnCount()\n列数を取得"]
+    B -- "DuckDBQueryResult" --> F["型安全に利用"]
+```
+
+## 6. 新人向けポイント
+
+1. **`duckdbTableToArray` が最もよく使う関数**。クエリ結果を JavaScript の配列にするにはこれを使う。
+2. **型パラメータ `<T>` は省略可能**。省略すると `unknown[]` になるが、できるだけ指定しよう。
+3. **`isDuckDBTable` は条件分岐で使う**。結果が有効かどうか事前にチェックしたい場合に便利。
+4. **すべての関数は安全**。何を渡してもクラッシュしない。ただしゴミデータを渡せば空配列や `0` が返るだけ。