0Pricing
TypeScript Academy · Aula

Um Mini Analisador de Rotas no Nível de Tipos

Analise caminhos de rotas em objetos de parâmetros tipados.

Um Mini Analisador de Rotas 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.

O objetivo

Vamos construir um analisador de rotas que lê um caminho como "users/:id/posts/:postId" e produz um objeto de parâmetros tipado { id: string; postId: string }, inteiramente no tempo de compilação. Esse é um padrão real usado por roteadores tipados.

type Params = ParseRoute<"users/:id/posts/:postId">;
// Goal: { id: string; postId: string }

Reconhecendo um parâmetro

Um segmento de caminho é um parâmetro quando começa com ":". Fazemos a correspondência desse prefixo com um literal de modelo e inferimos o nome do parâmetro depois dos dois-pontos.

Notação: o TypeScript real escreve tipos literais de modelo com cadeias delimitadas por acentos graves que contêm lacunas de cifrão e chaves. Nestes trechos, mostramos esse padrão como Tpl<...>, listando cada parte em ordem; por exemplo, um modelo com acento grave que corresponde ao prefixo literal seguido de Rest aparece como Tpl<'prefix', infer Rest>.

type ParamName<S> = S extends Tpl<':', infer Name> ? Name : never;
// Tpl<...> denotes a backtick template literal type: a colon then Name

type X = ParamName<':id'>;   // 'id'
type Y = ParamName<'users'>; // never

Dividindo o caminho

Primeiro, divida a rota em segmentos usando "/" e reutilizando o tipo Split. Cada segmento é então um literal ou um parâmetro.

type Split<S extends string, Sep extends string> =
  S extends Tpl<infer H, Sep, infer T> ? [H, ...Split<T, Sep>] : [S];
// Tpl<H, Sep, T> = a template literal type matching H, then Sep, then T

type Segs = Split<'users/:id', '/'>; // ['users', ':id']

Recursão direta de modelo

Também podemos analisar a cadeia bruta sem dividi-la primeiro, fazendo a correspondência de um segmento por vez. Faça a correspondência até o próximo "/", trate esse segmento e, em seguida, faça a recursão sobre o restante.

type ParseRoute<S extends string> =
  S extends Tpl<infer Seg, '/', infer Rest>
    ? SegParam<Seg> & ParseRoute<Rest>
    : SegParam<S>;
// Tpl<Seg, '/', Rest> matches a segment, a slash, then the rest

Parâmetro por segmento

O auxiliar transforma um único segmento em um objeto com uma propriedade, caso ele seja um parâmetro, ou em um objeto vazio, caso seja um literal.

type SegParam<S extends string> =
  S extends Tpl<':', infer Name> ? { [K in Name]: string } : {};
// Tpl<':', Name> matches a colon followed by the param name

type X = SegParam<':id'>;   // { id: string }
type Y = SegParam<'posts'>; // {}

Combinando com interseção

Cada segmento contribui com seus parâmetros por meio de uma interseção. Objetos vazios desaparecem em uma interseção, portanto apenas os parâmetros reais permanecem no tipo final.

type Params = ParseRoute<"users/:id/posts/:postId">;
// { id: string } & {} & { postId: string } & {}
// = { id: string; postId: string }

Rastreando a análise

Para "users/:id/posts/:postId":

  • Segmento "users" -> {} , faça a recursão sobre ":id/posts/:postId"
  • Segmento ":id" -> { id: string }, faça a recursão sobre "posts/:postId"
  • Segmento "posts" -> {}, faça a recursão sobre ":postId"
  • Segmento ":postId" -> { postId: string }, caso-base
type Final = { id: string } & { postId: string };

Limpando o resultado

A interseção de objetos é exibida de forma pouco intuitiva. Um auxiliar de "formatação" a achata em um único tipo de objeto limpo usando um tipo mapeado sobre suas chaves.

type Prettify<T> = { [K in keyof T]: T[K] } & {};

type Clean = Prettify<ParseRoute<"users/:id">>; // { id: string }

Usando o analisador

Insira o tipo analisado em uma função para que o manipulador receba parâmetros corretamente tipados. Passar a chave errada torna-se um erro de compilação.

declare function route<P extends string>(
  path: P,
  handler: (params: Prettify<ParseRoute<P>>) => void
): void;

route("users/:id", p => { const id: string = p.id; });

Benefício dos parâmetros tipados

Agora o compilador deriva params da própria cadeia da rota. Renomeie um parâmetro no caminho e todos os manipuladores atualizarão automaticamente suas chaves esperadas. Nenhuma interface manual e nenhuma divergência entre a rota e o manipulador.

route("users/:userId", p => {
  const u = p.userId; // ok
  // const x = p.id; // error: id does not exist
});

Estendendo o analisador

Este mini-analisador é a semente de um roteador tipado completo. Você pode adicionar valores tipados, como parâmetros numéricos, curingas e segmentos opcionais, tudo enriquecendo o auxiliar por segmento com mais padrões de modelo. A estrutura de modelo recursivo permanece a mesma.

type SegParam2<S extends string> =
  S extends Tpl<':', infer N, '(number)'> ? { [K in N]: number }
  : S extends Tpl<':', infer N> ? { [K in N]: string }
  : {};
// Tpl<...> stands for a backtick template literal type pattern

Verificação rápida

Teste sua compreensão sobre o analisador de rotas.

Recapitulação

Você construiu um analisador de rotas no tempo de compilação.

  • Faça a correspondência de cada segmento com inferência recursiva de literais de modelo.
  • Segmentos de parâmetro (:name) tornam-se { name: string }.
  • Segmentos literais tornam-se {} e desaparecem na interseção.
  • Prettify achata o resultado em parâmetros limpos.

A seguir, no curso 25: segurança de tipos de ponta a ponta com tRPC.

Perguntas Frequentes

A aula “Um Mini Analisador de Rotas no Nível de Tipos” é grátis?

Sim — o texto completo de “Um Mini Analisador de Rotas 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 “Um Mini Analisador de Rotas no Nível de Tipos”?

Analise caminhos de rotas em objetos de parâmetros tipados. 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 “Um Mini Analisador de Rotas 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

  1. Conceitos de Combinadores de Analisadores
  2. Divisão de Textos no Nível de Tipos
  3. Analisando com Literais de Modelo
  4. Um Mini Analisador de Rotas no Nível de Tipos
← Voltar para TypeScript Academy