DEV Community: Isaac Muniz

Mapped Types em TypeScript: gerando tipos derivados de outros tipos

Isaac Muniz — Tue, 07 Jul 2026 20:39:00 +0000

Em algum momento todo projeto TypeScript chega nesse ponto: você já tem um tipo que descreve um objeto, e agora precisa de uma variação dele. Quase igual, mas com todos os campos opcionais. Ou com todos os campos aceitando null. Ou com todos somente leitura.

A solução ingênua é copiar o tipo e ajustar campo por campo, na mão. Funciona, até o tipo original ganhar um campo novo. A cópia não acompanha sozinha, e nada te avisa disso.

Mapped types são a resposta do TypeScript para esse problema: em vez de reescrever cada campo, você descreve a transformação uma vez e manda o compilador percorrer todas as chaves de um tipo existente aplicando ela automaticamente. Adicione um campo ao tipo original, e toda variação construída a partir dele se atualiza sozinha no próximo compile, sem edição manual nenhuma.

Só o type consegue expressar isso. Um interface não tem mecanismo equivalente, e no final deste artigo vai ficar claro exatamente por quê.

Perto do final deste artigo você vai encontrar links para o TypeScript Playground oficial, com o código já pronto para rodar sem precisar instalar nada. Se preferir, também pode ir copiando os exemplos abaixo e testando na sua própria IDE ao longo da leitura.

Antes de chegar lá, uma passada rápida por três conceitos que este artigo assume que você já conhece: object types, union types e string literal types. Se você já domina os três, pule direto para a próxima seção.

As três peças de base

Um object type descreve a forma de um objeto:

type Entry = { id: string; minutes: number };

Um union type descreve um valor que pode ser de mais de um tipo, separados por |:

type MaybeNumber = number | null;

Um string literal type é quando um texto específico vira um tipo em si, não apenas um string genérico:

type OnlyId = "id";

E os três se combinam: "id" | "minutes" é uma union de string literal types, um tipo que aceita exatamente esses dois textos e nenhum outro. Esses três conceitos são a chave para entender os próximos.

O problema que os mapped types resolvem

Volte ao Entry acima. Suponha que você precise de um segundo tipo quase idêntico, mas em que todo campo também pode ser null (um rascunho de formulário antes do usuário preencher, por exemplo). Sem nenhuma ferramenta especial, você escreve na mão, campo por campo:

type Entry = { id: string; minutes: number };

// Manual, campo por campo: cada campo repetido e transformado na mão.
type NullableEntryManual = {
  id: string | null;
  minutes: number | null;
};

const draft: NullableEntryManual = { id: null, minutes: 90 };

console.log(draft.id, draft.minutes); // null 90

Funciona, e para dois campos está de bom tamanho. Mas repare que você digitou id e minutes pela segunda vez, e aplicou a mesma transformação, adicionar | null, em cada um dos campos, na mão. Se Entry ganhar um terceiro campo depois, o NullableEntryManual não se atualiza sozinho. Você teria que lembrar de voltar nele e editar também, e nada te avisa se você esquecer.

É esse acoplamento frágil que o mapped type elimina. Mas para chegar na sintaxe dele, precisamos de duas peças menores primeiro. Ambas só existem no TypeScript, nunca em código JavaScript comum.

Primeira peça: o operador keyof

keyof é uma palavra-chave exclusiva do TypeScript. Ela não existe em JavaScript. Como todo tipo aqui, ela é apagada antes do JavaScript ser emitido, então tem custo zero em tempo de execução. Ela existe só para o compilador raciocinar sobre os seus tipos.

O que ela faz é simples: keyof recebe um object type e produz a união dos nomes das chaves dele, como string literal types.

type Entry = { id: string; minutes: number };

// keyof lê um object type e produz a união dos nomes de suas chaves.
type EntryKeys = keyof Entry; // equivale a "id" | "minutes"

const entryKey: EntryKeys = "id";

console.log(entryKey); // id

Repare que aqui aparecem as duas peças da seção anterior juntas: keyof Entry é uma union de string literal types. Nada é transformado ainda. keyof Entry só responde a pergunta "quais são os nomes dos campos desse tipo, como uma união?".

Você pode provar que a resposta é exata, e não apenas "qualquer string", tentando uma chave que não existe:

type Entry = { id: string; minutes: number };
type EntryKeys = keyof Entry;
const invalidEntryKey: EntryKeys = "other"; // não compila

Isso não compila. O TypeScript rejeita com:

error TS2322: Type '"other"' is not assignable to type 'keyof Entry'.

Isso confirma que keyof Entry é mesmo o conjunto fechado "id" | "minutes", calculado a partir do próprio Entry em vez de escrito à mão.

Segunda peça: indexed access

