# @duckviz/db

In-browser SQL data engine powered by DuckDB-WASM. Handles file ingestion (CSV, XLSX, JSON, JSONL, XML), query execution, table persistence to IndexedDB, and log parsing — all client-side with zero server dependencies.

## Install

```bash
npm install @duckviz/db
# peer dependencies
npm install @duckdb/duckdb-wasm apache-arrow react
```

## Quick start

```tsx
import { DuckvizDBProvider, useDuckDB } from "@duckviz/db";

function App() {
  return (
    <DuckvizDBProvider persistence>
      <DataView />
    </DuckvizDBProvider>
  );
}

function DataView() {
  const { runQuery, loading } = useDuckDB();

  async function fetchData() {
    const rows = await runQuery("SELECT * FROM my_table LIMIT 100");
    console.log(rows);
  }

  if (loading) return <p>Initializing DuckDB...</p>;
  return <button onClick={fetchData}>Query</button>;
}
```

## Configuration

All configuration is via props on `<DuckvizDBProvider>`:

```tsx
<DuckvizDBProvider
  persistence // Persist tables to IndexedDB across page refreshes (default: false)
  arrowIngest // Use Arrow IPC for batch ingestion — faster, falls back to JSON (default: true)
  batchSize={5000} // Batch size for the file-ingestion worker (default: 5000)
  logLevel="warn" // Console verbosity: "silent" | "warn" | "debug" (default: "warn")
>
  <YourApp />
</DuckvizDBProvider>
```

## API

### Provider & hooks

| Export                | Description                                       |
| --------------------- | ------------------------------------------------- |
| `<DuckvizDBProvider>` | React context provider — initializes DuckDB-WASM  |
| `useDuckDB()`         | Hook returning the full `DuckDBContextValue`      |
| `useDuckDBOrNull()`   | Same as above but returns `null` outside provider |

### Context value (`useDuckDB()`)

| Method                          | Description                                      |
| ------------------------------- | ------------------------------------------------ |
| `runQuery(sql)`                 | Execute SQL, returns `Record<string, unknown>[]` |
| `ingest({ files, onProgress })` | Ingest files via Web Worker with progress        |
| `ingestJsonRows(rows, table)`   | Ingest parsed rows as a JSON table               |
| `getTableData(table)`           | Get all rows from a table                        |
| `getTableSchema(table)`         | Get `SchemaColumn[]` for a table                 |
| `listTables()`                  | List all `t_*` tables                            |
| `tableExists(table)`            | Check if a table exists                          |
| `clearAllTables()`              | Drop all `t_*` tables                            |

### Core utilities

```ts
import { pathToTableName } from "@duckviz/db";
```

- `pathToTableName(path)` — Convert file path to valid DuckDB table name (`t_` prefix)

## Peer dependencies

| Package               | Version   |
| --------------------- | --------- |
| `react`               | `>=18`    |
| `@duckdb/duckdb-wasm` | `^1.33.0` |
| `apache-arrow`        | `>=14`    |

## License

MIT
