@aiquants/duckdb-helper 1.4.1 → 1.6.1

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

@@ -0,0 +1,287 @@
+# 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 内部動作の詳細
+
+#### ステータス同期の仕組み（v1.6.0 で push 型に一本化）
+
+`useDuckDB` は**ステータスリスナー（push 型）のみ**で `DuckDBService` のステータスを React の状態に同期する。
+
+```
+DuckDBService
+  ├── addStatusListener(updateStatus)  ← マウント時に登録し、updateStatus() を1回即時実行して初期値を取得
+  └── removeStatusListener(updateStatus) ← アンマウント時に解除
+```
+
+`DuckDBService` は状態遷移（initializing / ready / error）と `cleanup()` のたびに必ず `notifyListeners()` を呼ぶため、リスナーだけで全遷移を漏れなく受け取れる。
+
+> **v1.6.0 での変更（1秒ポーリングの撤去）**: 旧実装は上記リスナーに加えて `setInterval(pollStatus, 1000)` を各フックインスタンスに常設していた。`useDuckDBQuery` は内部で `useDuckDB()` を呼ぶため、`root.tsx` のアプリ全体マウントと合わせて **消費者ごとに永久 1 秒タイマー** が積み上がり、しかも push リスナーと完全に重複していた。リスナーで全遷移が届く以上ポーリングは不要と判断し、effect ごと削除した。
+
+**SSR 環境での動作**: リスナー登録は `useEffect` 内で行われ、SSR（サーバー）では effect が実行されないため副作用は発生しない。初期レンダリングの `status` は `"not-initialized"` となる。
+
+#### 自動初期化フロー
+
+```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()` を手動で呼んだ
+
+> **`data` は生の Arrow Table**: `data` は `executeQuery()` の戻り値そのもの（Apache Arrow Table）であり、**行配列ではない**。`.length` や `.map` は持たないため、行として扱うときは必ず `duckdbTableToArray<Row>(data)` で変換すること（型パラメータ `T` には行の型ではなく Arrow Table 相当の型を想定する）。単一クエリの型付き行配列がほしい場合は `useDuckDB().executeQuery()` + `duckdbTableToArray()` の組み合わせが明快。
+
+> **`dependencies` の扱い（v1.6.0）**: 内部では可変長の `dependencies` を effect の依存配列へ直接スプレッドせず、`Object.is` 比較で変化を検知する**固定サイズのバージョン番号**（`useDependencyVersion`）に変換して `[refetch, version]` を依存にする。これにより、レンダー間で `dependencies` の**長さが変わっても** React の「依存配列サイズ変更」エラーを起こさず、要素の変化（React と同じ参照比較）で再フェッチされる。
+
+### 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` が返るだけ。

package/docs/specs/2026.04.11 [AI] 05-logger.md

