Queries, Mutationen und Subscriptions

Hängen Sie .input(zodSchema).query(async ({ input, ctx }) => ...) an publicProcedure an. Der Handler erhält die validierte Eingabe und den Request-Kontext. Geben Sie einen beliebigen serialisierbaren Wert zurück: ein Objekt, ein Array oder einen primitiven Wert.

Der Rückgabetyp wird automatisch abgeleitet und zum Datentyp des zugehörigen useQuery-Hooks auf dem Client.

trpc.post.getById.useQuery({ id: '1' }) ruft die getById-Procedure im Post-Router auf. Der Hook gibt das vertraute React-Query-Ergebnisobjekt zurück: { data, isLoading, isError, refetch }.

Das Eingabeobjekt ist statisch typisiert: Die Übergabe von { id: 123 }, wenn das Schema einen String erwartet, führt zu einem TypeScript-Fehler, der bereits während der Entwicklung erkannt wird.

Verwenden Sie .input(zodSchema).mutation(async ({ input, ctx }) => ...) für serverseitige Schreibvorgänge: zum Erstellen, Aktualisieren oder Löschen von Daten. Mutationen werden explizit aufgerufen, statt beim Mounten ausgeführt zu werden.

Über ctx hat der Mutation-Handler Zugriff auf den vollständigen Request-Kontext, einschließlich der Sitzung aus NextAuth.

const { mutate, isLoading, error } = trpc.post.create.useMutation(). Rufen Sie mutate({ title: 'New', content: '...' }) auf, um die Mutation auszulösen. Wie React Querys useMutation wird sie nicht beim Mounten ausgeführt.

Übergeben Sie den useMutation-Optionen onSuccess- und onError-Callbacks für Seiteneffekte nach der Mutation.

Um Query-Daten nach einer erfolgreichen Mutation zu aktualisieren, verwenden Sie den tRPC-Utilities-Hook: const utils = trpc.useUtils(). Rufen Sie in onSuccess utils.post.getAll.invalidate() auf, um das erneute Abrufen der Post-Liste auszulösen.

Dies entspricht in tRPC dem React-Query-Aufruf queryClient.invalidateQueries() und folgt demselben Muster aus Veraltenlassen und erneutem Abrufen.

tRPC verwendet standardmäßig Zod zur Eingabevalidierung. Das Zod-Schema wird zur Laufzeit auf dem Server ausgeführt und weist fehlerhafte Eingaben zurück, bevor sie den Handler erreichen. Dasselbe Schema stellt die TypeScript-Typen für den Client bereit.

Diese doppelte Funktion (Validierung zur Laufzeit und TypeScript-Typen) beseitigt Duplikation: Sie definieren den Vertrag einmal in Zod und erhalten beide Sicherheitsgarantien ohne zusätzlichen Aufwand.

Standardmäßig verwendet tRPC httpBatchLink, das mehrere gleichzeitig ausgeführte tRPC-Anfragen zu einer einzigen HTTP-Anfrage bündelt. Mehrere useQuery-Aufrufe im selben Renderzyklus einer Komponente werden gemeinsam gesendet und gemeinsam verarbeitet.

Dadurch wird der Netzwerkaufwand im Vergleich zu einzelnen HTTP-Anfragen für jede Query auf einer Seite mit mehreren Datenanforderungen deutlich reduziert.

Definieren Sie eine Subscription-Procedure: publicProcedure.subscription(async function*() { while (true) { yield await nextEvent(); } }). Subscriptions verwenden asynchrone Generatoren und erfordern einen WebSocket-Transport.

Subscriptions eignen sich ideal für Echtzeitfunktionen: Live-Benachrichtigungen, Cursor bei der kollaborativen Bearbeitung oder gestreamte KI-Antworten.

Ersetzen Sie httpBatchLink durch eine Kombination aus httpBatchLink und wsLink mit splitLink: Leiten Sie Subscriptions an wsLink sowie Queries und Mutationen an httpBatchLink weiter. Erstellen Sie den WebSocket-Client mit createWSClient({ url: 'ws://localhost:3000' }).

Dieser hybride Transport bedeutet, dass die meisten Anfragen effizientes HTTP-Batching verwenden, während Subscriptions persistente WebSocket-Verbindungen nutzen.

trpc.notifications.onNew.useSubscription(undefined, { onData: (notification) => addToList(notification), onError: console.error }) abonniert die Procedure. Der onData-Callback wird für jeden ausgegebenen Wert aufgerufen.

Die Subscription wird automatisch wiederhergestellt, wenn die WebSocket-Verbindung getrennt und erneut aufgebaut wird.

Eine Echtzeit-Listenseite könnte eine Query zum Laden der anfänglichen Liste, eine Mutation zum Hinzufügen eines Elements und eine Subscription zum Empfangen von Live-Ergänzungen anderer Benutzer verwenden. Alle drei sind gegen denselben AppRouter typisiert und lassen sich auf natürliche Weise kombinieren.

Die Strategie zur Cache-Invalidierung hängt davon ab, ob Sie einen vollständigen erneuten Abruf (nach der Mutation invalidate aufrufen) oder Cache-Aktualisierungen (utils.post.getAll.setData) bevorzugen.

Welche tRPC-Utility-Methode löst nach dem erfolgreichen Abschluss einer Mutation das erneute Abrufen einer Query aus?

Definieren Sie Queries mit .query() und Mutationen mit .mutation(), die beide durch Zod-Schemas validiert werden. Verwenden Sie auf dem Client trpc.router.procedure.useQuery() und useMutation(). Invalidieren Sie Queries nach einer Mutation mit utils.procedure.invalidate(). Subscriptions verwenden asynchrone Generatoren und erfordern wsLink als WebSocket-Transport.

httpBatchLink bündelt standardmäßig gleichzeitige Queries zu einer einzigen HTTP-Anfrage.