GraphQL SDL

TypeScript

Ce que fait ce convertisseur

Tu as un schéma GraphQL. Ton frontend est en TypeScript. Quelque part au milieu, il te faut un jeu de types qui colle au schéma champ par champ, et il te le faut tout de suite — pas après un build codegen de cinq minutes, pas après avoir branché graphql-code-generator sur un nouveau projet, pas après avoir expliqué à un junior quel plugin installer. Colle le GraphQL SDL dans le panneau de gauche et le panneau de droite te renvoie du TypeScript idiomatique : interface pour les types object et input, enum pour les enums, alias type simples pour les unions et les scalars.

Le mapping suit les règles que la plupart du code TypeScript attend. Les scalars natifs s’alignent sur leurs équivalents primitifs TypeScript : String et ID deviennent string, Int et Float deviennent number, Boolean devient boolean. Les scalars custom comme DateTime tombent par défaut sur string avec un marqueur // custom scalar pour que tu penses à les élargir plus tard. Les champs non-null (name: String!) sortent en propriétés obligatoires ; les champs nullable sortent avec le modificateur ?. Les types liste [Order!]! deviennent Order[]. type Order implements Node devient interface Order extends Node — la relation interface en GraphQL se mappe proprement sur l’extension structurelle de TS.

Aucun upload, aucun réseau, aucune IA. La conversion se fait côté client dans un tokenizer SDL fait main — ton schéma ne quitte jamais la page, ce que tu veux quand le schéma est interne ou en pré-release.

Comment l’utiliser

Trois étapes. La conversion est automatique — pas de bouton Convertir.

Colle, importe ou charge l’exemple

Mets ton SDL dans le panneau de gauche GraphQL SDL. Dès que tu arrêtes de taper, le panneau de droite se met à jour. Clique Importer pour un fichier .graphql / .graphqls / .gql, ou Exemple pour charger un schéma e-commerce réaliste. Un petit bout de SDL ressemble à ça :

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

Les schémas style serveur (avec extend type Query) comme les définitions de types autonomes fonctionnent. Les descriptions en block-string ("""...""") sont reprises et émises en commentaires JSDoc au-dessus du type généré, ce qui est la convention que documente l’implémentation de référence de GraphQL.

Lis le TypeScript généré

Le panneau de droite émet les types groupés par catégorie : d’abord les scalars, puis enums, unions, interfaces, types input, et enfin les types object. Dans chaque groupe, les définitions restent dans l’ordre source pour que le diff face à tes types écrits à la main soit le plus petit possible. Si le SDL a une erreur de parsing (accolades non fermées, block-string non terminé, etc.), le panneau de sortie affiche un seul commentaire // Invalid GraphQL: ... au lieu de lever une exception — le même schéma que Apollo Server utilise quand son parsing de démarrage échoue.

Copie ou télécharge

Clique Copier pour coller les types direct dans un fichier schema.types.ts de ton projet. Clique Télécharger pour les sauvegarder en fichier .ts. La sortie est du texte brut — pas d’imports de module, pas de code runtime — donc ça rentre dans n’importe quel projet TS, frontend ou backend.

Quand tu t’en servirais vraiment

Des types rapides sans monter un codegen

Tu prototypes un frontend contre un endpoint GraphQL existant et t’as pas envie de lancer un pipeline codegen complet juste pour avoir des types sur trois queries. Colle le schéma, copie la sortie dans types.ts, livre le proto. Tu basculeras vers un vrai pipeline codegen plus tard, quand le projet sera réel.

Vérifier ce que codegen va produire

Avant d’ajouter un nouveau type au schéma, colle le SDL proposé ici pour voir la forme qu’auront tes appelants TypeScript. Parfois un champ qui se lit bien en SDL produit du TS désagréable — une liste optionnelle de nullable, un enum dont la valeur entre en collision avec un mot réservé TS — et c’est bien moins coûteux de le voir ici qu’après le merge de la PR.

Documenter un schéma pour une équipe TypeScript

Onboarding d’une équipe TS-first sur une API GraphQL ? Colle le schéma, copie les types générés dans le wiki. Les devs qui pensent en interfaces TS pigent le schéma plus vite depuis une vue TS que depuis du SDL brut — les formes de données sont les mêmes, la syntaxe est juste celle qu’ils lisent couramment tous les jours.

Scripts jetables qui tapent un endpoint GraphQL

Un outil CLI ponctuel, un script Node, une tâche d’admin — tout ce où tu veux des types autour de la réponse sans t’engager dans un setup codegen complet. Colle, copie, type la réponse, lance le script. Jetable, mais assez typé pour ne pas avoir honte.

Questions fréquentes

Est-ce qu’il génère les types d’opération (résultats de Query / Mutation), ou seulement les types du schéma ?

Seulement les types du schéma — les types déclarés dans le SDL. Les types de résultat d’opération dépendent de la query ou mutation précise que lance un client, et c’est exactement pour ça qu’est fait graphql-code-generator avec le plugin typed-document-node. Cette page couvre la moitié schéma : chaque type, interface, enum, input, union et scalar de ton SDL devient une déclaration TS.

Comment sont gérés les champs nullable vs non-null ?

Les champs non-null (name: String!) sortent en propriétés TS obligatoires, non optionnelles : name: string;. Les champs nullable (name: String) sortent en optionnels : name?: string;. La sortie reste propre — pas d’unions | null partout — ce que la plupart des consommateurs veulent. Si tu préfères les strict null checks, fais un find-and-replace sur la sortie.

Et les types liste comme [Order] ou [Order!]! ?

Les listes deviennent des arrays TS. [Order!]! sort en Order[] sur un champ obligatoire. [Order] sort en Order[] sur un champ optionnel. La nullability au niveau de l’élément est aplatie pour la lisibilité — si tu en as besoin tu peux passer manuellement un T[] généré en (T | null)[], mais en pratique presque aucune base de code réelle ne lit la nullability interne séparément.

Comment sont gérés les scalars custom ?

Les scalars custom (tout ce qui n’est pas ID, String, Int, Float ou Boolean) tombent par défaut sur string avec un marqueur // custom scalar pour les retrouver et les élargir facilement. Pour un scalar DateTime tu pourrais élargir à string | Date ; pour un scalar JSON tu pourrais élargir à unknown ou à une forme typée. Le défaut string correspond à ce que la plupart des serveurs envoient sur le fil en JSON.

Mon schéma part-il vers un serveur ?

Non. La conversion tourne entièrement dans ton navigateur — le SDL est tokenisé côté client et la sortie TypeScript est rendue directement dans le panneau de droite. Rien n’est uploadé, rien n’est loggé. Tu peux coller des schémas internes ou non publiés en toute sécurité.

La sortie fait-elle un round-trip vers le même SDL ?

Non — et ce n’est pas le but. La sortie est du TypeScript, c’est un autre langage. Recoller la sortie TS dans le panneau SDL produira une erreur de parsing. Si tu veux formater ton SDL GraphQL, prends le GraphQL Formatter linké plus bas ; il est fait pour ça.

Autres outils GraphQL

Générer les types n’est qu’une pièce. Ces outils gèrent le reste du workflow GraphQL :

GraphQL Schema vers TypeScript