#Sheet

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

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

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

// "-" marks a fixed-shape position that needs no value (SheetNoData).
// 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.
Sheet.toObject({ b: [1], a: [2] }); // { a: [2], b: [1] }

#API Reference

@teakit/sheet is not a spreadsheet-formula engine or a linear-algebra library. It models keyed two-dimensional business data (forecasts, budgets, occupancy, KPIs, asset models) — no cell formulas, and no linear-algebra operations (multiplication, inverse, determinant, eigenvalues).

#Core types

type SheetRow<T> = readonly T[];
type Sheet<T = unknown, TKey extends string = string> = Readonly<
  Record<TKey, SheetRow<T>>
>;
type SheetCell<M extends Sheet> = M[keyof M][number];
type SheetKey<M extends Sheet> = Extract<keyof M, string>;
type SheetNoData = "-";

#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 { Sheet } from "@teakit/sheet"; no default import.
• Do not call Sheet(...) or new Sheet(...); it is a namespace of static functions, not a class.
• Keep sheets 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.