GraphQL SDL

TypeScript

Vad konverteraren gör

Du har ett GraphQL-schema. Din frontend är TypeScript. Någonstans där emellan behöver du en uppsättning typer som matchar schemat fält för fält, och du behöver dem nu — inte efter en fem minuter lång codegen-build, inte efter att ha kopplat in graphql-code-generator i ett nytt projekt, inte efter att ha förklarat för en junior vilken plugin som ska installeras. Klistra in GraphQL SDL i vänsterpanelen så ger högerpanelen tillbaka idiomatisk TypeScript: interface för object- och input-typer, enum för enums, vanliga type-aliases för unions och scalars.

Mappningen följer reglerna som det mesta av TypeScript-koden förväntar sig. Inbyggda scalars hamnar på sina TypeScript-primitivmotsvarigheter: String och ID blir string, Int och Float blir number, Boolean blir boolean. Egna scalars som DateTime faller som default på string med en // custom scalar-markör så att du kommer ihåg att vidga dem senare. Non-null-fält (name: String!) skrivs ut som required properties; nullable-fält skrivs ut med ?-modifikatorn. List-typer [Order!]! blir Order[]. type Order implements Node blir interface Order extends Node — interface-relationen i GraphQL mappar rent på strukturell extension i TS.

Ingen uppladdning, inget nätverk, ingen AI. Konverteringen sker klientsidan i en handskriven SDL-tokenizer — schemat lämnar aldrig sidan, vilket är vad du vill när schemat är internt eller pre-release.

Så här använder du den

Tre steg. Konverteringen är automatisk — ingen Convert-knapp.

Klistra in, ladda upp eller hämta exemplet

Släpp ditt SDL i den vänstra GraphQL SDL-panelen. Så fort du slutar skriva uppdateras högerpanelen. Klicka Ladda upp för en .graphql- / .graphqls- / .gql-fil, eller Exempel för att läsa in ett realistiskt e-handelsschema. En liten bit SDL ser ut så här:

type Order implements Node { id: ID! placedAt: DateTime! status: OrderStatus! items: [OrderItem!]! } enum OrderStatus { PENDING PAID SHIPPED DELIVERED CANCELLED }

Både scheman i serverstil (med extend type Query) och fristående typdefinitioner fungerar. Block-string-beskrivningar ("""...""") plockas upp och skrivs ut som JSDoc-kommentarer ovanför den genererade typen, vilket är konventionen som GraphQL:s referensimplementation dokumenterar.

Läs den genererade TypeScript-koden

Högerpanelen skriver ut typerna grupperade efter sort: scalars först, sedan enums, unions, interfaces, input-typer och sist object-typer. Inom varje grupp behåller definitionerna källordningen så att diffen mot dina handskrivna typer blir så liten som möjligt. Har SDL ett parse-fel (obalanserade måsvingar, en oavslutad block-string osv.) visar output-panelen en enda // Invalid GraphQL: ...-kommentar i stället för att kasta — samma mönster som Apollo Server använder när dess startup-parse fallerar.

Kopiera eller ladda ner

Tryck Kopiera för att klistra in typerna direkt i en schema.types.ts-fil i ditt projekt. Tryck Ladda ner för att spara dem som en .ts-fil. Output är ren text — inga modul-importer, ingen runtime-kod — så det går rakt in i vilket TS-projekt som helst, frontend eller backend.

När du faktiskt skulle använda det

Snabba typer utan att sätta upp codegen

Du prototypar en frontend mot en befintlig GraphQL-endpoint och har ingen lust att dra igång en hel codegen-pipeline bara för att få typer till tre queries. Klistra in schemat, kopiera output till types.ts, leverera prototypen. Du kan byta till en riktig codegen-pipeline senare när projektet blir på riktigt.

Sanity-checka vad codegen kommer att spotta ut

Innan du lägger till en ny typ i schemat, klistra in det föreslagna SDL:et här för att se vilken form dina TypeScript-anropare kommer att hamna i. Ibland producerar ett fält som läser snyggt i SDL klumpig TS — en optional list av nullables, en enum med ett värde som krockar med ett TS-reserverat ord — och det är mycket billigare att hitta det här än efter att PR:n är mergead.

Dokumentera ett schema för ett TypeScript-tungt team

Onboardar du ett TS-first-team mot ett GraphQL-API? Klistra in schemat, kopiera de genererade typerna till wikin. Ingenjörer som tänker i TS-interfaces fattar schemat snabbare via en TS-vy än via rå SDL — datalayouten är densamma, syntaxen är bara den de redan läser flytande varje dag.

Engångsskript som slår mot en GraphQL-endpoint

Ett engångs-CLI-verktyg, ett Node-skript, en admin-task — vad som helst där du vill ha lite typer kring svaret utan att binda upp dig på en hel codegen-setup. Klistra, kopiera, tipa svaret, kör skriptet. Engångs, men tillräckligt typsäkert för att inte göra bort sig.

Vanliga frågor

Genererar den operationstyper (Query- / Mutation-resultattyper), eller bara schematyper?

Bara schematyper — typerna som deklareras i SDL. Operationstypernas resultat beror på den specifika query eller mutation som en klient kör, och det är precis vad graphql-code-generator med typed-document-node-pluginet är byggt för. Den här sidan täcker schemahalvan: varje type, interface, enum, input, union och scalar i ditt SDL blir en TS-deklaration.

Hur hanteras nullable vs non-null-fält?

Non-null-fält (name: String!) skrivs ut som required, icke-optional TS-properties: name: string;. Nullable-fält (name: String) skrivs ut som optional: name?: string;. Output förblir rent — inga | null-unions överallt — vilket är vad de flesta konsumenter vill ha. Föredrar du strict null checks i stället, kör en find-and-replace över output.

Vad händer med list-typer som [Order] eller [Order!]!?

Listor blir TS-arrays. [Order!]! skrivs ut som Order[] på ett required fält. [Order] skrivs ut som Order[] på ett optional fält. Element-nivåns nullability plattas till för läsbarhet — om du behöver bevara den kan du manuellt byta en genererad T[] till (T | null)[], men i praktiken läser nästan ingen riktig kodbas inner-nullability separat.

Hur hanteras egna scalars?

Egna scalars (allt som inte är ID, String, Int, Float eller Boolean) faller som default på string med en // custom scalar-markör så att de är lätta att hitta och vidga. För en DateTime-scalar kan du vidga till string | Date; för en JSON-scalar kan du vidga till unknown eller till en typad form. Defaulten string matchar vad de flesta servrar skickar över ledningen som JSON.

Skickas mitt schema till en server?

Nej. Konverteringen körs helt i din webbläsare — SDL tokeniseras klientsidan och TypeScript-output renderas direkt in i högerpanelen. Inget laddas upp, inget loggas. Säkert att klistra in interna eller ej släppta scheman.

Round-trippar output tillbaka till samma SDL?

Nej — och det är inte tanken. Output är TypeScript, vilket är ett annat språk. Att klistra tillbaka TS-output i SDL-panelen ger ett parse-fel. Vill du formatera ditt GraphQL SDL i sig, använd GraphQL Formatter länkad nedan; den är byggd för det.

Andra GraphQL-verktyg

Att generera typer är en del. De här verktygen tar resten av GraphQL-flödet:

GraphQL-schema till TypeScript