Assinaturas de Índice versus Record
Escolha entre assinaturas de índice e o tipo utilitário Record.
Assinaturas de Índice versus Record é uma aula grátis de TypeScript Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de TypeScript Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de TypeScript Academy inclui 4 aulas no total.
Duas formas de tipar um mapa
O TypeScript oferece duas formas comuns de descrever um dicionário: uma assinatura de índice, como { [k: string]: V }, e o tipo utilitário integrado Record<K, V>. Eles se sobrepõem bastante, mas têm leituras diferentes.
O tipo utilitário Record
Record<K, V> constrói um tipo de objeto cujas keys são K e cujos valores são V. Com string como chave, ele equivale a uma assinatura de índice de cadeia de caracteres.
type Scores = Record<string, number>
const game: Scores = { alice: 10, bob: 7 }
console.log(game.alice)Equivalente a uma assinatura de índice
Esses dois tipos descrevem a mesma estrutura. Record<string, number> e { [key: string]: number } são intercambiáveis para keys arbitrárias de cadeia de caracteres.
type A = Record<string, number>
type B = { [key: string]: number }
const a: A = { x: 1 }
const b: B = a // assignable both ways
console.log(b.x)Record com uma união de keys literais
O verdadeiro poder de Record aparece com uma união finita de keys literais. Ele produz um objeto em que cada chave listada é obrigatória — algo que uma assinatura de índice não consegue expressar.
type Role = "admin" | "editor" | "viewer"
type Perms = Record<Role, boolean>
const p: Perms = { admin: true, editor: true, viewer: false }
console.log(p.admin)Keys ausentes são detectadas
Como cada chave literal é obrigatória, esquecer uma delas gera um erro de compilação. Essa é uma garantia forte que as assinaturas de índice simplesmente não conseguem oferecer.
type Role = "admin" | "editor" | "viewer"
// const bad: Record<Role, boolean> = { admin: true, editor: true }
// Error: property viewer is missingA assinatura de índice permite qualquer chave
Por outro lado, uma assinatura de índice é aberta. Você pode adicionar keys nunca mencionadas em lugar algum, e nada precisa estar presente.
type Open = { [key: string]: number }
const o: Open = {} // no keys required
o.anything = 1 // any key allowed
console.log(o.anything)Conjuntos finitos de keys: prefira Record
Quando as keys formam um conjunto finito conhecido, Record com uma união literal é mais claro e seguro. Ele documenta exatamente quais keys existem e impõe completude.
type Direction = "north" | "south" | "east" | "west"
type Moves = Record<Direction, number>
const m: Moves = { north: 1, south: 0, east: 2, west: 0 }
console.log(m.east)Conjuntos abertos de keys: ambas funcionam
Quando as keys são ilimitadas e descobertas em tempo de execução, tanto Record<string, V> quanto uma assinatura de índice funcionam. Muitas equipes escolhem Record pela concisão; outras escolhem a assinatura pela explicitude.
type Cache1 = Record<string, string>
type Cache2 = { [url: string]: string }
const c: Cache1 = {}
c["/home"] = "<html>"
console.log(c["/home"])Record é apenas um tipo mapeado
Internamente, Record<K, V> é definido como um tipo mapeado: { [P in K]: V }. Saber disso explica por que uma união literal produz keys obrigatórias, enquanto string produz uma assinatura de índice.
// lib definition (simplified):
// type Record<K extends string | number | symbol, V> = { [P in K]: V }
type Flags = Record<"a" | "b", boolean>
const f: Flags = { a: true, b: false }
console.log(f.a)Keys nomeadas e captura geral
Uma assinatura de índice pode combinar uma captura geral com keys fixas em uma única interface — útil quando você precisa das duas. Record sozinho não consegue combinar keys nomeadas obrigatórias com uma captura geral aberta de maneira tão simples.
interface Response {
status: number
[header: string]: number | string
}
const r: Response = { status: 200, "x-id": "abc" }
console.log(r.status)Escolhendo na prática
Regra prática: keys finitas e conhecidas → Record<Union, V> para verificar a completude. Keys ilimitadas → qualquer uma das formas. Precisa de keys nomeadas e uma captura geral → assinatura de índice dentro de uma interface.
type Status = "ok" | "error"
type Messages = Record<Status, string>
const msg: Messages = { ok: "done", error: "failed" }
console.log(msg.ok)Verificação rápida
Teste sua compreensão de Record em comparação com assinaturas de índice.
Recapitulação
Record<string, V> equivale a uma assinatura de índice de cadeia de caracteres, mas Record com uma união de keys literais torna obrigatória cada chave listada, detectando omissões em tempo de compilação. Utilize Record<Union, V> para keys finitas e conhecidas, qualquer uma das formas para keys ilimitadas e uma assinatura de índice quando precisar de keys nomeadas e uma captura geral. Internamente, Record é o tipo mapeado { [P in K]: V }.
Perguntas Frequentes
A aula “Assinaturas de Índice versus Record” é grátis?
Sim — o texto completo de “Assinaturas de Índice versus Record” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de TypeScript Academy, atualize para CoddyKit PRO. O curso de TypeScript Academy inclui 4 aulas no total.
O que vou aprender em “Assinaturas de Índice versus Record”?
Escolha entre assinaturas de índice e o tipo utilitário Record. Você pratica TypeScript Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar TypeScript Academy?
Nenhuma experiência prévia é necessária. TypeScript Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.
Quanto tempo leva a aula “Assinaturas de Índice versus Record”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de TypeScript Academy?
Sim. Cada aula de TypeScript Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Definindo Assinaturas de Índice
- Assinaturas de Índice de Texto versus Número
- Combinando Chaves Conhecidas e Dinâmicas
- Assinaturas de Índice versus Record