@teakit/matrix

normalize

Normalizes a matrix to a stable key set and fixed row length, padding with fill.

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

// Defaults: input keys, max existing row length, fill = undefined.
Matrix.normalize({ "2025": [1, 2], "2024": [3] });
// { "2024": [3, undefined], "2025": [1, 2] }

// Fix the key set and length.
Matrix.normalize({ "2025": [1, 2], "2024": [3] }, { keys: ["2024", "2025"], length: 3 });
// { "2024": [3, undefined, undefined], "2025": [1, 2, undefined] }

// A missing key becomes a full fill row.
Matrix.normalize({ "2024": [1] }, { keys: ["2024", "2025"], fill: 0 });
// { "2024": [1], "2025": [0] }

// Existing "-" / undefined are preserved; only the tail is filled.
Matrix.normalize({ a: ["-", undefined] }, { length: 3, fill: "x" });
// { a: ["-", undefined, "x"] }

API Reference

Signature

Matrix.normalize<T, TInputKey extends string, TOutputKey extends string, TFill>(
  matrix: Matrix<T, TInputKey>,
  options?: MatrixNormalizeOptions<TOutputKey, TFill>,
): Matrix<T | TFill | undefined, TOutputKey>;

Parameters

ParameterTypeRequiredNotes
options.keysreadonly string[]NoOutput key set (output is always ascending regardless of array order). No duplicates.
options.lengthnumberNoFixed row length. Finite non-negative integer, not below the max existing row length.
options.fillTFillNoPad value. Defaults to undefined; never auto-generates "-".

Returns

A matrix with the requested keys (ascending) and rows of length, existing values kept and tails padded with fill.

Throws

  • MATRIX_INVALID_NORMALIZE_OPTIONS — duplicate keys, or a length that is not a finite non-negative integer or is below the max existing row length.

Agent Contract

FieldValue
Kindstatic structure tool
Canonical namenormalize
AliasesNone
Mutates inputsNo
ReturnsMatrix<T | TFill | undefined, TOutputKey>

Agent Notes

  • normalize has no period semantics and never invents "-"; pass fill: "-" explicitly if you want it.
  • keys selects the output set only; ordering is always ascending.