GraphQL SDL

TypeScript

Hvad konverteren gør

Du har et GraphQL-skema. Din frontend er TypeScript. Et eller andet sted derimellem skal du bruge et sæt typer, der matcher skemaet felt for felt, og du skal bruge dem nu — ikke efter en fem-minutters codegen-build, ikke efter at have koblet graphql-code-generator på et nyt projekt, ikke efter at have forklaret en junior, hvilken plugin der skal installeres. Indsæt GraphQL SDL i venstre panel, og højre panel returnerer idiomatisk TypeScript: interface for object- og input-typer, enum for enums, almindelige type-aliaser for unions og scalars.

Mappingen følger reglerne, som det meste TypeScript-kode forventer. Indbyggede scalars lægger sig på deres TypeScript-primitive modstykker: String og ID bliver til string, Int og Float bliver til number, Boolean bliver til boolean. Custom scalars som DateTime falder som default på string med en // custom scalar-markør, så du husker at udvide dem senere. Non-null-felter (name: String!) skrives som required properties; nullable felter skrives med ?-modifieren. Liste-typer [Order!]! bliver til Order[]. type Order implements Node bliver til interface Order extends Node — interface-relationen i GraphQL mapper rent på TS strukturel extension.

Ingen upload, intet netværk, ingen AI. Konverteringen sker klientsidigt i en håndskrevet SDL-tokenizer — dit skema forlader aldrig siden, hvilket er præcis det, du vil have, når skemaet er internt eller pre-release.

Sådan bruger du den

Tre trin. Konverteringen er automatisk — ingen Convert-knap.

Indsæt, upload eller hent eksemplet

Smid din SDL ind i venstre GraphQL SDL-panel. Så snart du holder op med at skrive, opdaterer højre panel sig. Klik Upload for en .graphql- / .graphqls- / .gql-fil, eller Eksempel for at indlæse et realistisk e-handelsskema. Et lille stykke SDL ser sådan ud:

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

Både skemaer i serverstil (med extend type Query) og fritstående type-definitioner virker. Block-string-beskrivelser ("""...""") bliver opfanget og skrevet ud som JSDoc-kommentarer over den genererede type, hvilket er den konvention, GraphQL's referenceimplementation dokumenterer.

Læs den genererede TypeScript

Højre panel skriver typerne ud grupperet efter slags: scalars først, så enums, unions, interfaces, input-typer og til sidst object-typer. Inden for hver gruppe holder definitionerne kilde-rækkefølgen, så diff'en mod dine håndskrevne typer bliver så lille som muligt. Har SDL'en en parse-fejl (ubalancerede klammer, en uafsluttet block-string osv.) viser output-panelet en enkelt // Invalid GraphQL: ...-kommentar i stedet for at smide en exception — samme mønster som Apollo Server bruger, når dens startup-parse fejler.

Kopiér eller download

Tryk Kopiér for at indsætte typerne lige ind i en schema.types.ts-fil i dit projekt. Tryk Download for at gemme dem som en .ts-fil. Output er ren tekst — ingen modul-imports, ingen runtime-kode — så det glider lige ind i et hvilket som helst TS-projekt, frontend eller backend.

Hvornår du faktisk ville bruge det

Hurtige typer uden at sætte codegen op

Du prototyper en frontend mod et eksisterende GraphQL-endpoint og gider ikke fyre en hel codegen-pipeline op bare for at få typer til tre queries. Indsæt skemaet, kopiér output ind i types.ts, send prototypen afsted. Du kan skifte til en ordentlig codegen-pipeline senere, når projektet bliver til noget rigtigt.

Sanity-tjek hvad codegen vil spytte ud

Inden du føjer en ny type til skemaet, så indsæt det foreslåede SDL her for at se, hvilken form dine TypeScript-callere ender med. Nogle gange producerer et felt, der læser pænt i SDL, akavet TS — en optional list af nullables, en enum med en værdi, der støder ind i et TS-reserveret ord — og det er meget billigere at finde her end efter PR'en er merget.

Dokumentere et skema for et TypeScript-tungt team

Onboarder du et TS-first-team mod et GraphQL-API? Indsæt skemaet, kopiér de genererede typer over i wiki'en. Engineers, der tænker i TS-interfaces, fanger skemaet hurtigere via en TS-visning end via rå SDL — datalayoutet er det samme, syntaksen er bare den, de allerede læser flydende hver dag.

Engangs-scripts der hamrer på et GraphQL-endpoint

Et engangs-CLI-værktøj, et Node-script, en admin-task — alt hvor du gerne vil have lidt typer rundt om svaret uden at binde dig til en hel codegen-opsætning. Indsæt, kopiér, type respondsen, kør scriptet. Engangs, men typesikkert nok til ikke at gøre dig forlegen.

Almindelige spørgsmål

Genererer den operationstyper (Query- / Mutation-resultattyper) eller kun skematyper?

Kun skematyper — typerne, der er deklareret i SDL'en. Operationsresultattyper afhænger af den specifikke query eller mutation, en klient kører, og det er præcis, hvad graphql-code-generator med typed-document-node-pluginnet er bygget til. Den her side dækker skema-halvdelen: hver type, interface, enum, input, union og scalar i din SDL bliver til en TS-deklaration.

Hvordan håndteres nullable vs non-null-felter?

Non-null-felter (name: String!) skrives som required, ikke-optional TS-properties: name: string;. Nullable felter (name: String) skrives som optional: name?: string;. Output forbliver rent — ingen | null-unions overalt — hvilket er, hvad de fleste konsumenter vil have. Foretrækker du strict null checks i stedet, så kør en find-and-replace over output.

Hvad med liste-typer som [Order] eller [Order!]!?

Lister bliver til TS-arrays. [Order!]! skrives som Order[] på et required felt. [Order] skrives som Order[] på et optional felt. Element-niveau-nullability bliver fladet ud af læsbarhedshensyn — har du brug for at bevare den, kan du manuelt ændre en genereret T[] til (T | null)[], men i praksis læser næsten ingen rigtig codebase indre nullability særskilt.

Hvordan håndteres custom scalars?

Custom scalars (alt, der ikke er ID, String, Int, Float eller Boolean) falder som default på string med en // custom scalar-markør, så de er nemme at finde og udvide. For en DateTime-scalar kunne du udvide til string | Date; for en JSON-scalar kunne du udvide til unknown eller en typet form. Defaulten string matcher det, de fleste servere sender over kablet som JSON.

Bliver mit skema sendt til en server?

Nej. Konverteringen kører helt i din browser — SDL'en tokeniseres klientsidigt og TypeScript-output rendres direkte ind i højre panel. Intet uploades, intet logges. Trygt at indsætte interne eller endnu ikke offentliggjorte skemaer.

Round-tripper output tilbage til samme SDL?

Nej — og det er heller ikke meningen. Output er TypeScript, et andet sprog. At indsætte TS-output'et tilbage i SDL-panelet vil give en parse-fejl. Vil du formatere din GraphQL SDL selv, så brug GraphQL Formatter linket nedenfor; den er bygget til det.

Andre GraphQL-værktøjer

At generere typer er ét stykke. De her værktøjer tager resten af GraphQL-flowet:

GraphQL-skema til TypeScript