Inmatning (.proto-schema)

Utmatning (TypeScript)

Vad det här verktyget gör

Du har ett Protocol Buffers-schema och en TypeScript-frontend som behöver prata med en gRPC- eller HTTP-transcodad backend som serverar dessa meddelanden. Den officiella codegen-toolchainen (protoc med ts-proto eller protobuf-ts) kräver att du installerar verktyg, konfigurerar plugins och kopplar in ett build-steg. Den här konverteraren gör samma jobb i din webbläsare — klistra in, kopiera utmatningen, släng in den i ditt projekt.

Typmappningen följer hur handskrivna typer ser ut i riktiga kodbaser: string/bytes → string/Uint8Array, bool → boolean, de mindre numeriska typerna (int32, uint32, float, double) → number, och 64-bitars heltalstyperna (int64, uint64, fixed64, sfixed64, sint64) → string för att matcha proto3 JSON-mapping-specen. repeated T blir T[], map<K, V> blir Record<K, V>, nästade meddelanden blir nästade interface-deklarationer.

Fältnamn konverteras från snake_case (Protobuf-konvention) till camelCase (JavaScript/TypeScript-konvention) — vilket matchar standardbeteendet hos proto3 JSON-encodern. Enums blir string-literal-uniontyper (type OrderStatus = 'ORDER_STATUS_UNSPECIFIED' | 'ORDER_STATUS_PENDING' | ...), vilket är vad de flesta TypeScript-kodbaser faktiskt vill ha — utan runtime-overhead från en enum. Konverteraren körs helt och hållet i din webbläsare; inget av ditt schema lämnar sidan.

Så använder du det

Tre steg. Utmatningen är redo att klistras in i en <code>.ts</code>-fil på några sekunder.

Klistra in ditt .proto-schema

Släpp schemat i den vänstra editorn. syntax = "proto3"; i toppen är OK men valfritt. Parsern hanterar nästade message-block, enum-deklarationer, oneof, map<K, V> och fältoptioner. Imports känns igen men hoppas över — klistra in importerade typer inline om du behöver dem.

Fältnamnskonverteringen sker automatiskt: order_id i .proto blir orderId i TypeScript. Message- och enum-namn lämnas som de är (redan PascalCase).

Läs utmatningen

Till höger: TypeScript med export interface för varje meddelande och export type med en string-literal-union för varje enum. Nästade typer kommer före sin förälder så att filen är i deklarationsordning. Lägg filen i ditt projekt och importera gränssnitten från din gRPC-klient eller fetch-handler.

Använd typerna

Koppla gränssnitten till din fetch- / gRPC-Web- / Connect-RPC-klient. Formen matchar proto3 JSON-kodningen, så JSON-svar parsas direkt in i den typade formen utan manuell konvertering. Justera int64-hanteringen om din server använder en icke-standard JSON-kodning.

När det faktiskt sparar tid

Skissa typer för en ny gRPC-frontend

Du bygger en ny TS-app ovanpå en befintlig gRPC-tjänst. Du behöver inte full codegen ännu — bara gränssnittsformerna för att typa dina fetch-anrop. Klistra in .proto, släng utmatningen i types.ts, du är typad.

Granska en Protobuf-API-ändring

En backend-kollega lade till fält i ett meddelande. Du vill se hur det påverkar frontend-typerna utan att köra builden. Klistra in det nya .proto, diffa TypeScript-utmatningen mot dina nuvarande typer, lämna en fokuserad review-kommentar.

Korskolla genererade typer

Din build använder protobuf-ts eller ts-proto, som producerar typer med sina egna konventioner. Klistra in schemat här för en ren referens av hur enkla TS-gränssnitt ser ut — användbart för dokumentation eller migrationsplanering.

Engångsskript och tillfälliga integrationer

Du skriver ett snabbt Node-skript som POSTar JSON till en gRPC-gateway. Att sätta upp hela Protobuf-toolchainen för 30 rader är överdrivet. Hämta gränssnitten härifrån och du har typsäkerhet utan ceremoni.

Vanliga frågor

Skickas mitt schema någonstans?

Nej. Parsern och TS-emittern körs helt och hållet i din webbläsare som JavaScript. Öppna DevTools och titta på Network-fliken medan du klistrar in — noll requests. Bra när ditt schema innehåller interna typnamn, paketsökvägar eller något du inte vill skicka till en tredjepartstjänst.

Varför är int64-fält typade som string?

JavaScript-Numbers är IEEE-754-doubles som tappar precision över 2^53. Den officiella proto3 JSON-mappingen kräver att int64, uint64, fixed64, sfixed64 och sint64 kodas som JSON-strängar. Så TS-gränssnittet använder string för dessa — det matchar vad din server faktiskt skickar. Behöver du bigint i stället, gör find-replace i utmatningen.

Varför är enums string-unions i stället för TS-enums?

De flesta TypeScript-projekt föredrar idag string-literal-unions framför TS-enums — ingen runtime-kostnad, bättre tree-shaking, och de matchar proto3 JSON-kodningen (som serialiserar enums som deras strängnamn). Vill du ha en const enum eller en numerisk enum är konverteringen från unionen mekanisk.

Hur hanterar den map<K, V>?

Renderas som Record<K, V>. Protobuf-maps med icke-strängnycklar (t.ex. map<int32, string>) blir Record<number, string>. JSON har bara strängnycklar, så vid runtime blir nycklarna strängar även om proton säger int — det är en egenhet hos proto3 JSON-specen, inte konverteraren.

Markeras fält som valfria?

Nej. proto3-fält finns alltid med i JSON-utmatningen (med standardvärden — tom sträng, 0, false, [], {}), så TypeScript-gränssnittet markerar varje fält som obligatoriskt. Om du faktiskt vill ha valfria fält (för att din runtime kan utelämna dem), lägg till ? manuellt efter varje fältnamn.

Hanterar den oneof?

Varje fält i en oneof emitteras som ett vanligt gränssnittsfält. Utmatningen tvingar inte fram "exakt en"-villkoret som oneof antyder — för det skulle du behöva en diskriminerad union, vilket beror på din runtimes semantik. Redigera utmatningen för hand om du behöver striktare typer.

Relaterade verktyg

Om du jobbar med Protobuf, JSON och TypeScript passar dessa bra ihop:

Protobuf till TypeScript-konverterare