Inndata (.proto-skjema)

Utdata (TypeScript)

Hva verktøyet gjør

Du har et Protocol Buffers-skjema og en TypeScript-frontend som må snakke med en gRPC- eller HTTP-transcoded backend som serverer disse meldingene. Den offisielle codegen-toolchainen (protoc med ts-proto eller protobuf-ts) krever at du installerer verktøy, konfigurerer plugins og kobler på et build-steg. Denne konverteren gjør samme jobb i nettleseren din — lim inn, kopier output, dropp det inn i prosjektet ditt.

Type-mappingen følger hvordan håndskrevne typer ser ut i ekte kodebaser: string/bytes → string/Uint8Array, bool → boolean, de mindre numeriske typene (int32, uint32, float, double) → number, og 64-bits heltallstyper (int64, uint64, fixed64, sfixed64, sint64) → string for å matche proto3 JSON-mapping-spesifikasjonen. repeated T blir T[], map<K, V> blir Record<K, V>, nestede meldinger blir nestede interface-deklarasjoner.

Feltnavn konverteres fra snake_case (Protobuf-konvensjon) til camelCase (JavaScript/TypeScript-konvensjon) — det matcher standardatferden til proto3 JSON-encoderen. Enums blir string-literal union-typer (type OrderStatus = 'ORDER_STATUS_UNSPECIFIED' | 'ORDER_STATUS_PENDING' | ...), som er det de fleste TypeScript-kodebaser faktisk vil ha — uten runtime-overhead fra en enum. Konverteren kjører fullt ut i nettleseren din; ingenting fra skjemaet ditt forlater siden.

Slik bruker du den

Tre trinn. Outputen er klar til å limes inn i en <code>.ts</code>-fil på sekunder.

Lim inn .proto-skjemaet ditt

Slipp skjemaet i editoren til venstre. syntax = "proto3"; øverst er greit men valgfritt. Parseren håndterer nestede message-blokker, enum-deklarasjoner, oneof, map<K, V> og feltopsjoner. Imports gjenkjennes, men hoppes over — lim inn importerte typer inline hvis du trenger dem.

Konvertering av feltnavn skjer automatisk: order_id i .proto blir orderId i TypeScript. Message- og enum-navn forblir som de er (allerede PascalCase).

Les outputen

Til høyre: TypeScript med export interface for hver melding og export type med en string-literal union for hver enum. Nestede typer kommer før forelderen, så filen er i deklarasjonsrekkefølge. Legg filen til i prosjektet ditt og importer grensesnittene fra gRPC-klienten eller fetch-handleren din.

Bruk typene

Koble grensesnittene til fetch- / gRPC-Web- / Connect-RPC-klienten din. Formen matcher proto3 JSON-kodingen, så JSON-svar parses rett inn i den typede formen uten manuell konvertering. Juster int64-håndteringen hvis serveren din bruker en ikke-standard JSON-koding.

Når det faktisk sparer tid

Skissér typer for en ny gRPC-frontend

Du bygger en ny TS-app oppå en eksisterende gRPC-tjeneste. Du trenger ikke full codegen ennå — bare grensesnittformene for å type fetch-kallene dine. Lim inn .proto, dropp output i types.ts, så er du typet.

Gjennomgå en Protobuf-API-endring

En backend-kollega la til felter i en melding. Du vil se hvordan det påvirker frontend-typene uten å kjøre builden. Lim inn det nye .proto, diff TypeScript-outputen mot dine nåværende typer, og legg igjen en fokusert review-kommentar.

Krysssjekk genererte typer

Builden din bruker protobuf-ts eller ts-proto, som produserer typer med sine egne konvensjoner. Lim inn skjemaet her for å ha en ren referanse på hvordan enkle TS-grensesnitt ser ut — nyttig til dokumentasjon eller migrasjonsplanlegging.

Engangsskript og enkeltstående integrasjoner

Du skriver et raskt Node-skript som POSTer JSON til en gRPC-gateway. Å sette opp hele Protobuf-toolchainen for 30 linjer er overkill. Hent grensesnittene herfra, så har du typesikkerhet uten seremoni.

Vanlige spørsmål

Blir skjemaet mitt sendt noe sted?

Nei. Parseren og TS-emitteren kjører fullt ut i nettleseren din som JavaScript. Åpne DevTools og se på Network-fanen mens du limer inn — null requester. Nyttig når skjemaet ditt inneholder interne typenavn, pakkebaner eller noe du ikke ville sendt til en tredjepartstjeneste.

Hvorfor er int64-felter typet som string?

JavaScript Numbers er IEEE-754-double-tall som mister presisjon over 2^53. Den offisielle proto3 JSON-mappingen krever at int64, uint64, fixed64, sfixed64 og sint64 kodes som JSON-strenger. Derfor bruker TS-grensesnittet string for dem — det matcher det serveren din faktisk sender. Vil du heller ha bigint, gjør find-replace i outputen.

Hvorfor er enums string-unions i stedet for TS-enums?

De fleste TypeScript-prosjekter foretrekker i dag string-literal unions fremfor TS-enums — ingen runtime-kostnad, bedre tree-shaking, og de matcher proto3 JSON-kodingen (som serialiserer enums som strengnavnet sitt). Vil du ha en const enum eller en numerisk enum, er konverteringen fra unionen mekanisk.

Hvordan håndterer den map<K, V>?

Renderes som Record<K, V>. Protobuf-maps med ikke-string-nøkler (f.eks. map<int32, string>) blir Record<number, string>. JSON har bare strengnøkler, så ved runtime blir nøklene strenger selv om proto sier int — det er en særegenhet ved proto3 JSON-spesifikasjonen, ikke ved konverteren.

Markeres felter som valgfrie?

Nei. proto3-felter er alltid til stede i JSON-outputen (med default-verdier — tom streng, 0, false, [], {}), så TypeScript-grensesnittet markerer hvert felt som påkrevd. Hvis du faktisk vil ha valgfrie felter (fordi runtime-en din kan utelate dem), legg til ? manuelt etter hvert feltnavn.

Håndterer den oneof?

Hvert felt i en oneof emitteres som et vanlig grensesnittfelt. Outputen håndhever ikke "nøyaktig én"-begrensningen som oneof antyder — for det trenger du en diskriminert union, og det avhenger av runtime-semantikken din. Rediger outputen for hånd hvis du trenger strammere typer.

Relaterte verktøy

Hvis du jobber med Protobuf, JSON og TypeScript, passer disse godt sammen:

Protobuf til TypeScript-konverter