@aiquants/duckdb-helper

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

Features

• Worker-backed initialization: Set up DuckDB-wasm workers with recommended CDN bundles.
• React hooks: Provide useDuckDB and useDuckDBQuery for component integrations.
• Singleton service: Share a single DuckDB instance across application components.
• Typed helpers: Safely convert query results with type guards.
• TypeScript first: Full typings for queries, tables, and helper functions.

Installation

# Using pnpm (recommended)
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

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

For detailed guidance, see docs/useDuckDB.md.

Requirements

• React 16.8+ with Hooks support
• Modern browsers with Web Worker support

License

MIT License

Contributing

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