Se o keyof responde "quais são as chaves", um indexed access type responde "qual é o tipo do valor guardado nesta chave". Essa peça tem um significado exclusivo do TypeScript montado em cima de um símbolo com cara de JavaScript: os colchetes [...] são exatamente os mesmos que o JavaScript usa para ler uma propriedade em tempo de execução (entry["minutes"]), mas aqui, escritos depois de um nome de tipo em vez de uma variável, eles rodam inteiramente em tempo de compilação e produzem um tipo, não um valor.

type Entry = { id: string; minutes: number };

// Indexed access: lê o tipo do valor guardado em uma chave.
type IdType = Entry["id"]; // string
type MinutesType = Entry["minutes"]; // number

const idValue: IdType = "e1";
const minutesValue: MinutesType = 42;

console.log(idValue, minutesValue); // e1 42

Entry["minutes"] não está lendo um valor em tempo de execução, Entry é um tipo, não um objeto, então não há nada a ler. Ele está perguntando ao compilador: "no tipo Entry, qual tipo está guardado sob a chave "minutes"?". A resposta vira um tipo próprio, number, que você pode usar em qualquer lugar onde um tipo é esperado.

Juntando as duas peças

Antes de olhar a sintaxe completa do mapped type, vale separar os dois símbolos que ela usa: as chaves { } externas e os colchetes [ ] internos. Nenhum dos dois faz nada que você ainda não tenha visto, uma vez isolados.

As chaves `{ }` externas não têm nada de novo

Todo object type que você escreveu até aqui veio embrulhado em chaves: { x: number; y: number }, { id: string; minutes: number }. Um mapped type continua sendo um object type, então continua começando e terminando com { }. Nada muda aí.

O `[ ]` interno não é um array

Essa é a parte que parece estranha, então vale ancorar em algo que você provavelmente já conhece do JavaScript puro: computed property names. Em um object literal, se você quer que o nome de uma propriedade venha de uma variável em vez de ser digitado literalmente, você embrulha essa variável em colchetes:

// JavaScript puro, sem TypeScript ainda.
const key = "id";
const obj = { [key]: "e1" };

console.log(obj); // { id: 'e1' }

Aqui, [key] não está criando um array. Ele fica no lugar do nome da propriedade dentro do object literal, e diz ao JavaScript "use o valor da variável key como o nome desta propriedade", em vez de "a propriedade se chama literalmente key". Sem os colchetes, { key: "e1" } criaria uma propriedade chamada literalmente key, o que é outra coisa completamente diferente.

Um mapped type reutiliza exatamente esse mesmo lugar, a posição do nome da propriedade dentro das chaves { }. A diferença é que, em vez de calcular um único nome a partir de uma variável, como [key] fez, ele varre uma união inteira de chaves, uma de cada vez, usando duas peças novas.

type Toggles = { [K in "darkMode" | "compactView"]: boolean };

A primeira peça é o K. Ele não é uma palavra reservada, é só um nome escolhido por você, do mesmo jeito que key era um nome escolhido no exemplo em JavaScript. Na verdade, é o mesmo papel que a variável de um loop for...of exerce em JavaScript: em for (const item of list) { ... }, item é só um nome guardando o valor atual da iteração, e você poderia chamá-lo de qualquer coisa. K funciona igual, só que guarda a chave atual em vez de um item de lista. Poderia se chamar Prop ou Name sem mudar nada no resultado, mas a convenção da comunidade TypeScript é usar K (de "key"), e é isso que você vai encontrar no dia a dia.

A segunda peça é o in. É ele quem faz o trabalho de repetição: K in UNION significa "para cada membro da união UNION, rode esta linha uma vez, chamando o membro atual de K". É o in que transforma uma união estática em uma sequência de rodadas, uma por chave.

Leia a linha completa juntando as duas peças:

{ } diz "isto é um object type", como sempre.
[K in "darkMode" | "compactView"] diz "para cada string literal type dentro desta união, rode uma vez, chamando o valor atual de K, e use essa string literal como nome da propriedade desta rodada".

Cuidado para não confundir com o outro in: o JavaScript já tem um operador in que checa se um objeto tem uma certa propriedade, como em "id" in someObject. É um operador diferente. O in do mapped type só existe dentro dessa posição de colchete, em tempo de compilação, e some depois que o TypeScript vira JavaScript.

Ou seja, essa única linha está fazendo duas rodadas do mesmo template: uma com K = "darkMode", outra com K = "compactView", e cada rodada cria uma propriedade, darkMode: boolean e compactView: boolean, usando o tipo depois dos dois pontos como tipo de valor para as duas. O resultado é exatamente { darkMode: boolean; compactView: boolean }, só que gerado mecanicamente em vez de digitado na mão.

Do union escrito à mão para keyof

