GraphQL SDL

TypeScript

Hva denne konverteren gjør

Du har et GraphQL-skjema. Frontenden din er TypeScript. Et sted i mellom trenger du et sett med typer som matcher skjemaet felt for felt, og du trenger dem nå — ikke etter en fem minutters codegen-build, ikke etter å ha koblet graphql-code-generator på et ferskt prosjekt, ikke etter å ha forklart en junior hvilken plugin som skal installeres. Lim GraphQL SDL inn i venstre panel, og høyre panel gir tilbake idiomatisk TypeScript: interface for object- og input-typer, enum for enums, vanlige type-aliaser for unions og scalars.

Mappingen følger reglene mesteparten av TypeScript-koden forventer. Innebygde scalars legger seg på sine TypeScript-primitivmotstykker: String og ID blir string, Int og Float blir number, Boolean blir boolean. Egne scalars som DateTime faller som default på string med en // custom scalar-markør, så du husker å utvide dem senere. Non-null-felt (name: String!) skrives ut som required properties; nullable felt skrives ut med ?-modifikatoren. Liste-typer [Order!]! blir til Order[]. type Order implements Node blir til interface Order extends Node — interface-relasjonen i GraphQL mapper rent til strukturell extends i TS.

Ingen opplasting, ingen nettverk, ingen AI. Konverteringen skjer på klientsiden i en håndskrevet SDL-tokenizer — skjemaet ditt forlater aldri siden, som er nettopp det du vil ha når skjemaet er internt eller pre-release.

Slik bruker du den

Tre steg. Konverteringen skjer automatisk — ingen Convert-knapp.

Lim inn, last opp eller hent eksempelet

Slipp SDL-en din i venstre GraphQL SDL-panel. Så fort du slutter å skrive, oppdaterer høyre panel seg. Klikk Last opp for en .graphql- / .graphqls- / .gql-fil, eller Eksempel for å laste inn et realistisk e-handelsskjema. En liten bit SDL ser slik ut:

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

Både skjemaer i serverstil (med extend type Query) og frittstående type-definisjoner fungerer. Block-string-beskrivelser ("""...""") plukkes opp og skrives ut som JSDoc-kommentarer over den genererte typen, som er konvensjonen GraphQLs referanseimplementasjon dokumenterer.

Les den genererte TypeScript-koden

Høyre panel skriver ut typene gruppert etter slag: scalars først, så enums, unions, interfaces, input-typer, og til slutt object-typer. Innenfor hver gruppe beholder definisjonene kilde-rekkefølgen, slik at diffen mot dine håndskrevne typer blir så liten som mulig. Har SDL-en en parse-feil (ubalanserte krøllparenteser, en uavsluttet block-string osv.), viser output-panelet en enkelt // Invalid GraphQL: ...-kommentar i stedet for å kaste — samme mønster som Apollo Server bruker når dens oppstarts-parse feiler.

Kopier eller last ned

Trykk Kopier for å lime typene rett inn i en schema.types.ts-fil i prosjektet ditt. Trykk Last ned for å lagre dem som en .ts-fil. Output er ren tekst — ingen modul-imports, ingen runtime-kode — så det glir rett inn i et hvilket som helst TS-prosjekt, frontend eller backend.

Når du faktisk ville brukt det

Raske typer uten å sette opp codegen

Du prototyper en frontend mot et eksisterende GraphQL-endepunkt og gidder ikke fyre opp en hel codegen-pipeline bare for å få typer til tre queries. Lim inn skjemaet, kopier output inn i types.ts, send prototypen. Du kan bytte til en ordentlig codegen-pipeline senere når prosjektet blir på alvor.

Sanity-sjekke hva codegen kommer til å spytte ut

Før du legger en ny type til skjemaet, lim inn det foreslåtte SDL-et her for å se hvilken form TypeScript-kallerne dine ender med. Av og til produserer et felt som leser pent i SDL klønete TS — en optional list av nullables, en enum med en verdi som krasjer med et TS-reservert ord — og det er mye billigere å finne her enn etter at PR-en er merget.

Dokumentere et skjema for et TypeScript-tungt team

Onboarder du et TS-first-team mot en GraphQL-API? Lim inn skjemaet, kopier de genererte typene inn i wikien. Engineers som tenker i TS-interfaces fanger skjemaet kjappere via en TS-visning enn via rå SDL — dataformene er de samme, syntaksen er bare den de allerede leser flytende hver dag.

Engangs-skript som hamrer på et GraphQL-endepunkt

Et engangs-CLI-verktøy, et Node-skript, en admin-task — alt der du vil ha noen typer rundt responsen uten å binde deg til en hel codegen-oppsett. Lim inn, kopier, typ responsen, kjør skriptet. Engangs, men typesikkert nok til at du ikke dummer deg ut.

Vanlige spørsmål

Genererer den operasjonstyper (Query- / Mutation-resultattyper), eller bare skjematyper?

Bare skjematyper — typene som er deklarert i SDL-en. Operasjonsresultattyper avhenger av den spesifikke queryen eller mutationen en klient kjører, og det er nettopp det graphql-code-generator med typed-document-node-pluginen er bygget for. Denne siden dekker skjema-halvdelen: hver type, interface, enum, input, union og scalar i SDL-en din blir til en TS-deklarasjon.

Hvordan håndteres nullable vs non-null felt?

Non-null-felt (name: String!) skrives ut som required, ikke-optional TS-properties: name: string;. Nullable-felt (name: String) skrives ut som optional: name?: string;. Output holder seg rent — ingen | null-unions overalt — som er det de fleste konsumenter vil ha. Foretrekker du strict null checks i stedet, kan du kjøre en find-and-replace over output.

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

Lister blir TS-arrays. [Order!]! skrives som Order[] på et required felt. [Order] skrives som Order[] på et optional felt. Element-nivåets nullability flates ut for lesbarheten — trenger du å beholde den, kan du manuelt endre en generert T[] til (T | null)[], men i praksis leser nesten ingen reell kodebase indre nullability separat.

Hvordan håndteres egne scalars?

Egne scalars (alt som ikke er ID, String, Int, Float eller Boolean) faller som default på string med en // custom scalar-markør så de er enkle å finne og utvide. For en DateTime-scalar kan du utvide til string | Date; for en JSON-scalar kan du utvide til unknown eller til en typet form. Defaulten string matcher det de fleste servere sender over linja som JSON.

Blir skjemaet mitt sendt til en server?

Nei. Konverteringen kjører helt i nettleseren din — SDL-en tokeniseres på klientsiden og TypeScript-output rendres rett inn i høyre panel. Ingenting lastes opp, ingenting logges. Trygt å lime inn interne eller upubliserte skjemaer.

Round-tripper output tilbake til samme SDL?

Nei — og det er heller ikke meningen. Output er TypeScript, som er et annet språk. Å lime TS-output tilbake i SDL-panelet vil gi en parse-feil. Vil du formatere selve GraphQL SDL-en din, bruk GraphQL Formatter linket nedenfor; den er laget for det.

Andre GraphQL-verktøy

Å generere typer er én bit. Disse verktøyene tar resten av GraphQL-flyten:

GraphQL-skjema til TypeScript