Aller au contenu principal
Version : 11.x

Définir des procédures

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 →

Une procédure est une fonction exposée au client, qui peut être de l'un des types suivants :

  • une Query - utilisée pour récupérer des données, généralement sans les modifier

  • une Mutation - utilisée pour envoyer des données, souvent pour créer/mettre à jour/supprimer

  • une Subscription - vous n'en aurez peut-être pas besoin, et nous avons une documentation dédiée

Les procédures dans tRPC sont des primitives très flexibles pour créer des fonctions backend. Elles utilisent un modèle de construction immuable, ce qui signifie que vous pouvez créer des procédures de base réutilisables partageant des fonctionnalités entre plusieurs procédures.

Écrire des procédures​

L'objet t créé lors de la configuration tRPC retourne une t.procedure initiale sur laquelle toutes les autres procédures sont construites :

ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
 
const t = initTRPC.context<{ signGuestBook: () => Promise<void> }>().create();
 
export const router = t.router;
export const publicProcedure = t.procedure;
 
const appRouter = router({
  // Queries are the best place to fetch data
  hello: publicProcedure.query(() => {
    return {
      message: 'hello world',
    };
  }),
 
  // Mutations are the best place to do things like updating a database
  goodbye: publicProcedure.mutation(async (opts) => {
    await opts.ctx.signGuestBook();
 
    return {
      message: 'goodbye!',
    };
  }),
});
ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
 
const t = initTRPC.context<{ signGuestBook: () => Promise<void> }>().create();
 
export const router = t.router;
export const publicProcedure = t.procedure;
 
const appRouter = router({
  // Queries are the best place to fetch data
  hello: publicProcedure.query(() => {
    return {
      message: 'hello world',
    };
  }),
 
  // Mutations are the best place to do things like updating a database
  goodbye: publicProcedure.mutation(async (opts) => {
    await opts.ctx.signGuestBook();
 
    return {
      message: 'goodbye!',
    };
  }),
});

Procédures de base réutilisables​

En règle générale, nous vous recommandons de renommer et d'exporter t.procedure en tant que publicProcedure, ce qui vous permet ensuite de créer d'autres procédures nommées pour des cas d'usage spécifiques et de les exporter également. Ce modèle appelé "procédures de base" est un mécanisme clé pour la réutilisation de code et de comportements dans tRPC ; presque toutes les applications en auront besoin.

Dans le code ci-dessous, nous utilisons des procédures de base réutilisables pour implémenter des cas courants dans notre application - nous créons une procédure de base pour les utilisateurs connectés (authedProcedure) et une autre qui prend un organizationId et valide qu'un utilisateur fait partie de cette organisation.

Ceci est un exemple simplifié ; en pratique vous voudrez probablement combiner Headers, Context, Middleware et Metadata pour authentifier et autoriser vos utilisateurs.

ts
import { initTRPC, TRPCError } from '@trpc/server';
import { z } from 'zod';
 
type Organization = {
  id: string;
  name: string;
};
type Membership = {
  role: 'ADMIN' | 'MEMBER';
  Organization: Organization;
};
type User = {
  id: string;
  memberships: Membership[];
};
type Context = {
  /**
   * User is nullable
   */
  user: User | null;
};
 
const t = initTRPC.context<Context>().create();
 
export const publicProcedure = t.procedure;
 
// procedure that asserts that the user is logged in
export const authedProcedure = t.procedure.use(async function isAuthed(opts) {
  const { ctx } = opts;
  // `ctx.user` is nullable
  if (!ctx.user) {
            
(property) user: User | null
    throw new TRPCError({ code: 'UNAUTHORIZED' });
  }
 
  return opts.next({
    ctx: {
      // ✅ user value is known to be non-null now
      user: ctx.user,
    },
  });
});
 
// procedure that a user is a member of a specific organization
export const organizationProcedure = authedProcedure
  .input(z.object({ organizationId: z.string() }))
  .use(function isMemberOfOrganization(opts) {
    const membership = opts.ctx.user.memberships.find(
      (m) => m.Organization.id === opts.input.organizationId,
    );
    if (!membership) {
      throw new TRPCError({
        code: 'FORBIDDEN',
      });
    }
    return opts.next({
      ctx: {
        Organization: membership.Organization,
      },
    });
  });
 