Agora troque a união escrita à mão por keyof Entry, para que as chaves venham de um tipo existente em vez de serem listadas na mão, e use indexed access para que cada propriedade mantenha o seu tipo original em vez de um tipo fixo:

type Entry = { id: string; minutes: number };

// Mapped type sem transformação: percorre cada chave de Entry mantendo o tipo 
// do valor.
// O resultado é um tipo novo, mas com forma indistinguível de Entry.
type EntryCopy = { [K in keyof Entry]: Entry[K] };

const entryCopy: EntryCopy = { id: "e1", minutes: 90 };
const backToEntry: Entry = entryCopy; // intercambiáveis, mesma forma

console.log(entryCopy.id, entryCopy.minutes, backToEntry.minutes); // e1 90 90

O que { [K in keyof Entry]: Entry[K] } faz, passo a passo:

keyof Entry calcula "id" | "minutes", o conjunto de chaves a percorrer.
[K in ...] percorre essa união um membro de cada vez, chamando o membro atual de K.
Para cada K, Entry[K] busca o tipo de valor original naquela mesma chave.
O resultado é uma propriedade nova, chamada K, tipada exatamente como estava em Entry.

Esse mapped type em particular não muda nada, ele reproduz Entry campo por campo, e por isso pode ser chamado de mapped type sem transformação. Ele existe aqui só para isolar o mecanismo antes do próximo passo mexer nele.

Adicionando a transformação

O ponto inteiro de um mapped type é que o passo 4 acima, Entry[K], não precisa ficar intocado. Você pode embrulhar ele em qualquer coisa, e esse embrulho é aplicado a cada chave automaticamente:

type Entry = { id: string; minutes: number };
type NullableEntry = { [K in keyof Entry]: Entry[K] | null };

Agora Entry[K] | null significa "qualquer que fosse o tipo original deste campo, ou null". Como isso é calculado uma vez e aplicado a toda chave, não importa se Entry tem dois campos ou vinte: NullableEntry acompanha sozinho, sem nenhuma edição manual.

Compare com o NullableEntryManual lá do começo. O resultado é o mesmo, mas agora a transformação está descrita em um lugar só, e ela acompanha o Entry para sempre.

Por que isso importa: Partial, Readonly e companhia

Toda transformação campo por campo que você possa querer: deixar todos os campos opcionais, deixar todos somente leitura, deixar todos aceitando null, é um mapped type no fundo. Os utility types que o TypeScript já traz prontos, como Partial<T>, Required<T>, Readonly<T> e Record<K, V>, não são mágica especial do compilador: são mapped types comuns, já prontos pelo TypeScript, para você não precisar reescrever toda vez.

Como amostra, o Partial<T> é mais ou menos isso:

type Entry = { id: string; minutes: number };

// Uma versão manual e aproximada do que o Partial<T> te dá.
// O ? aqui é o modificador de opcional: ele pode ser aplicado dentro de um
// mapped type do mesmo jeito que se aplica a um campo normal.
type PartialEntry = { [K in keyof Entry]?: Entry[K] };

// O Partial<T> nativo do TypeScript faz exatamente a mesma coisa por baixo dos panos.
type PartialEntryBuiltIn = Partial<Entry>;

const patch: PartialEntry = { minutes: 45 }; // id pode ficar de fora
const builtInPatch: PartialEntryBuiltIn = { minutes: 45 }; // mesmo resultado

// Como os dois tipos têm a mesma forma, o valor de um serve perfeitamente como 
// o outro.
const proof: PartialEntry = builtInPatch;

console.log(patch.minutes, builtInPatch.minutes, proof.minutes); // 45 45 45

O ? é a novidade aqui. Ele é o modificador de opcional, e a única razão de mostrá-lo agora é para que, quando você esbarrar no Partial<T> no dia a dia, ele seja reconhecível como "o mecanismo de mapped type que você já conhece, mais um modificador", e não uma ideia inteiramente nova. Rode o arquivo você mesmo e veja: PartialEntry e PartialEntryBuiltIn são intercambiáveis, porque são o mesmo mapped type escrito de duas formas.

O arquivo completo

Tudo acima se resume nos dois casos abaixo: um mapped type sobre uma união de chaves explícita, e um mapped type sobre keyof com uma transformação. É um arquivo que você pode rodar com npx tsc e depois node.

/*
  Mapped type: constrói um tipo novo percorrendo um conjunto de chaves.
*/

// ---

// Caso A: percorre um conjunto explícito de chaves,
// dando a cada uma o mesmo tipo de valor.
type Toggles = { [K in "darkMode" | "compactView"]: boolean };

const settings: Toggles = { darkMode: true, compactView: false };

console.log(settings.darkMode, settings.compactView); // true false

// ---

