Mensagens de Erro em DSLs no Nível de Tipos
Exiba erros de compilação úteis para usuários de DSL.
Mensagens de Erro em DSLs no Nível de Tipos é 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.
Erros úteis em DSLs no nível de tipos
A parte mais difícil de uma DSL no nível de tipos é tornar as falhas legíveis. Erros brutos de never ou de "não atribuível" confundem os usuários. Nós exibimos erros descritivos usando tipos de erro com marca e mensagens never elaboradas.
O problema com never
Quando a validação falha ao resultar em never, o compilador diz "O argumento do tipo X não é atribuível a never", o que não informa ao usuário por quê. Podemos fazer melhor.
Tipos de erro com marca
Em vez de um never simples, retorne um tipo de erro com uma forma única que carregue uma cadeia de caracteres de mensagem legível para humanos em seu tipo.
type TypeError<Msg extends string> = {
readonly __error: Msg;
};
type E = TypeError<"Column 'foo' does not exist">;Retornando erros da validação
Um validador retorna ou o tipo do valor válido ou um erro com marca que descreve o problema. A verificação de "contém um ponto" é um padrão de literal de modelo (acentos graves no código real); nós a denotamos por HasDot.
// HasDot<S> is the backtick pattern: any text, ".", any text.
type Validate<S extends string> =
S extends HasDot
? S
: TypeError<"Path must contain a dot, e.g. user.name">;Fazendo o erro aparecer
Restrinja o parâmetro para que passar qualquer coisa que não seja atribuível à marca de erro faça a mensagem ser exibida. O tipo de erro aparece diretamente na saída do compilador.
declare function path<S extends string>(
p: Validate<S> extends TypeError<infer M> ? TypeError<M> : S
): void;
path("oops");
// Error message includes: __error: "Path must contain a dot..."Distinguindo vários erros
Falhas diferentes retornam mensagens diferentes, para que os usuários recebam orientações específicas em vez de uma única rejeição genérica. HasDot é novamente o padrão de literal de modelo com acentos graves para "contém um ponto".
type Check<S extends string> =
S extends "" ? TypeError<"Path cannot be empty">
: S extends HasDot ? S
: TypeError<"Missing dot separator">;never com uma variação
Outra técnica associa uma posição de valor a uma mensagem literal para que ela seja revelada ao passar o cursor. Você faz a interseção do tipo problemático com um objeto rotulado.
type Invalid<M extends string> = { error: M } & never;
// using never keeps it unassignable while the label hints the causeErros em DSLs encadeadas
Em uma DSL encadeada, faça com que uma próxima etapa inválida retorne um tipo com erro marcado em vez de uma etapa válida, para que o editor mostre a mensagem exatamente onde o erro ocorre.
interface Stage {
// calling done() before where() yields a labeled error
done(): TypeError<"Call .where() before .done()">;
}Mantendo as mensagens curtas
Tipos de mensagem longos aumentam a saída do compilador e tornam as ferramentas mais lentas. Prefira frases concisas e acionáveis. Inclua o símbolo problemático quando isso não tiver grande custo, mas evite interpolações enormes.
Testando seus erros
Escreva testes no nível de tipos que verifiquem se a marca de erro aparece para entradas reconhecidamente inválidas, para que refatorações não degradem silenciosamente a experiência de desenvolvimento.
type Expect<T extends true> = T;
type _t = Expect<Validate<"oops"> extends TypeError<any> ? true : false>;Por que isso é importante
Uma DSL é tão boa quanto seus erros. Tipos de erro com marca transformam falhas criptográficas de never em mensagens autoexplicativas, melhorando drasticamente a experiência de uso da sua API no nível de tipos.
Verificação rápida
Confirme sua compreensão das mensagens de erro no nível de tipos.
Recapitulação
Para tornar as DSLs no nível de tipos utilizáveis, substitua o never simples por tipos de erro com marca que incorporem mensagens legíveis. Os validadores retornam ou o tipo válido ou uma marca de erro específica; restringir parâmetros faz a mensagem aparecer na saída do compilador. Mantenha as mensagens curtas e teste-as.
Aprenda TypeScript com um tutor de IA — grátis
Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.
- Cursos
- 101
- Aulas
- 352
Perguntas Frequentes
A aula “Mensagens de Erro em DSLs no Nível de Tipos” é grátis?
Sim — o texto completo de “Mensagens de Erro em DSLs no Nível de Tipos” é 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 “Mensagens de Erro em DSLs no Nível de Tipos”?
Exiba erros de compilação úteis para usuários de DSL. 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 “Mensagens de Erro em DSLs no Nível de Tipos”?
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
- O que é uma DSL no Nível de Tipos
- Projetando uma DSL Fluente de Consultas
- Validação de Entrada em Tempo de Compilação
- Mensagens de Erro em DSLs no Nível de Tipos