export const appRouter = t.router({
  whoami: authedProcedure.query(async (opts) => {
    // user is non-nullable here
    const { ctx } = opts;
            
const ctx: {
    user: User;
}
    return ctx.user;
  }),
  addMember: organizationProcedure
    .input(
      z.object({
        email: z.string().email(),
      }),
    )
    .mutation((opts) => {
      // ctx contains the non-nullable user & the organization being queried
      const { ctx } = opts;
              
const ctx: {
    user: User;
    Organization: Organization;
}
 
      // input includes the validated email of the user being invited & the validated organizationId
      const { input } = opts;
               
const input: {
    organizationId: string;
    email: string;
}
 
      return '...';
    }),
});
ts
import { initTRPC, TRPCError } from '@trpc/server';
import { z } from 'zod';
 
type Organization = {
  id: string;
  name: string;
};
type Membership = {
  role: 'ADMIN' | 'MEMBER';
  Organization: Organization;
};
type User = {
  id: string;
  memberships: Membership[];
};
type Context = {
  /**
   * User is nullable
   */
  user: User | null;
};
 
const t = initTRPC.context<Context>().create();
 
export const publicProcedure = t.procedure;
 
// procedure that asserts that the user is logged in
export const authedProcedure = t.procedure.use(async function isAuthed(opts) {
  const { ctx } = opts;
  // `ctx.user` is nullable
  if (!ctx.user) {
            
(property) user: User | null
    throw new TRPCError({ code: 'UNAUTHORIZED' });
  }
 
  return opts.next({
    ctx: {
      // ✅ user value is known to be non-null now
      user: ctx.user,
    },
  });
});
 
// procedure that a user is a member of a specific organization
export const organizationProcedure = authedProcedure
  .input(z.object({ organizationId: z.string() }))
  .use(function isMemberOfOrganization(opts) {
    const membership = opts.ctx.user.memberships.find(
      (m) => m.Organization.id === opts.input.organizationId,
    );
    if (!membership) {
      throw new TRPCError({
        code: 'FORBIDDEN',
      });
    }
    return opts.next({
      ctx: {
        Organization: membership.Organization,
      },
    });
  });
 
export const appRouter = t.router({
  whoami: authedProcedure.query(async (opts) => {
    // user is non-nullable here
    const { ctx } = opts;
            
const ctx: {
    user: User;
}
    return ctx.user;
  }),
  addMember: organizationProcedure
    .input(
      z.object({
        email: z.string().email(),
      }),
    )
    .mutation((opts) => {
      // ctx contains the non-nullable user & the organization being queried
      const { ctx } = opts;
              
const ctx: {
    user: User;
    Organization: Organization;
}
 
      // input includes the validated email of the user being invited & the validated organizationId
      const { input } = opts;
               
const input: {
    organizationId: string;
    email: string;
}
 
      return '...';
    }),
});

Inférer le type d'options d'une "procédure de base"​

En plus de pouvoir inférer les types d'entrée et de sortie d'une procédure, vous pouvez aussi inférer le type d'options d'un constructeur de procédure spécifique (ou procédure de base) en utilisant inferProcedureBuilderResolverOptions.

Cet utilitaire de typage est utile pour déclarer un type aux paramètres d'une fonction. Par exemple, pour séparer le handler d'exécution principal d'une procédure de sa définition dans le routeur, ou pour créer une fonction utilitaire fonctionnant avec plusieurs procédures.

ts
async function getMembersOfOrganization(
  opts: inferProcedureBuilderResolverOptions<typeof organizationProcedure>,
) {
  // input and ctx are now correctly typed!
  const { ctx, input } = opts;
 
  return await prisma.user.findMany({
    where: {
      membership: {
        organizationId: ctx.Organization.id,
      },
    },
  });
}
export const appRouter = t.router({
  listMembers: organizationProcedure.query(async (opts) => {
    // use helper function!
    const members = await getMembersOfOrganization(opts);
 
    return members;
  }),
});
ts
async function getMembersOfOrganization(
  opts: inferProcedureBuilderResolverOptions<typeof organizationProcedure>,
) {
  // input and ctx are now correctly typed!
  const { ctx, input } = opts;
 
  return await prisma.user.findMany({
    where: {
      membership: {
        organizationId: ctx.Organization.id,
      },
    },
  });
}
export const appRouter = t.router({
  listMembers: organizationProcedure.query(async (opts) => {
    // use helper function!
    const members = await getMembersOfOrganization(opts);
 
    return members;
  }),
});

Abonnements​

Pour les informations sur les abonnements, consultez notre guide dédié.