Indexed access types in TypeScript: T[K], T[number] e altro

Un indexed access type cerca il tipo di una proprietà in un altro tipo, con la stessa sintassi a parentesi quadre che JavaScript usa per accedere alle proprietà. Person["age"] è number, e Person["address"]["city"] è 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

Il vantaggio è un'unica fonte di verità. Age non è una seconda copia di number: se Person["age"] diventa string, ogni tipo scritto come Person["age"] cambia con lui. Gli indexed access types esistono solo in fase di compilazione; non producono JavaScript.

Chiavi unione e T[keyof T]

L'indice può essere un'unione di chiavi. Il risultato è l'unione dei tipi delle proprietà:

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] è il modo, a livello di tipi, per dire "qualsiasi valore di proprietà di Product". Chiedere una chiave che non esiste è un errore di compilazione: Product["price"] dà error TS2339: Property 'price' does not exist on type 'Product'.

Le proprietà facoltative includono undefined

Con strictNullChecks (attivo con strict), il tipo di una proprietà facoltativa include undefined, e lo stesso vale per il suo indexed access type:

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

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

Per togliere undefined, avvolgilo: NonNullable<Profile["nickname"]> è string.

Tipi degli elementi di un array con T[number]

Gli array si indicizzano con numeri, quindi indicizzare un tipo array con number dà il tipo degli elementi. Funziona anche su più livelli:

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

È utile quando un tipo arriva da qualcosa che non controlli, come un client API generato: ApiResponse["data"]["users"][number] dà un nome al tipo utente senza che nessuno l'abbia esportato.

Tuple: indicizzare per posizione

Un tipo tupla si può indicizzare con una posizione specifica, con number per l'unione di tutti i tipi degli elementi, e con "length" per la sua lunghezza come tipo letterale:

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]: un'unione da un array const

L'uso più comune nel mondo reale: tieni un elenco di valori ammessi come array (così puoi ciclarci sopra a runtime) e ricavane il tipo unione (così il compilatore lo controlla).

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

Due elementi lo fanno funzionare. as const rende l'array una tupla readonly di tipi letterali; senza, ROLES è string[] e (typeof ROLES)[number] è solo string. Poi typeof trasforma il valore in un tipo, e [number] raccoglie i suoi elementi in un'unione. Le parentesi sono facoltative (typeof ROLES[number] significa la stessa cosa), ma rendono chiaro l'ordine delle operazioni.

Controllare una stringa rispetto all'array

Quella tupla readonly riserva una sorpresa. Il suo metodo includes accetta solo il tipo degli elementi, quindi non puoi passargli una stringa qualsiasi:

// 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"'.

Allarga l'array a readonly string[] per il controllo, e trasforma la funzione in una type guard così un controllo riuscito restringe il valore:

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

Questo schema ti dà un solo elenco per entrambi i compiti: il controllo a runtime usa l'array e il tipo ne viene ricavato, quindi non possono mai divergere.

Indexed access nei generics: T[K]

Dentro un generic, T[K] con K extends keyof T è il tipo della proprietà scelta da chi chiama:

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[]

È il vincolo K extends keyof T a rendere lecito T[K]. Senza, TypeScript non può sapere che K è una chiave di T e segnala error TS2536: Type 'K' cannot be used to index type 'T'.

La sintassi in sintesi

L'indice è sempre un tipo. Person[key], dove key è una variabile const, fallisce con due errori: error TS2538: Type 'key' cannot be used as an index type. e error TS2749: 'key' refers to a value, but is being used as a type here. Did you mean 'typeof key'?.