GraphQL SDL

TypeScript

O que esse conversor faz

Você tem um schema GraphQL. Seu frontend é TypeScript. Em algum ponto do meio você precisa de um conjunto de tipos que bata campo a campo com o schema, e precisa agora — não depois de um build de codegen de cinco minutos, não depois de plugar o graphql-code-generator em um projeto novo, não depois de explicar pro júnior qual plugin instalar. Cole o GraphQL SDL no painel da esquerda e o painel da direita devolve TypeScript idiomático: interface para tipos object e input, enum para enums, aliases type simples para unions e scalars.

O mapeamento segue as regras que a maior parte do código TypeScript espera. Os scalars nativos batem com seus equivalentes primitivos em TypeScript: String e ID viram string, Int e Float viram number, Boolean vira boolean. Scalars customizados como DateTime caem por padrão em string com um marcador // custom scalar para você lembrar de ampliá-los depois. Campos non-null (name: String!) saem como propriedades obrigatórias; campos nullable saem com o modificador ?. Tipos lista [Order!]! viram Order[]. type Order implements Node vira interface Order extends Node — a relação de interface no GraphQL mapeia limpinho para a extensão estrutural do TS.

Sem upload, sem rede, sem IA. A conversão acontece no cliente em um tokenizador SDL feito à mão — seu schema nunca sai da página, que é o que você quer quando o schema é interno ou pré-release.

Como usar

Três passos. A conversão é automática — não tem botão Converter.

Cole, envie ou carregue o exemplo

Solte seu SDL no painel esquerdo GraphQL SDL. Assim que você para de digitar, o painel direito atualiza. Clique em Enviar para um arquivo .graphql / .graphqls / .gql, ou em Exemplo para carregar um schema realista de e-commerce. Um pedacinho de SDL parece com isso:

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

Tanto schemas estilo servidor (com extend type Query) quanto definições de tipos avulsas funcionam. Descrições em block-string ("""...""") são capturadas e emitidas como comentários JSDoc acima do tipo gerado, que é a convenção que a implementação de referência do GraphQL documenta.

Leia o TypeScript gerado

O painel direito emite os tipos agrupados por categoria: scalars primeiro, depois enums, unions, interfaces, tipos input, e por último tipos object. Dentro de cada grupo, as definições mantêm a ordem do código-fonte, então o diff contra seus tipos escritos à mão fica o menor possível. Se o SDL tiver um erro de parsing (chaves desbalanceadas, block-string não terminada, etc.) o painel de saída mostra um único comentário // Invalid GraphQL: ... em vez de estourar — o mesmo padrão que o Apollo Server usa quando o parsing de inicialização falha.

Copie ou baixe

Aperte Copiar para colar os tipos direto em um arquivo schema.types.ts do seu projeto. Aperte Baixar para salvar como arquivo .ts. A saída é texto puro — sem imports de módulo, sem código de runtime — então cabe em qualquer projeto TS, frontend ou backend.

Quando você de fato usaria isso

Tipos rápidos sem montar codegen

Você está prototipando um frontend contra um endpoint GraphQL existente e não quer subir um pipeline inteiro de codegen só para conseguir tipos para três queries. Cola o schema, copia a saída para o types.ts, sobe o protótipo. Você pode migrar para um pipeline de codegen direito depois, quando o projeto for pra valer.

Conferir o que o codegen vai cuspir

Antes de adicionar um tipo novo ao schema, cole o SDL proposto aqui para ver o formato com que seus chamadores TypeScript vão acabar. Às vezes um campo que se lê bem em SDL produz um TS chato — uma lista opcional de nullables, um enum com um valor que colide com palavra reservada do TS — e é muito mais barato descobrir aqui do que depois de o PR ter sido mergeado.

Documentar um schema para um time TypeScript

Onboarding de um time TS-first em uma API GraphQL? Cole o schema, copie os tipos gerados para o wiki. Engenheiros que pensam em interfaces TS pegam o schema mais rápido por uma visão TS do que por SDL puro — os formatos de dados são os mesmos, a sintaxe só é uma que eles já leem fluente todo dia.

Scripts descartáveis que batem em um endpoint GraphQL

Uma ferramenta CLI única, um script Node, uma tarefa de admin — qualquer coisa em que você queira tipos em volta da resposta sem se comprometer com um setup completo de codegen. Cola, copia, tipa a resposta, roda o script. Descartável, mas tipado o suficiente para você não se envergonhar.

Perguntas frequentes

Ele gera tipos de operação (resultados de Query / Mutation) ou só tipos do schema?

Só tipos do schema — os tipos declarados no SDL. Tipos de resultado de operação dependem da query ou mutation específica que um cliente roda, e é exatamente para isso que serve o graphql-code-generator com o plugin typed-document-node. Esta página cobre a metade do schema: cada type, interface, enum, input, union e scalar do seu SDL vira uma declaração TS.

Como campos nullable vs non-null são tratados?

Campos non-null (name: String!) saem como propriedades TS obrigatórias, não opcionais: name: string;. Campos nullable (name: String) saem opcionais: name?: string;. A saída fica limpa — sem unions | null espalhadas — que é o que a maior parte dos consumidores quer. Se você prefere strict null checks, rode um find-and-replace na saída.

E os tipos lista como [Order] ou [Order!]!?

Listas viram arrays TS. [Order!]! sai como Order[] em um campo obrigatório. [Order] sai como Order[] em um campo opcional. A nullability no nível de elemento é colapsada por questão de legibilidade — se você precisa preservar dá para mudar à mão um T[] gerado para (T | null)[], mas na prática quase nenhum codebase real lê a nullability interna separadamente.

Como scalars customizados são tratados?

Scalars customizados (qualquer coisa que não seja ID, String, Int, Float ou Boolean) caem por padrão em string com um marcador // custom scalar para serem fáceis de achar e ampliar. Para um scalar DateTime você poderia ampliar para string | Date; para um scalar JSON você poderia ampliar para unknown ou para um formato tipado. O default string bate com o que a maior parte dos servidores manda na rede via JSON.

Meu schema é enviado para algum servidor?

Não. A conversão roda inteira no seu navegador — o SDL é tokenizado no cliente e a saída TypeScript é renderizada direto no painel direito. Nada é enviado, nada é logado. Pode colar schemas internos ou ainda não publicados sem medo.

A saída faz round-trip de volta para o mesmo SDL?

Não — e nem é a ideia. A saída é TypeScript, que é outra linguagem. Colar a saída TS de volta no painel do SDL vai dar erro de parsing. Se você quer formatar seu próprio SDL GraphQL, use o GraphQL Formatter linkado abaixo; ele foi feito para isso.

Outras ferramentas GraphQL

Gerar tipos é uma peça. Estas ferramentas cobrem o resto do fluxo GraphQL:

GraphQL Schema para TypeScript