Formatador GraphQL

Por que formatar GraphQL

As queries GraphQL muitas vezes são montadas no código, registradas em uma única linha nos logs ou copiadas do tráfego de rede no navegador. Uma query com alguns níveis de aninhamento fica quase impossível de ler assim. Não dá para saber quais campos pertencem a qual objeto, nem onde termina um fragment.

Um formatador GraphQL coloca cada campo em sua própria linha e dá a cada selection set um nível de recuo a mais que o do pai. A estrutura da query passa a corresponder à estrutura da resposta que você recebe, o que facilita a conferência.

Esta ferramenta usa o Prettier 3 com o plugin de GraphQL, no seu navegador.

Como usar

1. Cole uma query, uma mutation ou um schema na caixa da esquerda. Ele é formatado logo depois que você cola.
2. Ou clique em Abrir arquivo para carregar um arquivo .graphql, ou em Exemplo para ver um exemplo.
3. Escolha o Recuo: 2 espaços, 4 espaços ou tabulações.
4. Escolha a Largura da linha. Argumentos e listas de variáveis que não cabem são divididos em várias linhas.
5. Clique em Formatar ou use Ctrl+Enter.
6. Clique em Copiar, ou em Baixar para salvar um arquivo .graphql.

Depois de formatar uma vez, o resultado acompanha o que você digita. Se houver um erro de sintaxe, a mensagem mostra a linha e a coluna, e Mostrar na entrada leva até ele.

Antes e depois

Uma query em uma linha só:

query GetUser($id:ID!,$first:Int=5){user(id:$id){id name email posts(first:$first){edges{node{id title publishedAt}}}}}

Depois de Formatar com 2 espaços:

query GetUser($id: ID!, $first: Int = 5) {
  user(id: $id) {
    id
    name
    email
    posts(first: $first) {
      edges {
        node {
          id
          title
          publishedAt
        }
      }
    }
  }
}

As variáveis ganham um espaço depois dos dois-pontos, o valor padrão 5 ganha espaços em volta do =, e todos os selection sets aninhados recebem recuo. Agora dá para ver que title é um campo de node, dentro de edges, dentro de posts.

Mutations e objetos de entrada

Os objetos de entrada que cabem na largura da linha ficam em uma linha só:

mutation {
  createPost(input: { title: "Hello", tags: ["news", "update"] }) {
    id
  }
}

Quando não cabem, os argumentos são divididos. Esta é a mesma mutation com largura de linha 40:

mutation {
  createPost(
    input: {
      title: "Hello"
      tags: ["news", "update"]
    }
  ) {
    id
  }
}

Repare que as vírgulas entre os campos de entrada somem nos objetos com várias linhas. No GraphQL, as vírgulas são opcionais e contam como espaço em branco.

Fragments

Os fragments e os spreads ficam na ordem em que você os escreveu:

fragment UserParts on User {
  id
  name
}
query {
  me {
    ...UserParts
  }
}

Arquivos de schema

A linguagem de definição de schema é formatada com as mesmas regras. Um campo por linha, e cada valor de enum em sua própria linha:

type User {
  id: ID!
  name: String!
  posts(first: Int): [Post!]!
}
enum Role {
  ADMIN
  EDITOR
}

Com o Recuo em 4 espaços, query{viewer{login}} vira:

query {
    viewer {
        login
    }
}

Erros de sintaxe

O parser de GraphQL é rigoroso, e as mensagens dele, em inglês, são curtas. Duas das mais comuns:

• Uma chave de fechamento faltando no fim dá Linha 4, coluna 1: Syntax Error: Expected Name, found <EOF>. O parser chegou ao fim da entrada ainda dentro de um selection set.
• Um argumento sem valor, como em user(id: ), dá Linha 2, coluna 12: Syntax Error: Unexpected ")".

Conte as chaves a partir da posição mostrada. Um formatador também é um jeito rápido de achar uma chave faltando em uma query longa: cole, e se o erro apontar para o fim da entrada, algum selection set nunca foi fechado.

Limites

• Só a sintaxe é verificada. Nomes de campos, tipos de argumentos e variáveis obrigatórias não são validados com nenhum schema.
• O formatador não reordena campos, não ordena tipos e não remove fragments não usados.
• Para queries dentro de template strings gql em JavaScript ou TypeScript, cole aqui só o texto da query e depois coloque o resultado de volta. O formatador JavaScript e o formatador TypeScript formatam o código em volta, mas deixam a template string como está.
• As variáveis são enviadas como JSON, e não como GraphQL. Formate um objeto de variáveis no formatador JSON.

Outras formas de formatar GraphQL

• VS Code: com a extensão do Prettier, Formatar Documento (Shift+Alt+F no Windows, Shift+Option+F no macOS) formata arquivos .graphql e .gql com as mesmas regras desta página.
• Linha de comando: npx prettier --write schema.graphql.
• IDEs de GraphQL, como o GraphiQL, têm um botão Prettify que formata a query no editor. Ele é prático durante os testes, e esta página ajuda quando você só tem o texto e nenhuma IDE à mão.