Versión: 11.x

Llamadas desde el servidor

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 →

Puede que necesites llamar a tus procedimientos directamente desde el mismo servidor donde están alojados. Para esto puedes usar createCallerFactory(). Esto es útil para llamadas desde el servidor y para pruebas de integración de tus procedimientos tRPC.

información

No debes usar createCaller para llamar procedimientos desde dentro de otros procedimientos. Esto genera sobrecarga al (potencialmente) crear contexto nuevamente, ejecutar todos los middlewares y validar el input, acciones que ya realizó el procedimiento actual. En su lugar, debes extraer la lógica compartida en una función separada y llamarla desde los procedimientos, así:

Crear un llamador

Con la función t.createCallerFactory puedes crear un llamador del lado del servidor para cualquier router. Primero llamas a createCallerFactory con el router que quieres llamar como argumento, luego esto devuelve una función donde puedes pasar un Context para las llamadas posteriores a procedimientos.

Ejemplo básico

Creamos el router con una query para listar posts y una mutación para agregar posts, y luego llamamos a cada método.

ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
 
type Context = {
  foo: string;
};
 
const t = initTRPC.context<Context>().create();
 
const publicProcedure = t.procedure;
const { createCallerFactory, router } = t;
 
interface Post {
  id: string;
  title: string;
}
const posts: Post[] = [
  {
    id: '1',
    title: 'Hello world',
  },
];
const appRouter = router({
  post: router({
    add: publicProcedure
      .input(
        z.object({
          title: z.string().min(2),
        }),
      )
      .mutation((opts) => {
        const post: Post = {
          ...opts.input,
          id: `${Math.random()}`,
        };
        posts.push(post);
        return post;
      }),
    list: publicProcedure.query(() => posts),
  }),
});
 
// 1. create a caller-function for your router
const createCaller = createCallerFactory(appRouter);
 
// 2. create a caller using your `Context`
const caller = createCaller({
  foo: 'bar',
});
 
// 3. use the caller to add and list posts
const addedPost = await caller.post.add({
  title: 'How to make server-side call in tRPC',
});
 
const postList = await caller.post.list();
         
const postList: Post[]

ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
 
type Context = {
  foo: string;
};
 
const t = initTRPC.context<Context>().create();
 
const publicProcedure = t.procedure;
const { createCallerFactory, router } = t;
 
interface Post {
  id: string;
  title: string;
}
const posts: Post[] = [
  {
    id: '1',
    title: 'Hello world',
  },
];
const appRouter = router({
  post: router({
    add: publicProcedure
      .input(
        z.object({
          title: z.string().min(2),
        }),
      )
      .mutation((opts) => {
        const post: Post = {
          ...opts.input,
          id: `${Math.random()}`,
        };
        posts.push(post);
        return post;
      }),
    list: publicProcedure.query(() => posts),
  }),
});
 
// 1. create a caller-function for your router
const createCaller = createCallerFactory(appRouter);
 
// 2. create a caller using your `Context`
const caller = createCaller({
  foo: 'bar',
});
 
// 3. use the caller to add and list posts
const addedPost = await caller.post.add({
  title: 'How to make server-side call in tRPC',
});
 
const postList = await caller.post.list();
         
const postList: Post[]

Ejemplo de uso en una prueba de integración

Tomado de https://github.com/trpc/examples-next-prisma-starter/blob/main/src/server/routers/post.test.ts

ts
async function testAddAndGetPost() {
  const ctx = await createContextInner({});
  const caller = createCaller(ctx);
 
  const input: inferProcedureInput<AppRouter['post']['add']> = {
    text: 'hello test',
    title: 'hello test',
  };
 
  const post = await caller.post.add(input);
  const byId = await caller.post.byId({ id: post.id });
}

ts
async function testAddAndGetPost() {
  const ctx = await createContextInner({});
  const caller = createCaller(ctx);
 
  const input: inferProcedureInput<AppRouter['post']['add']> = {
    text: 'hello test',
    title: 'hello test',
  };
 
  const post = await caller.post.add(input);
  const byId = await caller.post.byId({ id: post.id });
}

`router.createCaller()`

Con la función router.createCaller({}) (donde el primer argumento es Context) obtenemos una instancia de RouterCaller.

Ejemplo de query con input

Creamos el router con una query que recibe input, y luego llamamos al procedimiento asíncrono greeting para obtener el resultado.

ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
 
const t = initTRPC.create();
 
