GraphQL SDL

TypeScript

Was dieser Konverter macht

Du hast ein GraphQL-Schema. Dein Frontend ist TypeScript. Irgendwo dazwischen brauchst du Typen, die zum Schema Feld für Feld passen, und du brauchst sie jetzt — nicht nach einem fünfminütigen Codegen-Build, nicht nachdem du graphql-code-generator in einem frischen Projekt aufgesetzt hast, nicht nachdem du dem Junior erklärt hast, welches Plugin er installieren soll. GraphQL-SDL ins linke Panel kleben und das rechte Panel liefert idiomatisches TypeScript zurück: interface für Object- und Input-Typen, enum für Enums, schlichte type-Aliasse für Unions und Scalars.

Das Mapping folgt den Regeln, die der meiste TypeScript-Code erwartet. Eingebaute Scalars liegen auf ihren TypeScript-Primitiv-Entsprechungen: String und ID werden zu string, Int und Float werden zu number, Boolean wird zu boolean. Eigene Scalars wie DateTime landen per Default auf string mit einem // custom scalar-Marker, damit du dran denkst, sie später zu erweitern. Non-null-Felder (name: String!) werden als required ausgegeben; nullable Felder bekommen den ?-Modifier. Listentypen [Order!]! werden zu Order[]. type Order implements Node wird zu interface Order extends Node — die Interface-Beziehung in GraphQL mappt sauber auf TS-Strukturerweiterung.

Kein Upload, kein Netzwerk, keine KI. Die Konvertierung läuft clientseitig in einem von Hand geschriebenen SDL-Tokenizer — dein Schema verlässt die Seite nie, was du genau dann willst, wenn das Schema intern oder pre-release ist.

So benutzt du das

Drei Schritte. Die Konvertierung läuft automatisch — kein Convert-Button.

Einfügen, hochladen oder Beispiel laden

Wirf dein SDL ins linke GraphQL SDL-Panel. Sobald du aufhörst zu tippen, aktualisiert sich das rechte Panel. Hochladen für eine .graphql / .graphqls / .gql-Datei, oder Beispiel, um ein realistisches E-Commerce-Schema zu laden. Ein kleines Stück SDL sieht so aus:

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

Sowohl Server-Stil-Schemas (mit extend type Query) als auch eigenständige Type-Definitionen funktionieren. Block-String-Beschreibungen ("""...""") werden mitgenommen und als JSDoc-Kommentare über dem generierten Typ ausgegeben — die Konvention, die die GraphQL-Referenzimplementierung dokumentiert.

Generierten TypeScript lesen

Das rechte Panel gibt die Typen nach Art gruppiert aus: Scalars zuerst, dann Enums, Unions, Interfaces, Input-Typen und am Ende Object-Typen. Innerhalb jeder Gruppe bleiben die Definitionen in Source-Reihenfolge, damit das Diff gegen deine handgeschriebenen Typen so klein wie möglich ausfällt. Hat das SDL einen Parse-Fehler (unausgeglichene Klammern, ein nicht beendeter Block-String etc.), zeigt das Output-Panel einen einzelnen Kommentar // Invalid GraphQL: ..., statt zu werfen — das gleiche Muster, das Apollo Server nutzt, wenn der Startup-Parse fehlschlägt.

Kopieren oder herunterladen

Kopieren klicken und die Typen direkt in eine schema.types.ts-Datei in deinem Projekt einfügen. Herunterladen klicken, um sie als .ts-Datei zu speichern. Output ist reiner Text — keine Modul-Imports, kein Runtime-Code — passt also in jedes TS-Projekt, Frontend oder Backend.

Wann du das wirklich brauchst

Schnell Typen ohne Codegen-Aufbau

Du prototypisierst ein Frontend gegen einen bestehenden GraphQL-Endpoint und willst keine komplette Codegen-Pipeline hochziehen, nur um Typen für drei Queries zu haben. Schema einfügen, Output in types.ts kopieren, Prototyp ausliefern. Auf eine richtige Codegen-Pipeline kannst du später wechseln, wenn das Projekt ernst wird.

Sanity-Check, was Codegen ausspucken wird

