@pivotblitz/core

Framework-agnostic pivot table engine with high-performance data processing.

Installation

pnpm add @pivotblitz/core

Features

• 24 Built-in Aggregators - Sum, Average, Median, Variance, Running Total, etc.
• 40+ Formula Functions - Math, Statistical, Date, Text, Financial
• TypedArrays Support - 2-25x faster aggregations with columnar storage
• Export Functions - Excel, PDF, CSV, JSON, HTML, PNG
• Conditional Formatting - Heatmaps, Data Bars, Icon Sets, Color Scales
• i18n - 10 locales with RTL support
• Zero Dependencies - Core engine has no external dependencies

Quick Start

import { PivotEngine, createPivotData } from '@pivotblitz/core';

const data = [
  { region: 'North', product: 'Widget', sales: 100 },
  { region: 'North', product: 'Gadget', sales: 150 },
  { region: 'South', product: 'Widget', sales: 200 },
];

const engine = new PivotEngine();
const result = engine.aggregate(data, {
  rows: ['region'],
  cols: ['product'],
  vals: ['sales'],
  aggregator: 'Sum'
});

console.log(result);
// {
//   headers: ['region', 'Widget', 'Gadget', 'Total'],
//   data: [
//     ['North', 100, 150, 250],
//     ['South', 200, 0, 200],
//     ['Total', 300, 150, 450]
//   ]
// }

API Reference

PivotEngine

The main pivot engine class.

import { PivotEngine } from '@pivotblitz/core';

const engine = new PivotEngine();

// Basic aggregation
const result = engine.aggregate(data, {
  rows: ['region', 'country'],
  cols: ['product'],
  vals: ['sales', 'quantity'],
  aggregator: 'Sum',
  filters: {
    region: ['North', 'South']
  },
  sorters: {
    region: 'asc',
    sales: 'desc'
  }
});

Aggregators

Built-in aggregators:

| Name | Description | |------|-------------| | Count | Count of records | | Sum | Sum of values | | Average | Arithmetic mean | | Minimum | Minimum value | | Maximum | Maximum value | | Median | Middle value (50th percentile) | | Variance | Statistical variance | | Std Deviation | Standard deviation | | Count Unique | Count of distinct values | | List Unique | Comma-separated unique values | | First | First value encountered | | Last | Last value encountered | | Sum over Sum | Ratio of two sums | | Integer Sum | Sum formatted as integer | | % of Total | Percentage of grand total | | % of Row | Percentage of row total | | % of Column | Percentage of column total | | Running Total | Cumulative sum | | Difference | Difference from previous value | | % Difference | Percentage change | | Rank | Rank within context | | Percentile 25 | 25th percentile | | Percentile 75 | 75th percentile | | Percentile 90 | 90th percentile |

Custom aggregator:

import { registerAggregator } from '@pivotblitz/core';

registerAggregator('Weighted Average', {
  push: (state, value, weight) => {
    state.sum = (state.sum || 0) + value * weight;
    state.weights = (state.weights || 0) + weight;
  },
  value: (state) => state.sum / state.weights,
  format: (val) => val.toFixed(2)
});

Calculated Fields

Create computed fields using formulas:

import { applyCalculatedFields } from '@pivotblitz/core';

const fields = [
  {
    name: 'profit',
    formula: 'revenue - cost'
  },
  {
    name: 'margin',
    formula: '(revenue - cost) / revenue * 100',
    format: { style: 'percent', minimumFractionDigits: 1 }
  },
  {
    name: 'category',
    formula: 'IF(profit > 1000, "High", IF(profit > 500, "Medium", "Low"))'
  }
];

const enrichedData = applyCalculatedFields(rawData, fields);

Built-in Functions

Math: ABS, CEIL, FLOOR, ROUND, SQRT, POW, LOG, LOG10, EXP, SIN, COS, TAN, MIN, MAX, MOD, SIGN

Statistical: AVERAGE, MEDIAN, STDDEV, VARIANCE, PERCENTILE, QUARTILE, SLOPE, INTERCEPT, CORREL, COVAR

Logical: IF, AND, OR, NOT, XOR, IFS, SWITCH, IFERROR, ISBLANK, ISNUMBER

