@teakit/matrix

range

Creates a fixed-shape period matrix range builder; only .fill(value) materializes the matrix.

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

Matrix.range("2024", "2026", { by: "year" }).fill(0);
// { "2024": [0], "2025": [0], "2026": [0] }

// Out-of-range positions become "-".
Matrix.range("2024-Q2", "2025-Q1", { by: "quarter" }).fill(0);
// { "2024": ["-", 0, 0, 0], "2025": [0, "-", "-", "-"] }

// Coarse boundaries expand at the `by` granularity.
Matrix.range("2024", "2024", { by: "month" }).fill(1);
// { "2024": [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1] }

// Non-existent days are "-": Feb 2024 has 29 days, indices 29 and 30 are "-".
Matrix.range("2024-02", "2024-02", { by: "day" }).fill(0)["2024-02"];
// [0, 0, ... (29 zeros), "-", "-"]

Matrix.range("2025", "2024", { by: "year" }); // throws "MATRIX_INVALID_RANGE_BOUNDARY"

API Reference

Signature

Matrix.range<TBy extends MatrixRangeBy>(
  start: MatrixRangeBoundary,
  end: MatrixRangeBoundary,
  options: MatrixRangeOptions<TBy>,
): MatrixRangeBuilder<TBy>;
// MatrixRangeBuilder.fill<T>(value: T): MatrixRangeResult<T, TBy>

Parameters

ParameterTypeRequiredNotes
startstringYesBoundary in a format allowed for by; may be coarser (expanded to its earliest sub-period).
endstringYesBoundary; coarser values expand to their latest sub-period.
options.by"year" | "quarter" | "month" | "day"YesGranularity and fixed row length.
value (on .fill)TYesFilled into every in-range, existing position.

Accepted boundary formats: year → YYYY; quarter → YYYY or YYYY-Qn; month → YYYY or YYYY-MM; day → YYYY, YYYY-MM, or YYYY-MM-DD.

Returns

A builder; .fill(value) returns the period matrix (YearMatrix / QuarterMatrix / MonthMatrix / DayMatrix) with out-of-range and non-existent positions set to "-".

Throws

  • MATRIX_INVALID_RANGE_OPTIONS — by missing or not one of the four.
  • MATRIX_INVALID_RANGE_BOUNDARY — invalid date/quarter, granularity mismatch (e.g. YYYY-MM with by: "quarter"), or start later than end.

Agent Contract

FieldValue
Kindstatic builder factory
Canonical namerange
AliasesNone (no Matrix.fromYear/fromMonth/etc.)
Mutates inputsNo
ReturnsMatrixRangeBuilder<TBy> → .fill returns a period matrix

Agent Notes

  • The matrix only exists after .fill(value); Matrix.range(...) alone returns a builder.
  • Match the boundary format to by; do not mix granularities (e.g. no YYYY-Qn with by: "month").
  • See period-shapes for the resulting shapes.