// Caso B: percorre as chaves de um tipo existente, transformando cada valor.
type Entry = { id: string; minutes: number };
type NullableEntry = { [K in keyof Entry]: Entry[K] | null };

const draft: NullableEntry = { id: null, minutes: 90 };

console.log(draft.id, draft.minutes); // null 90

// ---

/*
  Um corpo de interface não aceita a forma [K in ...] de mapped type.
  Se você descomentar a linha abaixo e rodar npx tsc, recebe:

  error TS1169: A computed property name in an interface must refer to
  an expression whose type is a literal type or a 'unique symbol' type.
*/
// interface TogglesIface { [K in "darkMode" | "compactView"]: boolean }

A saída é:

true false
null 90

Deixei esse mesmo código disponível, pronto para você rodar, sem precisar instalar nada.

🔗 Abrir este código no TypeScript Playground

É só abrir o link e ver o resultado logo do lado direito da tela. Se preferir, copie e cole o código acima e rode na sua própria IDE.

De uma forma ou de outra, descomente a linha do interface para ver o erro TS1169 de perto. Em seguida, experimente trocar a união de Toggles por outras chaves, ou embrulhar Entry[K] em algo diferente de | null no NullableEntry. É treinando essas variações que o { [K in ...]: ... } deixa de parecer sintaxe decorada e passa a ser uma ferramenta que você sabe montar do zero.

Conclusão

Mapped types resolvem um problema chato e comum: manter tipos paralelos em sincronia. Em vez de copiar um tipo e transformar campo por campo na mão, você descreve a transformação uma vez, { [K in keyof T]: ... }, e o compilador aplica ela a toda chave. Adicione um campo ao tipo de origem, e cada variação derivada dele se atualiza sozinha sem mais trabalho manual e com menos propensão a bugs.

Depois de destrinchar o mecanismo, { [K in keyof Entry]: Entry[K] | null } se lê como uma frase: "para cada chave K de Entry, mantenha o tipo de valor original, mas também permita null". E o ganho vai além do caso pontual: Partial, Required, Readonly e Record deixam de parecer mágica e passam a ser o que são de fato, mapped types comuns que o TypeScript já escreveu por você. Entender a mecânica por baixo deles é o que te permite ir além dos prontos e escrever a sua própria transformação quando nenhum utility type existente resolve.

Se quiser revisitar todos os exemplos deste artigo juntos, num único arquivo, prontos para você testar sem precisar montar nada do zero, aqui está:

🔗 Ver todos os exemplos juntos no TypeScript Playground

Os exemplos estão organizados na mesma ordem em que apareceram no texto.

Sistemas de Tipos: os três eixos que definem como uma linguagem se comporta

Isaac Muniz — Sat, 02 May 2026 16:38:53 +0000

Todo dado em um programa tem um tipo. Um número inteiro, um texto, um valor verdadeiro ou falso - cada um desses é um tipo diferente, e a linguagem precisa saber com qual está lidando para executar operações sobre ele corretamente.
Mas o que acontece quando você tenta somar um número com um texto? Ou usar um objeto onde se espera outro? É aí que entram os sistemas de tipos: o conjunto de regras que cada linguagem define para lidar com essas situações. Diferentes linguagens fazem escolhas muito diferentes nesse sentido, e entender essas escolhas é essencial para qualquer desenvolvedor.

Para entender essas diferenças, precisamos primeiro responder uma pergunta mais fundamental: o que é exatamente um tipo?

Mas afinal, o que é um tipo?

Um tipo define duas coisas: quais valores são válidos e quais operações podem ser realizadas sobre eles. Quando você cria uma variável do tipo number, a linguagem entende que você pode fazer contas com ela. Quando cria uma do tipo string, a linguagem sabe que você pode concatenar, dividir em partes, converter para maiúsculas.

Tipos Primitivos e Tipos Compostos

Existem dois grandes grupos de tipos: os primitivos e os compostos.

Tipos Primitivos

Tipos primitivos são os blocos de construção elementares. Toda linguagem tem algo parecido com isto:

// TypeScript
const idade: number = 27;
const nome: string = "Isaac";
const ativo: boolean = true;

# Python
idade = 27    # int
nome = "Isaac"    # str
ativo = True    # bool

// Go
var idade int = 27
var nome string = "Isaac"
var ativo bool = true

São valores simples, indivisíveis. Um número é um número. Uma string é uma sequência de caracteres. Um booleano é verdadeiro ou falso.

Tipos compostos

Tipos compostos são construídos a partir de outros tipos - sejam primitivos ou outros compostos. Eles agrupam dados relacionados em uma estrutura única. Aqui é onde as diferenças entre linguagens começam a aparecer:

// TypeScript
interface Pessoa {
  nome: string;
  idade: number;
}

