Entrada (esquema .proto)

Saída (TypeScript)

O que esta ferramenta faz

Você tem um esquema do Protocol Buffers e um frontend em TypeScript que precisa conversar com um backend gRPC ou transcodificado em HTTP servindo essas mensagens. A toolchain oficial de codegen (protoc com ts-proto ou protobuf-ts) exige instalar ferramentas, configurar plugins e amarrar uma etapa de build. Este conversor faz o mesmo trabalho no seu navegador — cole, copie a saída, jogue no seu projeto.

O mapeamento de tipos segue como ficam os tipos escritos à mão em bases de código reais: string/bytes → string/Uint8Array, bool → boolean, os tipos numéricos menores (int32, uint32, float, double) → number e os inteiros de 64 bits (int64, uint64, fixed64, sfixed64, sint64) → string para casar com a spec de mapeamento JSON do proto3. repeated T vira T[], map<K, V> vira Record<K, V>, mensagens aninhadas viram declarações interface aninhadas.

Os nomes de campo são convertidos de snake_case (convenção do Protobuf) para camelCase (convenção do JavaScript/TypeScript) — combinando com o comportamento padrão do encoder JSON do proto3. Enums viram tipos union de literais de string (type OrderStatus = 'ORDER_STATUS_UNSPECIFIED' | 'ORDER_STATUS_PENDING' | ...), que é o que a maioria das bases de código TypeScript realmente quer — sem precisar do custo em runtime de um enum. O conversor roda inteiramente no seu navegador; nada do seu esquema sai da página.

Como usar

Três passos. A saída fica pronta para colar em um arquivo <code>.ts</code> em segundos.

Cole seu esquema .proto

Solte o esquema no editor da esquerda. syntax = "proto3"; no topo é OK mas opcional. O parser lida com blocos message aninhados, declarações enum, oneof, map<K, V> e opções de campo. Imports são reconhecidos mas ignorados — cole os tipos importados inline se você precisar deles.

A conversão de nomes de campo é automática: order_id no .proto vira orderId em TypeScript. Nomes de message e enum permanecem como estão (já em PascalCase).

Leia a saída

À direita: TypeScript com export interface para cada message e export type com uma union de literais de string para cada enum. Tipos aninhados vêm antes do pai, então o arquivo fica em ordem de declaração. Adicione o arquivo ao seu projeto e importe as interfaces do seu cliente gRPC ou handler de fetch.

Use os tipos

Conecte as interfaces ao seu cliente fetch / gRPC-Web / Connect-RPC. O formato bate com a codificação JSON do proto3, então respostas JSON são parseadas direto na forma tipada sem conversão manual. Ajuste o tratamento de int64 se seu servidor usar uma codificação JSON não padrão.

Quando isso realmente economiza tempo

Esboçar tipos para um novo frontend gRPC

Você está construindo um novo app TS em cima de um serviço gRPC existente. Você ainda não precisa de codegen completo — só dos formatos das interfaces para tipar suas chamadas fetch. Cole o .proto, jogue a saída em types.ts, está tipado.

Revisar uma mudança em uma API Protobuf

Um colega de backend adicionou campos a um message. Você quer ver como isso afeta os tipos do frontend sem rodar o build. Cole o novo .proto, faça diff da saída TypeScript com seus tipos atuais e deixe um comentário de revisão focado.

Conferir tipos gerados

Seu build usa protobuf-ts ou ts-proto, que produzem tipos com convenções próprias. Cole o esquema aqui para ter uma referência limpa de como ficariam interfaces TS simples — útil para documentação ou planejamento de migração.

Scripts descartáveis e integrações pontuais

Você está escrevendo um script Node rápido que faz POST de JSON para uma gRPC-gateway. Montar a toolchain Protobuf inteira para 30 linhas é exagero. Pegue as interfaces aqui e você tem segurança de tipos sem cerimônia.

Perguntas frequentes

Meu esquema é enviado para algum lugar?

Não. O parser e o emissor TS rodam inteiramente no seu navegador como JavaScript. Abra o DevTools e olhe a aba Network enquanto cola — zero requisições. Útil quando seu esquema inclui nomes de tipos internos, caminhos de package ou qualquer coisa que você não queira mandar para um serviço de terceiros.

Por que campos int64 são tipados como string?

Os Number do JavaScript são doubles IEEE-754, que perdem precisão acima de 2^53. O mapeamento JSON oficial do proto3 exige que int64, uint64, fixed64, sfixed64 e sint64 sejam codificados como strings JSON. Por isso a interface TS usa string para esses — bate com o que seu servidor realmente envia. Se você precisar de bigint, faça find-replace na saída.

Por que enums são unions de string em vez de enums TS?

A maioria dos projetos TypeScript hoje prefere unions de literais de string aos enums TS — sem custo em runtime, melhor tree-shaking e batem com a codificação JSON do proto3 (que serializa enums pelo nome em string). Se você quer um const enum ou um enum numérico, a conversão a partir da union é mecânica.

Como ele lida com map<K, V>?

Renderiza como Record<K, V>. Maps Protobuf com chaves que não são strings (por ex. map<int32, string>) viram Record<number, string>. JSON só tem chaves de string, então em runtime as chaves serão strings mesmo se o proto disser int — isso é uma esquisitice da spec JSON do proto3, não do conversor.

Os campos são marcados como opcionais?

Não. Campos do proto3 estão sempre presentes na saída JSON (com defaults — string vazia, 0, false, [], {}), então a interface TypeScript marca todo campo como obrigatório. Se você realmente quer campos opcionais (porque seu runtime pode omiti-los), adicione ? manualmente após cada nome de campo.

Ele lida com oneof?

Cada campo de um oneof é emitido como um campo de interface comum. A saída não força a restrição "exatamente um" que oneof implica — para isso você precisaria de uma union discriminada, que depende da semântica do seu runtime. Edite a saída na mão se quiser tipos mais estritos.

Ferramentas relacionadas

Se você trabalha com Protobuf, JSON e TypeScript, estas combinam bem:

Conversor Protobuf para TypeScript