Hooks useQuery y useMutation

La etiqueta de plantilla gql de @apollo/client analiza una cadena de consulta de GraphQL y la convierte en un DocumentNode al cargar el módulo. Defina las consultas fuera de los componentes: const GET_USERS = gql`query GetUsers { users { id name email } }`.

Nota: en el código de producción, use cadenas entre comillas simples envueltas por gql como una plantilla etiquetada. La etiqueta gql acepta la sintaxis de un literal de plantilla en el código fuente de JavaScript.

useQuery(GET_USERS) devuelve { loading, error, data, refetch, fetchMore, networkStatus }. loading es true durante la obtención inicial. error contiene cualquier error de GraphQL o de red. data contiene el resultado de la consulta con la misma estructura que esta.

Compruebe primero loading y error antes de acceder a data para evitar representar valores null.

Represente un componente de esqueleto mientras loading sea true. Represente un mensaje de error si error está definido (acceda a error.message para obtener el texto del error). Represente el contenido real únicamente cuando data esté definido y loading sea false.

Este patrón de tres estados (loading / error / data) es la estructura estándar de los componentes de Apollo Client.

El objeto data refleja la estructura de la consulta de GraphQL. Para query { users { id name } }, acceda a data.users, que es un array de objetos {id, name}. Los tipos de TypeScript coinciden si utiliza graphql-codegen para generar hooks tipados.

Sin codegen, data tiene el tipo any. Con codegen, useQuery devuelve automáticamente datos completamente tipados.

Pase las variables como segundo argumento: useQuery(GET_USER, { variables: { id: userId } }). La consulta se vuelve a ejecutar automáticamente cuando cambia userId, igual que con un array de dependencias de useEffect.

Apollo Client almacena en la caché cada combinación única de consulta + variables por separado, por lo que GET_USER con id: "1" y GET_USER con id: "2" tienen entradas independientes en la caché.

Pase skip: true en las opciones para impedir que se ejecute la consulta: useQuery(GET_USER, { skip: !userId }). Apollo no envía la solicitud cuando skip es true, y loading es false y data es undefined.

Este es el equivalente de Apollo a la clave null de SWR y a la opción enabled: false de React Query.

La función refetch que devuelve useQuery activa una solicitud de red independientemente de la fetch policy. Llame a refetch() después de una acción del usuario que pueda haber modificado los datos del servidor; por ejemplo, refetch() después de enviar un formulario.

Pase nuevas variables a refetch: refetch({ id: newId }) para volver a obtener los datos con parámetros diferentes.

Pase notifyOnNetworkStatusChange: true en las opciones para recibir actualizaciones cuando cambie el estado de la red (obtención, nueva obtención, sondeo, etc.). El campo networkStatus contiene un código numérico del enum NetworkStatus.

Esto permite mostrar un indicador sutil de "actualizando" mientras se realiza una nueva obtención en segundo plano, sin ocultar los datos actuales.

useMutation(CREATE_USER) devuelve [mutateFunction, { loading, error, data, reset }]. La función mutate se llama cuando el usuario envía un formulario. Devuelve una Promise con { data, errors }.

Llame a mutate({ variables: { name: 'Alice', email: 'alice@example.com' } }) para pasar datos de entrada a la mutación.

Pase onCompleted: (data) => navigate('/dashboard') y onError: (error) => showToast(error.message) a las opciones de useMutation. Estos callbacks se ejecutan después de que la mutación se resuelva o se rechace.

onCompleted recibe los datos del resultado de la mutación, lo que resulta útil para activar una navegación, mostrar mensajes de éxito o restablecer formularios.

La opción optimisticResponse de la llamada a mutate escribe inmediatamente un resultado sintético en la caché antes de que responda el servidor. Apollo muestra los datos optimistas al instante y luego los reemplaza por la respuesta real del servidor cuando llega.

Si la mutación falla, Apollo revierte automáticamente al estado de la caché anterior a la respuesta optimista, manteniendo la interfaz coherente.

¿Qué ocurre con useQuery cuando se pasa skip: true?

Defina consultas con la etiqueta gql, llame a useQuery(QUERY, { variables, skip }) y gestione los estados loading/error/data. useMutation devuelve una función de activación y un objeto de estado; llámela con variables y gestione los resultados mediante onCompleted y onError. Las respuestas optimistas actualizan inmediatamente la caché y revierten los cambios automáticamente si se produce un error.

La opción skip y la nueva obtención controlada por variables permiten gestionar la carga de datos condicional y parametrizada.