@teakit/sheet

rollup

Rolls a finer period sheet up to a coarser one, detecting the input period from its shape (no from argument).

import { Sheet } from "@teakit/sheet";

Sheet.rollup({ "2024": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] }, { to: "year" });
// { "2024": [78] }  (default aggregation is sum; "-"/undefined skipped)

Sheet.rollup({ "2024": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] }, { to: "quarter" });
// { "2024": [6, 15, 24, 33] }

Sheet.rollup({ "2024": [10, 20, 30, 40] }, { to: "year" }); // { "2024": [100] }

// Empty target buckets are "-": only January is present here.
Sheet.rollup({ "2024-01": Array(31).fill(1) }, { to: "month" });
// { "2024": [31, "-", "-", "-", "-", "-", "-", "-", "-", "-", "-", "-"] }

// Override the per-bucket aggregation (receives only valid values).
Sheet.rollup(monthSheet, { to: "year", using: (values) => Arith.sum(...values) });

API Reference

Signature

Sheet.rollup<TCell, TTo extends SheetRollupTo, TResult>(
  sheet: Sheet<TCell>,
  options: SheetRollupOptions<TTo, SheetValueOf<TCell>, TResult>,
): SheetRollupResult<TTo, TResult>;

Parameters

ParameterTypeRequiredNotes
options.to"year" | "quarter" | "month"YesMust be strictly coarser than the input.
options.using(values) => TResultNoPer-bucket aggregation over valid values, no context. Defaults to sum.

Supported directions: day → month/quarter/year, month → quarter/year, quarter → year.

Returns

A fixed-shape target period sheet, keys ascending, no auto-filled gap years; buckets with no source period or no valid value are "-".

Throws

  • SHEET_INVALID_ROLLUP_OPTIONS — invalid to or non-function using.
  • SHEET_UNRECOGNIZED_PERIOD_SHEET — input is not a recognizable period sheet (mixed or unknown shape).
  • SHEET_UNSUPPORTED_ROLLUP — same-or-finer target.

Agent Contract

FieldValue
Kindstatic period transform
Canonical namerollup
AliasesNone
Mutates inputsNo
ReturnsSheetRollupResult<TTo, TResult>

Agent Notes

  • Do not pass from; the input period is detected from key format + row length (see period-shapes).
  • using receives only valid values (no "-"/undefined) and no context.
  • For the opposite direction (coarser → finer) use rolldown.