@teakit/sheet

rolldown

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

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

// Default expansion copies the source value to every valid target period.
Sheet.rolldown({ "2024": [100] }, { to: "quarter" });
// { "2024": [100, 100, 100, 100] }

Sheet.rolldown({ "2024": [10, 20, 30, 40] }, { to: "month" });
// { "2024": [10, 10, 10, 20, 20, 20, 30, 30, 30, 40, 40, 40] }

// Allocate instead of copy, using the context.
Sheet.rolldown({ "2024": [100] }, {
  to: "quarter",
  using: (value, ctx) => value / ctx.targetCount, // 100 / 4
});
// { "2024": [25, 25, 25, 25] }

// month -> day: each month value fills its existing days; non-existent days "-".
Sheet.rolldown({ "2024": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] }, { to: "day" });
// 12 keys "2024-01".."2024-12"; "2024-02" is [2 x29, "-", "-"]

API Reference

Signature

Sheet.rolldown<TCell, TTo extends SheetRolldownTo, TResult>(
  sheet: Sheet<TCell>,
  options: SheetRolldownOptions<TTo, SheetValueOf<TCell>, TResult>,
): SheetRolldownResult<TTo, TResult>;

Parameters

ParameterTypeRequiredNotes
options.to"quarter" | "month" | "day"YesMust be strictly finer than the input.
options.using(value, context) => TResultNoPer-target value. context has targetOffset/targetCount (and from/to/sourceKey/sourceIndex/targetKey/targetIndex). Defaults to copying the source value.

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

Returns

A fixed-shape target period sheet, keys ascending. Source "-"/undefined and non-existent days are "-" without calling using. A leap year expands to 366 valid target days, a common year to 365.

Throws

  • SHEET_INVALID_ROLLDOWN_OPTIONS — invalid to or non-function using.
  • SHEET_UNRECOGNIZED_PERIOD_SHEET — input is not a recognizable period sheet.
  • SHEET_UNSUPPORTED_ROLLDOWN — same-or-coarser target.

Agent Contract

FieldValue
Kindstatic period transform
Canonical namerolldown
AliasesNone
Mutates inputsNo
ReturnsSheetRolldownResult<TTo, TResult>

Agent Notes

  • Unlike aggregation/rollup, using receives a single value plus a context (allocation needs the target position and count).
  • The default copies — divide by context.targetCount for even allocation.
  • Do not pass from; the shape is detected.