const router = t.router({
  // Create procedure at path 'greeting'
  greeting: t.procedure
    .input(z.object({ name: z.string() }))
    .query((opts) => `Hello ${opts.input.name}`),
});
 
const caller = router.createCaller({});
const result = await caller.greeting({ name: 'tRPC' });
        
const result: string

ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
 
const t = initTRPC.create();
 
const router = t.router({
  // Create procedure at path 'greeting'
  greeting: t.procedure
    .input(z.object({ name: z.string() }))
    .query((opts) => `Hello ${opts.input.name}`),
});
 
const caller = router.createCaller({});
const result = await caller.greeting({ name: 'tRPC' });
        
const result: string

Ejemplo de mutación

Creamos el router con una mutación, y luego llamamos al procedimiento asíncrono post para obtener el resultado.

ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
 
const posts = ['One', 'Two', 'Three'];
 
const t = initTRPC.create();
const router = t.router({
  post: t.router({
    add: t.procedure.input(z.string()).mutation((opts) => {
      posts.push(opts.input);
      return posts;
    }),
  }),
});
 
const caller = router.createCaller({});
const result = await caller.post.add('Four');
        
const result: string[]

ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
 
const posts = ['One', 'Two', 'Three'];
 
const t = initTRPC.create();
const router = t.router({
  post: t.router({
    add: t.procedure.input(z.string()).mutation((opts) => {
      posts.push(opts.input);
      return posts;
    }),
  }),
});
 
const caller = router.createCaller({});
const result = await caller.post.add('Four');
        
const result: string[]

Ejemplo de contexto con middleware

Creamos un middleware para verificar el contexto antes de ejecutar el procedimiento secret. A continuación se muestran dos ejemplos: el primero falla porque el contexto no cumple con la lógica del middleware, y el segundo funciona correctamente.

información

Los middlewares se ejecutan antes de que se llame a cualquier procedimiento.

ts
import { initTRPC, TRPCError } from '@trpc/server';
 
type Context = {
  user?: {
    id: string;
  };
};
const t = initTRPC.context<Context>().create();
 
const protectedProcedure = t.procedure.use((opts) => {
  const { ctx } = opts;
  if (!ctx.user) {
    throw new TRPCError({
      code: 'UNAUTHORIZED',
      message: 'You are not authorized',
    });
  }
 
  return opts.next({
    ctx: {
      // Infers that the `user` is non-nullable
      user: ctx.user,
    },
  });
});
 
const router = t.router({
  secret: protectedProcedure.query((opts) => opts.ctx.user),
});
 
{
  // ❌ this will return an error because there isn't the right context param
  const caller = router.createCaller({});
 
  const result = await caller.secret();
}
 
{
  // ✅ this will work because user property is present inside context param
  const authorizedCaller = router.createCaller({
    user: {
      id: 'KATT',
    },
  });
  const result = await authorizedCaller.secret();
          const result: {
    id: string;
}
}

ts
import { initTRPC, TRPCError } from '@trpc/server';
 
type Context = {
  user?: {
    id: string;
  };
};
const t = initTRPC.context<Context>().create();
 
const protectedProcedure = t.procedure.use((opts) => {
  const { ctx } = opts;
  if (!ctx.user) {
    throw new TRPCError({
      code: 'UNAUTHORIZED',
      message: 'You are not authorized',
    });
  }
 
  return opts.next({
    ctx: {
      // Infers that the `user` is non-nullable
      user: ctx.user,
    },
  });
});
 
const router = t.router({
  secret: protectedProcedure.query((opts) => opts.ctx.user),
});
 
{
  // ❌ this will return an error because there isn't the right context param
  const caller = router.createCaller({});
 
  const result = await caller.secret();
}
 
{
  // ✅ this will work because user property is present inside context param
  const authorizedCaller = router.createCaller({
    user: {
      id: 'KATT',
    },
  });
  const result = await authorizedCaller.secret();
          const result: {
    id: string;
}
}

Ejemplo para un endpoint API de Next.js

consejo

Este ejemplo muestra cómo usar el llamador en un endpoint API de Next.js. tRPC ya crea endpoints API por ti, así que este archivo solo pretende mostrar cómo llamar un procedimiento desde otro endpoint personalizado.

ts
type ResponseData = {
  data?: {
    postTitle: string;
  };
  error?: {
    message: string;
  };
};
 
