Indexed access types em TypeScript: T[K], T[number] e mais

Um indexed access type busca o tipo de uma propriedade em outro tipo, com a mesma sintaxe de colchetes que o JavaScript usa para acessar propriedades. 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

A vantagem é ter uma única fonte da verdade. Age não é uma segunda cópia de number: se Person["age"] mudar para string, todo tipo escrito como Person["age"] muda junto. Indexed access types existem só em tempo de compilação; eles não geram JavaScript.

Chaves em union e T[keyof T]

O índice pode ser uma union de chaves. O resultado é a union dos tipos das propriedades:

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] é o jeito, no nível dos tipos, de dizer "qualquer valor de propriedade de Product". Pedir uma chave que não existe é erro de compilação: Product["price"] dá error TS2339: Property 'price' does not exist on type 'Product'.

Propriedades opcionais incluem undefined

Com strictNullChecks (ligado com strict), o tipo de uma propriedade opcional inclui undefined, e o indexed access type dela também:

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

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

Para remover o undefined, envolva-o: NonNullable<Profile["nickname"]> é string.

Tipos de elemento de array com T[number]

Arrays são indexados por números, então indexar um tipo array com number dá o tipo do elemento. Isso também funciona em vários níveis:

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

Isso é útil quando um tipo vem de um lugar que você não controla, como um cliente de API gerado: ApiResponse["data"]["users"][number] dá nome ao tipo de usuário sem que ninguém o tenha exportado.

Tuplas: indexe pela posição

Um tipo de tupla pode ser indexado com uma posição específica, com number para a union de todos os tipos de elemento, e com "length" para o tamanho dela como literal type:

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]: uma union a partir de um array const

O uso mais comum no mundo real: manter uma lista de valores permitidos como array (para poder percorrê-la em tempo de execução) e derivar o union type dela (para que o compilador a verifique).

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

Duas partes fazem isso funcionar. O as const transforma o array em uma tupla readonly de literal types; sem ele, ROLES é string[] e (typeof ROLES)[number] é só string. Depois, o typeof transforma o valor em um tipo, e o [number] junta os elementos dele em uma union. Os parênteses são opcionais (typeof ROLES[number] significa o mesmo), mas deixam clara a ordem das operações.

Verificando uma string contra o array

Essa tupla readonly tem uma surpresa. O método includes dela só aceita o tipo do elemento, então você não pode passar uma string qualquer para ele:

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

Amplie o array para readonly string[] na verificação e transforme a função em um type guard, para que uma verificação bem-sucedida estreite o valor:

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

Esse padrão dá uma única lista para os dois trabalhos: a verificação em tempo de execução usa o array, e o tipo é derivado dele, então os dois não conseguem ficar dessincronizados.

Indexed access em generics: T[K]

Dentro de um generic, T[K] com K extends keyof T é o tipo de qualquer propriedade que quem chama escolheu:

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

A restrição K extends keyof T é o que torna T[K] válido. Sem ela, o TypeScript não tem como saber que K é uma chave de T e mostra error TS2536: Type 'K' cannot be used to index type 'T'.

Sintaxe em resumo

O índice é sempre um tipo. Person[key], em que key é uma variável const, falha com dois erros: 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'?.