Saltar al contenido principal
Versión: 11.x

Visión general de los Links

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

Los links te permiten personalizar el flujo de datos entre el Cliente y Servidor de tRPC. Cada link debe realizar una única tarea, que puede ser una modificación autocontenida de una operación tRPC (query, mutation o subscription) o un efecto secundario basado en la operación (como logging).

Puedes componer varios links en un array que proporcionas a la configuración del cliente tRPC mediante la propiedad links, representando así una cadena de links. Esto significa que el cliente tRPC ejecutará los links en el orden en que se añaden al array links al hacer una solicitud, y los ejecutará en orden inverso al manejar la respuesta. Esta representación visual ilustra la cadena de links:

tRPC Link DiagramtRPC Link Diagram. Based on Apollo's.
nota

Los siguientes ejemplos asumen que usas Next.js, pero se aplican igualmente si usas el cliente vanilla de tRPC

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,
        }),
      ],
    };
  },
});

Un link es una función que sigue el tipo TRPCLink. Cada link se compone de tres partes:

  1. El link retorna una función que recibe un parámetro de tipo TRPCClientRuntime. Este argumento es proporcionado por tRPC y se usa al crear un link terminador. Si no estás creando un link terminador, puedes crear directamente una función sin parámetros. En este caso, el link debe añadirse al array links sin invocarse (links: [..., myLink, httpBatchLink(...)]).

  2. La función del paso 1 retorna otra función que recibe un objeto con dos propiedades: op (la Operation que está ejecutando el cliente) y next (la función para llamar al siguiente link en la cadena).

  3. La función del paso 2 retorna una función final que devuelve la función observable de @trpc/server. El observable recibe una función que obtiene un observer, el cual ayuda a nuestro link a notificar al siguiente link ascendente cómo debe manejar el resultado de la operación. En esta función, podemos simplemente retornar next(op) o suscribirnos a next, lo que permite a nuestro link manejar el resultado de la operación.

Ejemplo​

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;
    });
  };
};

Referencias​

Si necesitas referencias más prácticas para crear tu link personalizado, puedes revisar algunos links incorporados que tRPC proporciona en GitHub.

El link terminador es el último eslabón en la cadena de links. En lugar de llamar a la función next, el link terminador se encarga de enviar tu operación tRPC compuesta al servidor tRPC y retornar un OperationResultEnvelope.

El array links que añades a la configuración del cliente tRPC debe contener al menos un link, y ese link debe ser terminador. Si links no tiene un link terminador al final, la operación tRPC no se enviará al servidor.

httpBatchLink es el link terminador recomendado por tRPC.

httpLink, wsLink y localLink son otros ejemplos de links terminadores.

Gestión del contexto​

Cuando una operación avanza por tu cadena de links, mantiene un contexto que cada link puede leer y modificar. Esto permite que los links pasen metadatos a lo largo de la cadena que otros links usan en su lógica de ejecución.

Obtén y modifica el objeto de contexto actual accediendo a op.context.

Puedes establecer el valor inicial del objeto de contexto para una operación específica proporcionando el parámetro context al hook query o useQuery (o mutation, subscription, etc.).

Para un caso de uso de ejemplo, consulta Desactivar el procesamiento por lotes para ciertas solicitudes.