Consultas, mutações e assinaturas

Encadeie .input(zodSchema).query(async ({ input, ctx }) => ...) a publicProcedure. O manipulador recebe a entrada validada e o contexto da solicitação. Retorne qualquer valor serializável: um objeto, uma matriz ou um valor primitivo.

O tipo de retorno é inferido automaticamente e se torna o tipo de dados do gancho useQuery correspondente no cliente.

trpc.post.getById.useQuery({ id: '1' }) chama o procedimento getById no roteador post. O gancho retorna o conhecido objeto de resultado do React Query: { data, isLoading, isError, refetch }.

O objeto de entrada é tipado estaticamente: passar { id: 123 } quando o esquema espera uma cadeia de caracteres é um erro do TypeScript detectado durante o desenvolvimento.

Use .input(zodSchema).mutation(async ({ input, ctx }) => ...) para operações de gravação no servidor: criar, atualizar ou excluir dados. As mutações são chamadas explicitamente, em vez de serem executadas durante a montagem.

O manipulador da mutação tem acesso ao contexto completo da solicitação (incluindo a sessão do NextAuth) por meio de ctx.

const { mutate, isLoading, error } = trpc.post.create.useMutation(). Chame mutate({ title: 'New', content: '...' }) para disparar a mutação. Assim como useMutation do React Query, ela não é executada durante a montagem.

Passe funções de retorno onSuccess e onError para as opções de useMutation a fim de executar efeitos colaterais após a mutação.

Para atualizar os dados de uma consulta após uma mutação bem-sucedida, use o gancho de utilitários do tRPC: const utils = trpc.useUtils(). Em onSuccess, chame utils.post.getAll.invalidate() para disparar uma nova busca da lista de publicações.

Esse é o equivalente no tRPC a React Query's queryClient.invalidateQueries() e segue o mesmo padrão de considerar os dados obsoletos e recarregá-los.

O tRPC usa o Zod para validação da entrada por padrão. O esquema do Zod é executado no servidor em tempo de execução, rejeitando entradas malformadas antes que elas cheguem ao seu manipulador. O mesmo esquema fornece tipos do TypeScript para o cliente.

Essa dupla função (validação em tempo de execução + tipos do TypeScript) elimina a duplicação: defina o contrato uma única vez no Zod e obtenha as duas garantias de segurança sem esforço adicional.

Por padrão, o tRPC usa httpBatchLink, que agrupa várias solicitações simultâneas do tRPC em uma única solicitação HTTP. Várias chamadas de useQuery no mesmo ciclo de renderização de um componente são enviadas e resolvidas juntas.

Isso reduz significativamente a sobrecarga da rede em comparação com solicitações HTTP individuais para cada consulta em uma página com várias necessidades de dados.

Defina um procedimento de assinatura: publicProcedure.subscription(async function*() { while (true) { yield await nextEvent(); } }). As assinaturas usam geradores assíncronos e exigem um transporte WebSocket.

As assinaturas são ideais para recursos em tempo real: notificações ao vivo, cursores de edição colaborativa ou transmissão contínua de respostas de IA.

Substitua httpBatchLink por uma combinação de httpBatchLink e wsLink usando splitLink: encaminhe as assinaturas para wsLink e as consultas/mutações para httpBatchLink. Crie o cliente WebSocket com createWSClient({ url: 'ws://localhost:3000' }).

Esse transporte híbrido faz com que a maioria das solicitações use o agrupamento HTTP eficiente, enquanto as assinaturas usam conexões WebSocket persistentes.

trpc.notifications.onNew.useSubscription(undefined, { onData: (notification) => addToList(notification), onError: console.error }) inscreve-se no procedimento. A função de retorno onData é chamada para cada valor produzido.

A assinatura é restabelecida automaticamente se o WebSocket for desconectado e se conectar novamente.

Uma página de lista em tempo real pode usar uma consulta para carregar a lista inicial, uma mutação para adicionar um item e uma assinatura para receber adições ao vivo de outros usuários. Os três recursos são tipados com base no mesmo AppRouter e combinam naturalmente.

A estratégia de invalidação do cache depende de você preferir um recarregamento completo (invalidar após a mutação) ou atualizações do cache (utils.post.getAll.setData).

Qual método utilitário do tRPC dispara uma nova busca de uma consulta depois que uma mutação é concluída com sucesso?

Defina consultas com .query() e mutações com .mutation(), ambas validadas por esquemas do Zod. No cliente, use trpc.router.procedure.useQuery() e useMutation(). Invalide as consultas após a mutação com utils.procedure.invalidate(). As assinaturas usam geradores assíncronos e exigem wsLink para o transporte WebSocket.

Por padrão, o httpBatchLink agrupa consultas simultâneas em uma única solicitação HTTP.