Présentation des liens

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

Les liens vous permettent de personnaliser le flux de données entre le client et le serveur tRPC. Chaque lien doit accomplir une seule tâche, soit une modification autonome d'une opération tRPC (requête, mutation ou abonnement), soit un effet secondaire basé sur l'opération (comme la journalisation).

Vous pouvez composer les liens dans un tableau que vous fournissez à la configuration du client tRPC via la propriété links, représentant une chaîne de liens. Le client tRPC exécutera les liens dans l'ordre du tableau links lors d'une requête, puis les exécutera à nouveau en sens inverse lors du traitement de la réponse. Voici une représentation visuelle de la chaîne de liens :

tRPC Link Diagram. Based on Apollo's.

note

Les exemples ci-dessous supposent que vous utilisez Next.js, mais les mêmes principes s'appliquent au client tRPC standard.

utils/trpc.ts
tsx
import { httpBatchLink, loggerLink } from '@trpc/client';
import { createTRPCNext } from '@trpc/next';
export default createTRPCNext<AppRouter>({
  config() {
    const url = `http://localhost:3000`;
    return {
      links: [
        loggerLink(),
        httpBatchLink({
          url,
        }),
      ],
    };
  },
});

utils/trpc.ts
tsx
import { httpBatchLink, loggerLink } from '@trpc/client';
import { createTRPCNext } from '@trpc/next';
export default createTRPCNext<AppRouter>({
  config() {
    const url = `http://localhost:3000`;
    return {
      links: [
        loggerLink(),
        httpBatchLink({
          url,
        }),
      ],
    };
  },
});

Créer un lien personnalisé

Un lien est une fonction conforme au type TRPCLink. Chaque lien se compose de trois parties :

1. Le lien retourne une fonction prenant un paramètre de type TRPCClientRuntime. Cet argument est fourni par tRPC et utilisé lors de la création d'un lien terminal. Si vous ne créez pas de lien terminal, définissez simplement une fonction sans paramètre. Dans ce cas, ajoutez le lien au tableau links sans invocation (links: [..., myLink, httpBatchLink(...)]).

2. Cette fonction retourne une autre fonction recevant un objet avec deux propriétés : op (l'Operation exécutée par le client) et next (la fonction appelant le prochain lien de la chaîne).

3. Cette fonction retourne finalement une fonction qui renvoie l'observable fournie par @trpc/server. L'observable accepte une fonction recevant un observer qui permet à notre lien de notifier au lien précédent comment traiter le résultat. Dans cette fonction, vous pouvez soit retourner next(op) tel quel, soit vous abonner à next pour gérer le résultat de l'opération.

Exemple

utils/customLink.ts
tsx
import { TRPCLink } from '@trpc/client';
import { observable } from '@trpc/server/observable';
import type { AppRouter } from 'server/routers/_app';
export const customLink: TRPCLink<AppRouter> = () => {
  // here we just got initialized in the app - this happens once per app
  // useful for storing cache for instance
  return ({ next, op }) => {
    // this is when passing the result to the next link
    // each link needs to return an observable which propagates results
    return observable((observer) => {
      console.log('performing operation:', op);
      const unsubscribe = next(op).subscribe({
        next(value) {
          console.log('we received value', value);
          observer.next(value);
        },
        error(err) {
          console.log('we received error', err);
          observer.error(err);
        },
        complete() {
          observer.complete();
        },
      });
      return unsubscribe;
    });
  };
};

utils/customLink.ts
tsx
import { TRPCLink } from '@trpc/client';
import { observable } from '@trpc/server/observable';
import type { AppRouter } from 'server/routers/_app';
export const customLink: TRPCLink<AppRouter> = () => {
  // here we just got initialized in the app - this happens once per app
  // useful for storing cache for instance
  return ({ next, op }) => {
    // this is when passing the result to the next link
    // each link needs to return an observable which propagates results
    return observable((observer) => {
      console.log('performing operation:', op);
      const unsubscribe = next(op).subscribe({
        next(value) {
          console.log('we received value', value);
          observer.next(value);
        },
        error(err) {
          console.log('we received error', err);
          observer.error(err);
        },
        complete() {
          observer.complete();
        },
      });
      return unsubscribe;
    });
  };
};

Références

Pour des exemples concrets de création de liens, consultez les liens intégrés de tRPC sur GitHub.

Le lien terminal

Le lien terminal est le dernier maillon de la chaîne. Au lieu d'appeler next, il envoie l'opération tRPC composée au serveur tRPC et retourne une OperationResultEnvelope.

Le tableau links que vous ajoutez à la configuration du client tRPC doit contenir au moins un lien, et ce lien doit être terminal. Si links ne comporte pas de lien terminal à la fin, l'opération tRPC ne sera pas envoyée au serveur.

httpBatchLink est le lien terminal recommandé par tRPC.

httpLink et wsLink sont d'autres exemples de liens terminaux.

Gestion du contexte

Lorsqu'une opération traverse votre chaîne de liens, elle conserve un contexte que chaque lien peut lire et modifier. Cela permet aux liens de transmettre des métadonnées utilisées par d'autres maillons dans leur logique d'exécution.

Accédez au contexte actuel et modifiez-le via op.context.

Définissez la valeur initiale du contexte pour une opération spécifique via le paramètre context du hook query ou useQuery (ou mutation, subscription, etc.).

Pour un exemple d'utilisation, consultez Désactiver le traitement par lots pour certaines requêtes.