Documentação de TypeScript
Referência concisa e baseada em exemplos de TypeScript. Leia o conceito, veja o código e pratique em uma jornada da Coddy.
Inicie uma jornada guiada de TypeScriptPrimeiros passos
- O que é TypeScriptO que é TypeScript? É JavaScript com tipos estáticos. Você anota os valores com tipos, o compilador verifica tudo antes de o código rodar e a saída é JavaScript puro, que roda em qualquer navegador ou no Node.js, Deno e Bun.
- TypeScript vs JavaScriptTypeScript é JavaScript com um sistema de tipos estáticos verificado antes de o código rodar. Compare os dois lado a lado: sintaxe, o que o verificador de tipos pega, o passo de build, desempenho, curva de aprendizado e como migrar um projeto JavaScript.
- Instalar TypeScriptInstale o TypeScript com npm como dev dependency do projeto, veja a versão com npx tsc --version, crie um tsconfig.json com tsc --init e compile o primeiro arquivo. Inclui instalação global, pnpm, Yarn e Bun e os erros mais comuns.
- Rodar TypeScriptCinco jeitos de rodar um arquivo .ts: compilar com tsc e rodar o JavaScript, rodar direto com node arquivo.ts (type stripping), usar tsx ou ts-node, ou usar Deno e Bun. Quais verificam tipos, que sintaxe cada um aceita e qual escolher.
- tsconfig.jsonO tsconfig.json marca uma pasta como projeto TypeScript e define as opções do compilador. As opções que importam (target, module, moduleResolution, strict, rootDir, outDir, include, lib, types, noEmit, skipLibCheck), uma configuração inicial recomendada, extends e o que mudou no TypeScript 7.
- TypeScript 7O TypeScript 7 é o compilador do TypeScript reescrito em Go como programa nativo: cerca de dez vezes mais rápido, com o mesmo comando tsc e a mesma linguagem. O que mudou para quem usa (novos padrões, opções removidas, a API JavaScript ausente), quais ferramentas ainda precisam do TypeScript 6 e como atualizar.
- ComentáriosO TypeScript usa os comentários // e /* */ do JavaScript, além de comentários JSDoc /** */ que os editores mostram ao passar o mouse. Ele também lê alguns comentários especiais: @ts-expect-error, @ts-ignore, @ts-nocheck, @ts-check e as diretivas /// <reference>.
- TypeScript vs PythonTypeScript e Python são linguagens de alto nível com garbage collector, mas o TypeScript verifica os tipos antes de o código rodar, enquanto os type hints do Python são opcionais e ignorados em tempo de execução. Uma comparação lado a lado de tipagem, runtime, velocidade, ecossistemas e usos, com o mesmo programa nas duas.
Tipos básicos
- Tipos básicosOs tipos nativos do TypeScript: string, number, boolean, bigint, symbol, null e undefined, com uma visão rápida de arrays e objetos. Como escrever uma anotação de tipo, por que não existe um tipo inteiro e por que se escreve string em vez de String.
- Inferência de tiposO TypeScript deduz a maioria dos tipos a partir dos valores que você escreve. Veja o que ele infere para variáveis, let vs const, objetos, arrays e valores de retorno, como callbacks recebem seus tipos pelo contexto e onde você ainda precisa de uma anotação.
- StringsTrabalhando com strings em TypeScript: interpolação com template literals, strings de várias linhas, como verificar se uma string contém uma substring, os métodos mais comuns com os tipos que retornam e os tipos literais de string.
- String para númeroConverta uma string em número no TypeScript com Number(), parseInt(), parseFloat() ou + unário, veja como cada um trata entradas como "42px", "" e "1e3", verifique NaN com segurança e converta números de volta em strings.
- ArraysComo tipar arrays em TypeScript: T[] vs Array<T>, arrays de objetos, arrays com vários tipos, arrays readonly e o que map, filter, reduce e find retornam. Mais a armadilha do includes com arrays de literais.
- TuplasUma tupla em TypeScript é um array com um número fixo de elementos cujos tipos são conhecidos pela posição, como [string, number]. Veja a sintaxe, elementos nomeados, opcionais e rest, tuplas readonly e as const, como retornar tuplas de funções e a diferença entre tuplas e arrays.
- Tipos de objetoComo tipar objetos em TypeScript: tipos de objeto inline, propriedades opcionais com ?, propriedades readonly, objetos aninhados, métodos, excess property checks e a diferença entre object, {} e Object.
- EnumsUm enum em TypeScript é um conjunto nomeado de constantes, como enum Direction { Up, Down }. Veja enums numéricos e de string, o JavaScript que um enum gera, reverse mapping, como iterar um enum, const enums e quando uma union de literais de string ou um objeto as const é a melhor escolha.
Tipos especiais
- Literal typesUm literal type é um tipo com exatamente um valor, como "GET" ou 404. Veja literal types de string, number e boolean, unions de literais, por que let alarga o tipo e const não, o que o as const faz e os const type parameters.
- any vs unknownany e unknown aceitam qualquer valor. any desliga a verificação de tipos para aquele valor, enquanto unknown obriga você a verificar o valor antes de usá-lo. Veja as diferenças, como fazer narrowing de unknown, o noImplicitAny e por onde o any entra em código tipado.
- Tipo nevernever é o tipo sem nenhum valor. É o tipo de retorno de funções que nunca terminam, o tipo que sobra quando o narrowing descartou todos os casos e a ferramenta por trás das verificações exaustivas em switch. Veja de onde ele vem e como difere de void.
- null e undefinedCom strictNullChecks, null e undefined são tipos separados que o TypeScript obriga você a tratar. Veja como verificá-los, optional chaining (?.), o operador de dupla interrogação (??) e ??=, e a diferença entre uma propriedade opcional e | undefined.
- Non-null assertion (!)Um ponto de exclamação depois de um valor, como user!, é o operador non-null assertion: ele remove null e undefined do tipo sem nenhuma verificação em tempo de execução. Veja o que x! faz, as formas de definite assignment let x!: T e prop!: T, por que são arriscadas e alternativas mais seguras.
Interfaces e aliases de tipo
- InterfacesUma interface dá nome ao formato de um objeto: quais propriedades ele tem e que tipos elas guardam. Veja como declarar uma, propriedades opcionais e readonly, métodos, index signatures, extends, implements em uma classe, declaration merging, interfaces genéricas e como dar valores padrão a uma interface.
- Type aliasesUm type alias dá nome a qualquer tipo com a palavra-chave type: formatos de objeto, unions, tuplas, funções, generics e tipos recursivos. Veja a sintaxe, como fica cada forma e por que um alias é só um nome, e não um tipo novo e separado.
- Interface vs typeinterface e type conseguem descrever formatos de objeto, e na maior parte do tempo qualquer um serve. Veja as diferenças reais: declaration merging, unions e mapped types, extends vs intersections, index signatures implícitas, mensagens de erro e desempenho do compilador, além de uma regra clara para escolher.
- Palavra-chave extendsA palavra-chave extends cria um tipo a partir de outro. Veja como estender uma interface (uma ou várias), estender um type alias com &, sobrescrever o tipo de uma propriedade, trocar propriedades com Omit e o que extends significa em classes, restrições de generics e conditional types.
- Union typesUm union type como string | number significa que um valor pode ser qualquer um de vários tipos. Veja o que dá para fazer com uma union (só o que todos os membros suportam), como fazer o narrowing, unions de literais e de tipos de objeto e a diferença entre (A | B)[] e A[] | B[].
- Intersection typesUm intersection type A & B descreve um valor que é A e B ao mesmo tempo, então tem todos os membros dos dois. Veja como combinar tipos de objeto com &, por que propriedades conflitantes viram never, como intersections de unions mantêm só os membros em comum e quando usar extends no lugar.
- Discriminated unionsUma discriminated union é uma union de tipos de objeto que compartilham uma propriedade-tag literal, como kind ou status. Verificar a tag estreita o objeto inteiro. Veja o padrão, o narrowing com switch, verificações exaustivas com never e como modelar resultados de API, estado de requisições e máquinas de estado.
Funções
- FunçõesComo tipar funções em TypeScript: anote cada parâmetro, anote ou deixe inferir o tipo de retorno, use void para funções que não retornam nada e tipe arrow functions, function expressions, funções async e o parâmetro this.
- Tipos de funçãoComo escrever o tipo de uma função em TypeScript: a sintaxe de arrow (a: number) => string, type aliases para funções, como tipar arrow functions e callbacks, call signatures e construct signatures, e por que o tipo Function é frouxo demais.
- Parâmetros opcionaisMarque um parâmetro do TypeScript como opcional com ?, dê a ele um valor padrão ou junte qualquer número de argumentos com um rest parameter. Inclui as regras de ordem, omitido vs undefined, objetos de opções e parâmetros opcionais em tipos de função.
- Sobrecarga de funçõesOs overloads de função do TypeScript permitem que uma função tenha várias call signatures, cada uma com o próprio tipo de retorno. Veja o padrão de overload signatures mais implementação, as regras que o compilador verifica, quando um parâmetro union é melhor e overloads em classes.
Estreitamento e verificação de tipos
- Type narrowingNarrowing é como o TypeScript transforma um tipo amplo como string | number em um tipo específico dentro de um if, de um switch ou depois de um return antecipado. Todas as formas de narrowing em um só lugar: typeof, truthiness, igualdade, in, instanceof, atribuições, type predicates e discriminated unions.
- Operador typeofO typeof tem duas funções no TypeScript. No código, é o operador do JavaScript que retorna "string", "number", "object" e assim por diante em tempo de execução, e o TypeScript faz narrowing com ele. Em um tipo, é a type query que copia o tipo de uma variável, como em keyof typeof obj e ReturnType<typeof fn>.
- Operador instanceofO instanceof verifica em tempo de execução se um objeto foi criado por uma classe, e o TypeScript estreita a variável para essa classe. Como ele funciona com suas próprias classes e com subclasses de Error, por que não consegue verificar interfaces nem type aliases e onde dá respostas surpreendentes.
- Type guardsUm type guard é uma verificação em tempo de execução que o TypeScript entende. Veja os type guards nativos, como escrever os seus com um type predicate value is Type, como verificar se um objeto é de um tipo, assertion functions com asserts e como validar dados unknown.
- Type assertionsA palavra-chave as diz ao TypeScript para tratar um valor como outro tipo. Não é um cast: nada é convertido nem verificado em tempo de execução. Veja a sintaxe com as e com sinais de menor e maior, o que o compilador permite, assertions duplas passando por unknown e quando um type guard é a ferramenta melhor.
- Operador satisfiesO operador satisfies verifica se um valor corresponde a um tipo sem mudar o tipo inferido do valor. Veja o que ele faz, como se compara a uma anotação de tipo e ao as (o mesmo objeto escrito de três jeitos), como se combina com as const e por que combina com objetos de configuração.
Classes
- ClassesAs classes do TypeScript são classes JavaScript com campos, métodos e construtores tipados. Veja como funcionam as declarações de campos e o strictPropertyInitialization, como tipar o this, getters e setters, membros estáticos, implements e como uma classe também serve de tipo.
- ConstrutoresComo tipar o construtor de uma classe em TypeScript: parâmetros tipados e opcionais, parameter properties como constructor(private name: string), ordem de inicialização dos campos, overloads de construtor, chamadas a super em subclasses, construtores privados e tipos de construtor com new.
- Modificadores de acessoO TypeScript tem três modificadores de acesso, public, private e protected, além do readonly. Veja o que cada um permite, por que o private do TypeScript é uma verificação de tempo de compilação enquanto os campos #private do JavaScript são aplicados em tempo de execução, e qual escolher.
- HerançaHerança de classes em TypeScript: extends e super, sobrescrita de métodos com tipos compatíveis, a palavra-chave override e o noImplicitOverride, membros protected, redeclaração de campos com declare e quando o implements é a ferramenta melhor.
- Classes abstratasUma classe abstrata em TypeScript é uma classe base que não pode ser instanciada e pode deixar métodos para as subclasses implementarem. Veja métodos e propriedades abstratos, o padrão template method, tipos de construtor abstratos e quando uma interface é a escolha melhor.
- DecoratorsDecorators são funções que envolvem ou substituem membros de classe com a sintaxe @. Veja os decorators padrão que o TypeScript suporta sem nenhuma flag (de classe, método, getter, campo e accessor), decorator factories, addInitializer e como eles diferem do experimentalDecorators legado usado por Angular e NestJS.
Genéricos
- GenericsGenerics permitem que uma função, interface, tipo ou classe funcione com muitos tipos mantendo-os ligados: o que entra decide o que sai. Veja funções genéricas, inferência de argumentos de tipo, vários type parameters, interfaces e classes genéricas, valores padrão e quando não usar generics.
- Restrições de genericsUma restrição de generic, T extends Something, limita quais tipos um type parameter aceita e deixa a função usar o que a restrição garante. Inclui extends com formatos de objeto e interfaces, K extends keyof T para acesso seguro a propriedades, restrições com primitivos e os erros que você vai encontrar.
Operadores de tipo
- Operador keyofO keyof recebe um tipo de objeto e dá a union dos nomes das propriedades dele. Veja keyof com interfaces, keyof typeof para objetos simples, acesso tipado a propriedades com generics, index signatures (string | number) e por que Object.keys retorna string[].
- Indexed access typesUm indexed access type lê o tipo de uma propriedade de outro tipo: Person["age"] é number. Veja T["key"], chaves em union, T[keyof T], T[number] para elementos de array, índices de tuplas e (typeof arr)[number] para transformar um array const em uma union.
- Mapped typesUm mapped type cria um novo tipo de objeto percorrendo chaves: { [K in keyof T]: ... }. Veja a sintaxe, os modificadores readonly e ? com + e -, o remapeamento de chaves com as, a filtragem de chaves e como Partial, Readonly, Required, Pick e Record são escritos.
- Conditional typesUm conditional type escolhe um de dois tipos com base em um teste: T extends U ? X : Y. Veja a sintaxe, como os conditional types se distribuem sobre unions (e como impedir isso), como extrair tipos com infer e como escrever o seu próprio ReturnType.
- Template literal typesTemplate literal types montam string literal types com a mesma sintaxe de crases das template strings do JavaScript: `on${Capitalize<E>}`. Veja a sintaxe, como as unions se multiplicam, Uppercase e Capitalize, padrões como `${number}px`, getters com mapped types e como analisar strings com infer.
- Branded typesUm branded type é um primitivo com uma etiqueta invisível, como string & { readonly __brand: "UserId" }, para que um UserId não possa ser passado onde se espera um OrderId. Veja como as brands funcionam, funções construtoras que validam, um helper Brand genérico, brands com unique symbol e números com brand.
Tipos utilitários
- Utility typesTodos os utility types embutidos do TypeScript em um só lugar: Partial, Required, Readonly, Pick, Omit, Record, Exclude, Extract, NonNullable, Parameters, ReturnType, Awaited, os tipos de string e outros, cada um com uma descrição de uma linha e um exemplo executável.
- RecordRecord<K, V> é o tipo de objeto cujas chaves são K e cujos valores são todos V. Veja Record com chaves string e com chaves em union (toda chave obrigatória), Partial<Record>, como percorrer um Record com chaves tipadas, a armadilha da chave ausente e quando usar uma index signature ou um Map.
- Partial e RequiredPartial<T> torna opcional toda propriedade de T, que é exatamente o tipo de um objeto de atualização ou patch. Veja Partial em funções de update, por que ele é raso, como escrever um DeepPartial, a armadilha do undefined explícito e o oposto dele, Required<T>.
- OmitOmit<T, K> cria um tipo com todas as propriedades de T, exceto as chaves K. Veja Omit com uma e várias chaves, como sobrescrever o tipo de uma propriedade, remover a propriedade em tempo de execução, Omit vs Exclude e Pick, por que Omit aceita chaves que não existem, um Omit estrito e Omit em union types.
- PickPick<T, K> cria um tipo só com as propriedades de T cujas chaves estão em K. Veja Pick com uma ou várias chaves, como ele verifica as chaves, Pick vs Omit, como selecionar de tipos aninhados, uma função pick() tipada e como selecionar propriedades pelo tipo do valor.
- readonly e ReadonlyO modificador readonly e o utility type Readonly<T> impedem que o código reatribua propriedades. Veja propriedades readonly e campos de classe, Readonly<T>, arrays readonly (readonly T[] e ReadonlyArray), ReadonlyMap e ReadonlySet, por que readonly é raso e só de tempo de compilação, e como ele se compara com Object.freeze e as const.
- Exclude e ExtractExclude, Extract e NonNullable filtram os membros de um union type. Veja o que cada um mantém e remove, como selecionar membros de uma union pelo formato, como eles são montados com conditional types e como diferem de Omit e Pick.
- ReturnType e ParametersReturnType, Parameters, ConstructorParameters, InstanceType e Awaited extraem tipos de funções, classes e promises. Veja como usá-los com typeof, como obter o tipo do resultado de uma função async, o que acontece com overloads e generics, e como ReturnType é montado com infer.
Laços e coleções
- LoopsTodas as formas de fazer loop em TypeScript e os tipos que cada uma entrega: o for clássico, for...of em arrays, maps e strings, for...in e suas chaves string, forEach (sem break, sem await), loops tipados sobre as chaves de um objeto e while.
- SwitchA instrução switch em TypeScript: sintaxe, como cada case estreita um union type, switches exaustivos que deixam de compilar quando falta um case, o padrão switch (true), fallthrough e escopo de bloco.
- MapComo usar Map em TypeScript: criar um Map<K, V> tipado, por que get retorna V | undefined, set, has e delete, iteração na ordem de inserção, chaves que são objetos, conversão de e para objetos e JSON, Map vs objeto vs Record e como tipar array.map().
- DicionárioO TypeScript não tem uma classe de dicionário ou hashmap; você tipa uma busca por chave e valor com uma index signature, Record<K, V> ou Map<K, V>. Veja cada uma, como verificar se uma chave existe, adicionar, remover e iterar, e por que noUncheckedIndexedAccess importa para dicionários.
Assíncrono e erros
- PromisesComo as promises são tipadas em TypeScript: o tipo Promise<T>, como tipar new Promise e resolve, como then muda o tipo, por que catch dá any, Promise.all com resultados em tupla, os tipos de resultado de Promise.allSettled e como envolver APIs de callback em uma promise tipada.
- Async/AwaitComo async e await são tipados em TypeScript: uma função async retorna Promise<T>, await o desembrulha, erros são capturados com try/catch, top-level await exige um módulo ES, e a diferença entre esperar uma por uma, esperar em paralelo e a armadilha do forEach.
- Tratamento de errosTratamento de erros em TypeScript: por que a variável do catch é unknown, como estreitá-la com instanceof Error, como lançar erros, como escrever classes de erro personalizadas com name e cause, e o padrão Result para erros que você espera.
- SleepO TypeScript não tem um sleep embutido, mas uma linha resolve: uma função que retorna uma Promise<void> resolvida por setTimeout. Veja como usá-la com await, pausar dentro de loops, tentar de novo com um intervalo, cancelar um sleep e por que não existe sleep bloqueante em JavaScript.
Módulos e ferramentas
- MódulosTodo arquivo TypeScript com um import ou export no nível superior é um módulo. Veja exports nomeados e default, import type e export type, como a opção module decide entre saída ES module e CommonJS e por que node16 e nodenext exigem a extensão .js nos imports.
- NamespacesUm namespace em TypeScript agrupa valores e tipos sob um único nome e vira um objeto comum na compilação. Veja a sintaxe, como namespaces se mesclam entre si e com funções e classes, por que os ES modules os substituíram e onde eles ainda aparecem: arquivos de declaração e global augmentation.
- Arquivos de declaraçãoUm arquivo .d.ts descreve os tipos de um código JavaScript sem conter nada dele, e a palavra-chave declare faz o mesmo dentro de um arquivo .ts. Veja como arquivos de declaração são gerados, onde entram os pacotes @types, como tipar um módulo sem tipos e como declare global e module augmentation estendem tipos existentes.
- Strict modestrict: true no tsconfig.json ativa uma família de verificações de tipos: noImplicitAny, strictNullChecks, strictPropertyInitialization e mais cinco. Veja o que cada uma pega, como ativar o strict mode em um projeto existente e as flags úteis que o strict não inclui.
- JSONJSON.parse retorna any, então o TypeScript confia em qualquer tipo que você dê ao resultado. Veja como tipar JSON lido, validá-lo com um type guard, transformar um exemplo de JSON em interface, importar arquivos .json e o que JSON.stringify faz com Dates, Sets e undefined.
Indo além
- Boas práticasOito hábitos de TypeScript que evitam bugs reais: manter o strict ativado, usar unknown em vez de any, deixar a inferência trabalhar, preferir unions a enums, verificar configurações com satisfies, modelar estado com discriminated unions, evitar ! e as e tornar os dados readonly. Cada um vem com um antes e depois executável.
- Perguntas de entrevista25 perguntas de entrevista de TypeScript com respostas curtas e corretas e código, agrupadas do nível iniciante ao avançado: any vs unknown, interface vs type, generics, narrowing, utility types, mapped e conditional types, tipagem estrutural, tsconfig e TypeScript 7.