const isaac: Pessoa = {
  nome: "Isaac",
  idade: 27,
};

# Python
class Pessoa:
    def __init__(self, nome: str, idade: int):
        self.nome = nome
        self.idade = idade

isaac = Pessoa("Isaac", 27)

// Go
type Pessoa struct {
    Nome  string
    Idade int
}

isaac := Pessoa{Nome: "Isaac", Idade: 27}

A ideia é a mesma em todas: agrupar dados relacionados sob um único tipo. Mas por que isso importa?

Porque assim a linguagem consegue garantir certos comportamentos. Se você tem uma função que espera receber uma Pessoa, a linguagem pode verificar que você está passando realmente uma Pessoa - não uma string confundida por acaso. E é aqui que as linguagens começam a divergir: cada uma tem regras diferentes sobre o que é ou não permitido. Vamos começar pela diferença mais intuitiva.

Como diferentes linguagens tratam a tipagem

Agora que sabemos o que é um tipo, podemos explorar como as linguagens diferem na forma de lidar com eles. Essa diferença aparece em situações concretas do dia a dia: o que acontece quando você passa um valor do tipo errado para uma função? Quando a linguagem detecta o problema? Ela avisa ou simplesmente segue em frente? As respostas variam bastante, e entendê-las ajuda a tomar decisões mais conscientes, tanto na escolha de uma linguagem quanto no uso dela. Vamos aos exemplos.

Em JavaScript:

// JavaScript
"5" + 3   // == "53" - o número foi silenciosamente convertido para string
"5" - 3   // == 2 - agora a string foi silenciosamente convertida para número
[] + {}   // "[object Object]" - resultado que não faz sentido

O resultado muda dependendo do operador, sem nenhum aviso, sem nenhum erro. Por isso nos exemplos está escrito "silenciosamente". A linguagem fez coerções implícitas - converteu os tipos automaticamente para tentar fazer a operação funcionar de qualquer jeito. Isso é tipagem fraca: a linguagem aceita operações entre tipos incompatíveis sem reclamar.

PHP tem um comportamento semelhante:

// PHP
"5" + 3;   // == 8 - string convertida para número automaticamente

PHP moderno evoluiu bastante com o suporte a type hints.

O que são type hints?
Type hints são anotações opcionais que você adiciona ao código para indicar explicitamente qual tipo de dado uma variável, parâmetro ou retorno de função deve ter. O nome é sugestivo: são "dicas de tipo". Dependendo da linguagem, elas podem ser verificadas pela própria linguagem, por ferramentas externas como editores e analisadores estáticos, ou por ambos. Em PHP moderno, ficaria assim:
// PHP
function dobrar(int $n): int {
    return $n * 2;
}

PHP moderno, com type hints, melhorou bastante - mas ainda carrega o legado de ser permissivo com coerções. Outras linguagens fizeram a escolha oposta. Veja o que acontece em Python com a mesma tentativa de somar string e número:

# Python
"5" + 3  # TypeError: can only concatenate str (not "int") to str

# Ou seja: "Erro de Tipagem: só é possível concatenar uma string (não um inteiro) à outra string"

A linguagem simplesmente se recusa. Se você quiser concatenar, precisa ser explícito: "5" + str(3). Isso é tipagem forte: a linguagem exige que as operações façam sentido entre os tipos envolvidos.

TypeScript e Go se comportam da mesma forma:

// TypeScript
const x: number = "cinco"; // Erro: Type 'string' is not assignable to type 'number'

// Traduzindo: "Erro: Tipo 'string' não é atribuível a tipo 'número'"

// Go
var x int = "cinco" // cannot use "cinco" (type string) as type int

// Traduzindo: "não é possível usar "cinco" (do tipo string) como tipo inteiro"

Resumindo: forte/fraco mede a tolerância da linguagem à ambiguidade de tipos. Linguagens fracas tentam resolver a situação sozinhas, linguagens fortes exigem que você resolva.

Type hints e verificação em cada linguagem

Type hints existem em várias linguagens, mas como cada uma as usa na prática? As diferenças são grandes - vão desde linguagens que verificam tudo antes de executar até linguagens que tratam type hints como puros comentários decorativos.

Antes de ver uma tabela comparativa, vale entender o que acontece em cada linguagem quando um erro de tipo ocorre num programa real, porque as consequências são muito diferentes dependendo de onde a verificação acontece.

Nas linguagens que verificam tipos em compilação, como TypeScript, Go e Java, erros de tipo nunca chegam ao usuário. O compilador rejeita o código e o programa simplesmente não é gerado. O desenvolvedor precisa corrigir o problema antes de compilar e portanto antes de publicar qualquer coisa.

