GraphQL.js para JavaScript (Node.js): Guía Completa

1. ¿Qué es y para qué sirve?

GraphQL.js es la implementación de referencia de la especificación GraphQL en JavaScript. Proporciona un conjunto completo de herramientas para crear, ejecutar y validar consultas GraphQL tanto en el lado del servidor (Node.js) como en el navegador. A diferencia de una API REST, donde cada endpoint devuelve una estructura de datos fija, GraphQL permite al cliente solicitar exactamente los datos que necesita, sin información adicional. Esto soluciona los problemas de over-fetching (obtener datos de más) y under-fetching (falta de datos), algo crucial para el rendimiento de aplicaciones móviles e interfaces web complejas.

La librería GraphQL.js es la base de todos los frameworks GraphQL populares en el ecosistema JavaScript, como Apollo Server, Express-GraphQL, Yoga y otros. Se encarga del trabajo pesado: analizar consultas, validarlas, ejecutar los resolvers y generar la respuesta cumpliendo estrictamente con la especificación. Al usar GraphQL.js directamente, obtienes el máximo control sobre el proceso de manejo de consultas, lo cual es ideal para crear middleware personalizado, herramientas de testing o integraciones con fuentes de datos no convencionales.

Las principales ventajas de usar GraphQL.js incluyen: tipado estricto del esquema, generación automática de documentación (mediante Introspection Query), la capacidad de combinar datos de múltiples fuentes (bases de datos, APIs REST, microservicios) en una sola consulta, y mecanismos integrados para el manejo de errores y paginación. Esto convierte a la librería en una herramienta indispensable para construir APIs modernas, escalables y flexibles.

2. Instalación

La instalación de la librería se realiza a través del gestor de paquetes npm (Node Package Manager). Asegúrate de tener instalado Node.js versión 12 o superior.

npm install graphql

Para usar la librería en un proyecto con soporte para módulos ES (type: "module" en package.json), importa las funciones de la siguiente manera:

import { graphql, buildSchema } from 'graphql';

Para CommonJS (el enfoque estándar en Node.js):

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

3. Inicio rápido — ejemplo mínimo funcional

A continuación se muestra un servidor muy simple que recibe una consulta GraphQL y devuelve un saludo. Este ejemplo demuestra el núcleo de la librería: definición del esquema, resolvers y ejecución de la consulta.

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

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

// 2. Definimos el resolver raíz (root resolver)
const rootValue = {
  hello: () => {
    return '¡Hola, GraphQL.js!';
  },
};

// 3. Ejecutamos la consulta
const query = '{ hello }';

graphql({
  schema,
  source: query,
  rootValue,
}).then((response) => {
  console.log(JSON.stringify(response, null, 2));
  // Salida: { "data": { "hello": "¡Hola, GraphQL.js!" } }
});

4. Métodos/funciones/clases principales

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

Qué hace: Analiza una cadena de texto escrita en el lenguaje de esquemas GraphQL (SDL) y crea un objeto GraphQLSchema. Es la forma más rápida de definir un esquema sin usar el constructor programático.

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

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