Text: CONCAT, UPPER, LOWER, TRIM, LEN, LEFT, RIGHT, MID, SUBSTRING, REPLACE, SUBSTITUTE, FIND, SEARCH, SPLIT, JOIN, TEXT, VALUE

Date: YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, NOW, TODAY, DATEDIF, DATEADD, WEEKDAY, WEEKNUM, EOMONTH

Financial: NPV, IRR, PV, FV, PMT, RATE, NPER

Aggregation: SUM, COUNT, COUNTIF, SUMIF, AVERAGEIF, MINIF, MAXIF

Export Functions

import {
  exportToExcel,
  exportToPDF,
  exportToCSV,
  exportToJSON,
  exportToHTML,
  exportToImage
} from '@pivotblitz/core';

// Excel
await exportToExcel(pivotResult, {
  filename: 'report',
  sheetName: 'Sales',
  includeFilters: true,
  freezeHeaders: true
});

// PDF
await exportToPDF(pivotResult, {
  filename: 'report',
  title: 'Sales Report',
  subtitle: 'Q1 2024',
  orientation: 'landscape',
  pageSize: 'A4'
});

// CSV
exportToCSV(pivotResult, {
  filename: 'data',
  delimiter: ',',
  includeHeaders: true
});

// JSON
exportToJSON(pivotResult, {
  filename: 'data',
  pretty: true
});

// HTML
exportToHTML(pivotResult, {
  filename: 'report',
  title: 'Sales Report',
  theme: 'dark',
  responsive: true,
  includeStyles: true
});

// Image (PNG/JPEG/WebP)
await exportToImage(element, {
  format: 'png',
  filename: 'chart',
  scale: 2,
  quality: 0.95
});

Conditional Formatting

import { applyConditionalFormatting, presetRules } from '@pivotblitz/core';

const rules = [
  // Highlight top 10
  presetRules.highlightTop10,
  
  // Highlight negative values
  presetRules.highlightNegative,
  
  // Heatmap
  {
    type: 'heatmap',
    minColor: '#f0f9ff',
    maxColor: '#1e40af'
  },
  
  // Data bars
  {
    type: 'dataBar',
    color: '#3b82f6',
    backgroundColor: '#dbeafe',
    showValue: true
  },
  
  // Icon sets
  {
    type: 'iconSet',
    icons: ['▲', '▶', '▼'],
    thresholds: [0.33, 0.67]
  },
  
  // Custom rule
  {
    type: 'condition',
    condition: (value) => value > 1000,
    style: {
      backgroundColor: '#dcfce7',
      color: '#166534',
      fontWeight: 'bold'
    }
  }
];

const formattedResult = applyConditionalFormatting(pivotResult, rules);

TypedDataStore (High Performance)

For large datasets (100K+ rows), use TypedArrays for better performance:

import { createTypedDataStore } from '@pivotblitz/core';

// Convert data to columnar format
const typedStore = createTypedDataStore(largeData, {
  numericFields: ['sales', 'quantity', 'price'],
  stringFields: ['region', 'product', 'category']
});

// Aggregation is now 2-25x faster
const result = typedStore.aggregate({
  groupBy: ['region'],
  aggregations: [
    { field: 'sales', type: 'sum' },
    { field: 'quantity', type: 'avg' }
  ]
});

// Memory usage is ~68% lower
console.log(typedStore.memoryUsage());

Internationalization

import { setLocale, t, isRTL, formatNumber, formatDate } from '@pivotblitz/core';

// Set locale
setLocale('de'); // German

// Translate
console.log(t('total')); // "Gesamt"
console.log(t('grandTotal')); // "Gesamtsumme"

// Check RTL
setLocale('ar'); // Arabic
console.log(isRTL()); // true

// Format numbers
console.log(formatNumber(1234.56, 'de')); // "1.234,56"
console.log(formatNumber(1234.56, 'en')); // "1,234.56"

// Format dates
console.log(formatDate(new Date(), 'de')); // "04.02.2026"

Available locales: en, it, de, fr, es, pt, ja, zh, ar, he

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type {
  PivotConfig,
  PivotResult,
  AggregatorName,
  CalculatedField,
  ConditionalRule,
  ExportOptions
} from '@pivotblitz/core';

const config: PivotConfig = {
  rows: ['region'],
  cols: ['product'],
  vals: ['sales'],
  aggregator: 'Sum' as AggregatorName
};

License

MIT