Nas linguagens que verificam em runtime, como PHP, o erro aparece durante a execução. Se não for tratado pelo código, o servidor retorna uma tela de erro para o usuário. Mas o PHP faz isso de duas formas diferentes, dependendo da configuração do arquivo.

Type hints em PHP, e modo padrão vs modo estrito

No modo padrão, o PHP tenta ser prestativo: antes de reclamar de um tipo errado, ele tenta converter o valor para o tipo esperado. Se conseguir, segue em frente silenciosamente. Só lança um erro quando a conversão é realmente impossível:

// PHP
dobrar("5");   // PHP converte "5" para 5 silenciosamente - sem erro
dobrar("abc"); // TypeError - impossível converter

Esse comportamento é conveniente, mas também perigoso - pode esconder bugs em vez de expô-los. Por isso o PHP oferece um modo mais rigoroso. Basta adicionar a linha declare(strict_types=1); no topo do arquivo para que a linguagem passe a exigir que os tipos batam exatamente, sem nenhuma conversão automática:

// PHP
declare(strict_types=1);

dobrar("5"); // TypeError - mesmo sendo conversível

JavaScript

Em JavaScript, o comportamento é o mais permissivo de todos: erros de tipo raramente interrompem o programa. A linguagem tenta resolver a situação por conta própria com coerções, e o que sobra vai para o console do navegador - invisível para o usuário, silencioso para o desenvolvedor desatento.

Type hints em Python

Python fica num meio-termo curioso: a linguagem tem tipagem forte - não faz coerções - mas as type hints não causam nenhum erro por si só. Se um valor do tipo errado entrar numa função, Python não vai reclamar das anotações. Vai reclamar somente quando a operação em si falhar, como tentar multiplicar uma string por outra. Nesse caso, lança uma exceção que, se não tratada, retorna um erro 500 para o usuário.

Para verificação antecipada em Python, existem ferramentas externas que leem as type hints e apontam inconsistências antes da execução. As mais usadas são mypy, a mais tradicional da comunidade, e pyright, criada pela Microsoft. Já o Pylance é uma extensão do VS Code que usa o pyright por baixo dos panos para mostrar os erros diretamente no editor enquanto você digita.

JSDoc em JavaScript

JavaScript também tem uma solução para verificação antecipada sem abrir mão de ser JavaScript: o JSDoc combinado com a diretiva // @ts-check. JSDoc é um padrão de comentários estruturados que permite anotar tipos diretamente em arquivos .js:

// JavaScript
// @ts-check

/**
 * @param {number} n
 * @returns {number}
 */
function dobrar(n) {
  return n * 2;
}

dobrar("cinco"); // o editor sublinha o erro

A diretiva // @ts-check no topo do arquivo instrui o VS Code a verificar o arquivo usando o mesmo mecanismo do TypeScript por baixo dos panos. Você continua escrevendo JavaScript puro, sem mudar a extensão do arquivo, sem compilar nada. Em execução, os comentários são ignorados e nenhuma verificação acontece - só o editor lê e interpreta as anotações.

Tabela: Tipagem em diferentes linguagens

Com isso em mente, a tabela abaixo resume como cada linguagem se comporta:

Linguagem	Quando a verificação acontece	Quem verifica	O que acontece num programa rodando quando há erro de tipo
JavaScript	Não acontece nativamente	Ferramentas externas (VS Code com `// @ts-check` e JSDoc)	O programa continua rodando com resultado imprevisível; erros aparecem só no console do navegador
PHP (modo padrão)	Em runtime	A própria linguagem	Converte o valor silenciosamente e segue em frente
PHP (modo estrito)	Em runtime	A própria linguagem	Lança `TypeError`; se não tratado, o usuário vê uma página de erro 500
Python	Não acontece nativamente	Ferramentas externas (mypy, pyright, Pylance)	Lança exceção; se não tratada, o usuário vê uma página de erro 500
TypeScript	Em compilação	O compilador `tsc`	Impossível: o código não compila e nunca chega ao usuário
Go	Em compilação	O compilador `go`	Impossível: o código não compila e nunca chega ao usuário
Java	Em compilação	O compilador `javac`	Impossível: o código não compila e nunca chega ao usuário

Os três eixos dos sistemas de tipos

Forte e fraca, como falamos acima, é apenas uma das formas de classificar o sistema de tipos de uma linguagem. Existem três eixos independentes, e confundir um com o outro é muito comum:

Eixo	Pergunta que responde	Resposta
Forte / Fraca	A linguagem aceita operações entre tipos incompatíveis?	Não aceita: Forte / Aceita: Fraca
Estática / Dinâmica	Os tipos são verificados antes ou durante a execução?	Antes: Estática / Durante: Dinâmica
Nominal / Estrutural	Dois tipos são compatíveis pelo nome ou pela forma?	Pelo nome: Nominal / Pela forma: Estrutural