Bevor du einen neuen Typ ins Schema legst, das vorgeschlagene SDL hier reinkleben, um zu sehen, welche Form deine TypeScript-Aufrufer am Ende bekommen. Manchmal liest sich ein Feld im SDL ok und produziert dann unangenehmes TS — eine optionale Liste von Nullables, ein Enum mit einem Wert, der mit einem TS-Reservierten kollidiert — und es ist viel günstiger, das hier zu finden als nach dem Mergen des PR.

Schema für ein TypeScript-lastiges Team dokumentieren

Onboarding eines TS-first-Teams auf eine GraphQL-API? Schema einfügen, generierte Typen ins Wiki kopieren. Engineers, die in TS-Interfaces denken, verstehen das Schema schneller über eine TS-Sicht als über rohes SDL — die Datenformen sind gleich, die Syntax ist nur die, die sie täglich fließend lesen.

Wegwerf-Skripte gegen einen GraphQL-Endpoint

Ein einmaliges CLI-Tool, ein Node-Skript, ein Admin-Task — alles, wo du Typen rund um die Antwort haben willst, ohne dich auf ein vollständiges Codegen-Setup festzulegen. Einfügen, kopieren, Antwort tippen, Skript laufen lassen. Wegwerfartig, aber typsicher genug, um sich nicht zu blamieren.

Häufige Fragen

Generiert es Operationstypen (Query- / Mutation-Ergebnistypen) oder nur Schema-Typen?

Nur Schema-Typen — die Typen, die im SDL deklariert sind. Operationsergebnistypen hängen von der konkreten Query oder Mutation ab, die ein Client ausführt, und genau dafür ist graphql-code-generator mit dem typed-document-node-Plugin gebaut. Diese Seite deckt die Schema-Hälfte ab: Jedes type, interface, enum, input, union und scalar in deinem SDL wird zu einer TS-Deklaration.

Wie werden nullable vs. non-null Felder behandelt?

Non-null-Felder (name: String!) werden als required, nicht optionale TS-Properties ausgegeben: name: string;. Nullable Felder (name: String) werden optional ausgegeben: name?: string;. Der Output bleibt sauber — keine | null-Unions überall — was die meisten Konsumenten wollen. Wenn du strict null checks bevorzugst, ein Find-and-Replace über den Output laufen lassen.

Was ist mit Listentypen wie [Order] oder [Order!]!?

Listen werden zu TS-Arrays. [Order!]! wird auf einem required-Feld zu Order[]. [Order] wird auf einem optional-Feld zu Order[]. Die Element-Nullability wird aus Lesbarkeitsgründen zusammengefaltet — wenn du sie erhalten willst, kannst du ein generiertes T[] per Hand zu (T | null)[] machen, aber in der Praxis liest fast keine echte Codebase die innere Nullability separat.

Wie werden eigene Scalars behandelt?

Eigene Scalars (alles, was nicht ID, String, Int, Float oder Boolean ist) landen per Default auf string mit einem // custom scalar-Marker, damit sie leicht zu finden und zu erweitern sind. Für einen DateTime-Scalar könntest du auf string | Date erweitern; für einen JSON-Scalar auf unknown oder eine getypte Form. Der string-Default passt zu dem, was die meisten Server per JSON über die Leitung schicken.

Wird mein Schema an einen Server geschickt?

Nein. Die Konvertierung läuft komplett in deinem Browser — das SDL wird clientseitig tokenisiert und der TypeScript-Output direkt ins rechte Panel gerendert. Nichts wird hochgeladen, nichts geloggt. Interne oder unveröffentlichte Schemas kannst du bedenkenlos einfügen.

Geht der Output round-trip zurück zum gleichen SDL?

Nein — und das ist auch nicht der Sinn. Der Output ist TypeScript, eine andere Sprache. Den TS-Output zurück ins SDL-Panel zu kleben ergibt einen Parse-Fehler. Wenn du dein GraphQL-SDL selbst formatieren willst, nimm den unten verlinkten GraphQL Formatter; der ist genau dafür gebaut.

Andere GraphQL-Tools

Typen generieren ist ein Stück. Diese Tools übernehmen den Rest des GraphQL-Workflows:

GraphQL-Schema zu TypeScript