@aiquants/duckdb-helper 1.4.1 → 1.5.0

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

@@ -0,0 +1,188 @@
+# 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. 利用側でのログレベル制御
+
+### 開発中（すべてのログを表示）
+
+> **重要**: `Logger` と `LogLevel` は `index.ts` から公開エクスポートされておらず、`package.json` の `exports` にもサブパスが定義されていないため、**現状では利用側から直接インポートできない**。ログレベルを変更するには、パッケージ側で `index.ts` にエクスポートを追加する必要がある（追加方法は[開発ガイド](../guides/2026.04.11%20%5BAI%5D%20development.md)の「Q: Logger を公開 API にしたい」を参照）。
+
+パッケージ側でエクスポートが追加された場合の使用例:
+
+```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 は `index.ts` から公開エクスポートされていない**。ライブラリ内部用の位置づけ。`package.json` の `exports` にもサブパスが未定義のため、`@aiquants/duckdb-helper/utils/simple-logger` のような直接パスインポートも動作しない。利用側からログレベルを変更するにはパッケージのエクスポートを拡張する必要がある。
+2. **デフォルトレベルは `WARN`**。つまり `DuckDBService` 内の `Logger.info(...)` による初期化ログは通常表示されない。デバッグ時にログを見たい場合は `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 で検索すると便利。

package/docs/specs/2026.04.11 [AI] 06-build-config.md

