Requêtes, mutations et abonnements

Chaînez .input(zodSchema).query(async ({ input, ctx }) => ...) à publicProcedure. Le gestionnaire reçoit l’entrée validée et le contexte de la requête. Renvoyez n’importe quelle valeur sérialisable : un objet, un tableau ou une valeur primitive.

Le type de retour est automatiquement inféré et devient le type de données de la fonction useQuery correspondante sur le client.

trpc.post.getById.useQuery({ id: '1' }) appelle la procédure getById du routeur post. La fonction d’accroche renvoie l’objet de résultat familier de React Query : { data, isLoading, isError, refetch }.

L’objet d’entrée est typé statiquement : transmettre { id: 123 } lorsque le schéma attend une chaîne de caractères provoque une erreur TypeScript détectée pendant le développement.

Utilisez .input(zodSchema).mutation(async ({ input, ctx }) => ...) pour les opérations d’écriture côté serveur : créer, modifier ou supprimer des données. Les mutations sont appelées explicitement plutôt que de s’exécuter au montage.

Le gestionnaire de mutation a accès à l’intégralité du contexte de la requête (notamment à la session provenant de NextAuth) via ctx.

const { mutate, isLoading, error } = trpc.post.create.useMutation(). Appelez mutate({ title: 'New', content: '...' }) pour déclencher la mutation. Comme la fonction useMutation de React Query, elle ne s’exécute pas au montage.

Transmettez des fonctions de rappel onSuccess et onError aux options de useMutation pour gérer les effets secondaires après la mutation.

Pour actualiser les données d’une requête après une mutation réussie, utilisez la fonction d’accroche des utilitaires tRPC : const utils = trpc.useUtils(). Dans onSuccess, appelez utils.post.getAll.invalidate() pour déclencher un nouveau chargement de la liste des articles.

C’est l’équivalent tRPC de queryClient.invalidateQueries() de React Query, selon le même modèle d’invalidation puis de rechargement des données obsolètes.

tRPC utilise Zod par défaut pour valider les entrées. Le schéma Zod s’exécute sur le serveur au moment de l’exécution et rejette les entrées malformées avant qu’elles n’atteignent votre gestionnaire. Le même schéma fournit les types TypeScript du client.

Ce double rôle (validation à l’exécution et types TypeScript) élimine la duplication : vous définissez le contrat une seule fois dans Zod et obtenez gratuitement les deux garanties de sécurité.

Par défaut, tRPC utilise httpBatchLink, qui regroupe plusieurs requêtes tRPC simultanées en une seule requête HTTP. Plusieurs appels à useQuery dans le même cycle de rendu d’un composant sont envoyés et résolus ensemble.

Cela réduit considérablement la surcharge réseau par rapport à des requêtes HTTP individuelles pour chaque requête d’une page ayant plusieurs besoins en données.

Définissez une procédure d’abonnement : publicProcedure.subscription(async function*() { while (true) { yield await nextEvent(); } }). Les abonnements utilisent des générateurs asynchrones et nécessitent un transport WebSocket.

Les abonnements sont idéaux pour les fonctionnalités en temps réel : notifications en direct, curseurs d’édition collaborative ou réponses d’IA diffusées en continu.

Remplacez httpBatchLink par une combinaison de httpBatchLink et wsLink à l’aide de splitLink : acheminez les abonnements vers wsLink et les requêtes et mutations vers httpBatchLink. Créez le client WebSocket avec createWSClient({ url: 'ws://localhost:3000' }).

Ce transport hybride signifie que la plupart des requêtes utilisent un regroupement HTTP efficace, tandis que les abonnements utilisent des connexions WebSocket persistantes.

trpc.notifications.onNew.useSubscription(undefined, { onData: (notification) => addToList(notification), onError: console.error }) s’abonne à la procédure. La fonction de rappel onData est appelée pour chaque valeur produite.

L’abonnement est automatiquement rétabli si la connexion WebSocket est interrompue puis rétablie.

Une page de liste en temps réel peut utiliser une requête pour charger la liste initiale, une mutation pour ajouter un élément et un abonnement pour recevoir les ajouts effectués en direct par d’autres utilisateurs. Les trois sont typés à partir du même AppRouter et se composent naturellement.

La stratégie d’invalidation du cache dépend de votre préférence pour un rechargement complet (invalidation après la mutation) ou des mises à jour du cache (utils.post.getAll.setData).

Quelle méthode utilitaire de tRPC déclenche le rechargement d’une requête après la réussite d’une mutation ?

Définissez les requêtes avec .query() et les mutations avec .mutation(), toutes deux validées par des schémas Zod. Sur le client, utilisez trpc.router.procedure.useQuery() et useMutation(). Invalidez les requêtes après une mutation avec utils.procedure.invalidate(). Les abonnements utilisent des générateurs asynchrones et nécessitent wsLink pour le transport WebSocket.

Par défaut, httpBatchLink regroupe les requêtes simultanées en une seule requête HTTP.