12k
All articles

Recursos pouco conhecidos do TypeScript que vale a pena aprender

Explore sete recursos pouco conhecidos do TypeScript, de parâmetros const e NoInfer a funções de asserção e verbatimModuleSyntax, com versões e exemplos de código.

OpenReplay Team
OpenReplay Team
Recursos pouco conhecidos do TypeScript que vale a pena aprender

Sete recursos do TypeScript que muitos desenvolvedores experientes ainda não usam são os const type parameters (5.0), o NoInfer (5.4), as assertion functions (3.7), os elementos de tupla rotulados (4.0), as variance annotations (4.7), a palavra-chave accessor (4.9) e o import type combinado com verbatimModuleSyntax (3.8 e 5.0).

Se você aprendeu TypeScript por volta da versão 4.x e passou o tempo desde então ocupado entregando código, provavelmente ainda escreve as const nos pontos de chamada e adiciona type parameters extras para impedir que a inferência alargue os tipos. As versões mais recentes oferecem formas mais curtas de fazer as duas coisas.

Este artigo aborda cada recurso individualmente: o que ele faz, em qual versão foi introduzido e um exemplo curto que compila em strict mode.

Principais conclusões

  • Um type parameter const (TypeScript 5.0) infere ["/", "/users"] como readonly ["/", "/users"] quando a restrição é readonly, como readonly string[].
  • NoInfer<T> (TypeScript 5.4) impede que um parâmetro atue como ponto de inferência, de modo que um valor padrão não consiga alargar o tipo estabelecido pelos demais argumentos.
  • Uma assertion function escrita como asserts value is T estreita o tipo do argumento pelo restante do escopo após a chamada, e não apenas dentro de um bloco if.
  • Com verbatimModuleSyntax, um import só é removido quando type se aplica à instrução inteira. import { type X } from "./mod" gera import {} from "./mod", então o módulo continua sendo executado.

Recursos avançados do TypeScript por versão

A tabela lista cada um dos sete recursos pouco conhecidos do TypeScript, junto com a versão que o introduziu e os desenvolvedores para quem ele é mais relevante.

RecursoIntroduzido na versãoPúblico principal
Assertion functions3.7Código de aplicações e bibliotecas
import type3.8Configuração de build
Elementos de tupla rotulados4.0Autores de hooks e APIs
Variance annotations (in/out)4.7Autores de bibliotecas
Palavra-chave accessor4.9Usuários de decorators
const type parameters5.0Autores de APIs genéricas
verbatimModuleSyntax5.0Configuração de build
NoInfer<T>5.4Autores de APIs genéricas

Const type parameters (TypeScript 5.0)

O TypeScript 5.0 adicionou o modificador const em type parameters. Ele faz o compilador inferir literais de array e de objeto como se quem chama tivesse escrito as const. Assim, quem chama a função não precisa mais se lembrar da asserção para obter tipos literais.

Combine o modificador const com uma restrição readonly se quiser resultados readonly. Com uma restrição mutável como string[], as versões 5.0 a 5.2 do TypeScript recorriam a string[]. A partir da 5.3, o compilador passou a inferir uma tupla mutável. O modificador const também só se aplica a literais escritos diretamente na chamada. Uma variável declarada anteriormente mantém o tipo alargado que já possuía.

function defineRoutes<T extends readonly string[]>(paths: T): T { return paths; }
const a = defineRoutes(["/", "/users"]);        // string[]

function defineRoutesExact<const T extends readonly string[]>(paths: T): T { return paths; }
const b = defineRoutesExact(["/", "/users"]);   // readonly ["/", "/users"]

function defineRoutesMutable<const T extends string[]>(paths: T): T { return paths; }
const c = defineRoutesMutable(["/", "/users"]); // ["/", "/users"] (TS 5.3+; string[] in 5.0–5.2)

NoInfer para controlar a inferência (TypeScript 5.4)

