Tableaux en TypeScript : types, tableaux d'objets, map et filter

Un type tableau TypeScript s'écrit avec le type des éléments suivi de [] : string[] est un tableau de chaînes, number[] un tableau de nombres. L'écriture générique Array<string> désigne le même type. Une fois le tableau typé, chaque élément que vous ajoutez et chaque élément que vous lisez a ce type.

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 ligne @ts-expect-error est une erreur de compilation (TS2345). Elle est marquée ici comme attendue pour que le bloc s'exécute quand même, et comme les types sont effacés, le 42 est bel et bien ajouté à l'exécution : la sortie le montre.

string[] ou Array<string>

Choisissez un style par base de code. La règle array-type de typescript-eslint utilise T[] par défaut.

Tableaux d'objets

Décrivez l'élément avec un alias de type ou une interface, puis utilisez Type[]. Tout ce qui est lu dans le tableau est vérifié par rapport à cette forme.

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 littéral objet ajouté à users doit correspondre exactement à User : un admin manquant ou une propriété mal orthographiée est une erreur de compilation.

map, filter, reduce et find typés

Les méthodes de tableau sont génériques, leurs résultats portent donc des types. Ce que fait chaque méthode à l'exécution est expliqué sur la page JavaScript des méthodes de tableau ; les types sont l'apport de 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 ]

Le dernier exemple fonctionne parce que TypeScript (depuis la 5.5) infère que (n) => n !== undefined est un prédicat de type, si bien que filter renvoie number[] au lieu de (number | undefined)[]. Pour les vérifications qu'il ne sait pas inférer, écrivez le prédicat vous-même : filter((x): x is User => x !== null).

Tableaux contenant plus d'un type

Une union comme type d'élément autorise le mélange. Une union de types tableau, non :

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));
}

Quand les positions ont des types fixes, comme une paire [name, age], utilisez plutôt un tuple : [string, number] sait que l'indice 0 est une chaîne et l'indice 1 un nombre, ce que (string | number)[] ignore.

Tableaux readonly

readonly T[] retire toutes les méthodes qui modifient le tableau. Utilisez-le pour les paramètres qu'une fonction ne doit pas changer, et pour les 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[]'.

Supprimez la ligne push et le bloc affiche 4. Un number[] modifiable peut toujours être passé là où readonly number[] est attendu, les paramètres readonly ne coûtent donc rien aux appelants. La vérification n'a lieu qu'à la compilation : à l'exécution, c'est un tableau ordinaire. Pour trier un tableau readonly, triez une copie : [...values].sort().

Le piège de includes avec les tableaux de littéraux

as const transforme un tableau en tuple readonly de types littéraux. C'est pratique pour une liste de valeurs autorisées, mais son includes n'accepte alors que ces littéraux :

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

Placer la vérification dans un type guard (value is Color) fait que l'élargissement n'a lieu qu'une fois, et les appelants récupèrent une valeur affinée.

Indices et tableaux vides

Lire arr[i] donne le type T, même quand i est hors limites et que la valeur à l'exécution est undefined. at(i) est typé T | undefined, et l'option de compilation noUncheckedIndexedAccess fait aussi renvoyer T | undefined à l'accès simple par indice.

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() compilerait puis lèverait une TypeError à l'exécution. Préférez at(), une vérification de longueur, ou noUncheckedIndexedAccess quand un indice peut manquer.