Package Exports

chart-data-grouper
chart-data-grouper/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (chart-data-grouper) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Chart Data Grouper

A flexible TypeScript library for grouping and aggregating data with support for nested properties, date/time grouping, and histogram generation.

Installation

npm install chart-data-grouper
# or
yarn add chart-data-grouper

Features

Group data by date/time with multiple precision levels
Generate histograms with equal or quantile bins
Aggregate values using sum, average, min, max, count
Handle nested property paths (e.g., "user.profile.age")
TypeScript support with full type safety

API Reference

`groupByDate`

Groups data by date/time intervals and applies aggregations.

import { groupByDate } from 'chart-data-grouper';

const result = groupByDate(data, {
  dateField: 'createdAt',       // Path to date field (supports nesting)
  valueFields: ['value'],       // Fields to aggregate
  operation: 'sum',            // 'sum' | 'average' | 'max' | 'min' | 'count'
  timeGrouping: 'days',       // 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months' | 'years' | 'YYYY-MM-DD-HH:mm:ss:SSS'
});

`groupByProperty`

Groups data by property values and applies aggregations.

import { groupByProperty } from 'chart-data-grouper';

const result = groupByProperty(data, {
  groupBy: 'category',         // Path to group by field
  valueFields: ['price', 'qty'], // Fields to aggregate
  operation: 'average',        // Aggregation operation
  sortBy: 'key',              // 'key' or field path
  sortDirection: 'asc'        // 'asc' | 'desc'
});

`generateHistogram`

Generates histogram data for numerical values.

import { generateHistogram } from 'chart-data-grouper';

const result = generateHistogram(data, {
  valueField: 'age',           // Path to numerical field
  groupBy: 'gender',          // Optional grouping field
  bins: 5,                    // Number of bins
  binType: 'equal',           // 'equal' | 'quantile'
  formatLabel: (min, max) =>  // Custom bin label formatter
    `${min.toFixed(0)}-${max.toFixed(0)}`
});

`getValueByPath`

Utility function to get nested property values.

import { getValueByPath } from 'chart-data-grouper';

const value = getValueByPath(obj, 'nested.property.path');

Usage Examples

1. Group By Date, Sum and Average, Monthly, Daily, Hourly, Minute, Second, Yearly, Weekly, Histogram

const testCaseForSumAndAverage = [
    { month: 'January', desktop: 100, mobile: 50 },
    { month: 'January', desktop: 86, mobile: 30 },
    { month: 'February', desktop: 305, mobile: 200 },
    { month: 'March', desktop: 305, mobile: 200 },
    { month: 'April', desktop: 305, mobile: 200 },
    { month: 'May', desktop: 305, mobile: 200 },
    { month: 'June', desktop: 305, mobile: 200 },
];
const testCaseForCountSumAndAverageByMinutesHourlyDailyMonthlyYearlyAndNone = [
    { createdAt: '2025-06-25T12:00:00Z', desktop: 100, mobile: 50 },
    { createdAt: '2025-06-25T12:02:01Z', desktop: 86, mobile: 30 },
    { createdAt: '2025-06-26T12:02:04Z', desktop: 305, mobile: 200 },
    { createdAt: '2025-06-25T12:00:02Z', desktop: 305, mobile: 200 },
];
const histogramTestCase = [
    {dataOption:{ gender: 'iphone', age: 100 }},
    {dataOption:{ gender: 'android', age: 86 }},
    {dataOption:{ gender: 'iphone', age: 5 }},
    {dataOption:{ gender: 'android', age: 35 }},
    {dataOption:{ gender: 'motorola', age: 5 }},
    {dataOption:{ gender: 'android', age: 1 }},
    {dataOption:{ gender: 'motorola', age: 5 }},
    {dataOption:{ gender: 'nokia', age: 35 }},
    {dataOption:{ gender: 'nokia', age: 35 }},
    {dataOption:{ gender: 'iphone', age: 5 }},
];
// 1. Date grouping example
const dateGrouped = groupByDate(testCaseForCountSumAndAverageByMinutesHourlyDailyMonthlyYearlyAndNone, {
    dateField: 'createdAt',
    valueFields: ['desktop', 'mobile'],
    operation: 'sum',
    timeGrouping: 'minutes',
    monthFormat: 'long'
});

// 2. Histogram example
const histogramData = generateHistogram(histogramTestCase, {
    valueField: 'dataOption.age',
    groupBy: 'dataOption.gender',
    bins: 5
});

// 3. Property grouping example
const propertyGrouped = groupByProperty(testCaseForSumAndAverage, {
    groupBy: 'month',
    valueFields: ['desktop', 'mobile'],
    sortBy: 'month',
});
// Returns histogram data grouped by gender
console.log("dateGrouped", dateGrouped);
console.log("histogramData", JSON.stringify(histogramData, null, 2));
console.log("propertyGrouped", propertyGrouped);

2. Daily Sales Aggregation

const salesData = [...] // Array of sales transactions

const dailySales = groupByDate(salesData, {
  dateField: 'transactionDate',
  valueFields: ['amount'],
  operation: 'sum',
  timeGrouping: 'days'
});

3. Product Category Statistics

const products = [...] // Array of products

const categoryStats = groupByProperty(products, {
  groupBy: 'category.name',
  valueFields: ['price', 'stock'],
  operation: 'average'
});

4. Age Distribution Histogram

const users = [...] // Array of user profiles

const ageHistogram = generateHistogram(users, {
  valueField: 'profile.age',
  groupBy: 'profile.gender',
  bins: 10,
  binType: 'equal'
});

Type Support

All functions are fully typed with TypeScript support. The package exports these types for your convenience:

import {
  TimeGrouping,
  MonthFormat,
  AggregationOperation,
  SortDirection,
  HistogramBin,
  HistogramResult
} from 'chart-data-grouper';

Error Handling

The library handles:

Missing or invalid dates
Non-numerical values in aggregation fields
Missing nested properties
Empty data sets gracefully

License

MIT


## Key Features of This README:

1. **Clear Installation Instructions** - Shows both npm and yarn options
2. **Basic Usage Example** - Gets users started quickly
3. **Comprehensive API Reference** - Documents all parameters and options
4. **Practical Examples** - Covers common use cases
5. **Output Format Documentation** - Clearly shows what to expect
6. **Development Section** - For contributors
7. **Clean Formatting** - Uses markdown tables and code blocks for readability