Queries, mutaciones y suscripciones

Encadene .input(zodSchema).query(async ({ input, ctx }) => ...) a publicProcedure. El handler recibe la entrada validada y el contexto de la solicitud. Devuelva cualquier valor serializable: un objeto, un array o un primitivo.

El tipo de retorno se infiere automáticamente y se convierte en el tipo de datos del hook useQuery correspondiente en el cliente.

trpc.post.getById.useQuery({ id: '1' }) llama al procedimiento getById del router post. El hook devuelve el conocido objeto de resultados de React Query: { data, isLoading, isError, refetch }.

El objeto de entrada tiene tipos estáticos: pasar { id: 123 } cuando el esquema espera una cadena produce un error de TypeScript detectado durante el desarrollo.

Use .input(zodSchema).mutation(async ({ input, ctx }) => ...) para operaciones de escritura en el servidor: crear, actualizar o eliminar datos. Las mutaciones se llaman explícitamente en lugar de ejecutarse al montar el componente.

El handler de la mutación tiene acceso a todo el contexto de la solicitud (incluida la sesión de NextAuth) mediante ctx.

const { mutate, isLoading, error } = trpc.post.create.useMutation(). Llame a mutate({ title: 'New', content: '...' }) para activar la mutación. Al igual que useMutation de React Query, no se ejecuta al montar el componente.

Pase callbacks onSuccess y onError a las opciones de useMutation para ejecutar efectos secundarios después de la mutación.

Para actualizar los datos de una consulta después de una mutación correcta, use el hook de utilidades de tRPC: const utils = trpc.useUtils(). En onSuccess, llame a utils.post.getAll.invalidate() para activar una nueva obtención de la lista de publicaciones.

Este es el equivalente de tRPC de queryClient.invalidateQueries() de React Query y sigue el mismo patrón de marcar como obsoletos los datos y volver a obtenerlos.

tRPC usa Zod para validar las entradas de forma predeterminada. El esquema de Zod se ejecuta en el servidor durante el tiempo de ejecución y rechaza las entradas con formato incorrecto antes de que lleguen al handler. El mismo esquema proporciona los tipos de TypeScript para el cliente.

Esta doble función (validación en tiempo de ejecución y tipos de TypeScript) elimina la duplicación: defina el contrato una sola vez en Zod y obtenga ambas garantías de seguridad sin esfuerzo adicional.

De forma predeterminada, tRPC usa httpBatchLink, que agrupa varias solicitudes simultáneas de tRPC en una sola solicitud HTTP. Varias llamadas a useQuery en el mismo ciclo de renderizado del componente se envían y resuelven juntas.

Esto reduce significativamente la sobrecarga de red en comparación con realizar solicitudes HTTP individuales para cada consulta en una página con varias necesidades de datos.

Defina un procedimiento de suscripción: publicProcedure.subscription(async function*() { while (true) { yield await nextEvent(); } }). Las suscripciones usan generadores asíncronos y requieren un transporte WebSocket.

Las suscripciones son ideales para funciones en tiempo real: notificaciones en directo, cursores de edición colaborativa o respuestas de IA en streaming.

Reemplace httpBatchLink por una combinación de httpBatchLink y wsLink mediante splitLink: dirija las suscripciones a wsLink y las consultas y mutaciones a httpBatchLink. Cree el cliente WebSocket con createWSClient({ url: 'ws://localhost:3000' }).

Este transporte híbrido permite que la mayoría de las solicitudes utilicen una agrupación HTTP eficiente, mientras que las suscripciones usan conexiones WebSocket persistentes.

trpc.notifications.onNew.useSubscription(undefined, { onData: (notification) => addToList(notification), onError: console.error }) se suscribe al procedimiento. El callback onData se llama con cada valor producido.

La suscripción se restablece automáticamente si el WebSocket se desconecta y vuelve a conectarse.

Una página de lista en tiempo real podría usar una consulta para cargar la lista inicial, una mutación para añadir un elemento y una suscripción para recibir en directo las adiciones de otros usuarios. Las tres operaciones tienen tipos basados en el mismo AppRouter y se combinan de forma natural.

La estrategia de invalidación de la caché depende de si prefiere volver a obtener todos los datos (invalidar después de la mutación) o actualizar la caché (utils.post.getAll.setData).

¿Qué método de utilidad de tRPC activa una nueva obtención de una consulta después de que una mutación se complete correctamente?

Defina consultas con .query() y mutaciones con .mutation(), ambas validadas mediante esquemas de Zod. En el cliente, use trpc.router.procedure.useQuery() y useMutation(). Invalide las consultas después de una mutación con utils.procedure.invalidate(). Las suscripciones usan generadores asíncronos y requieren wsLink para el transporte WebSocket.

De forma predeterminada, httpBatchLink agrupa las consultas simultáneas en una sola solicitud HTTP.