@aiquants/duckdb-helper

DuckDB helper utilities with React hooks, worker initialization, and typed query helpers for browser applications.

DuckDB をブラウザアプリケーションで扱うための React フック、Worker 初期化、型付きクエリヘルパーを提供するユーティリティ集。

Features / 機能

• Worker-backed initialization: Set up DuckDB-wasm workers with the recommended CDN bundles / 推奨 CDN バンドルを用いた DuckDB-wasm Worker 初期化
• React hooks: Provide useDuckDB と useDuckDBQuery for component integrations / コンポーネント統合向けの useDuckDB と useDuckDBQuery
• Singleton service: Share a single DuckDB インスタンス全体で共有できるシングルトンサービス
• Typed helpers: Safely convert query results with type guards / 型ガード付きでクエリ結果を安全に変換
• TypeScript first: Full typings for queries, tables, and helper functions / クエリやテーブル、ヘルパー関数の完全な型定義

Installation / インストール

# Using pnpm (recommended) / pnpm を使用（推奨）
pnpm add @aiquants/duckdb-helper

# Using npm
npm install @aiquants/duckdb-helper

# Using yarn
yarn add @aiquants/duckdb-helper

Quick Start / クイックスタート

Initialize the service / サービスの初期化

import duckDBService from '@aiquants/duckdb-helper'

await duckDBService.initialize()

const result = await duckDBService.executeQuery('SELECT 1 AS value')
console.log(result)

Use the React hook / React フックを利用

import { useDuckDB } from '@aiquants/duckdb-helper'

export const Dashboard = () => {
    const { status, executeQuery, isReady } = useDuckDB()

    const handleClick = async () => {
        if (!isReady) {
            return
        }
        const table = await executeQuery('SELECT * FROM users LIMIT 10')
        console.log(table)
    }

    return (
        <div>
            <p>Status: {status}</p>
            <button onClick={handleClick} disabled={!isReady}>
                Run Query
            </button>
        </div>
    )
}

Convert results to arrays / 結果を配列に変換

import { duckdbTableToArray } from '@aiquants/duckdb-helper'

const table = await duckDBService.executeQuery('SELECT * FROM items')
const rows = duckdbTableToArray<{ id: number; name: string }>(table)

Documentation / ドキュメント

詳しい使用方法は docs/useDuckDB.md を参照してください。

For detailed guidance, see docs/useDuckDB.md.

Requirements / 必要要件

• React 16.8+ with Hooks support / React 16.8 以上（Hooks 対応）
• Modern browsers with Web Worker support / Web Worker をサポートする最新ブラウザ

License / ライセンス

MIT License

Contributing / 貢献

Contributions are welcome! Please open an issue or submit a pull request.

貢献を歓迎します。Issue や Pull Request をぜひお寄せください。