Types d'accès indexé en TypeScript : T[K], T[number] et plus

Un type d'accès indexé cherche le type d'une propriété dans un autre type, avec la même syntaxe à crochets que JavaScript utilise pour l'accès aux propriétés. Person["age"] vaut number, et Person["address"]["city"] vaut string.

type Person = {
  name: string;
  age: number;
  address: { city: string; zip: string };
};

type Age = Person["age"];                 // number
type City = Person["address"]["city"];    // string
type Address = Person["address"];         // { city: string; zip: string }

const age: Age = 36;
const home: Address = { city: "London", zip: "N1" };
const city: City = home.city;

console.log(age, city); // 36 London

L'avantage est une source de vérité unique. Age n'est pas une seconde copie de number : si Person["age"] devient string, chaque type écrit Person["age"] change avec lui. Les types d'accès indexé n'existent qu'à la compilation ; ils n'émettent aucun JavaScript.

Unions de clés et T[keyof T]

L'indice peut être une union de clés. Le résultat est l'union des types de propriétés :

type Product = {
  id: number;
  title: string;
  inStock: boolean;
};

type IdOrTitle = Product["id" | "title"];  // number | string
type AnyValue = Product[keyof Product];    // number | string | boolean

function describe(value: AnyValue): string {
  return `${typeof value}: ${value}`;
}

const p: Product = { id: 7, title: "Lamp", inStock: false };
for (const key of ["id", "title", "inStock"] as const) {
  console.log(describe(p[key]));
}
// number: 7
// string: Lamp
// boolean: false

Product[keyof Product] est la façon de dire au niveau des types « n'importe quelle valeur de propriété de Product ». Demander une clé qui n'existe pas est une erreur de compilation : Product["price"] donne error TS2339: Property 'price' does not exist on type 'Product'.

Les propriétés optionnelles incluent undefined

Avec strictNullChecks (activé par strict), le type d'une propriété optionnelle inclut undefined, et son type d'accès indexé aussi :

type Profile = { name: string; nickname?: string };

type Nick = Profile["nickname"]; // string | undefined

Pour retirer le undefined, enveloppez-le : NonNullable<Profile["nickname"]> vaut string.

Type des éléments de tableau avec T[number]

Les tableaux sont indexés par des nombres : indexer un type tableau avec number donne donc le type des éléments. Cela fonctionne aussi sur plusieurs niveaux :

type Order = {
  id: number;
  items: { sku: string; qty: number }[];
};

type Orders = Order[];

type OneOrder = Orders[number];             // Order
type Item = Order["items"][number];         // { sku: string; qty: number }
type Sku = Orders[number]["items"][number]["sku"]; // string

const item: Item = { sku: "A-100", qty: 2 };
const sku: Sku = item.sku;
console.log(sku, item.qty); // A-100 2

C'est utile quand un type vient d'un endroit que vous ne contrôlez pas, comme un client d'API généré : ApiResponse["data"]["users"][number] nomme le type utilisateur sans que personne ne l'ait exporté.

Tuples : indexer par position

Un type tuple peut être indexé par une position précise, par number pour l'union de tous les types d'éléments, et par "length" pour sa longueur sous forme de type littéral :

type Entry = [string, number, boolean];

type First = Entry[0];         // string
type Second = Entry[1];        // number
type AnyElement = Entry[number]; // string | number | boolean
type Len = Entry["length"];    // 3

const len: Len = 3;
const entry: Entry = ["ada", 36, true];
const first: First = entry[0];

console.log(first, len); // ada 3
// Entry[3] is error TS2493: Tuple type 'Entry' of length '3' has no element at index '3'.

(typeof arr)[number] : une union à partir d'un tableau const

L'usage le plus courant en pratique : garder une liste de valeurs autorisées sous forme de tableau (pour pouvoir la parcourir à l'exécution) et en dériver le type union (pour que le compilateur la vérifie).

const ROLES = ["admin", "editor", "viewer"] as const;

type Role = (typeof ROLES)[number]; // "admin" | "editor" | "viewer"

function canPublish(role: Role): boolean {
  return role !== "viewer";
}

for (const role of ROLES) {
  console.log(role, canPublish(role));
}
// admin true
// editor true
// viewer false

Deux éléments font fonctionner cela. as const fait du tableau un tuple readonly de types littéraux ; sans lui, ROLES est un string[] et (typeof ROLES)[number] n'est qu'un string. Ensuite, typeof transforme la valeur en type, et [number] rassemble ses éléments en une union. Les parenthèses sont facultatives (typeof ROLES[number] signifie la même chose), mais elles rendent l'ordre des opérations clair.

Vérifier une chaîne par rapport au tableau

Ce tuple readonly réserve une surprise. Sa méthode includes n'accepte que le type des éléments : vous ne pouvez donc pas lui passer une chaîne quelconque.

// This does not compile: includes() on the tuple only accepts a Role
const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number];

function isRole(value: string): boolean {
  return ROLES.includes(value);
}

console.log(isRole("admin"));

index.ts(6,25): error TS2345: Argument of type 'string' is not assignable to parameter of type '"admin" | "editor" | "viewer"'.

Élargissez le tableau en readonly string[] pour la vérification, et faites de la fonction un type guard pour qu'une vérification réussie affine la valeur :

const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number];

function isRole(value: string): value is Role {
  return (ROLES as readonly string[]).includes(value);
}

const input: string = "editor"; // imagine this came from a URL or a form
if (isRole(input)) {
  const role: Role = input; // narrowed to Role here
  console.log("valid role:", role);
}
console.log(isRole("owner")); // false

Ce motif vous donne une seule liste pour les deux rôles : la vérification à l'exécution utilise le tableau, et le type en est dérivé, si bien qu'ils ne peuvent pas diverger.

Accès indexé dans les génériques : T[K]

Dans un générique, T[K] avec K extends keyof T est le type de la propriété choisie par l'appelant, quelle qu'elle soit :

function pluck<T, K extends keyof T>(items: T[], key: K): T[K][] {
  return items.map((item) => item[key]);
}

const users = [
  { name: "Ada", age: 36 },
  { name: "Linus", age: 28 },
];

const names = pluck(users, "name"); // string[]
const ages = pluck(users, "age");   // number[]

C'est la contrainte K extends keyof T qui rend T[K] légal. Sans elle, TypeScript ne peut pas savoir que K est une clé de T et signale error TS2536: Type 'K' cannot be used to index type 'T'.

La syntaxe en un coup d'œil

L'indice est toujours un type. Person[key], où key est une variable const, échoue avec deux erreurs : error TS2538: Type 'key' cannot be used as an index type. et error TS2749: 'key' refers to a value, but is being used as a type here. Did you mean 'typeof key'?.