Já vimos o primeiro eixo em detalhes. Vamos relembrá-lo e explorar os outros dois.

Forte vs. Fraca: o quanto a linguagem tolera operações entre tipos incompatíveis?

Linguagens com tipagem fraca, como JavaScript e PHP, fazem coerções implícitas para tentar fazer a operação funcionar. Linguagens com tipagem forte, como Python, TypeScript e Go, se recusam e exigem que o código seja explícito.

Estática vs. Dinâmica: quando os tipos são verificados?

Linguagens como Go compilam o código antes de rodar: um programa chamado compilador lê o código inteiro, verifica os tipos e só então gera o executável. Se houver um erro de tipo, o programa nem começa a rodar. Isso é tipagem estática.

Linguagens como Python e JavaScript não têm essa etapa. O código é lido e executado linha a linha, e os tipos só são verificados quando aquela linha específica roda. Um erro de tipo numa função raramente chamada pode passar despercebido por muito tempo - até o dia em que essa função for executada em produção. Isso é tipagem dinâmica.

TypeScript é um caso especial: ele compila, mas não gera código de máquina - gera JavaScript, que depois é interpretado. Mesmo assim, é durante a compilação que os tipos são verificados, por isso é considerado estaticamente tipado.

Uma consequência prática da tipagem dinâmica é que a mesma variável pode receber valores de tipos diferentes ao longo do código:

# Python
x = 5        # x aponta para um inteiro
x = "hello"  # x agora aponta para uma string - sem erro

Isso funciona porque em Python o tipo pertence ao valor, não à variável. A variável x é só um nome que aponta para um valor: primeiro apontava para 5 (do tipo int), depois passou a apontar para "hello" (do tipo str). Os valores em si continuam tendo seus tipos - o que mudou foi apenas para qual valor x está apontando.

Em linguagens com tipagem estática, como Go, é o oposto: o tipo pertence à variável. Quando você declara var x int, está dizendo que x é um recipiente que só aceita inteiros. Ele não pode passar a apontar para uma string, independentemente do que aconteça:

// Go
var x int = 5
x = "hello" // ❌ cannot use "hello" (type string) as type int

A escolha entre tipagem estática vs. dinâmica

A escolha entre estática e dinâmica envolve uma troca. Tipagem estática oferece segurança antecipada: erros são detectados antes de o programa rodar, o que é especialmente valioso em projetos grandes. Tipagem dinâmica oferece flexibilidade e agilidade: o código tende a ser mais enxuto e não exige declarações de tipo em todo lugar, o que pode acelerar o desenvolvimento em projetos menores ou exploratórios. Não há uma escolha universalmente certa - depende do contexto.

Nominal vs. Estrutural: o que torna dois tipos compatíveis?

Esse eixo responde a uma pergunta mais sutil: para a linguagem aceitar que um tipo B seja usado onde se espera um tipo A, o que precisa ser verdade?

Em linguagens com tipagem nominal, o que importa é o nome declarado. Dois tipos são compatíveis somente se houver uma relação explícita entre eles. Java é um exemplo claro:

// Java
interface Animal {
    void speak();
}

class Dog implements Animal {
    public void speak() { System.out.println("Au!"); }
}

Se você criar uma classe Cat com exatamente os mesmos métodos mas sem declarar implements Animal, o Java não vai aceitar um Cat onde se espera um Animal - mesmo que a estrutura seja idêntica:

// Java
class Cat {
    public void speak() { System.out.println("Miau!"); }
}

Animal a = new Cat(); // ❌ Cat cannot be converted to Animal

Em linguagens com tipagem estrutural, o que importa é a forma - os métodos e propriedades que o tipo possui. Se a estrutura bate, a operação é aceita, independentemente do nome ou de qualquer declaração explícita. TypeScript funciona assim:

// TypeScript
interface Animal {
  speak(): void;
}

class Dog {
  speak() {
    console.log("Au!");
  }
}

// Dog nunca declarou que implementa Animal,
// mas TypeScript aceita porque a estrutura é compatível
const a: Animal = new Dog(); // ✅

Isso tem um nome: duck typing estático. A expressão vem de um ditado em inglês: "If it walks like a duck and quacks like a duck, it's a duck" - "se anda como pato e grasna como pato, é um pato". A identidade de um tipo é definida pelo que ele faz, não pelo que ele se declara ser. O "estático" indica que essa verificação ainda acontece em tempo de compilação.

Python também é estrutural, mas sem checagem antecipada - qualquer objeto que tenha os métodos certos é aceito, e a linguagem só descobre incompatibilidades em execução. Go mistura as duas abordagens: tipos concretos são nominais, mas interfaces são estruturais, o que significa que uma struct satisfaz uma interface automaticamente, sem precisar declará-la explicitamente.

