╔═══════════════╗
   ║   ◇  QUBE  ◇  ║
   ╚═══════════════╝

Powerful in-memory OLAP cube for JavaScript/TypeScript

✨ Features

• 🔷 Hypercube Support — 1 to N dimensions (not limited to 3!)
• 📊 Rich Aggregations — sum, count, min, max, average, first, last, distinct, variance, stddev
• 🔍 Flexible Querying — slice, dice, query, rollup, drilldown, filter
• 📋 Dimension Operations — enumerate, get dimension info
• 💾 Serialization — save and restore cubes
• 📝 TypeScript — full type definitions included

📦 Installation

npm install qube

🚀 Quick Start

import { Qube } from 'qube';
// or: const { Qube } = require('qube');

const qube = new Qube({
    measures: [
        { type: 'sum', key: 'sales', name: 'total_sales' },
        { type: 'count', key: 'sales', name: 'transaction_count' },
        { type: 'average', key: 'sales', name: 'avg_sales' }
    ],
    dimensions: [
        { type: 'string', key: 'year' },
        { type: 'string', key: 'location' },
        { type: 'string', key: 'product' }
    ]
});

// Add data
qube.push([
    { year: '2023', location: 'Seattle', product: 'Apple', sales: 100 },
    { year: '2023', location: 'Seattle', product: 'Orange', sales: 80 },
    { year: '2023', location: 'Portland', product: 'Apple', sales: 120 },
    { year: '2024', location: 'Seattle', product: 'Apple', sales: 150 },
]);

// Query total
qube.one({ measure: 'total_sales' }); // → 450

// Query with partial dimensions (slice)
qube.query({ 
    measure: 'total_sales', 
    dimensions: { year: '2023', product: 'Apple' } 
}); // → 220

// Query specific cell (dice)
qube.dice({ 
    measure: 'total_sales', 
    dimensions: { year: '2023', location: 'Seattle', product: 'Apple' } 
}); // → 100

📊 Measure Types

| Type | Description | |------|-------------| | sum | Sum of all values | | count | Count of records | | min | Minimum value | | max | Maximum value | | average | Average of values | | first | First value encountered | | last | Last value encountered | | distinct | Count of unique values | | variance | Population variance | | stddev | Population standard deviation |

📖 API Reference

Constructor

const qube = new Qube({ measures, dimensions })

| Option | Description | |--------|-------------| | measures | Array of { type, key, name } | | dimensions | Array of { type, key } |

Properties

| Property | Description | |----------|-------------| | rowCount | Number of rows pushed | | dimensionCount | Number of dimensions |

Methods

Data Operations

qube.push(rows)    // Add rows
qube.clear()       // Clear all data

Querying

// Get total for a measure
qube.one({ measure: 'total_sales' })

// Query with any combination of dimensions
qube.query({ measure: 'total_sales', dimensions: { year: '2023' } })

// Slice (alias for query)
qube.slice({ measure: 'total_sales', dimensions: { year: '2023', location: 'Seattle' } })

// Dice - query specific cell (all dimensions provided)
qube.dice({ measure: 'total_sales', dimensions: { year: '2023', location: 'Seattle', product: 'Apple' } })

Rollup & Drilldown

// Rollup - aggregate by dimension with totals
qube.rollup('year', { measure: 'total_sales' })
// → [{ dimensions: { year: '2023' }, value: 300 }, 
//    { dimensions: { year: '__TOTAL__' }, value: 450 }]

// Drilldown - break down by a dimension
qube.drilldown('product', { measure: 'total_sales', dimensions: { year: '2023' } })
// → [{ dimensions: { year: '2023', product: 'Apple' }, value: 220 }, ...]

Enumeration

// Get unique values for a dimension
qube.enumerateDimension('year') // → ['2023', '2024']

// Query across all values of a dimension
qube.queryWithEnumeration('year', { measure: 'total_sales' })
// → [{ value: 300, year: '2023' }, { value: 150, year: '2024' }]

Filter

// Filter by dimension values
qube.filter({ dimensions: { year: '2023' } })

// Filter by multiple values
qube.filter({ dimensions: { year: ['2023', '2024'] } })

// Filter with custom predicate
qube.filter({ predicate: (dims, measures) => measures.total_sales > 100 })

Metadata

qube.getDimensionInfo()
// → [{ key: 'year', type: 'string', cardinality: 2, values: ['2023', '2024'] }, ...]

qube.getDimensionInfo('year')
// → { key: 'year', type: 'string', cardinality: 2, values: ['2023', '2024'] }

qube.getMeasureInfo()
// → [{ name: 'total_sales', key: 'sales', type: 'sum' }, ...]

Serialization

// Basic serialization
const data = qube.serializeCube()   // Serialize to object
const restored = Qube.fromCube(data) // Restore from object

// Compressed serialization (gzip) - ~80% smaller
const compressed = await qube.serializeCompressed()     // Returns Buffer
const restored = await Qube.fromCompressed(compressed)  // Restore from Buffer

// Sync versions also available
const compressed = qube.serializeCompressedSync()
const restored = Qube.fromCompressedSync(compressed)

// Save to file
const fs = require('fs');
fs.writeFileSync('cube.gz', qube.serializeCompressedSync());
const loaded = Qube.fromCompressedSync(fs.readFileSync('cube.gz'));

🔷 Hypercube Example (N Dimensions)

const qube = new Qube({
    measures: [{ type: 'sum', key: 'revenue', name: 'total_revenue' }],
    dimensions: [
        { type: 'string', key: 'year' },
        { type: 'string', key: 'quarter' },
        { type: 'string', key: 'region' },
        { type: 'string', key: 'product' },
        { type: 'string', key: 'channel' }  // 5 dimensions!
    ]
});

qube.push([
    { year: '2024', quarter: 'Q1', region: 'West', product: 'Widget', channel: 'Online', revenue: 1000 },
    // ... more data
]);

// Query across any combination of dimensions
qube.query({ 
    measure: 'total_revenue', 
    dimensions: { year: '2024', region: 'West' } 
});

⚠️ Limitations

• In-memory storage only
• All data must fit in memory

🤝 Contributing

Contributions welcome! Please open an issue to discuss changes first.

📄 License

MIT