O NoInfer<T>, adicionado no TypeScript 5.4, impede que o compilador use determinado argumento como fonte de inferência. Esse argumento passa então a ser verificado em relação ao tipo inferido a partir dos outros parâmetros, em vez de alargá-lo. Antes da 5.4, a solução alternativa comum era um segundo type parameter restrito pelo primeiro. Funcionava, mas acrescentava um type parameter que aparecia apenas uma vez na assinatura.

function createSelect<T extends string>(options: T[], initial: NoInfer<T>) {
  return { options, value: initial };
}

createSelect(["draft", "published"], "draft");    // OK
createSelect(["draft", "published"], "archived");
// Error: Argument of type '"archived"' is not assignable
// to parameter of type '"draft" | "published"'.

Sem o NoInfer, T seria alargado para "draft" | "published" | "archived" e o erro de digitação compilaria normalmente. A referência de utility types o documenta ao lado de Partial e Pick.

Assertion functions (TypeScript 3.7)

Uma assertion function estreita o tipo do seu argumento pelo restante do escopo envolvente assim que retorna sem lançar exceção. Isso a torna uma boa opção para guard clauses do tipo fail-fast que não precisam de ramificação. Um type guard (value is T) estreita o tipo apenas dentro da condicional que o chama. Já uma assinatura asserts value is T, introduzida no TypeScript 3.7, estreita tudo o que vem depois da chamada.

function assertIsDefined<T>(value: T, name = "value"): asserts value is NonNullable<T> {
  if (value === undefined || value === null) {
    throw new Error(`${name} is not defined`);
  }
}

const root = document.getElementById("app"); // HTMLElement | null
assertIsDefined(root, "#app");
root.classList.add("ready");                 // root: HTMLElement

As assertion functions têm uma pegadinha. Se você escrever o helper como uma arrow function atribuída a uma const sem anotação de tipo, a chamada falha com “Assertions require every name in the call target to be declared with an explicit type annotation.” Use uma declaração de função ou dê à const um tipo explícito.

Elementos de tupla rotulados (TypeScript 4.0)

Os elementos de tupla rotulados, adicionados no TypeScript 4.0, permitem nomear cada posição de um tipo de tupla. Os nomes aparecem nos hovers do editor, na ajuda de assinatura e nas mensagens de erro. Os rótulos da tupla alteram apenas o que os editores e as mensagens de erro exibem. Eles não mudam o tipo da tupla, e quem chama pode desestruturar os elementos com os nomes que quiser. Desde o TypeScript 5.2, uma tupla também pode misturar elementos rotulados e não rotulados.

Um tipo de retorno no estilo de hook é o caso de uso clássico:

type ToggleState = [isOn: boolean, toggle: () => void];

function useToggle(initial = false): ToggleState {
  let isOn = initial;
  return [isOn, () => { isOn = !isOn; }];
}

const [open, toggleOpen] = useToggle(); // any names work; labels show in hovers

Variance annotations: in e out (TypeScript 4.7)

As variance annotations, introduzidas no TypeScript 4.7, permitem declarar explicitamente se um type parameter é covariante (out), contravariante (in) ou ambos. As variance annotations são voltadas principalmente para autores de bibliotecas. Código de aplicação quase nunca precisa delas. As notas da versão 4.7 as apresentam como uma forma de documentar a intenção e, no caso de tipos profundamente recursivos, de acelerar a verificação de tipos. O TypeScript reporta um erro quando uma anotação contradiz a forma como o parâmetro é de fato usado, mas aceita anotações mais restritivas do que o necessário.

interface Producer<out T> { get: () => T }
interface Consumer<in T> { accept: (value: T) => void }

interface Bad<in T> { get: () => T }
// Error: Type 'Bad<super-T>' is not assignable to type 'Bad<sub-T>'
// as implied by variance annotation.

A palavra-chave accessor (TypeScript 4.9)

O TypeScript 4.9 adicionou os auto-accessors. Você os declara como um campo de classe, mas com o prefixo accessor. O compilador os transforma em um par getter e setter apoiado por um campo privado inacessível. Assim, um auto-accessor oferece a um decorator um único ponto para interceptar tanto as leituras quanto as escritas do campo.