A escolha entre tipagem nominal vs. estrutural

Tipagem nominal exige mais cerimônia no código - você precisa declarar explicitamente as relações entre tipos - mas em troca oferece contratos mais claros e verificáveis. É mais fácil saber exatamente o que uma função aceita e o que ela rejeita. Tipagem estrutural é mais flexível e menos verbosa, mas exige mais atenção do desenvolvedor: dois tipos podem ser compatíveis por acidente, simplesmente por terem os mesmos métodos, mesmo que representem conceitos completamente diferentes.

Onde cada linguagem se encaixa

Com os três eixos em mente, fica mais fácil comparar as linguagens de forma objetiva. A tabela abaixo mostra como cada uma se posiciona nesses eixos de tipagem:

Linguagem	Forte / Fraca	Estática / Dinâmica	Nominal / Estrutural
Java	Forte	Estática	Nominal
C#	Forte	Estática	Nominal
Go	Forte	Estática	Misto (nominal para tipos concretos, estrutural para interfaces)
TypeScript	Forte	Estática	Estrutural
Python	Forte	Dinâmica	Estrutural
Ruby	Forte	Dinâmica	Estrutural
PHP	Fraca	Dinâmica	Ambíguo (nominal com classes e interfaces, mas historicamente permissivo)
JavaScript	Fraca	Dinâmica	Estrutural

Nenhuma combinação é universalmente melhor. Cada uma reflete escolhas de design que priorizam coisas diferentes: segurança, flexibilidade, produtividade ou clareza de contrato.

Do sistema de tipos mais rígido para o mais permissivo

Considerando os três eixos juntos - onde forte é mais rígido que fraco, estática mais rígida que dinâmica, e nominal mais rígida que estrutural - é possível ordenar as linguagens do sistema de tipos mais restritivo para o mais permissivo:

Java, C# - forte + estática + nominal: o nível mais alto de restrição, com verificação antecipada e contratos explícitos obrigatórios
Go - forte + estática + nominal/estrutural: tão rígido quanto Java e C# na verificação antecipada, mas um pouco mais flexível nas interfaces
TypeScript - forte + estática + estrutural: verificação antecipada sem exigir declarações explícitas de conformidade
Python, Ruby - forte + dinâmica + estrutural: sem coerções, mas erros só aparecem em execução
PHP - fraca + dinâmica + ambíguo: permissivo por padrão, com rigor opcional via strict_types
JavaScript - fraca + dinâmica + estrutural: o sistema de tipos mais permissivo da lista

Vale lembrar que essa ordenação é uma simplificação. Na prática, a rigidez de um sistema de tipos depende também de como o desenvolvedor usa a linguagem - PHP com strict_types e mypy no Python, por exemplo, podem se comportar de forma bem mais rígida do que a posição deles na lista sugere.

Conclusão

Tipos são um daqueles assuntos que parecem simples até você começar a comparar como linguagens diferentes os tratam. Um mesmo erro pode travar o programa antes de rodar, explodir em produção, ou passar completamente despercebido, dependendo das escolhas que a linguagem faz. Conhecer essas diferenças muda a forma como você lê erros, escolhe ferramentas e escreve código.

DEV Community: Isaac Muniz

Mapped Types em TypeScript: gerando tipos derivados de outros tipos

As três peças de base

O problema que os mapped types resolvem

Primeira peça: o operador keyof

Segunda peça: indexed access

Juntando as duas peças

As chaves { } externas não têm nada de novo

O [ ] interno não é um array

Do union escrito à mão para keyof

Adicionando a transformação

Por que isso importa: Partial, Readonly e companhia

O arquivo completo

Conclusão

Sistemas de Tipos: os três eixos que definem como uma linguagem se comporta

Mas afinal, o que é um tipo?

Tipos Primitivos e Tipos Compostos

Tipos Primitivos

Tipos compostos

Como diferentes linguagens tratam a tipagem

Type hints e verificação em cada linguagem

Type hints em PHP, e modo padrão vs modo estrito

JavaScript

Type hints em Python

JSDoc em JavaScript

Tabela: Tipagem em diferentes linguagens

Os três eixos dos sistemas de tipos

Forte vs. Fraca: o quanto a linguagem tolera operações entre tipos incompatíveis?

Estática vs. Dinâmica: quando os tipos são verificados?

A escolha entre tipagem estática vs. dinâmica

Nominal vs. Estrutural: o que torna dois tipos compatíveis?

A escolha entre tipagem nominal vs. estrutural

Onde cada linguagem se encaixa

Do sistema de tipos mais rígido para o mais permissivo

Conclusão

As chaves `{ }` externas não têm nada de novo

O `[ ]` interno não é um array