#Matrix

A matrix is a keyed business structure — row key -> ordered values — stored as a plain object: Record<string, readonly T[]>.

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

const revenue = {
  "2024": [100, 120, 130, 140],
  "2025": [150, 160, 170, 180],
};

// "-" marks a fixed-shape position that needs no value (MatrixNoData).
// undefined marks a genuinely missing key or column. They are NOT the same.
const quarterly = {
  "2024": ["-", 0, 0, 0], // Q1 intentionally empty
  "2025": [0, undefined, undefined, undefined], // Q2..Q4 missing
};

// Every returning API emits keys in ascending order and never mutates input.
Matrix.toObject({ b: [1], a: [2] }); // { a: [2], b: [1] }

#API Reference

@teakit/matrix is not a linear-algebra library. It models keyed two-dimensional business data (forecasts, budgets, occupancy, KPIs, asset models), not matrix multiplication, inverses, determinants, or eigenvalues.

#Core types

type MatrixRow<T> = readonly T[];
type Matrix<T = unknown, TKey extends string = string> = Readonly<
  Record<TKey, MatrixRow<T>>
>;
type MatrixCell<M extends Matrix> = M[keyof M][number];
type MatrixKey<M extends Matrix> = Extract<keyof M, string>;
type MatrixNoData = "-";

#Invariants

• Key order: integer-index keys sort numerically first, then other string keys lexicographically. Fixed-width period keys (YYYY, YYYY-MM) therefore sort in time order. All returning APIs emit keys ascending; map, reduce, and entries traverse in that same order.
• No-data vs missing: aggregation and rollup skip both "-" and undefined; merge, zip, normalize, and transpose pass "-" through verbatim and never invent it.
• Immutability: every operation returns a new object; inputs are not mutated. Row arrays are copied; cell values are not deep-copied.

#Agent Contract

#Agent Notes

• Import with import { Matrix } from "@teakit/matrix"; no default import.
• Do not call Matrix(...) or new Matrix(...); it is a namespace of static functions, not a class.
• Keep matrices as plain objects and arrays; do not wrap them in classes.
• See period-shapes for the fixed period shapes and errors for the error model.