@iobroker/aggregate

Shared data aggregation for the ioBroker history adapters.

ioBroker.history, ioBroker.sql and ioBroker.influxdb all answer the same getHistory message and therefore all need the same bucket logic, the same border handling and the same integral calculation. Until now every adapter carried its own copy of aggregate.ts with the comment "THIS file should be identical with SQL and history adapter's one" — which, of course, they were not.

This package is that file, extracted, typed and covered by unit tests.

Installation

npm install @iobroker/aggregate

Usage

The aggregation runs in three steps: initialize the state, feed the raw data points into it, finish it.

import { initAggregate, aggregation, finishAggregation } from '@iobroker/aggregate';
import type { IobDataEntry } from '@iobroker/aggregate';

const rawData: IobDataEntry[] = await readFromDatabase();

const options = initAggregate({
    start: Date.now() - 86400000,
    end: Date.now(),
    count: 500,
    limit: 2000,
    aggregate: 'average',
});

aggregation(options, rawData);
finishAggregation(options);

console.log(options.result);

Most adapters do not need the three steps at all, because sendResponse does everything including the answer on the message bus:

import { sendResponse } from '@iobroker/aggregate';

adapter.on('message', msg => {
    if (msg.command === 'getHistory') {
        const startTime = Date.now();
        const options = { ...msg.message.options, id: msg.message.id };
        readFromDatabase(options)
            .then(data => sendResponse(adapter, msg, options.id, options, data, startTime))
            .catch(e => sendResponse(adapter, msg, options.id, options, e.toString(), startTime));
    }
});

Aggregation methods

| Method | Result per interval | |------------------|---------------------------------------------------------------------------------| | none | the raw values, only cut to the requested range | | onchange | the raw values, drawn as a step chart | | minmax | start, min, max and end of the interval, in chronological order | | min | the smallest value | | max | the largest value | | average | the arithmetic mean, rounded to two decimals | | total | the sum of all values | | count | the number of values | | percentile | the value at the requested percentile (percentile: 0..100, default 50) | | quantile | the value at the requested quantile (quantile: 0..1, default 0.5) | | integral | the integral per interval, divided by integralUnit seconds (default 60) | | integralTotal | one single integral over the whole range, in value × hours |

integral supports two interpolations: none (default, the value is held until the next data point) and linear (a straight line is drawn between two data points).

Note: integralUnit is only applied to the fixed-step integral. If smart intervals are used, the integral is always returned in value × hours, exactly like integralTotal.

Smart intervals

Statistics per hour, per day or per month cannot use a fixed step, because a real day has 23, 24 or 25 hours and a real month has 28 to 31 days. getSmartIntervals builds the calendar-aligned intervals, which can be handed to initAggregate instead of a step:

import { getSmartIntervals, initAggregate, aggregation, finishAggregation } from '@iobroker/aggregate';

// every day of March 2026, including the 23 hours long one
const intervals = getSmartIntervals(
    { year: 2026, month: 3, date: 1, timeZone: 1 },
    'day',
    { year: 2026, month: 4, date: 1, timeZone: 1 },
);

const options = initAggregate(
    { start: intervals[0].start, end: intervals[intervals.length - 1].end, aggregate: 'integral' },
    'javascript.0.consumption',
    intervals,
);

The daylight saving time is resolved via the local time zone of the process, timeZone only gives the offset of the standard (winter) time in hours — 1 for Germany.

API

| Export | Description | |-----------------------------|-----------------------------------------------------------------------------| | initAggregate | builds the aggregation state out of the getHistory options | | aggregation | sorts the raw data points into the buckets | | finishAggregation | calculates the result of every bucket and beautifies it | | beautify | cuts to the range, handles nulls, adds border values, rounds, adds the ID | | sendResponse | the complete getHistory answer including the aggregation | | sendResponseCounter | the getCounter answer: the sum of all increases of a counter | | calcDiff | the trapezoid between two data points, in value × hours | | sortByTs | sort comparator for IobDataEntry | | getSmartIntervals | calendar-aligned intervals per hour, day or month | | HSmartDate | a date that can be advanced hour by hour over DST and month borders |

The types (GetHistoryOptions, InternalHistoryOptions, IobDataEntry, TimeInterval, SmartDate, …) are exported as well and are also available from the subpath @iobroker/aggregate/types.

Development

npm ci
npm run build          # compile to build/
npm run check          # lint + type check + tests
npm test               # unit tests only
npm run test:coverage  # unit tests with a coverage report

The unit tests pin process.env.TZ to Europe/Berlin, because the smart intervals depend on the local time zone.

License

MIT — Copyright (c) 2019-2026 bluefox [email protected]