Input (schema .proto)

Output (TypeScript)

Cosa fa questo strumento

Hai uno schema Protocol Buffers e un frontend TypeScript che deve parlare con un backend gRPC o transcodificato in HTTP che serve quei messaggi. La toolchain ufficiale di codegen (protoc con ts-proto o protobuf-ts) richiede di installare strumenti, configurare plugin e collegare uno step di build. Questo convertitore fa lo stesso lavoro nel tuo browser — incolla, copia l'output, mettilo nel tuo progetto.

Il mapping dei tipi rispecchia come si scrivono i tipi a mano nelle codebase reali: string/bytes → string/Uint8Array, bool → boolean, i tipi numerici più piccoli (int32, uint32, float, double) → number, e gli interi a 64 bit (int64, uint64, fixed64, sfixed64, sint64) → string per allinearsi alla specifica di mapping JSON di proto3. repeated T diventa T[], map<K, V> diventa Record<K, V>, i messaggi annidati diventano dichiarazioni interface annidate.

I nomi dei campi vengono convertiti da snake_case (convenzione Protobuf) a camelCase (convenzione JavaScript/TypeScript) — coincidendo con il comportamento di default dell'encoder JSON di proto3. Gli enum diventano tipi union di letterali stringa (type OrderStatus = 'ORDER_STATUS_UNSPECIFIED' | 'ORDER_STATUS_PENDING' | ...), che è ciò che la maggior parte delle codebase TypeScript vuole davvero — senza il costo a runtime di un enum. Il convertitore gira interamente nel tuo browser; nulla del tuo schema lascia la pagina.

Come usarlo

Tre passi. L'output è pronto per essere incollato in un file <code>.ts</code> in pochi secondi.

Incolla il tuo schema .proto

Lascia cadere lo schema nell'editor a sinistra. syntax = "proto3"; in cima va bene ma è opzionale. Il parser gestisce blocchi message annidati, dichiarazioni enum, oneof, map<K, V> e opzioni di campo. Gli import vengono riconosciuti ma saltati — incolla i tipi importati inline se ti servono.

La conversione dei nomi dei campi è automatica: order_id in .proto diventa orderId in TypeScript. I nomi di message ed enum restano come sono (già PascalCase).

Leggi l'output

A destra: TypeScript con export interface per ogni message ed export type con un'union di letterali stringa per ogni enum. I tipi annidati vengono prima del genitore, quindi il file è in ordine di dichiarazione. Aggiungi il file al tuo progetto e importa le interfacce dal tuo client gRPC o handler fetch.

Usa i tipi

Collega le interfacce al tuo client fetch / gRPC-Web / Connect-RPC. La forma combacia con la codifica JSON di proto3, quindi le risposte JSON vengono parsate direttamente nella forma tipizzata senza conversione manuale. Aggiusta la gestione di int64 se il tuo server usa una codifica JSON non standard.

Quando fa davvero risparmiare tempo

Abbozzare i tipi per un nuovo frontend gRPC

Stai costruendo una nuova app TS sopra a un servizio gRPC esistente. Non ti serve ancora la codegen completa — solo le forme delle interfacce per tipizzare le tue chiamate fetch. Incolla il .proto, butta l'output in types.ts, sei tipizzato.

Rivedere una modifica all'API Protobuf

Un collega backend ha aggiunto campi a un message. Vuoi vedere come questo influisce sui tipi del frontend senza far girare la build. Incolla il nuovo .proto, fai diff dell'output TypeScript con i tuoi tipi attuali, lascia un commento di review mirato.

Verificare i tipi generati

La tua build usa protobuf-ts o ts-proto, che producono tipi con convenzioni proprie. Incolla qui lo schema per avere un riferimento pulito di come si presentano interfacce TS pure, utile per documentazione o pianificazione di migrazioni.

Script usa-e-getta e integrazioni una tantum

Stai scrivendo uno script Node veloce che fa POST di JSON a una gRPC-gateway. Mettere su tutta la toolchain Protobuf per 30 righe è esagerato. Prendi le interfacce da qui e hai sicurezza dei tipi senza cerimonie.

Domande frequenti

Il mio schema viene inviato da qualche parte?

No. Il parser e l'emitter TS girano interamente nel tuo browser come JavaScript. Apri i DevTools e guarda la tab Network mentre incolli — zero richieste. Utile quando il tuo schema include nomi di tipi interni, percorsi di package o qualunque cosa che non vorresti mandare a un servizio di terze parti.

Perché i campi int64 sono tipizzati come string?

I Number di JavaScript sono double IEEE-754, che perdono precisione sopra 2^53. Il mapping JSON ufficiale di proto3 richiede che int64, uint64, fixed64, sfixed64 e sint64 siano codificati come stringhe JSON. Quindi l'interfaccia TS usa string per quelli — coincide con quello che il tuo server manda davvero. Se ti serve bigint, fai trova-e-sostituisci nell'output.

Perché gli enum sono union di stringhe invece di enum TS?

La maggior parte dei progetti TypeScript oggi preferisce union di letterali stringa agli enum TS — nessun costo a runtime, miglior tree-shaking, e combaciano con la codifica JSON di proto3 (che serializza gli enum col loro nome stringa). Se vuoi un const enum o un enum numerico, la conversione dall'union è meccanica.

Come gestisce map<K, V>?

Lo rende come Record<K, V>. Le map Protobuf con chiavi non-stringa (es. map<int32, string>) diventano Record<number, string>. JSON ha solo chiavi stringa, quindi a runtime le chiavi saranno stringhe anche se il proto dice int — è una stranezza della spec JSON di proto3, non del convertitore.

I campi sono marcati come opzionali?

No. I campi di proto3 sono sempre presenti nell'output JSON (con valori di default — stringa vuota, 0, false, [], {}), quindi l'interfaccia TypeScript marca ogni campo come obbligatorio. Se vuoi davvero campi opzionali (perché il tuo runtime potrebbe ometterli), aggiungi ? manualmente dopo ogni nome di campo.

Gestisce oneof?

Ogni campo di un oneof viene emesso come campo di interfaccia normale. L'output non impone il vincolo "esattamente uno" che oneof implica — per quello servirebbe una union discriminata, che dipende dalla semantica del tuo runtime. Modifica l'output a mano se ti servono tipi più stretti.

Strumenti correlati

Se lavori con Protobuf, JSON e TypeScript, questi si abbinano bene:

Convertitore da Protobuf a TypeScript