@kolistat/bedevere-wise

Embeddable browser components for DuckDB-WASM-backed data exploration:

• SpreadsheetVisualizer — canvas-rendered grid; virtually scrolled, HiDPI-sharp.
• ColumnStatsVisualizer — per-column summary stats + value-filter UI.
• ChartVisualizer — Vega-Lite renderer for stats_duck's VISUALIZE … DRAW output.
• EmbedSqlEditor — slim CodeMirror SQL editor with Bedevere's PostgreSQL-extended dialect.
• DuckDBService + DuckDBDataProvider — DuckDB-WASM runtime wrapper + bridge to the UI components.

These are the same components that compose the standalone web app at bedeverewise.app. Also consumed by tlf-studio for clinical-trial pipeline inspection.

Status: pre-1.0. Shipping on the @next dist-tag while the embedding API settles. Breaking changes are possible between 0.x minor versions (the CHANGELOG flags them). Pin to an exact version in production.

Install

bun add @kolistat/bedevere-wise@next

# Peer dependencies — install one shared copy of each in your tree:
bun add @duckdb/duckdb-wasm \
  @codemirror/autocomplete @codemirror/commands @codemirror/lang-sql \
  @codemirror/language @codemirror/search @codemirror/state \
  @codemirror/view @lezer/highlight codemirror \
  vega-embed

All peer deps are required if you import from the package's main entry today. See Bundler compatibility for the rationale and the WASM-free entry split (/ui, /app, /ipc).

Quick start

import {
  DuckDBService,
  DuckDBDataProvider,
  SpreadsheetVisualizer,
  ColumnStatsVisualizerFocusable,
} from "@kolistat/bedevere-wise";
import "@kolistat/bedevere-wise/style.css";

const duck = new DuckDBService();
await duck.initialize();

// Point DuckDB at a remote dataset; the host must serve permissive CORS.
await duck.registerFileURL("adsl.parquet", "https://example.org/adsl.parquet");
await duck.executeQuery(
  `CREATE OR REPLACE TABLE adsl AS SELECT * FROM read_parquet('adsl.parquet')`,
);

const provider = new DuckDBDataProvider(duck, "adsl", "adsl.parquet");

// One shared stats panel, mounted next to the spreadsheet:
const stats = new ColumnStatsVisualizerFocusable(
  document.querySelector("#stats")!,
  null,
);

const grid = new SpreadsheetVisualizer(
  document.querySelector("#grid")!,
  provider,
  { minHeight: 240, minWidth: 320 },
  stats,
  "my-app-grid",
);
await grid.initialize();

Embedding surface

The package ships two tiers of exports.

Embedding tier — recommended

Components in this tier accept their dependencies via constructor; no module-level singleton reach-through. Safe to mount inside any host app.

Export	Purpose
DuckDBService	DuckDB-WASM runtime wrapper. One instance per app.
DuckDBDataProvider	Implements DataProvider over a DuckDB table.
DataProvider (interface)	The per-dataset integration boundary. Implement your own to feed rows from anywhere — HTTP, IPC, a server.
Backend (interface)	The SQL-engine boundary. Implement to point BedevereApp at a non-WASM engine (native IPC, remote relay). Optional exportTable(opts) writes a whole table to Parquet / JSON / SAS / SPSS — ExportFormat, ExportTableOptions, ExportResult, and EXPORT_FORMATS are exported for it.
SpreadsheetVisualizer	Canvas-rendered spreadsheet.
ColumnStatsVisualizer / ColumnStatsVisualizerFocusable	Column stats + filter panel; share one across many spreadsheets.
ChartVisualizer	Renders Vega-Lite specs produced by stats_duck's VISUALIZE … DRAW.
EmbedSqlEditor	Slim CodeMirror SQL editor with the Bedevere dialect + tokyonight palette.
Type helpers (isNumericType, normalizeDuckDBType, dataTypeCategory, …)	For consumers writing custom DataProviders.

The UI components (SpreadsheetVisualizer, ColumnStatsVisualizer, ChartVisualizer, EmbedSqlEditor) have no hard dependency on DuckDB-WASM — they consume the DataProvider interface and Vega specs respectively. A consumer can ignore DuckDBService / DuckDBDataProvider entirely and supply their own DataProvider over an alternative backend (HTTP API, native IPC, an in-memory pipeline, …).

