Biblioteca GraphQL JavaScript (Node.js) — Guía completa

Biblioteca GraphQL JavaScript (Node.js): Guía completa

GraphQL es un lenguaje de consultas y un entorno de ejecución para API, desarrollado por Facebook. En el ecosistema Node.js, la biblioteca principal para trabajar con GraphQL es el paquete graphql. Proporciona todas las herramientas necesarias para crear, validar y ejecutar consultas GraphQL. Esta biblioteca es la base de frameworks populares como Apollo Server, Express-GraphQL y otros.

¿Qué es GraphQL y por qué es necesario?

A diferencia de las API REST, donde cada endpoint devuelve una estructura de datos fija, GraphQL permite al cliente solicitar solo los campos que necesita. Esto resuelve el problema de over-fetching (obtener datos innecesarios) y under-fetching (falta de datos). Las principales ventajas son:

• Flexibilidad de consultas: el cliente decide qué datos obtener.
• Punto de entrada único: todas las consultas van a un solo endpoint (por ejemplo, /graphql).
• Tipado estricto: el esquema GraphQL define los tipos de datos y sus relaciones.
• Introspección: se puede generar documentación y herramientas de prueba automáticamente (GraphiQL).

Instalación de la biblioteca GraphQL para Node.js

Para empezar, instale el paquete mediante npm o yarn:

npm install graphql

También necesitará un servidor HTTP, como express, y middleware express-graphql (o Apollo Server). Pero la biblioteca graphql en sí misma es el núcleo.

Creación del primer esquema y resolver

El esquema es una descripción de los tipos de datos y las operaciones disponibles (consultas, mutaciones). Los resolvers son funciones que ejecutan la lógica real de obtención de datos.

Ejemplo de un esquema simple con un tipo User y una consulta user:

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

// Definimos el esquemaconst schema = buildSchema(`  type User {    id: ID!    name: String    email: String  }

  type Query {    user(id: ID!): User  }`);

// Datos (en un proyecto real, sería una base de datos)const users = [  { id: '1', name: 'Iván', email: 'ivan@example.com' },  { id: '2', name: 'María', email: 'maria@example.com' }];

// Resolversconst root = {  user: ({ id }) => users.find(user => user.id === id)};

// Ejecutamos la consultagraphql({  schema,  source: '{ user(id: "1") { name email } }',  rootValue: root}).then(response => {  console.log(JSON.stringify(response));  // {"data":{"user":{"name":"Iván","email":"ivan@example.com"}}}});

Tipos de datos en GraphQL

La biblioteca graphql soporta todos los tipos escalares estándar:

• String — cadena de texto;
• Int — número entero;
• Float — número de punto flotante;
• Boolean — valor booleano;
• ID — identificador único (se serializa como cadena).

También se pueden crear tipos de objeto personalizados, enumeraciones (enum), listas ([Type]) y campos no nulos (Type!).

Mutaciones y suscripciones

Las mutaciones se utilizan para modificar datos (análogo a POST/PUT/DELETE en REST). Las suscripciones permiten recibir actualizaciones en tiempo real a través de WebSocket.

Ejemplo de mutación para agregar un usuario:

const schema = buildSchema(`  type Mutation {    addUser(name: String!, email: String!): User  }`);

const root = {  addUser: ({ name, email }) => {    const newUser = { id: String(users.length + 1), name, email };    users.push(newUser);    return newUser;  }};

// Ejecución de la mutacióngraphql({  schema,  source: 'mutation { addUser(name: "Pedro", email: "pedro@example.com") { id name } }',  rootValue: root}).then(console.