O exemplo abaixo usa a assinatura padrão de decorators do TypeScript 5.0, com tipos do decorators.d.ts embutido no compilador. Ele exige que experimentalDecorators esteja desativado, porque os decorators legados usam uma assinatura diferente.

function logged<This, V>(
  target: ClassAccessorDecoratorTarget<This, V>,
  context: ClassAccessorDecoratorContext<This, V>
): ClassAccessorDecoratorResult<This, V> {
  return {
    set(value) {
      console.log(`set ${String(context.name)} =`, value);
      target.set.call(this, value);
    },
  };
}

class Settings {
  @logged accessor theme = "light";
}

import type com verbatimModuleSyntax (TypeScript 3.8 e 5.0)

Com verbatimModuleSyntax, o TypeScript remove um import apenas quando type se aplica à instrução inteira. Todos os demais imports são emitidos exatamente como foram escritos. A sintaxe import type existe desde o TypeScript 3.8. A flag em si chegou na 5.0 e substituiu importsNotUsedAsValues e preserveValueImports, que foram descontinuadas na 5.0 e não existem mais no TypeScript 7.

{ "compilerOptions": { "verbatimModuleSyntax": true } }
import type { User } from "./api";         // erased entirely
import { fetchUser, type Post } from "./api"; // emits: import { fetchUser } from "./api";
import { type Config } from "./config";    // emits: import {} from "./config";

A terceira linha, import { type Config }, é a que pega muita gente desprevenida. Um modificador type inline ainda deixa para trás um import vazio, então o módulo é carregado e seus efeitos colaterais são executados. Ao ativar a flag, qualquer tipo importado sem o modificador type passa a gerar um erro de compilação. A migração consiste basicamente em converter os named imports que trazem apenas tipos para import type.

Tópicos avançados de TypeScript relacionados

Alguns tópicos foram deixados de fora de propósito, pois têm artigos próprios:

Conclusão

A maioria desses recursos substitui uma solução alternativa ou transfere uma verificação que dependia de convenção em tempo de execução para o sistema de tipos. Os const type parameters e o NoInfer dão às APIs genéricas uma inferência precisa sem exigir trabalho extra de quem as chama. As assertion functions e as tuplas rotuladas deixam o código cotidiano das aplicações mais rigoroso, e o verbatimModuleSyntax torna previsíveis os imports emitidos. Um primeiro passo prático é ativar o verbatimModuleSyntax em um pacote, corrigir os imports apenas de tipos apontados pelo compilador e, em seguida, adicionar const a qualquer genérico que hoje instrua quem o chama a acrescentar as const.

Perguntas frequentes

O verbatimModuleSyntax funciona em projetos que emitem CommonJS?

Sim, mas os arquivos emitidos como CommonJS devem usar a sintaxe no estilo CommonJS do TypeScript: import fs = require('fs') para imports e export = para exports. Escrever instruções import ou export do ESM nesses arquivos gera um erro de compilação. As versões atuais o reportam como TS1295, sugerindo alterar o campo type no package.json ou ajustar as configurações de módulo. Os arquivos emitidos como ESM mantêm a sintaxe normal de import e export.

Ainda preciso do isolatedModules se eu ativar o verbatimModuleSyntax?

Não. A referência do TSConfig define isolatedModules como true por padrão sempre que o verbatimModuleSyntax está ativado, então as verificações de transpilação por arquivo único se aplicam automaticamente e você pode remover a entrada explícita. Essas verificações são importantes para ferramentas como esbuild, SWC e Babel, que compilam cada arquivo separadamente e não conseguem saber se um nome importado é um tipo ou um valor.

Uma assertion function pode ser async?

Não. O TypeScript não tem uma assinatura de asserção assíncrona, então um tipo de retorno como Promise<asserts value is T> não é válido. O recurso foi solicitado na issue 37681 do TypeScript, mas não faz parte da linguagem. A solução alternativa comum é aguardar primeiro o trabalho assíncrono com await e depois chamar uma assertion function síncrona sobre o resultado, ou fazer a função async retornar o valor validado com um tipo estreitado.

Open-source session replay

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Star on GitHub12k

We use cookies to improve your experience. By using our site, you accept cookies.