export default async (
  req: NextApiRequest,
  res: NextApiResponse<ResponseData>,
) => {
  /** We want to simulate an error, so we pick a post ID that does not exist in the database. */
  const postId = `this-id-does-not-exist-${Math.random()}`;
 
  const caller = appRouter.createCaller({});
 
  try {
    // the server-side call
    const postResult = await caller.post.byId({ id: postId });
 
    res.status(200).json({ data: { postTitle: postResult.title } });
  } catch (cause) {
    // If this a tRPC error, we can extract additional information.
    if (cause instanceof TRPCError) {
      // We can get the specific HTTP status code coming from tRPC (e.g. 404 for `NOT_FOUND`).
      const httpStatusCode = getHTTPStatusCodeFromError(cause);
 
      res.status(httpStatusCode).json({ error: { message: cause.message } });
      return;
    }
 
    // This is not a tRPC error, so we don't have specific information.
    res.status(500).json({
      error: { message: `Error while accessing post with ID ${postId}` },
    });
  }
};

ts
type ResponseData = {
  data?: {
    postTitle: string;
  };
  error?: {
    message: string;
  };
};
 
export default async (
  req: NextApiRequest,
  res: NextApiResponse<ResponseData>,
) => {
  /** We want to simulate an error, so we pick a post ID that does not exist in the database. */
  const postId = `this-id-does-not-exist-${Math.random()}`;
 
  const caller = appRouter.createCaller({});
 
  try {
    // the server-side call
    const postResult = await caller.post.byId({ id: postId });
 
    res.status(200).json({ data: { postTitle: postResult.title } });
  } catch (cause) {
    // If this a tRPC error, we can extract additional information.
    if (cause instanceof TRPCError) {
      // We can get the specific HTTP status code coming from tRPC (e.g. 404 for `NOT_FOUND`).
      const httpStatusCode = getHTTPStatusCodeFromError(cause);
 
      res.status(httpStatusCode).json({ error: { message: cause.message } });
      return;
    }
 
    // This is not a tRPC error, so we don't have specific information.
    res.status(500).json({
      error: { message: `Error while accessing post with ID ${postId}` },
    });
  }
};

Manejo de errores

Las funciones createCallerFactory y createCaller pueden recibir un manejador de errores mediante la opción onError. Esto permite lanzar errores que no están envueltos en un TRPCError o responder a errores de otras maneras. Cualquier manejador pasado a createCallerFactory se ejecutará antes que el manejador pasado a createCaller. El manejador recibe los mismos argumentos que un formateador de errores, excepto por el campo shape:

ts
interface OnErrorShape {
  ctx: unknown;
  error: TRPCError;
  path: string | undefined;
  input: unknown;
  type: 'query' | 'mutation' | 'subscription' | 'unknown';
}

ts
interface OnErrorShape {
  ctx: unknown;
  error: TRPCError;
  path: string | undefined;
  input: unknown;
  type: 'query' | 'mutation' | 'subscription' | 'unknown';
}

ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
 
const t = initTRPC
  .context<{
    foo?: 'bar';
  }>()
  .create();
 
const router = t.router({
  greeting: t.procedure.input(z.object({ name: z.string() })).query((opts) => {
    if (opts.input.name === 'invalid') {
      throw new Error('Invalid name');
    }
 
    return `Hello ${opts.input.name}`;
  }),
});
 
const caller = router.createCaller(
  {
    /* context */
  },
  {
    onError: (opts) => {
      console.error('An error occurred:', opts.error);
    },
  },
);
 
// The following will log "An error occurred: Error: Invalid name", and then throw the error
await caller.greeting({ name: 'invalid' });

ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
 
const t = initTRPC
  .context<{
    foo?: 'bar';
  }>()
  .create();
 
const router = t.router({
  greeting: t.procedure.input(z.object({ name: z.string() })).query((opts) => {
    if (opts.input.name === 'invalid') {
      throw new Error('Invalid name');
    }
 
    return `Hello ${opts.input.name}`;
  }),
});
 
const caller = router.createCaller(
  {
    /* context */
  },
  {
    onError: (opts) => {
      console.error('An error occurred:', opts.error);
    },
  },
);
 
// The following will log "An error occurred: Error: Invalid name", and then throw the error
await caller.greeting({ name: 'invalid' });

Crear un llamador​

Ejemplo básico​

Ejemplo de uso en una prueba de integración​

router.createCaller()​

Ejemplo de query con input​

Ejemplo de mutación​

Ejemplo de contexto con middleware​

Ejemplo para un endpoint API de Next.js​

Manejo de errores​