GraphQL SDL

TypeScript

Cosa fa questo convertitore

Hai uno schema GraphQL. Il tuo frontend è TypeScript. Da qualche parte nel mezzo ti serve un set di tipi che combaci con lo schema campo per campo, e ti serve adesso — non dopo un build di codegen da cinque minuti, non dopo aver collegato graphql-code-generator in un progetto nuovo, non dopo aver spiegato al junior quale plugin installare. Incolla l’SDL GraphQL nel pannello a sinistra e il pannello a destra ti restituisce TypeScript idiomatico: interface per tipi object e input, enum per gli enum, semplici alias type per union e scalar.

Il mapping segue le regole che la maggior parte del codice TypeScript si aspetta. Gli scalar nativi si allineano ai loro equivalenti primitivi TypeScript: String e ID diventano string, Int e Float diventano number, Boolean diventa boolean. Gli scalar custom come DateTime di default cadono su string con un marker // custom scalar così ti ricordi di allargarli dopo. I campi non-null (name: String!) escono come proprietà obbligatorie; i campi nullable escono col modificatore ?. I tipi lista [Order!]! diventano Order[]. type Order implements Node diventa interface Order extends Node — la relazione interface in GraphQL si mappa pulita sull’estensione strutturale di TS.

Niente upload, niente rete, niente IA. La conversione avviene client-side dentro un tokenizer SDL scritto a mano — il tuo schema non lascia mai la pagina, che è quello che vuoi quando lo schema è interno o pre-release.

Come si usa

Tre passaggi. La conversione è automatica — nessun bottone Convert.

Incolla, carica o lancia l’esempio

Butta il tuo SDL nel pannello a sinistra GraphQL SDL. Appena smetti di scrivere, il pannello a destra si aggiorna. Clicca Carica per un file .graphql / .graphqls / .gql, oppure Esempio per caricare uno schema e-commerce realistico. Un pezzetto di SDL ha questo aspetto:

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

Funzionano sia gli schemi in stile server (con extend type Query) sia le definizioni di tipo isolate. Le descrizioni in block-string ("""...""") vengono raccolte e emesse come commenti JSDoc sopra il tipo generato, che è la convenzione che documenta l’implementazione di riferimento di GraphQL.

Leggi il TypeScript generato

Il pannello a destra emette i tipi raggruppati per categoria: prima gli scalar, poi enum, union, interface, tipi input, e infine i tipi object. Dentro ciascun gruppo le definizioni mantengono l’ordine sorgente, così il diff rispetto ai tuoi tipi scritti a mano è il più piccolo possibile. Se l’SDL ha un errore di parsing (graffe non bilanciate, una block-string non chiusa, ecc.) il pannello di output mostra un singolo commento // Invalid GraphQL: ... invece di tirare un’eccezione — lo stesso pattern che Apollo Server usa quando il parsing all’avvio fallisce.

Copia o scarica

Premi Copia per incollare i tipi direttamente in un file schema.types.ts del tuo progetto. Premi Scarica per salvarli come file .ts. L’output è testo semplice — niente import di moduli, niente codice runtime — quindi entra in qualunque progetto TS, frontend o backend.

Quando lo useresti davvero

Tipi al volo senza tirare su un codegen

Stai prototipando un frontend contro un endpoint GraphQL già esistente e non hai voglia di mettere in piedi una pipeline codegen completa solo per avere i tipi di tre query. Incolli lo schema, copi l’output dentro types.ts, spedisci il prototipo. Passerai a una pipeline codegen come si deve dopo, quando il progetto sarà serio.

Verifica preventiva di cosa emetterà codegen

Prima di aggiungere un nuovo tipo allo schema, incolla qui l’SDL proposto per vedere che forma assumeranno i tuoi chiamanti TypeScript. A volte un campo che si legge bene in SDL produce un TS scomodo — una lista opzionale di nullable, un enum con un valore che collide con una parola riservata di TS — ed è molto più economico scoprirlo qui che dopo aver mergiato la PR.

Documentare uno schema per un team TypeScript

Stai facendo l’onboarding di un team TS-first su un’API GraphQL? Incolla lo schema, copia i tipi generati nel wiki. Gli ingegneri che ragionano in interface TS capiscono lo schema più in fretta da una vista TS che dall’SDL grezzo — le forme dei dati sono le stesse, la sintassi è solo quella che leggono fluenti tutti i giorni.

Script usa-e-getta che colpiscono un endpoint GraphQL

Un tool CLI estemporaneo, uno script Node, un task d’admin — qualunque cosa in cui vuoi avere dei tipi attorno alla risposta senza impegnarti in un setup completo di codegen. Incolli, copi, tipizzi la risposta, lanci lo script. Usa-e-getta, ma con abbastanza tipi da non fare brutta figura.

Domande frequenti

Genera tipi di operazione (risultati di Query / Mutation) o solo tipi dello schema?

Solo tipi dello schema — i tipi dichiarati nell’SDL. I tipi di risultato di operazione dipendono dalla specifica query o mutation che il client esegue, ed è esattamente il lavoro per cui è fatto graphql-code-generator con il plugin typed-document-node. Questa pagina copre la metà schema: ogni type, interface, enum, input, union e scalar nel tuo SDL diventa una dichiarazione TS.

Come vengono gestiti i campi nullable vs non-null?

I campi non-null (name: String!) escono come proprietà TS obbligatorie e non opzionali: name: string;. I campi nullable (name: String) escono come opzionali: name?: string;. L’output resta pulito — niente union | null sparse ovunque — che è quello che la maggior parte dei consumatori vuole. Se preferisci strict null checks, fai un find-and-replace sull’output.

E i tipi lista come [Order] o [Order!]!?

Le liste diventano array TS. [Order!]! esce come Order[] su un campo obbligatorio. [Order] esce come Order[] su un campo opzionale. La nullability a livello di elemento viene appiattita per leggibilità — se devi preservarla puoi cambiare a mano un T[] generato in (T | null)[], ma in pratica quasi nessuna codebase reale legge la nullability interna in modo separato.

Come vengono gestiti gli scalar custom?

Gli scalar custom (qualunque cosa non sia ID, String, Int, Float o Boolean) di default cadono su string con un marker // custom scalar così sono facili da trovare e allargare. Per uno scalar DateTime potresti allargare a string | Date; per uno scalar JSON potresti allargare a unknown o a una forma tipata. Il default string combacia con quello che la maggior parte dei server manda sulla rete in JSON.

Il mio schema viene mandato a un server?

No. La conversione gira interamente nel tuo browser — l’SDL viene tokenizzato lato client e l’output TypeScript viene renderizzato direttamente nel pannello a destra. Niente upload, niente log. Sicuro per incollare schemi interni o non ancora pubblicati.

L’output fa round-trip allo stesso SDL?

No — e non è il suo scopo. L’output è TypeScript, che è un altro linguaggio. Reincollare l’output TS nel pannello SDL produrrà un errore di parsing. Se vuoi formattare il tuo SDL GraphQL, usa il GraphQL Formatter linkato sotto; è fatto per quello.

Altri tool GraphQL

Generare i tipi è un pezzo. Questi tool coprono il resto del workflow GraphQL:

GraphQL Schema in TypeScript