Entrada (esquema .proto)

Salida (TypeScript)

Qué hace esta herramienta

Tienes un esquema de Protocol Buffers y un frontend en TypeScript que necesita hablar con un backend gRPC o transcodificado a HTTP que sirve esos mensajes. La cadena oficial de codegen (protoc con ts-proto o protobuf-ts) requiere instalar herramientas, configurar plugins y conectar un paso de build. Este conversor hace lo mismo en tu navegador — pega, copia el resultado, pégalo en tu proyecto.

El mapeo de tipos sigue cómo se ven los tipos hechos a mano en bases de código reales: string/bytes → string/Uint8Array, bool → boolean, los tipos numéricos pequeños (int32, uint32, float, double) → number, y los enteros de 64 bits (int64, uint64, fixed64, sfixed64, sint64) → string para coincidir con la especificación de mapeo JSON de proto3. repeated T se vuelve T[], map<K, V> se vuelve Record<K, V>, los mensajes anidados se convierten en declaraciones interface anidadas.

Los nombres de campo se convierten de snake_case (convención de Protobuf) a camelCase (convención de JavaScript/TypeScript) — coincidiendo con el comportamiento por defecto del codificador JSON de proto3. Los enums se convierten en tipos union de literales de cadena (type OrderStatus = 'ORDER_STATUS_UNSPECIFIED' | 'ORDER_STATUS_PENDING' | ...), que es lo que la mayoría de bases de código TypeScript prefiere — sin la sobrecarga en runtime de un enum. El conversor se ejecuta enteramente en tu navegador; nada de tu esquema sale de la página.

Cómo usarlo

Tres pasos. La salida está lista para pegar en un archivo <code>.ts</code> en segundos.

Pega tu esquema .proto

Suelta el esquema en el editor de la izquierda. syntax = "proto3"; al inicio está bien pero es opcional. El parser maneja bloques message anidados, declaraciones enum, oneof, map<K, V> y opciones de campo. Las importaciones se reconocen pero se omiten — pega los tipos importados en línea si los necesitas.

La conversión de nombres de campo es automática: order_id en .proto se vuelve orderId en TypeScript. Los nombres de mensaje y enum quedan como están (ya en PascalCase).

Lee la salida

A la derecha: TypeScript con export interface para cada mensaje y export type con un union de literales de cadena para cada enum. Los tipos anidados aparecen antes que su padre para mantener el orden de declaración. Añade el archivo a tu proyecto e importa las interfaces desde tu cliente gRPC o handler de fetch.

Usa los tipos

Conecta las interfaces a tu cliente fetch / gRPC-Web / Connect-RPC. La forma coincide con la codificación JSON de proto3, así que las respuestas JSON se parsean directamente a la forma tipada sin conversión manual. Ajusta el manejo de int64 si tu servidor usa una codificación JSON no estándar.

Cuándo realmente ahorra tiempo

Esbozar tipos para un nuevo frontend gRPC

Estás construyendo una nueva app TS sobre un servicio gRPC existente. Aún no necesitas codegen completo — solo las formas de las interfaces para tipar tus llamadas fetch. Pega el .proto, suelta la salida en types.ts, ya estás tipado.

Revisar un cambio en una API Protobuf

Un compañero de backend añadió campos a un mensaje. Quieres ver cómo afecta a los tipos del frontend sin correr el build. Pega el nuevo .proto, haz diff de la salida TypeScript contra tus tipos actuales, deja un comentario de revisión enfocado.

Comprobar tipos generados

Tu build usa protobuf-ts o ts-proto, que producen tipos con sus propias convenciones. Pega el esquema aquí para tener una referencia limpia de cómo lucen interfaces TS planas, útil para documentación o planificación de migración.

Scripts desechables e integraciones puntuales

Estás escribiendo un script Node rápido que hace POST de JSON a una gRPC-gateway. Montar toda la cadena de Protobuf para 30 líneas es excesivo. Toma las interfaces de aquí y tienes seguridad de tipos sin ceremonia.

Preguntas comunes

¿Mi esquema se envía a algún sitio?

No. El parser y el emisor TS se ejecutan enteramente en tu navegador como JavaScript. Abre DevTools y mira la pestaña de red mientras pegas — cero peticiones. Útil cuando tu esquema incluye nombres de tipos internos, rutas de paquete o cualquier cosa que no querrías enviar a un servicio de terceros.

¿Por qué los campos int64 se tipan como string?

Los Number de JavaScript son doubles IEEE-754, que pierden precisión por encima de 2^53. El mapeo JSON oficial de proto3 requiere que int64, uint64, fixed64, sfixed64 y sint64 se codifiquen como cadenas JSON. Por eso la interfaz TS usa string para esos — coincide con lo que tu servidor realmente envía. Si necesitas bigint, haz un find-replace en la salida.

¿Por qué los enums son uniones de cadenas en lugar de enums TS?

Hoy la mayoría de proyectos TypeScript prefieren uniones de literales de cadena sobre los enums TS — sin coste en runtime, mejor tree-shaking, y coinciden con la codificación JSON de proto3 (que serializa los enums como su nombre de cadena). Si quieres un const enum o un enum numérico, la conversión desde la unión es mecánica.

¿Cómo maneja map<K, V>?

Lo renderiza como Record<K, V>. Los mapas Protobuf con claves no-string (p. ej. map<int32, string>) se vuelven Record<number, string>. JSON solo tiene claves de cadena, así que en runtime las claves serán cadenas aunque el proto diga int — esto es una rareza de la spec JSON de proto3, no del conversor.

¿Los campos se marcan como opcionales?

No. Los campos proto3 siempre están presentes en la salida JSON (con valores por defecto — cadena vacía, 0, false, [], {}), por lo que la interfaz TypeScript marca cada campo como obligatorio. Si realmente quieres campos opcionales (porque tu runtime puede omitirlos), añade ? manualmente después de cada nombre de campo.

¿Maneja oneof?

Cada campo de un oneof se emite como un campo de interfaz normal. La salida no impone la restricción de "exactamente uno" que oneof implica — para eso necesitarías una unión discriminada, que depende de la semántica de tu runtime. Edita la salida a mano si necesitas tipos más estrictos.

Herramientas relacionadas

Si trabajas con Protobuf, JSON y TypeScript, estas combinan bien:

Conversor Protobuf a TypeScript