Formateador GraphQL

Por qué formatear GraphQL

Un formateador GraphQL resuelve un problema muy común: las consultas GraphQL suelen construirse en el código, registrarse en una sola línea o copiarse desde el panel de red del navegador. Una consulta con varios niveles de anidamiento es casi imposible de leer así. No sabes qué campos pertenecen a qué objeto ni dónde termina un fragmento.

El formateador pone cada campo en su propia línea y sangra cada conjunto de selección un nivel más que su padre. Así la estructura de la consulta coincide con la de la respuesta que recibes, y es fácil comprobarla.

Esta herramienta usa Prettier 3 con su plugin de GraphQL, en tu navegador.

Cómo usarlo

1. Pega una consulta, una mutación o un esquema en el cuadro de la izquierda. Se formatea justo después de pegarlo.
2. O pulsa Abrir archivo para cargar un archivo .graphql, o Ejemplo para ver una muestra.
3. Elige la Sangría: 2 espacios, 4 espacios o tabulaciones.
4. Elige el Ancho de línea. Los argumentos y las listas de variables que no caben se reparten en varias líneas.
5. Pulsa Formatear o Ctrl+Intro.
6. Pulsa Copiar, o Descargar para guardar un archivo .graphql.

Después de formatear una vez, el resultado sigue lo que escribes. Si hay un error de sintaxis, el mensaje indica su línea y columna, y Mostrar en la entrada te lleva a ese punto.

Antes y después

Una consulta en una sola línea:

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

Después de Formatear con 2 espacios:

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

Las variables reciben un espacio después de los dos puntos, el valor por defecto 5 lleva espacios alrededor del = y cada conjunto de selección anidado tiene sangría. Ahora se ve que title es un campo de node, dentro de edges, dentro de posts.

Mutaciones y objetos de entrada

Los objetos de entrada que caben en el ancho de línea se quedan en una sola línea:

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

Cuando no caben, los argumentos se reparten. Esta es la misma mutación con un ancho de línea de 40:

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

Fíjate en que las comas entre los campos de entrada desaparecen en los objetos de varias líneas. En GraphQL las comas son opcionales y cuentan como espacio en blanco.

Fragmentos

Los fragmentos y sus expansiones (spreads) se mantienen en el orden en que los escribiste:

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

Archivos de esquema

El lenguaje de definición de esquemas (SDL) se formatea con las mismas reglas. Un campo por línea, y cada valor de un enum en su propia línea:

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

Con la Sangría en 4 espacios, query{viewer{login}} pasa a:

query {
    viewer {
        login
    }
}

Errores de sintaxis

El analizador de GraphQL es estricto y sus mensajes son breves. Dos de los más comunes:

• Si falta una llave de cierre al final, aparece Línea 4, columna 1: Syntax Error: Expected Name, found <EOF>. El analizador llegó al final de la entrada cuando todavía estaba dentro de un conjunto de selección.
• Un argumento sin valor, como en user(id: ), da Línea 2, columna 12: Syntax Error: Unexpected ")".

Cuenta las llaves a partir de la posición indicada. Un formateador también es una forma rápida de encontrar una llave que falta en una consulta larga: pégala, y si el error apunta al final de la entrada, hay un conjunto de selección que nunca se cerró.

Límites

• Solo se revisa la sintaxis. Los nombres de campo, los tipos de los argumentos y las variables obligatorias no se validan contra ningún esquema.
• El formateador no reordena campos, no ordena tipos ni elimina fragmentos sin uso.
• Para consultas dentro de plantillas gql en JavaScript o TypeScript, pega aquí solo el texto de la consulta y luego vuelve a colocar el resultado. El formateador JavaScript y el formateador TypeScript formatean el código que la rodea, pero dejan la plantilla tal como está.
• Las variables se envían como JSON, no como GraphQL. Para dar formato a un objeto de variables, usa el formateador JSON.

Otras formas de formatear GraphQL

• VS Code: con la extensión de Prettier, Dar formato al documento (Mayús+Alt+F en Windows, Mayús+Option+F en macOS) formatea archivos .graphql y .gql con las mismas reglas que esta página.
• Línea de comandos: npx prettier --write schema.graphql.
• IDE de GraphQL como GraphiQL tienen un botón Prettify que formatea la consulta en el editor. Es práctico mientras haces pruebas, y esta página es útil cuando solo tienes el texto y ningún IDE a mano.