Template Literal Types: Manipulação Avançada e Construtores Dinâmicos de Strings no TypeScript
Template Literal Types: Manipulação Avançada e Construtores Dinâmicos de Strings no TypeScript
${}). No TypeScript 4.1, essa mesma sintaxe poderosa foi transportada para o sistema de tipos em tempo de compilação: os Template Literal Types. Hoje você aprenderá a criar strings dinâmicas fortemente tipadas, a multiplicação cartesiana de uniões, os utilitários intrínsecos de manipulação textual (Uppercase, Capitalize) e a modelar namespaces de eventos enterprise imunes a erros de digitação!
📑 Índice do Conteúdo
1. O Conceito Fundamental de Template Literal Types
Até a chegada do TypeScript 4.1, se você precisasse de um tipo que representasse uma string com um prefixo específico (como uma URL HTTPS ou uma cor hexadecimal), era obrigado a recorrer ao tipo genérico e permissivo string, perdendo qualquer segurança contra valores inválidos.
Com os Template Literal Types, você pode usar a sintaxe de interpolação exata do JavaScript para compor tipos literais de string a partir de outros tipos:
type Saudacao = "Olá";
type Destino = "Mundo" | "Desenvolvedor" | "ZoneWare";
// O TypeScript interpola os tipos gerando uniões precisas:
type MensagemBoasVindas = `${Saudacao}, ${Destino}!`;
// Resultado resolvido: "Olá, Mundo!" | "Olá, Desenvolvedor!" | "Olá, ZoneWare!"
2. Multiplicação Cartesiana de Uniões
O superpoder mais impressionante dos Template Literal Types ocorre quando interpolamos múltiplas uniões de strings. O compilador gera automaticamente o produto cartesiano de todas as combinações possíveis entre os membros das uniões:
// Eixos verticais e horizontais
type Vertical = "top" | "center" | "bottom";
type Horizontal = "left" | "center" | "right";
// Gera automaticamente todas as 9 combinações de posicionamento:
type PosicaoAlinhamento = `${Vertical}-${Horizontal}`;
/*
Resultado estático exato:
| "top-left" | "top-center" | "top-right"
| "center-left" | "center-center" | "center-right"
| "bottom-left" | "bottom-center" | "bottom-right"
*/
// Aplicação em classes BEM (Block-Element-Modifier):
type BlocoUI = "btn" | "card" | "badge";
type VarianteTema = "primary" | "secondary" | "danger";
type ClasseCssBEM = `${BlocoUI}--${VarianteTema}`;
// "btn--primary" | "btn--secondary" | "btn--danger" | "card--primary" ...
3. Utilitários Intrínsecos de Manipulação Textual
O TypeScript oferece quatro utilitários nativos embutidos diretamente no compilador para manipular a caixa de letras de tipos de strings:
| Utilitário | Entrada de Exemplo | Saída Resultante | Descrição |
|---|---|---|---|
Uppercase<S> |
"post" |
"POST" |
Converte todos os caracteres para letras maiúsculas. |
Lowercase<S> |
"GET_USER" |
"get_user" |
Converte todos os caracteres para letras minúsculas. |
Capitalize<S> |
"usuario" |
"Usuario" |
Converte apenas a primeira letra para maiúscula. |
Uncapitalize<S> |
"IdConta" |
"idConta" |
Converte apenas a primeira letra para minúscula. |
type PropriedadeEntidade = "nome" | "email" | "idade";
// Cria nomes de métodos getter tipados: "obterNome" | "obterEmail" | "obterIdade"
type NomeMetodoGetter = `obter${Capitalize}`;
// Cria nomes de métodos setter tipados: "definirNome" | "definirEmail" | "definirIdade"
type NomeMetodoSetter = `definir${Capitalize}`;
4. Validação de Padrões Estruturais de Strings (Pattern Types)
Podemos combinar Template Literal Types com o tipo primitivo string ou number para criar validadores de formato estático que impedem valores arbitrários em tempo de compilação:
// Exige que a string comece obrigatoriamente com "#"
type CorHexadecimal = `#${string}`;
// Exige que a URL seja segura (iniciada com https://)
type UrlSegura = `https://${string}`;
// Exige um endpoint de versão de API válido
type RotaApi = `/api/v${number}/${string}`;
// 1. Atribuições Válidas:
const corPrimaria: CorHexadecimal = "#10B981"; // Válido!
const urlProducao: UrlSegura = "https://webzoneware.com/api"; // Válido!
const endpointUsuarios: RotaApi = "/api/v1/usuarios"; // Válido!
// 2. O Compilador REJEITA padrões fora do contrato:
// @ts-expect-error - Não começa com "#"
const corInvalida: CorHexadecimal = "rgb(255, 0, 0)";
// @ts-expect-error - Protocolo http:// inseguro bloqueado!
const urlInsegura: UrlSegura = "http://inseguro.com";
// @ts-expect-error - Falta o identificador de versão v1, v2...
const rotaInvalida: RotaApi = "/api/usuarios";
5. Namespaces e Barramentos de Eventos Hierárquicos
Em arquiteturas modernas de microsserviços, mensageria (Kafka / RabbitMQ) e WebSockets, tópicos de eventos costumam seguir convenções de namespace como modulo:entidade:acao. Com Template Literals, criamos o catálogo completo de tópicos válidos sem risco de erros de digitação:
type ModuloSistema = "auth" | "billing" | "catalog";
type AcaoOperacao = "created" | "updated" | "deleted";
// Gera: "auth:created" | "auth:updated" | "auth:deleted" | "billing:created" ...
type TopicoEvento = `${ModuloSistema}:${AcaoOperacao}`;
function publicarEvento(topico: TopicoEvento, payload: Record<string, unknown>): void {
console.log(`[EVENTO PUBLICADO NO BROKER] Tópico: ${topico}`, payload);
}
// Válido com autocomplete completo no VS Code:
publicarEvento("billing:created", { faturaId: "FAT-909" });
// Erro imediato caso o desenvolvedor cometa typo:
// @ts-expect-error - "billing:creatd" não existe em TopicoEvento!
publicarEvento("billing:creatd", {});
6. Exemplo Enterprise: EventEmitter Tipado Dinâmico
Vamos construir um Barramento Reativo de Eventos Enterprise onde métodos on e emit recebem strings dinâmicas de eventos com namespaces (entidade:acao) e inferem a carga útil correta:
interface MapaEventosModelos {
usuario: { id: number; email: string };
pedido: { pedidoId: string; totalCentavos: number };
}
type EntidadesDisponiveis = keyof MapaEventosModelos; // ___WZW_STR_0___ | ___WZW_STR_1___
type AcoesCrud = "criado" | "excluido";
// Evento no formato: "usuario:criado" | "usuario:excluido" | "pedido:criado" ...
type EventoComposto = `${EntidadesDisponiveis}:${AcoesCrud}`;
class BarramentoEventosCorporativo {
private ouvintes: Map<string, Array<(dado: any) => void>> = new Map();
public assinar<E extends EntidadesDisponiveis, A extends AcoesCrud>(
evento: `${E}:${A}`,
ouvinte: (payload: MapaEventosModelos[E]) => void
): void {
const lista = this.ouvintes.get(evento) ?? [];
lista.push(ouvinte);
this.ouvintes.set(evento, lista);
}
public disparar<E extends EntidadesDisponiveis, A extends AcoesCrud>(
evento: `${E}:${A}`,
payload: MapaEventosModelos[E]
): void {
console.log(`[BARRAMENTO] Disparando evento ${evento}`);
const lista = this.ouvintes.get(evento) ?? [];
lista.forEach(fn => fn(payload));
}
}
const barramento = new BarramentoEventosCorporativo();
// O compilador verifica o evento E deduz automaticamente o payload esperado!
barramento.assinar("usuario:criado", (usuario) => {
// Autocomplete ativo: usuario.email e usuario.id!
console.log(`Novo usuário registrado com sucesso: ${usuario.email}`);
});
barramento.disparar("usuario:criado", {
id: 101,
email: "[email protected]"
});
7. Armadilhas Comuns e Boas Práticas de Engenharia
- Cuidado com a Explosão Combinatória: Interpolar quatro uniões de 10 membros cada gera
10 x 10 x 10 x 10 = 10.000tipos literais únicos. Se essa multiplicação ultrapassar dezenas de milhares de membros, o compilador do TypeScript emitirá o erro de segurança TS2590: Expression produces a union type that is too complex to represent e a compilação falhará por estouro de memória. - Restringir Tipos Genéricos com
string: Ao interpolar uma variável genéricaK, lembre-se de que chaves de objetos podem serstring | number | symbol. Usestring & Kpara garantir que apenas strings sejam interpoladas. - Template Literals com Tipos Numéricos: Ao usar
v${number}, o TypeScript aceita qualquer número válido na interpolação, permitindo criar identificadores numéricos tipados comoID-${number}.
Resumo da Lição 36
- Template Literal Types utilizam a sintaxe de crases
`${TipoA}_${TipoB}`para compor strings em tempo de compilação. - A interpolação entre uniões produz automaticamente a multiplicação cartesiana de todas as combinações válidas.
- Os quatro utilitários intrínsecos de manipulação de strings são
Uppercase,Lowercase,CapitalizeeUncapitalize. - Permitem a validação estrita de padrões estruturais como URLs seguras (
https://${string}), cores hexadecimais (#${string}) e rotas versionadas. - São a base da arquitetura de barramentos de eventos tipados com namespaces (
modulo:acao) e DSLs estáticas.
📝 Exercício Prático Desafiador da Lição 36
1. Crie uma união MetodoHttp = "get" | "post" | "put" | "delete" e transforme-a em maiúsculas utilizando o utilitário intrínseco Uppercase.
2. Crie um tipo NomeEventoCustomizado que combine um prefixo de módulo "user" | "order" | "invoice", separado por dois pontos :, com um estado "created" | "failed" | "completed" transformado em maiúsculas com Uppercase (exemplo de saída esperada: "user:CREATED" | "user:FAILED" | ...).
3. Crie um tipo ChavePixValida que exija que qualquer chave Pix comece obrigatoriamente com "pix_" seguido por qualquer string.
Aplique o que você aprendeu nesta lição
Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.
Editor de Códigos Web Online
Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.
Abrir Ferramenta OnlinePlayground Web Online
Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.
⚡ Codificar no Playground IDE