App-shell tier — @kolistat/bedevere-wise/app

The full standalone-app shell as composable pieces: BedevereApp, TabManager, ControlPanel, StatusBar, CommandBar, plus the PersistenceService singleton. BedevereApp is backend-agnostic — pass options.backend (there is no built-in default), so importing from /app pulls no DuckDB-WASM. Pair it with /duckdb for the in-browser engine, or hand it an IpcBackend / remote relay (this is exactly how bedevere-desktop drives the same UI against native DuckDB):

import { BedevereApp } from "@kolistat/bedevere-wise/app";
import { DuckDBService } from "@kolistat/bedevere-wise/duckdb";
import "@kolistat/bedevere-wise/style.css";

const backend = new DuckDBService();
await backend.initialize();
const app = new BedevereApp(document.getElementById("app")!, "1.0.0", { backend });
await app.initAsync();

These shells assume module-level singletons (CommandRegistry, EnvironmentService, KeymapService, PersistenceService) and expect one BedevereApp per page. If you only need a piece of the UI rather than the whole shell, prefer the component tier above.

Theming

The package ships four themes as CSS custom-property sets, selected by a single body class — exactly one is applied at a time:

Body class	Theme
theme-dark	GitHub-Dark — the default dark
theme-light	Light (warm-neutral)
theme-classic-dark	Tokyonight Storm
theme-classic-light	Tokyonight Day

Override the tokens in your own stylesheet, after importing the package CSS (see dist/style.css for the full token list):

body.theme-dark {
  --bg: #1f1f1f;
  --fg: #e1e4e8;
  /* ... */
}

Switching the body class re-renders theme-sensitive canvas surfaces (the spreadsheet repaints; the chart re-embeds with a matching Vega palette). BedevereApp manages this class for you and exposes setTheme().

Bundler compatibility

The package is browser-only and currently Vite-friendly. DuckDB-WASM, which DuckDBService depends on, ships its worker scripts as separate JS files referenced via Vite's ?url import syntax. The compiled bundle (dist/index.es.js) preserves these ?url imports verbatim; resolving them is your bundler's job.

Bundler	Status
Vite	Works out of the box. This is the supported path.
webpack 5	Works with asset/resource rules for the worker URLs. See the DuckDB-WASM docs for setup.
Bun bundler / esbuild / Parcel	The ?url suffix isn't resolved natively; needs custom plugins or loader config. Untested.
SSR / Node / Bun runtime	Not supported. The DuckDB worker code requires browser APIs at module load.

The ?url worker chain lives only behind the /duckdb entry. If your bundler can't resolve ?url (or you simply don't want DuckDB-WASM in your bundle), import from the WASM-free entries instead and bring your own engine:

Entry	Pulls DuckDB-WASM?	Use for
@kolistat/bedevere-wise/ui	No	Individual UI components over your own DataProvider.
@kolistat/bedevere-wise/app	No	The full app shell (BedevereApp) with an injected Backend.
@kolistat/bedevere-wise/duckdb	Yes	The in-browser DuckDBService engine (the ?url chain).
@kolistat/bedevere-wise/ipc	No	IpcBackend for a native/remote DuckDB over WebSocket.
@kolistat/bedevere-wise (root)	Yes	Back-compat barrel; re-exports /duckdb, so it pulls the chain.

Local development against this package

The package's source lives in bedevere-wise (active development happens on the current dev-X.Y branch). To hack on both this and a consumer at once:

# in bedevere-wise/
bun run build:lib    # produces dist/
bun link             # registers @kolistat/bedevere-wise locally

# in your consumer app/
bun link @kolistat/bedevere-wise

After source changes in bedevere-wise, re-run bun run build:lib to refresh the linked dist/. The consumer's Vite dev server picks up the new code on next reload.

Source + standalone app

Source code: github.com/KoliStat/bedevere-wise. The standalone web app at bedeverewise.app is built from the same source. End-user docs and screenshots live on the Bedevere Wise app site (it's a desktop-only browser app; mobile isn't supported yet).

License

MIT — see LICENSE.