@@ -0,0 +1,186 @@
+# Logger 仕様書
+
+> ソースファイル: `src/utils/simple-logger.ts`
+
+## 1. 概要
+
+ライブラリ内部で使用するログ出力ユーティリティ。ログレベルによるフィルタリング、プレフィックス付与、カスタムロガー実装の差し替えが可能。
+
+## 2. ログレベル（`LogLevel` enum）
+
+```typescript
+export enum LogLevel {
+    DEBUG = 0,   // 最も詳細（開発中のデバッグ情報）
+    INFO  = 1,   // 一般的な情報（初期化ステップなど）
+    WARN  = 2,   // 警告（処理は継続するが注意が必要）
+    ERROR = 3,   // エラー（処理が失敗）
+    NONE  = 4,   // ログ出力なし
+}
+```
+
+| レベル | 数値 | 出力対象 | 用途例 |
+|--------|------|---------|--------|
+| `DEBUG` | 0 | debug, info, warn, error すべて出力 | 開発中のデバッグ |
+| `INFO` | 1 | info, warn, error を出力 | 初期化ステップの確認 |
+| `WARN` | 2 | warn, error のみ出力 | **デフォルト** |
+| `ERROR` | 3 | error のみ出力 | 本番環境での最小ログ |
+| `NONE` | 4 | 何も出力しない | テスト時のログ抑制 |
+
+**判定ルール**: `設定レベル <= メソッドのレベル` の場合にログが出力される。
+
+## 3. `ILogger` インターフェース
+
+```typescript
+export interface ILogger {
+    debug(message?: unknown, ...optionalParams: unknown[]): void
+    info(message?: unknown, ...optionalParams: unknown[]): void
+    warn(message?: unknown, ...optionalParams: unknown[]): void
+    error(message?: unknown, ...optionalParams: unknown[]): void
+}
+```
+
+`console` オブジェクトと互換のインターフェース。カスタムロガーを作る場合はこれを実装する。
+
+## 4. `Logger` クラス
+
+### 4.1 二重のAPI: インスタンスメソッドと静的メソッド
+
+`Logger` は2つの使い方ができる。
+
+| 使い方 | 対象 | 用途 |
+|--------|------|------|
+| **静的メソッド** | 内部のデフォルトインスタンス | ライブラリ内部での標準的な使用 |
+| **インスタンスメソッド** | 個別のインスタンス | カスタム設定が必要な場合 |
+
+```typescript
+// 静的メソッド（ライブラリ内部で使用）
+Logger.info("初期化開始")
+Logger.error("クエリ失敗:", error)
+
+// インスタンスメソッド（カスタム用途）
+const myLogger = new Logger(LogLevel.DEBUG, "[my-app]")
+myLogger.debug("デバッグ情報")
+```
+
+### 4.2 コンストラクタ
+
+```typescript
+constructor(
+    level: LogLevel = LogLevel.WARN,
+    prefix: string = "[duckdb-helper]",
+    impl: ILogger = console
+)
+```
+
+| 引数 | デフォルト | 説明 |
+|------|-----------|------|
+| `level` | `LogLevel.WARN` | 最小出力レベル |
+| `prefix` | `"[duckdb-helper]"` | ログメッセージの先頭に付与する文字列 |
+| `impl` | `console` | 実際のログ出力を行うオブジェクト |
+
+### 4.3 デフォルトインスタンス（static）
+
+```typescript
+private static instance: Logger = new Logger(LogLevel.WARN, "[duckdb-helper]")
+```
+
+- 静的メソッド（`Logger.info()` など）はこのインスタンスを使用する
+- デフォルトレベルは `WARN` なので、`info` や `debug` のログは出力されない
+- `DuckDBService` 内の初期化ログ（`Logger.info("🔧 Starting...")` など）はデフォルトでは非表示
+
+### 4.4 静的メソッド一覧
+
+#### ログ出力
+
+| メソッド | 出力条件 |
+|---------|---------|
+| `Logger.debug(message, ...params)` | `level <= DEBUG (0)` |
+| `Logger.info(message, ...params)` | `level <= INFO (1)` |
+| `Logger.warn(message, ...params)` | `level <= WARN (2)` |
+| `Logger.error(message, ...params)` | `level <= ERROR (3)` |
+
+#### 設定変更
+
+| メソッド | 説明 |
+|---------|------|
+| `Logger.setLevel(level)` | デフォルトインスタンスのログレベルを変更 |
+| `Logger.setImplementation(impl)` | デフォルトインスタンスのロガー実装を差し替え |
+| `Logger.setPrefix(prefix)` | デフォルトインスタンスのプレフィックスを変更 |
+
+### 4.5 メッセージフォーマット
+
+```typescript
+private formatMessage(message: unknown): unknown[] {
+    if (typeof message === "string") {
+        return [`${this.prefix} ${message}`]
+    }
+    return [this.prefix, message]
+}
+```
+
+| 入力 | 出力 |
+|------|------|
+| `"初期化中..."` | `["[duckdb-helper] 初期化中..."]` |
+| `{ key: "value" }` | `["[duckdb-helper]", { key: "value" }]` |
+
+文字列の場合はプレフィックスを結合し、オブジェクトの場合はプレフィックスを別引数として渡す（console の展開表示を活用）。
+
+## 5. ライブラリ内での使用箇所
+
+| ファイル | 使用メソッド | 内容 |
+|---------|------------|------|
+| `services/duckdb.ts` | `Logger.info` | Worker 初期化の各ステップのログ |
+| `services/duckdb.ts` | `Logger.warn` | splink_udfs ロード失敗時の警告 |
+| `services/duckdb.ts` | `Logger.error` | 初期化失敗・クエリ失敗のエラーログ |
+| `hooks/useDuckDB.ts` | `Logger.info` | ステータス変更・自動初期化のログ |
+| `hooks/useDuckDB.ts` | `Logger.error` | 初期化失敗のエラーログ |
+
+## 6. 利用側でのログレベル制御
+
+### 開発中（すべてのログを表示）
+
+> **v1.6.0 で公開**: `Logger` / `LogLevel` / `ILogger` は `index.ts` から公開エクスポートされるようになった。利用側から直接インポートしてログレベルを制御できる（旧バージョンではエクスポートされておらず、初期化ログを有効化する手段が無かった）。
+
+```typescript
+import { Logger, LogLevel } from '@aiquants/duckdb-helper'
+
+Logger.setLevel(LogLevel.DEBUG)
+```
+
+### 本番環境（エラーのみ表示）
+
+```typescript
+Logger.setLevel(LogLevel.ERROR)
+```
+
+### テスト（ログを完全に抑制）
+
+```typescript
+Logger.setLevel(LogLevel.NONE)
+```
+
+### カスタムロガーに差し替え
+
+```typescript
+const customLogger: ILogger = {
+    debug: (...args) => myLoggingService.log('debug', ...args),
+    info:  (...args) => myLoggingService.log('info', ...args),
+    warn:  (...args) => myLoggingService.log('warn', ...args),
+    error: (...args) => myLoggingService.log('error', ...args),
+}
+
+Logger.setImplementation(customLogger)
+```
+
+## 7. 注意事項
+
+1. **Logger / LogLevel / ILogger は `index.ts` から公開エクスポートされている（v1.6.0〜）**。`import { Logger, LogLevel } from '@aiquants/duckdb-helper'` で利用でき、`Logger.setLevel()` などでログレベルや実装を制御できる。
+2. **デフォルトレベルは `WARN`**。つまり `DuckDBService` 内の `Logger.info(...)` による初期化ログは通常表示されない。ただし初期化の**失敗**（`Logger.error`）は WARN でも表示される。詳細なステップを見たい場合は `Logger.setLevel(LogLevel.DEBUG)` を設定する。
+3. **リスナーでの例外はキャッチされる**。`DuckDBService.notifyListeners()` 内でリスナーが例外を投げた場合、`Logger.error` でログに出力されるが、他のリスナーへの通知は続行される。
+
+## 8. 新人向けポイント
+
+1. **普段は Logger を意識しなくてOK**。ライブラリ内部で勝手にログを出す仕組み。
+2. **デバッグしたい時は `Logger.setLevel(LogLevel.DEBUG)` するだけ**。初期化の各ステップが詳細に表示される。
+3. **テストで邪魔なログを消すには `Logger.setLevel(LogLevel.NONE)`**。
+4. **プレフィックス `[duckdb-helper]` でログをフィルタリング**できる。ブラウザの DevTools で検索すると便利。