GraphQL.js para JavaScript (Node.js): Guia Completo

1. O que é e para que serve?

GraphQL.js é a implementação de referência da especificação GraphQL em JavaScript. Ela fornece um conjunto completo de ferramentas para criar, executar e validar consultas GraphQL no lado do servidor (Node.js) e no navegador. Diferente de uma API REST, onde cada endpoint retorna uma estrutura de dados fixa, o GraphQL permite que o cliente solicite exatamente os dados de que precisa, sem excessos. Isso resolve os problemas de over-fetching (receber dados demais) e under-fetching (receber dados de menos), algo crucial para a performance de aplicativos móveis e interfaces web complexas.

A biblioteca GraphQL.js é a base para todos os frameworks GraphQL populares no ecossistema JavaScript, como Apollo Server, Express-GraphQL, Yoga e outros. Ela assume o trabalho pesado de analisar consultas, validá-las, executar resolvers e formatar a resposta em estrita conformidade com a especificação. Usando GraphQL.js diretamente, você obtém o máximo controle sobre o processo de manipulação de consultas, o que é especialmente importante ao criar middlewares personalizados, ferramentas de teste ou integrações com fontes de dados não convencionais.

As principais vantagens de usar GraphQL.js incluem: tipagem forte do schema, geração automática de documentação (via Introspection Query), capacidade de combinar dados de várias fontes (bancos de dados, APIs REST, microsserviços) em uma única consulta, além de mecanismos integrados para tratamento de erros e paginação. Isso torna a biblioteca indispensável para construir APIs modernas, escaláveis e flexíveis.

2. Instalação

A instalação da biblioteca é feita através do gerenciador de pacotes npm (Node Package Manager). Certifique-se de ter o Node.js versão 12 ou superior instalado.

npm install graphql

Para usar no projeto com suporte a módulos ES (type: "module" no package.json), importe as funções da seguinte forma:

import { graphql, buildSchema } from 'graphql';

Para CommonJS (abordagem padrão no Node.js):

const { graphql, buildSchema } = require('graphql');

3. Início rápido — exemplo mínimo funcional

Abaixo está um servidor simples que recebe uma consulta GraphQL e retorna uma saudação. Este exemplo demonstra o núcleo da biblioteca: definição do schema, resolvers e execução da consulta.

const { graphql, buildSchema } = require('graphql');

// 1. Define o schema (Schema Definition Language - SDL)
const schema = buildSchema(`
  type Query {
    hello: String
  }
`);

// 2. Define o resolver raiz (root resolver)
const rootValue = {
  hello: () => {
    return 'Olá, GraphQL.js!';
  },
};

// 3. Executa a consulta
const query = '{ hello }';

graphql({
  schema,
  source: query,
  rootValue,
}).then((response) => {
  console.log(JSON.stringify(response, null, 2));
  // Saída: { "data": { "hello": "Olá, GraphQL.js!" } }
});

4. Principais métodos/funções/classes

4.1. `buildSchema(schemaString: string): GraphQLSchema`

O que faz: Analisa uma string escrita na linguagem de schema GraphQL (SDL) e cria um objeto GraphQLSchema. Esta é a forma mais rápida de definir um schema sem usar um construtor programático.

const { buildSchema } = require('graphql');

const schema = buildSchema(`
  type Query {
    user(id: ID!): User
  }
  type User {
    id: ID
    name: String
  }
`);