@@ -0,0 +1,170 @@
+# ビルド設定仕様書
+
+> ソースファイル: `tsup.config.ts`, `tsconfig.json`, `package.json`
+
+## 1. 概要
+
+このパッケージは **tsup**（esbuild ベースのバンドラー）を使ってビルドされ、CommonJS と ESM の両形式で配布される。
+
+## 2. tsup 設定（`tsup.config.ts`）
+
+```typescript
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+    entry: ['src/index.ts'],       // エントリーポイント
+    format: ['cjs', 'esm'],        // 出力形式（CommonJS + ESM）
+    dts: true,                     // 型定義ファイル (.d.ts) を生成
+    clean: true,                   // ビルド前に dist/ をクリーン
+    sourcemap: true,               // ソースマップを生成
+    external: ['react', 'react-dom', '@duckdb/duckdb-wasm'],  // バンドルに含めない
+    outDir: 'dist',                // 出力先
+    target: 'es2020',              // ターゲット環境
+    splitting: false,              // コード分割なし
+    minify: true                   // ミニファイ有効
+})
+```
+
+### 各設定の意味
+
+| 設定 | 値 | 説明 |
+|------|------|------|
+| `entry` | `['src/index.ts']` | ビルドのエントリーポイント。`index.ts` の公開 API のみがバンドルされる |
+| `format` | `['cjs', 'esm']` | CommonJS（`.js`）と ESM（`.mjs`）の両形式を生成 |
+| `dts` | `true` | TypeScript 型定義ファイル（`.d.ts`）を自動生成 |
+| `clean` | `true` | ビルド前に `dist/` を削除してクリーンビルド |
+| `sourcemap` | `true` | デバッグ用のソースマップを生成 |
+| `external` | 3パッケージ | これらはバンドルに含めず、利用側でインストールしてもらう |
+| `outDir` | `'dist'` | ビルド成果物の出力先 |
+| `target` | `'es2020'` | ES2020 の構文までを使用。Optional chaining, nullish coalescing 等が使える |
+| `splitting` | `false` | チャンク分割を無効化。1ファイルにまとめる |
+| `minify` | `true` | 配布サイズ削減のためミニファイ |
+
+### external の意味
+
+| パッケージ | 理由 |
+|-----------|------|
+| `react` | ピア依存。利用側が提供する |
+| `react-dom` | ピア依存。利用側が提供する |
+| `@duckdb/duckdb-wasm` | 本番依存だがサイズが大きいため、利用側のバンドラーに委ねる |
+
+## 3. TypeScript 設定（`tsconfig.json`）
+
+### 主要設定
+
+| 設定 | 値 | 説明 |
+|------|------|------|
+| `target` | `ES2020` | 出力する JavaScript のバージョン |
+| `module` | `ES2020` | モジュールシステム |
+| `lib` | `["ES2020", "DOM", "DOM.Iterable"]` | 利用可能な型定義。DOM はブラウザ API 用 |
+| `strict` | `true` | すべての strict チェックを有効化 |
+| `jsx` | `react-jsx` | React 17+ の JSX トランスフォーム |
+| `moduleResolution` | `node` | Node.js スタイルのモジュール解決 |
+| `noEmit` | `true` | tsc は型チェックのみ。ビルドは tsup が担当 |
+| `isolatedModules` | `true` | 各ファイルを独立してトランスパイル可能にする（tsup 互換） |
+
+### パスエイリアス
+
+```json
+"paths": {
+    "@/*": ["./src/*"]
+}
+```
+
+`@/services/duckdb` のように `src/` からの相対パスを `@/` で参照できる。ただし現在のソースコードでは使用されていない。
+
+### 除外設定
+
+```json
+"exclude": [
+    "node_modules",
+    "dist",
+    "**/*.test.*",
+    "**/*.spec.*"
+]
+```
+
+テストファイルはビルド・型チェックの対象外。
+
+## 4. package.json のビルド関連設定
+
+### 出力形式のマッピング
+
+```json
+{
+    "main": "dist/index.js",       // CommonJS (require)
+    "module": "dist/index.mjs",    // ESM (import)
+    "types": "dist/index.d.ts",    // 型定義
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js",
+            "default": "./dist/index.mjs"
+        }
+    }
+}
+```
+
+| フィールド | 用途 |
+|-----------|------|
+| `main` | Node.js / 古いバンドラーが参照（CommonJS） |
+| `module` | Webpack / Rollup 等が参照（ESM） |
+| `types` | TypeScript の型定義 |
+| `exports` | Node.js 12+ のモジュール解決。条件付きエクスポート |
+
+### npm スクリプト
+
+| スクリプト | コマンド | 説明 |
+|-----------|---------|------|
+| `build` | `tsup` | ビルド実行 |
+| `build:watch` | `tsup --watch` | ファイル変更時に自動リビルド |
+| `dev` | `tsup --watch` | 開発用（build:watch と同一） |
+| `watch` | `tsup --watch` | ウォッチモード |
+| `type-check` | `tsc --noEmit` | 型チェックのみ実行 |
+| `clean` | `rimraf dist` | ビルド成果物を削除 |
+| `prepare` | `pnpm run build` | パッケージインストール後に自動ビルド |
+| `prepublishOnly` | clean → typecheck → test(`--if-present`) → build | 公開前の品質チェック |
+| `lint` | `biome lint src/` | Biome による Lint |
+| `lint:fix` | `biome lint --write src/` | Biome による Lint 自動修正 |
+| `format` | `biome format src/` | Biome によるフォーマット |
+| `format:fix` | `biome format --write src/` | Biome によるフォーマット自動修正 |
+| `check` | `biome check src/` | Lint + フォーマットの同時チェック |
+| `check:fix` | `biome check --write src/` | Lint + フォーマットの同時自動修正 |
+| `typecheck` | `npm run type-check` | `type-check` のエイリアス |
+| `test` | `vitest run` | テスト実行 |
+| `test:coverage` | `vitest run --coverage` | カバレッジ付きテスト |
+| `license-check` | `pnpm dlx license-checker ...` | 許可ライセンスのチェック |
+| `license-check:json` | `pnpm dlx license-checker ... --json` | ライセンスチェック（JSON 出力） |
+| `publish:patch` | version patch → publish | パッチバージョン公開 |
+| `publish:minor` | version minor → publish | マイナーバージョン公開 |
+| `publish:major` | version major → publish | メジャーバージョン公開 |
+
+### 配布ファイル
+
+```json
+"files": ["dist", "README.md", "LICENSE", "docs"]
+```
+
+npm に公開されるファイル。`src/` はパッケージに含まれない。
+
+## 5. ビルド成果物の構成
+
+```
+dist/
+├── index.js        # CommonJS バンドル（require() 用）
+├── index.mjs       # ESM バンドル（import 用）
+├── index.d.ts      # TypeScript 型定義
+├── index.d.mts     # ESM 用 TypeScript 型定義
+├── index.js.map    # CommonJS ソースマップ
+└── index.mjs.map   # ESM ソースマップ
+```
+
+## 6. 新人向けポイント
+
+1. **`pnpm run build` でビルド**。`dist/` にファイルが生成される。
+2. **`pnpm run dev` で開発中はウォッチモード**を使うと、ソース変更が自動で反映される。
+3. **`pnpm run type-check` で型エラーだけ確認**できる。ビルドせずに素早くチェック。
+4. **`external` に指定されたパッケージはバンドルに含まれない**。利用側でインストールが必要。
+5. **ビルドは tsup（esbuild ベース）が行い、tsc は型チェック専用**。この分業により高速ビルドと厳密な型チェックを両立。
+6. **`src/` は npm パッケージに含まれない**。利用者が見るのは `dist/` のビルド済みコードのみ。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/duckdb-helper",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "DuckDB helper utilities with React hooks, worker initialization, and typed query helpers",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -36,18 +36,18 @@
     "@duckdb/duckdb-wasm": "^1.30.0"
   },
   "devDependencies": {
-    "@types/react": "^18.3.27",
-    "@types/react-dom": "^18.3.7",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
     "rimraf": "^6.1.2",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
   },
   "peerDependencies": {
-    "react": ">=18.0.0",
-    "react-dom": ">=18.0.0"
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -69,8 +69,7 @@
     "build:watch": "tsup --watch",
     "dev": "tsup --watch",
     "watch": "tsup --watch",
-    "type-check": "tsc --noEmit",
-    "typecheck": "npm run type-check",
+    "typecheck": "tsc --noEmit",
     "clean": "rimraf dist",
     "publish:patch": "npm version patch && pnpm publish --no-git-checks",
     "publish:minor": "npm version minor && pnpm publish --no-git-checks",