@voltcube/core

High-performance pivot table engine powered by DuckDB-WASM, running entirely in a Web Worker. No server required.

The engine layer of VoltCube — a worker-backed pivot API (createPivot) with its own DuckDB-WASM bootstrap. Most apps should use voltcube, which bundles this engine with the renderer behind a single Pivot builder facade. Reach for @voltcube/core directly when you need the engine without the renderer — a custom UI, headless analytics, or non-DOM environments.

Installation

npm install @voltcube/core

@duckdb/duckdb-wasm, apache-arrow, and comlink come transitively. DuckDB-WASM is auto-discovered through your bundler graph (new URL('@duckdb/duckdb-wasm/dist/...', import.meta.url)) — no CDN call by default.

Usage

import { createPivot } from '@voltcube/core';

const pivot = await createPivot();
await pivot.loadData({ type: 'csv', url: '/sales.csv' });

const result = await pivot.query({
  rows:    [{ field: 'region' }, { field: 'category' }],
  columns: [{ field: 'year' }],
  values:  [{ field: 'sales', agg: 'sum', as: 'sum_sales' }],
  totals:  { subtotalRows: true, grandTotalRow: true },
});

// Walk the hierarchy + read cells via the dense-grid store.
for (const row of result.hierarchy.visibleRows) {
  for (const col of result.hierarchy.visibleColumns) {
    const cell = result.hierarchy.getCell(row.id, col.id, 'sum_sales');
    console.log(row.label, col.label, cell?.formatted);
  }
}

await pivot.destroy();

CSV/JSON sources accept a per-field schema to coerce columns at load time (e.g. cast an epoch-millisecond column to a real TIMESTAMP). Pass duckdbBundleUrl / memoryLimitMb to createPivot(...) to self-host DuckDB or tune memory. Subscribe to typed events with pivot.on('query:complete', …).

Full reference

The complete API — every option, event payload, and type — is at voltcube-playground.pages.dev/docs.