Arrays en TypeScript: tipos, arrays de objetos, map y filter

Un tipo array en TypeScript es el tipo de los elementos seguido de []: string[] es un array de strings, number[] un array de números. La forma genérica Array<string> es el mismo tipo. Una vez tipado el array, cada elemento que añades y cada elemento que lees tiene ese tipo.

const names: string[] = ["Ada", "Grace"];
const scores: Array<number> = [90, 85, 72]; // same as number[]

names.push("Alan");
// @ts-expect-error: Argument of type 'number' is not assignable to parameter of type 'string'.
names.push(42);

const first: string = names[0];
const total = scores.reduce((sum, s) => sum + s, 0); // number

console.log(names, first, total);

La línea con @ts-expect-error es un error de compilación (TS2345). Aquí se marca como esperado para que el bloque se ejecute igualmente, y como los tipos se borran, el 42 sí se añade en tiempo de ejecución: la salida lo muestra.

string[] frente a Array<string>

Elige un estilo para todo el código. La regla array-type de typescript-eslint usa T[] por defecto.

Arrays de objetos

Describe el elemento con un alias de tipo o una interfaz y luego usa Type[]. Todo lo que lees del array se comprueba contra esa forma.

type User = { id: number; name: string; admin: boolean };

const users: User[] = [
    { id: 1, name: "Ada", admin: true },
    { id: 2, name: "Grace", admin: false },
    { id: 3, name: "Alan", admin: false },
];

users.push({ id: 4, name: "Linus", admin: false });

const admins = users.filter((u) => u.admin);       // User[]
const names = users.map((u) => u.name);            // string[]
const byId = users.find((u) => u.id === 2);        // User | undefined

console.log(admins.length, names);
console.log(byId?.name ?? "not found"); // Grace

Un objeto literal que añades a users debe coincidir exactamente con User: si falta admin o una propiedad está mal escrita, es un error de compilación.

map, filter, reduce y find tipados

Los métodos de array son genéricos, así que sus resultados llevan tipo. Lo que hace cada método en tiempo de ejecución está en la página de métodos de array de JavaScript; los tipos son lo que añade TypeScript:

const prices = [4.5, 12, 8.25];

const labels = prices.map((p) => `$${p.toFixed(2)}`); // string[]
console.log(labels); // [ '$4.50', '$12.00', '$8.25' ]

const expensive = prices.find((p) => p > 100); // number | undefined
console.log(expensive ?? "none"); // none

// reduce's result type comes from the initial value,
// or from a type argument when the initial value is just {}
const byInitial = ["apple", "avocado", "banana"].reduce<Record<string, string[]>>(
    (acc, word) => {
        (acc[word[0]] ??= []).push(word);
        return acc;
    },
    {},
);
console.log(byInitial); // { a: [ 'apple', 'avocado' ], b: [ 'banana' ] }

// filter narrows when the callback is a type check
const raw = [1, undefined, 3, undefined];
const defined = raw.filter((n) => n !== undefined); // number[]
console.log(defined); // [ 1, 3 ]

El último ejemplo funciona porque TypeScript (desde la 5.5) infiere que (n) => n !== undefined es un predicado de tipo, así que filter devuelve number[] en lugar de (number | undefined)[]. Para comprobaciones que no puede inferir, escribe tú el predicado: filter((x): x is User => x !== null).

Arrays con más de un tipo

Una unión como tipo de elemento permite mezclar. Una unión de tipos array no:

const mixed: (string | number)[] = [1, "two", 3]; // each element: string or number

let ids: string[] | number[] = [1, 2, 3]; // all numbers...
ids = ["a", "b"];                          // ...or all strings

// @ts-expect-error: (string | number)[] is not assignable to string[] | number[]
ids = [1, "b"];

for (const item of mixed) {
    // narrow each element before using type-specific methods
    console.log(typeof item === "string" ? item.toUpperCase() : item.toFixed(1));
}

Cuando las posiciones tienen tipos fijos, como un par [name, age], usa una tupla: [string, number] sabe que el índice 0 es un string y el índice 1 un número, y (string | number)[] no lo sabe.

Arrays readonly

readonly T[] elimina todos los métodos que modifican el array. Úsalo para parámetros que una función no debe cambiar y para constantes.

// This does not compile: readonly arrays have no push.
function average(values: readonly number[]): number {
    values.push(0);
    return values.reduce((a, b) => a + b, 0) / values.length;
}

console.log(average([2, 4, 6]));

index.ts(3,12): error TS2339: Property 'push' does not exist on type 'readonly number[]'.

Borra la línea del push y el bloque imprime 4. Un number[] mutable siempre se puede pasar donde se espera readonly number[], así que los parámetros readonly no le cuestan nada a quien llama. La comprobación es solo en tiempo de compilación: en tiempo de ejecución es un array normal. Para ordenar un array readonly, ordena una copia: [...values].sort().

La trampa de includes con arrays de literales

as const convierte un array en una tupla readonly de tipos literales. Es útil para una lista de valores permitidos, pero entonces su includes solo acepta esos literales:

const COLORS = ["red", "green", "blue"] as const;
type Color = (typeof COLORS)[number]; // "red" | "green" | "blue"

function isColor(value: string): value is Color {
    // COLORS.includes(value) is error TS2345: 'string' is not assignable
    // to '"blue" | "green" | "red"'. Widen the array for the check:
    return (COLORS as readonly string[]).includes(value);
}

const input: string = "green";
if (isColor(input)) {
    const c: Color = input; // narrowed to Color
    console.log("valid color:", c);
}
console.log(isColor("purple")); // false

Meter la comprobación en un type guard (value is Color) hace que el ensanchamiento ocurra una sola vez, y quien llama recibe un valor ya estrechado.

Indexación y arrays vacíos

Leer arr[i] da tipo T, incluso cuando i está fuera de rango y el valor en tiempo de ejecución es undefined. at(i) tiene tipo T | undefined, y la opción del compilador noUncheckedIndexedAccess hace que la indexación simple también devuelva T | undefined.

const queue: string[] = []; // annotate empty arrays

const head = queue[0];     // type string, value undefined
const last = queue.at(-1); // type string | undefined

console.log(head, last);            // undefined undefined
console.log(last?.toUpperCase());   // undefined, safely

queue[0].toUpperCase() compilaría y luego lanzaría un TypeError en tiempo de ejecución. Prefiere at(), una comprobación de longitud o noUncheckedIndexedAccess cuando un índice puede faltar.