@aiquants/duckdb-helper 1.4.0 → 1.5.0

package/docs/guides/2026.04.11 [AI] development.md

@@ -0,0 +1,291 @@
+# @aiquants/duckdb-helper 開発ガイド
+
+このガイドは、`@aiquants/duckdb-helper` パッケージの開発・保守・改修を行う開発者向けです。
+
+## 1. 開発環境のセットアップ
+
+### 前提条件
+
+| ツール | バージョン |
+|--------|-----------|
+| Node.js | >= 16.0.0 |
+| pnpm | >= 8.0.0 |
+
+### 初回セットアップ
+
+```bash
+# リポジトリルートで依存をインストール
+pnpm install
+
+# パッケージディレクトリに移動
+cd packages/duckdb-helper
+
+# ビルド確認
+pnpm run build
+
+# 型チェック
+pnpm run type-check
+```
+
+## 2. 開発ワークフロー
+
+### 日常的なコマンド
+
+| やりたいこと | コマンド |
+|-------------|---------|
+| ビルド | `pnpm run build` |
+| ウォッチモードで開発 | `pnpm run dev` |
+| 型チェック | `pnpm run type-check` |
+| Lint | `pnpm run lint` |
+| Lint の自動修正 | `pnpm run lint:fix` |
+| フォーマット | `pnpm run format` |
+| フォーマットの自動修正 | `pnpm run format:fix` |
+| Lint + フォーマット | `pnpm run check` |
+| Lint + フォーマットの自動修正 | `pnpm run check:fix` |
+| テスト | `pnpm run test` |
+| テスト（カバレッジ付き） | `pnpm run test:coverage` |
+| ライセンスチェック | `pnpm run license-check` |
+
+### 開発中の推奨フロー
+
+```bash
+# ターミナル1: ウォッチモードでビルド
+pnpm run dev
+
+# ターミナル2: 必要に応じてテスト
+pnpm run test
+
+# コミット前に
+pnpm run check:fix && pnpm run type-check
+```
+
+## 3. ディレクトリ構成と役割
+
+```
+src/
+├── index.ts                  # エントリーポイント
+│                             # → 公開 API をここで管理する
+│                             # → 新しいエクスポートを追加する際はここに追記
+│
+├── hooks/
+│   └── useDuckDB.ts          # React Hooks
+│                             # → React 固有のロジックはここに書く
+│                             # → サービス層の薄いラッパー
+│
+├── services/
+│   └── duckdb.ts             # DuckDBService（コアロジック）
+│                             # → DuckDB の初期化・クエリ実行など
+│                             # → React に依存しない純粋なサービス
+│
+├── types/
+│   └── duckdb.ts             # 型定義
+│                             # → インターフェースと型エイリアス
+│
+└── utils/
+    ├── duckdb-helpers.ts     # ヘルパー関数
+    │                         # → クエリ結果の変換・検証ユーティリティ
+    │
+    └── simple-logger.ts      # ロガー
+                              # → ライブラリ内部のログ管理
+```
+
+### ファイルの責務境界
+
+| 変更したい内容 | 編集するファイル |
+|---------------|----------------|
+| DuckDB の初期化方法を変えたい | `services/duckdb.ts` の `internalInitializeWorker()` |
+| 新しい DuckDB 拡張を追加したい | `services/duckdb.ts` の `internalInitializeWorker()` |
+| クエリ実行のタイムアウトを変更したい | `services/duckdb.ts` の `executeQuery()` 内の `TIMEOUT_MS` |
+| 型推定ロジックを改善したい | `services/duckdb.ts` の `inferColumnTypes()` |
+| React Hook の API を変えたい | `hooks/useDuckDB.ts` |
+| 新しいヘルパー関数を追加したい | `utils/duckdb-helpers.ts` + `index.ts` にエクスポート追加 |
+| ログレベルのデフォルトを変えたい | `utils/simple-logger.ts` の static instance |
+| 公開 API を追加したい | `index.ts` にエクスポートを追記 |
+
+## 4. コードの読み方ガイド
+
+### DuckDBService を理解する順序
+
+1. **`getStatus()`** を読む → ステータスの4状態を理解する
+2. **`initialize()`** を読む → 重複防止とタイムアウトの仕組みを理解する
+3. **`internalInitializeWorker()`** を読む → 実際の WASM 初期化の流れを理解する
+4. **`getConnection()`** を読む → コネクションの遅延初期化を理解する
+5. **`executeQuery()`** を読む → クエリ実行とタイムアウトを理解する
+6. **`createTableFromData()`** を読む → 型推定とバッチ INSERT を理解する
+
+### useDuckDB を理解する順序
+
+1. **`UseDuckDBResult` インターフェース** を読む → 戻り値の全体像を把握する
+2. **`useDuckDB` 関数** の useState/useEffect を読む → ステータス同期の仕組みを理解する
+3. **各操作関数（executeQuery 等）** を読む → すべて `useCallback` でメモ化されていることを確認する
+4. **`useDuckDBQuery`** を読む → `useDuckDB` の上に構築されたシンプルなフック
+
+## 5. 新機能の追加手順
+
+### 例: 新しいヘルパー関数を追加する
+
+**ステップ1**: `src/utils/duckdb-helpers.ts` に関数を追加
+
+```typescript
+/**
+ * Get first N rows from DuckDB result
+ * DuckDB 結果から最初の N 行を取得します
+ */
+export const getFirstRows = <T>(result: unknown, count: number): T[] => {
+    const rows = duckdbTableToArray<T>(result)
+    return rows.slice(0, count)
+}
+```
+
+**ステップ2**: `src/index.ts` にエクスポートを追加
+
+```typescript
+export {
+    duckdbTableToArray,
+    getDuckDBColumnCount,
+    getDuckDBRowCount,
+    isDuckDBTable,
+    getFirstRows,  // ← 追加
+} from "./utils/duckdb-helpers"
+```
+
+**ステップ3**: テストを追加
+
+```typescript
+// tests/unit/duckdb-helpers.test.ts
+import { describe, expect, it } from "vitest"
+import { getFirstRows } from "../../src/utils/duckdb-helpers"
+
+describe("getFirstRows", () => {
+    it("should return first N rows", () => {
+        const mockResult = {
+            toArray: () => [{ id: 1 }, { id: 2 }, { id: 3 }],
+            numRows: 3,
+            numCols: 1,
+        }
+        expect(getFirstRows(mockResult, 2)).toEqual([{ id: 1 }, { id: 2 }])
+    })
+})
+```
+
+**ステップ4**: ビルド・テスト・型チェック
+
+```bash
+pnpm run type-check && pnpm run test && pnpm run build
+```
+
+## 6. テストのガイドライン
+
+### テストフレームワーク
+
+- **Vitest** を使用
+- 設定は `vitest.config.ts`（またはデフォルト設定）
+
+### テストの分類
+
+| ディレクトリ | 種類 | 説明 |
+|-------------|------|------|
+| `tests/unit/` | 単体テスト | 個々の関数・クラスのテスト |
+| `tests/integration/` | 統合テスト | 複数モジュールの連携テスト |
+
+### テスト時の注意
+
+- DuckDB-WASM はブラウザ環境が必要なため、Service のフルテストはブラウザテストランナーが必要
+- ユーティリティ関数（`duckdb-helpers.ts`）は Node.js 環境でテスト可能
+- React Hooks のテストには `@testing-library/react` の使用を推奨
+
+## 7. リリース手順
+
+### バージョンアップ
+
+```bash
+# パッチ版 (1.4.1 → 1.4.2): バグ修正
+pnpm run publish:patch
+
+# マイナー版 (1.4.1 → 1.5.0): 機能追加（後方互換あり）
+pnpm run publish:minor
+
+# メジャー版 (1.4.1 → 2.0.0): 破壊的変更
+pnpm run publish:major
+```
+
+### リリース前チェックリスト
+
+- [ ] 型チェックが通ること（`pnpm run type-check`）
+- [ ] テストが通ること（`pnpm run test`）
+- [ ] Lint エラーがないこと（`pnpm run check`）
+- [ ] ビルドが成功すること（`pnpm run build`）
+- [ ] ライセンスチェックが通ること（`pnpm run license-check`）
+- [ ] `index.ts` のエクスポートが正しいこと
+- [ ] 破壊的変更がある場合はメジャーバージョンアップ
+
+### `prepublishOnly` スクリプト
+
+`pnpm publish` 実行時に自動で以下が実行される:
+
+```text
+clean → typecheck → test(--if-present) → build
+```
+
+`test` は `--if-present` フラグ付きで実行されるため、テストスクリプトが定義されていない場合はスキップされる。それ以外のステップが失敗すると公開は中断される。
+
+## 8. アーキテクチャ上の注意点
+
+### シングルトンの影響
+
+`DuckDBService` はシングルトンなので:
+
+- アプリ全体で1つの DuckDB インスタンスを共有する
+- テスト間で状態が残る可能性がある → `DuckDBService.resetInstance()` でリセット
+- SSR 環境では Web Worker が使えないため初期化に失敗する
+
+### コネクションの共有
+
+- `getConnection()` は1つのコネクションを返す
+- 複数のコンポーネントが同時にクエリを実行しても、内部では同一コネクションが使われる
+- DuckDB-WASM は単一コネクションでの逐次実行を前提としている
+
+### メモリ管理
+
+- WASM インスタンスはメモリを消費する
+- 不要になったら `cleanup()` でリソースを解放する
+- テーブルデータは DuckDB の内部メモリに保持される
+
+## 9. よくある質問
+
+### Q: 新しい DuckDB 拡張を追加するには？
+
+`services/duckdb.ts` の `internalInitializeWorker()` 内、splink_udfs のインストール箇所の後に追加する:
+
+```typescript
+try {
+    await connection.query("INSTALL 拡張名 FROM community;")
+    await connection.query("LOAD 拡張名;")
+    Logger.info("✅ 拡張名 loaded")
+} catch (error) {
+    Logger.warn("⚠️ Failed to load 拡張名:", error)
+}
+```
+
+### Q: Logger を公開 API にしたい
+
+`src/index.ts` にエクスポートを追加する:
+
+```typescript
+export { Logger, LogLevel } from "./utils/simple-logger"
+export type { ILogger } from "./utils/simple-logger"
+```
+
+### Q: React なしで使いたい
+
+`DuckDBService` は React に依存していないので、そのまま使える:
+
+```typescript
+import { DuckDBService } from '@aiquants/duckdb-helper'
+
+const service = DuckDBService.getInstance()
+await service.initialize()
+const result = await service.executeQuery('SELECT 1')
+```
+
+React はオプショナルなピア依存なので、インストールしなくてもパッケージの利用は可能。

