#Period shapes

@teakit/matrix builds in four fixed-shape period matrices, each with a fixed row length and a fixed key format.

import { Matrix } from "@teakit/matrix";

// Built by Matrix.range(...).fill(value); see the range reference.
Matrix.range("2024", "2024", { by: "quarter" }).fill(0);
// { "2024": [0, 0, 0, 0] }  (QuarterMatrix: YYYY -> 4)

Matrix.range("2024-02", "2024-02", { by: "day" }).fill(0)["2024-02"].length;
// 31  (DayMatrix: YYYY-MM -> 31; Feb 30/31 are "-")

#API Reference

DayMatrix uses YYYY-MM -> 31 (one month per row), not YYYY -> 366. Non-existent days (e.g. Feb 30) are "-".

#Shape detection

rollup and rolldown take no from argument — they detect the input period from key format + row length:

• YYYY -> 1 → year
• YYYY -> 4 → quarter
• YYYY -> 12 → month
• YYYY-MM -> 31 → day

All rows must match one shape. Mixed or unrecognized shapes raise MATRIX_UNRECOGNIZED_PERIOD_MATRIX. An ordinary matrix that happens to match a shape is treated as that period — this is intentional.

#Agent Contract

#Agent Notes

• Create period matrices with range; convert between granularities with rollup (finer → coarser) and rolldown (coarser → finer).
• Do not assume a from option on rollup/rolldown — pass only to.
• Non-existent days in a DayMatrix are always "-", never undefined.