package/docs/guides/2026.04.11 [AI] getting-started.md

@@ -0,0 +1,278 @@
+# @aiquants/duckdb-helper 入門ガイド
+
+このガイドは、`@aiquants/duckdb-helper` を初めて使う開発者向けのステップバイステップの導入手順書です。
+
+## 前提知識
+
+- TypeScript / JavaScript の基本
+- React の基本（Hooks の概念）
+- SQL の基本構文
+
+## 1. DuckDB とは
+
+DuckDB は高速な列指向の分析用データベースエンジンです。通常はサーバーで動作しますが、**DuckDB-WASM** を使うとブラウザ上で直接 SQL を実行できます。
+
+このライブラリは、DuckDB-WASM のセットアップと利用を簡単にするためのヘルパーです。
+
+## 2. インストール
+
+```bash
+# pnpm（推奨）
+pnpm add @aiquants/duckdb-helper
+
+# npm
+npm install @aiquants/duckdb-helper
+
+# yarn
+yarn add @aiquants/duckdb-helper
+```
+
+React Hooks を使う場合は、React 18 以上が必要です。
+
+```bash
+pnpm add react react-dom
+```
+
+## 3. 最初のクエリを実行する
+
+### 3.1 サービスを直接使う方法（React なし）
+
+```typescript
+import { duckDBService, duckdbTableToArray } from '@aiquants/duckdb-helper'
+
+async function main() {
+    // ステップ1: DuckDB を初期化する
+    // （WASM のダウンロードがあるため、初回は数秒かかる）
+    await duckDBService.initialize()
+
+    // ステップ2: SQL を実行する
+    const result = await duckDBService.executeQuery('SELECT 42 AS answer')
+
+    // ステップ3: 結果を JavaScript 配列に変換する
+    const rows = duckdbTableToArray<{ answer: number }>(result)
+
+    console.log(rows)
+    // → [{ answer: 42 }]
+}
+
+main()
+```
+
+### 3.2 React Hook を使う方法（推奨）
+
+```tsx
+import { useDuckDBQuery, duckdbTableToArray } from '@aiquants/duckdb-helper'
+
+interface QueryResult {
+    answer: number
+}
+
+const MyFirstComponent = () => {
+    // SQL を渡すだけで自動的に初期化 → 実行 → 結果取得
+    const { data, loading, error } = useDuckDBQuery<unknown>(
+        'SELECT 42 AS answer'
+    )
+
+    if (loading) return <p>読み込み中...</p>
+    if (error)   return <p>エラー: {error}</p>
+    if (!data)   return <p>データなし</p>
+
+    const rows = duckdbTableToArray<QueryResult>(data)
+
+    return (
+        <div>
+            <h1>初めてのクエリ結果</h1>
+            <p>答え: {rows[0]?.answer}</p>
+        </div>
+    )
+}
+```
+
+## 4. データをテーブルに投入する
+
+JavaScript の配列データを DuckDB テーブルとして登録し、SQL で分析できます。
+
+```tsx
+import { useDuckDB, duckdbTableToArray } from '@aiquants/duckdb-helper'
+import { useEffect, useState } from 'react'
+
+// サンプルデータ
+const sampleData = [
+    { id: 1, name: '田中太郎', age: 30, department: '開発' },
+    { id: 2, name: '鈴木花子', age: 25, department: '営業' },
+    { id: 3, name: '佐藤次郎', age: 35, department: '開発' },
+    { id: 4, name: '高橋美咲', age: 28, department: '人事' },
+]
+
+const DataAnalysis = () => {
+    const { isReady, createTableFromData, executeQuery } = useDuckDB()
+    const [result, setResult] = useState<string>('')
+
+    useEffect(() => {
+        const analyze = async () => {
+            if (!isReady) return
+
+            // ステップ1: データをテーブルとして作成
+            await createTableFromData('employees', sampleData, {
+                dropIfExists: true,  // 既存テーブルがあれば削除
+            })
+
+            // ステップ2: SQL で分析
+            const queryResult = await executeQuery(
+                'SELECT department, COUNT(*) as count, AVG(age) as avg_age FROM employees GROUP BY department'
+            )
+
+            const rows = duckdbTableToArray<{
+                department: string
+                count: number
+                avg_age: number
+            }>(queryResult)
+
+            setResult(JSON.stringify(rows, null, 2))
+        }
+
+        analyze()
+    }, [isReady, createTableFromData, executeQuery])
+
+    return (
+        <div>
+            <h1>部署別分析</h1>
+            <pre>{result || '分析中...'}</pre>
+        </div>
+    )
+}
+```
+
+## 5. 初期化の仕組みを理解する
+
+DuckDB の初期化には以下のステップがあり、**初回は数秒かかります**。
+
+```
+1. CDN から WASM バンドルをダウンロード
+2. ブラウザに最適なバンドルを自動選択
+3. Web Worker を作成
+4. WASM モジュールを読み込み
+5. splink_udfs 拡張をインストール（オプション）
+```
+
+### ステータスの遷移
+
+```mermaid
+stateDiagram-v2
+    state "not-initialized" as not_init
+    [*] --> not_init
+    not_init --> initializing : initialize()
+    initializing --> ready : 成功
+    initializing --> error : 失敗
+```
+
+### 初期化を待つパターン
+
+```tsx
+const MyComponent = () => {
+    const { status, isReady, error } = useDuckDB()
+
+    // ステータスに応じた UI の出し分け
+    switch (status) {
+        case 'not-initialized':
+            return <p>待機中...</p>
+        case 'initializing':
+            return <p>DuckDB を準備しています...</p>
+        case 'error':
+            return <p>エラーが発生しました: {error}</p>
+        case 'ready':
+            return <p>準備完了！</p>
+    }
+}
+```
+
+## 6. よくあるパターン
+
+### パターン A: パラメータでクエリを変える
+
+```tsx
+const UserDetail = ({ userId }: { userId: number }) => {
+    const { data, loading } = useDuckDBQuery(
+        `SELECT * FROM users WHERE id = ${userId}`,
+        [userId]  // ← userId が変わるとクエリが再実行される
+    )
+
+    if (loading) return <p>読み込み中...</p>
+    // ...
+}
+```
+
+### パターン B: 複数クエリを順番に実行
+
+```typescript
+const { executeQueries } = useDuckDB()
+
+// CREATE → INSERT → SELECT を順番に実行
+const results = await executeQueries([
+    "CREATE TABLE temp (id INTEGER, value VARCHAR)",
+    "INSERT INTO temp VALUES (1, 'hello'), (2, 'world')",
+    "SELECT * FROM temp"
+])
+
+// results[2] が SELECT の結果
+```
+
+### パターン C: 手動で初期化タイミングを制御
+
+```tsx
+const LazyInit = () => {
+    const { initialize, status, isReady } = useDuckDB(false)  // false = 自動初期化しない
+
+    return (
+        <div>
+            <p>Status: {status}</p>
+            {!isReady && (
+                <button onClick={() => initialize()}>
+                    DuckDB を初期化する
+                </button>
+            )}
+        </div>
+    )
+}
+```
+
+## 7. トラブルシューティング
+
+### Q: 初期化が失敗する
+
+**原因**: ブラウザが Web Worker または WASM をサポートしていない、もしくはネットワークが CDN にアクセスできない。
+
+**対処**:
+1. ブラウザの DevTools コンソールでエラーを確認
+2. jsDelivr CDN（`cdn.jsdelivr.net`）へのアクセスが許可されているか確認
+3. CORS やプロキシの設定を確認
+
+### Q: クエリが "DuckDB is not ready" エラーになる
+
+**原因**: 初期化が完了する前にクエリを実行しようとしている。
+
+**対処**:
+```tsx
+// isReady をチェックしてから実行
+if (isReady) {
+    const result = await executeQuery('SELECT 1')
+}
+```
+
+### Q: 大量データの投入が遅い
+
+**対処**:
+- `createTableFromData` は内部で1000行ずつバッチ INSERT する
+- データが非常に大きい場合は、CSV/Parquet ファイルを直接読み込む DuckDB のネイティブ機能の使用を検討
+
+### Q: 初期化ログが表示されない
+
+**原因**: デフォルトのログレベルが `WARN` のため、`info` レベルのログは非表示。
+
+**対処**: `Logger` と `LogLevel` は現在公開 API としてエクスポートされておらず、`package.json` の `exports` にもサブパスが未定義のため、利用側から直接ログレベルを変更することはできない。ログレベル制御が必要な場合は、パッケージ側で `index.ts` にエクスポートを追加する対応が必要（詳細は [Logger 仕様書](../spec/2026.04.11%20%5BAI%5D%2005-logger.md) を参照）。
+
+## 8. 次のステップ
+
+- 各モジュールの詳細は [設計書](../spec/) を参照
+- API リファレンスは [useDuckDB.md](../useDuckDB.md) を参照
+- 開発・保守作業については [開発ガイド](./2026.04.11%20%5BAI%5D%20development.md) を参照