Även om tRPC v11 länge varit produktionsredo via @next-taggen har vi fastnat i att lägga till nya funktioner utan att strikt hålla oss till semantisk versionering. Idag är vi glada att äntligen kunna dra av plåstret och meddela den officiella releasen av tRPC v11!

Sedan vårt senaste majorversionssläpp i november 2022 har tRPC-gemenskapen vuxit avsevärt:

• Vi har nu över 35 000 stjärnor på GitHub

• En Discord-gemenskap med mer än 5 000 medlemmar

• 700k+ veckovisa npm-nedladdningar

• Hundratals bidragsgivare

• Ett fantastiskt ekosystem av tillägg, exempel och innehåll

Med lanseringen av tRPC v11 är vi glada att dela med oss att v11 redan används i produktion av många stora TypeScript-projekt tack vare dess stabila utveckling på vår @next-kanal

För nya projekt kan du komma igång med ett exempelprogram för att lära dig om tRPC v11. För projekt som fortfarande kör tRPC v10 besök migrationsguiden för v11.

Översikt över förändringar​

v11 är till stor del bakåtkompatibel med v10, men den innehåller många nya funktioner och förbättringar. Här är höjdpunkterna:

Stöd för TanStack Query v5​

När TanStack Query v5 släpptes krävdes några brytande ändringar i tRPC:s react-query-integration. Detta har funnits tillgängligt ganska länge via @next-taggen, men nu är det officiellt släppt. Många projekt har redan valt att uppgradera och njuter av fullt React Suspense-stöd samt många andra förbättringar. För råd om att migrera din tRPC React-klientkod kan du följa TanStack Querys egen migrationsguide.

Ny TanStack React Query-integration​

Se blogginlägget

Stöd för FormData / icke-JSON-innehållstyper​

En av våra mest efterfrågade funktioner är möjligheten att skicka och ta emot mer än bara JSON-data. Med tRPC v11 kan du nu skicka och ta emot data i olika icke-JSON-innehållstyper, FormData, och binära typer som Blob, File och Uint8Array. Du hittar ett exempel på hur du använder dessa innehållstyper här

ts
import { publicProcedure, router } from './trpc';
import { octetInputParser } from '@trpc/server/http';
import { z } from 'zod';
 
const appRouter = router({
  formData: publicProcedure
    .input(z.instanceof(FormData))
    .mutation(async ({ input }) => {
                        
(parameter) input: FormData
    }),
  file: publicProcedure
    .input(octetInputParser)
    .mutation(async ({ input }) => {
                        
(parameter) input: ReadableStream<any>
    }),
});
Copy

ts
import { publicProcedure, router } from './trpc';
import { octetInputParser } from '@trpc/server/http';
import { z } from 'zod';
 
const appRouter = router({
  formData: publicProcedure
    .input(z.instanceof(FormData))
    .mutation(async ({ input }) => {
                        
(parameter) input: FormData
    }),
  file: publicProcedure
    .input(octetInputParser)
    .mutation(async ({ input }) => {
                        
(parameter) input: ReadableStream<any>
    }),
});
Copy

React Server Components / Next.js App Router​

Även om du kunnat använda tRPC med Next.js App Router sedan dag ett, antingen genom att:

• använda ett servercentrerat tillvägagångssätt med async/await via antingen createCaller eller createTRPCClient,

• eller ett klientcentrerat tillvägagångssätt med React Query-integrationen och klientsidohooks,

Bron mellan dessa två metoder har varit lite hackig. Valideringsmönster blir inkonsekventa när man måste hantera olika datahämtningsmetoder, vilket resulterar i en mindre optimal utvecklarupplevelse som inte lever upp till tRPC:s standard.

För att åtgärda detta har vi förbättrat stödet för React Server Components (RSC) och lagt till prefetch-hjälpmedel för att underlätta användandet av RSC:ers kraft som körs enbart på servern, i kombination med React Queries mycket dynamiska klientcache. Du kan nu köra en procedur på servern i en RSC, plocka upp det väntande löftet på klienten och automatiskt hydrera React Query-cachen på klientsidan. Detta gör att du kan bygga mycket dynamiska applikationer utan att drabbas av server-klient-vattenfall. Läs mer i vår dokumentation om Server Components.

Utöver dessa nya prefetch-mönster har vi lagt till experimentellt stöd för serverfunktioner. Du kan läsa mer om detta i vårt blogginlägg. Vi planerar att fortsätta iterera på denna funktion när serverfunktioner blir en mer etablerad metod i ekosystemet.

Vi har också samarbetat med TanStack-teamet för att hjälpa till att designa API:er för deras serverfunktioner. Vårt mål är att dela upp delar av tRPC:s kraftfulla mellanvarussystem i ett separat paket som kan användas i hela ekosystemet.

Strömmade svar från queries och mutationer​

Vi har introducerat httpBatchStreamLink som möjliggör strömmade svar från queries. Detta är användbart när du arbetar med stora dataset eller när du behöver bearbeta data i realtid och skicka dem till frontend under tiden. Detta är inte en ersättning för prenumerationer, utan ytterligare ett verktyg i din verktygslåda.

ts
// @filename: server.ts
import { publicProcedure, router } from './trpc';
 
const appRouter = router({
  examples: {
    iterable: publicProcedure.query(async function* () {
      let i = 0;
      while (true) {
        await new Promise((resolve) => setTimeout(resolve, 500));
        yield i++;
      }
    }),
  },
});
 
export type AppRouter = typeof appRouter;
 
 
// @filename: client.ts
import { createTRPCClient, httpBatchStreamLink } from '@trpc/client';
import type { AppRouter } from './server';
 
const trpc = createTRPCClient<AppRouter>({
  links: [
    httpBatchStreamLink({
      url: 'http://localhost:3000',
    }),
  ],
});
const iterable = await trpc.examples.iterable.query();
         
const iterable: AsyncIterable<number, never, unknown>
 
for await (const value of iterable) {
  console.log('Iterable:', value);
                            
const value: number
}
Copy

ts
// @filename: server.ts
import { publicProcedure, router } from './trpc';
 
const appRouter = router({
  examples: {
    iterable: publicProcedure.query(async function* () {
      let i = 0;
      while (true) {
        await new Promise((resolve) => setTimeout(resolve, 500));
        yield i++;
      }
    }),
  },
});
 
export type AppRouter = typeof appRouter;
 
 
// @filename: client.ts
import { createTRPCClient, httpBatchStreamLink } from '@trpc/client';
import type { AppRouter } from './server';
 
const trpc = createTRPCClient<AppRouter>({
  links: [
    httpBatchStreamLink({
      url: 'http://localhost:3000',
    }),
  ],
});
const iterable = await trpc.examples.iterable.query();
         
const iterable: AsyncIterable<number, never, unknown>
 
for await (const value of iterable) {
  console.log('Iterable:', value);
                            
const value: number
}
Copy

Förenklade routerdefinitioner​

Vi har infört en ny förkortad syntax för att definiera din router, vilket förenklar processen att skapa dina routes. Dokumentation

ts
const appRouter = router({
  // Shorthand plain object for creating a sub-router
  nested1: {
    proc: publicProcedure.query(() => '...'),
  },
  // Equivalent of:
  nested2: router({
    proc: publicProcedure.query(() => '...'),
  }),
});
Copy

ts
const appRouter = router({
  // Shorthand plain object for creating a sub-router
  nested1: {
    proc: publicProcedure.query(() => '...'),
  },
  // Equivalent of:
  nested2: router({
    proc: publicProcedure.query(() => '...'),
  }),
});
Copy

Prenumerationer: Server-Sent Events och andra förbättringar​

• tRPC v11 introducerar ett nytt sätt att hantera prenumerationer med Server-Sent Events (SSE). Detta är ett utmärkt sätt att hantera realtidsuppdateringar i din applikation utan behov av mer komplexa WebSockets. Vi rekommenderar att använda detta som första val framöver.

• Vi har lagt till stöd för JavaScript- generatorer i prenumerationer. Detta gör att du kan skriva mer komplexa prenumerationshanterare som kan leverera flera värden över tid och städa upp efter sig på ett mycket JS-nativt sätt.

• Prenumerationer stöder nu utvalidering vilket förbättrar typsäkerheten i dina prenumerationshanterare.

Adjö v9 .interop()-läge​

I tRPC v10 introducerade vi .interop()-läget för att ge en smidig migreringsväg för tRPC v9-användare. Med tRPC v11 har vi tagit bort .interop()-läget. Om du fortfarande använder .interop()-läget kan du följa v10-migreringsguiden för att slutföra din övergång till de API:er som används av dagens tRPC.

Migrera till v11​

Om du för närvarande använder tRPC v10 kan du följa migreringsguiden för att uppgradera till v11. Guiden täcker alla brytande ändringar och nya funktioner i v11.

Tack!​

Från hela tRPC Core Team - tack för att du använder och stöder tRPC.

slug: typescript-performance-lessons title: Lärdomar om TypeScript-prestanda vid omstrukturering för v10 authors: [sachinraja]​

• Följ @trpcio på Twitter.

• Gå med i vår Discord-community

• Testa tRPC direkt i webbläsaren

Vi är glada att meddela att den nya TanStack React Query-integrationen för tRPC nu finns tillgänglig i tRPC:s next-release. Jämfört med vår klassiska React Query-integration är den enklare och mer TanStack Query-inriktad genom att direkt använda de inbyggda gränssnitten QueryOptions och MutationOptions från TanStack React Query, istället för att wrappa useQuery och useMutation med vår egen klient.

greeting.tsx
tsx
import { useQuery } from '@tanstack/react-query';
import { useTRPC } from './trpc';
 
export function Greeting() {
  const trpc = useTRPC();
 
  const greetingQuery = useQuery(trpc.greeting.queryOptions({ name: 'Jerry' }));
 
  // greetingQuery.data === 'Hello Jerry'
 
  return null;
}
Copy

greeting.tsx
tsx
import { useQuery } from '@tanstack/react-query';
import { useTRPC } from './trpc';
 
export function Greeting() {
  const trpc = useTRPC();
 
  const greetingQuery = useQuery(trpc.greeting.queryOptions({ name: 'Jerry' }));
 
  // greetingQuery.data === 'Hello Jerry'
 
  return null;
}
Copy

Med denna nya klient tar vi bort ett abstraktionslager som ofta orsakar förvirring för nya användare, och erbjuder istället ett mer direkt sätt att arbeta med TanStack React Query som känns omedelbart bekant för de som följer TanStacks egna dokumentation. Det innebär också att vi behöver mindre tRPC-dokumentation för att förklara den, även om vi naturligtvis har dokumentation för att komma igång.

Varför denna förändring?​

Du kan läsa vår ursprungliga RFC för denna förändring här som går in på detaljer. Men några av våra huvudsakliga skäl är:

• Enkelhet: Den nya klienten är enklare och mer TanStack Query-inriktad genom att tillhandahålla fabriker för vanliga TanStack React Query-gränssnitt som QueryKeys, QueryOptions och MutationOptions. Detta minskar inlärningskurvan eftersom du kan följa den officiella TanStack Query-dokumentationen

• Bekanthet: Den nya klienten är mer bekant för de som redan använder TanStack Query, där du använder TanStack Query för andra arbetsbelastningar i din applikation utan att tvingas använda en alternativ syntax för tRPC

• React: Vår klassiska React Query-integration bryter faktiskt mot hooks-regler; den kan inte korrekt linteras och uppmuntrar vissa mönster som kommer att brytas under React Compiler, som att skicka hooks som props. I detta avseende är den nya klienten mer idiomatisk React

• Underhållbarhet: En utmaning vi haft med vår versionshantering är att hålla tRPC i takt med förändringar i TanStack Query, särskilt nya funktioner som tillförs QueryClient då och då. Genom att använda det minimala gränssnittet för native interfaces kan vi stödja React Query mycket enklare, samtidigt som vi följer vad TanStacks maintainers anser vara bästa praxis

• Feedback: Som vi nämnt orsakar den klassiska klienten ofta svårigheter för nya användare, men feedbacken vi fick på RFC:en för denna klient var överväldigande positiv, där majoriteten av användare som lämnade kommentarer eller meddelanden var entusiastiska över att använda denna klient. Naturligtvis är inte alla övertygade om klienten än, så vi kommer att behålla den klassiska klienten

Vad händer med den klassiska tRPC React Query-integrationen?​

Den försvinner inte på länge! Vi åtar oss att underhålla den länge framöver, men den kommer inte att få några betydande nya funktioner och vi kommer att betrakta den som stabil.

Vi rekommenderar fortfarande att nya projekt startar med den nya TanStack React Query-integrationen, och befintliga projekt bör överväga att migrera gradvis.

Hur migrerar jag?​

Även om den klassiska klienten kommer att underhållas länge framöver rekommenderar vi att nya projekt startar med den nya klienten och aktiva projekt överväger en gradvis migrering.

Båda klienterna är kompatibla med varandra och kan finnas i samma applikation, så du kan migrera i din egen takt. Vi arbetar också med en codemod där vi skulle älska bidrag från communityn. Vi vill tacka @reaper för hans bidrag till codemoden hittills!

👉 Läs migrationsdokumentationen

Byggarmönstret för att skapa procedurer som introducerades i tRPC v10 har fått stor uppskattning från communityt, och många bibliotek har antagit liknande mönster. Det har till och med myntats en term tRPC like XYZ som bevis på mönstrets ökande popularitet. För inte så länge sedan såg jag faktiskt någon som undrade om det fanns ett sätt att skriva CLI-applikationer med ett liknande API som tRPC. Sidnotering: du kan till och med använda tRPC direkt för detta. Men det är inte det vi ska prata om idag, vi ska diskutera hur man använder tRPC med server actions från Next.js.

Vad är en server action?​

Om du levt under en sten och inte hängt med i de senaste React- och Next.js-funktionerna: server actions låter dig skriva vanliga funktioner som körs på servern, importera dem på klienten och anropa dem precis som om de vore vanliga funktioner. Du kanske tycker att detta låter likt tRPC - och det stämmer. Enligt Dan Abramov är server actions "tRPC som en bundler-funktion":

Och detta är helt korrekt. Server actions liknar tRPC, i slutändan är de båda RPC:er. Båda låter dig skriva funktioner på backend och anropa dem med full typstyrning på frontend med nätverkslagret abstraherat bort.

Så var kommer tRPC in i bilden? Varför skulle jag behöva både tRPC och server actions? Server actions är en primitiv, och som alla primitiver är de ganska grundläggande och saknar därmed vissa fundamentala aspekter när det gäller att bygga API:er. För alla API-slutpunkter som exponeras över nätverket måste du validera och auktorisera förfrågningar för att säkerställa att ditt API inte missbrukas. Som tidigare nämnts uppskattas tRPC:s API av communityt, så vore det inte trevligt om vi kunde använda tRPC för att definiera server actions och utnyttja alla fantastiska funktioner som kommer inbyggda i tRPC? Tänk validering av indata, autentisering och auktorisering via middleware, validering av utdata, datatransformatorer, etc. Jag tycker det, så låt oss gräva djupare.

Definiera server actions med tRPC​

npm install @trpc/serverKopiera

yarn add @trpc/serverKopiera

pnpm add @trpc/serverKopiera

bun add @trpc/serverKopiera

deno add npm:@trpc/serverKopiera

Låt oss börja med att initiera tRPC och definiera vår basprocedur för server actions. Vi kommer använda metoden experimental_caller i procedure-builder:en, en ny metod som låter dig anpassa hur proceduren anropas när den invokeras som en funktion. Vi kommer också använda adapter:en experimental_nextAppDirCaller för att göra den kompatibel med Next.js. Denna adapter hanterar fall där server action:en är inlindad i useActionState på klienten, vilket ändrar anropssignaturen för server action:en.

Vi kommer också använda en span-egenskap som metadata, eftersom det inte finns någon vanlig sökväg som när du använder en router (t.ex. user.byId). Du kan använda span-egenskapen för att skilja mellan procedurer, till exempel vid loggning eller observabilitet.

server/trpc.ts
ts
import { initTRPC, TRPCError } from '@trpc/server';
import { experimental_nextAppDirCaller } from '@trpc/server/adapters/next-app-dir';
 
interface Meta {
  span: string;
}
 
export const t = initTRPC.meta<Meta>().create();
 
const serverActionProcedure = t.procedure.experimental_caller(
  experimental_nextAppDirCaller({
    pathExtractor: ({ meta }) => (meta as Meta).span,
  }),
);
Copy

server/trpc.ts
ts
import { initTRPC, TRPCError } from '@trpc/server';
import { experimental_nextAppDirCaller } from '@trpc/server/adapters/next-app-dir';
 
interface Meta {
  span: string;
}
 
export const t = initTRPC.meta<Meta>().create();
 
const serverActionProcedure = t.procedure.experimental_caller(
  experimental_nextAppDirCaller({
    pathExtractor: ({ meta }) => (meta as Meta).span,
  }),
);
Copy

Därefter lägger vi till kontext. Eftersom vi inte kommer hosta en router med en vanlig HTTP-adapter kommer vi inte få någon kontext injicerad genom createContext-metoden på adapter:en. Istället använder vi en middleware för att injicera vår kontext. I detta exempel hämtar vi den aktuella användaren från sessionen och injicerar den i kontexten.

server/trpc.ts
ts
import { initTRPC, TRPCError } from '@trpc/server';
import { experimental_nextAppDirCaller } from '@trpc/server/adapters/next-app-dir';
import { currentUser } from './auth';
 
interface Meta {
  span: string;
}
 
export const t = initTRPC.meta<Meta>().create();
 
export const serverActionProcedure = t.procedure
  .experimental_caller(
    experimental_nextAppDirCaller({
      pathExtractor: ({ meta }) => (meta as Meta).span,
    }),
  )
  .use(async (opts) => {
    // Inject user into context
    const user = await currentUser();
    return opts.next({ ctx: { user } });
  });
Copy

server/trpc.ts
ts
import { initTRPC, TRPCError } from '@trpc/server';
import { experimental_nextAppDirCaller } from '@trpc/server/adapters/next-app-dir';
import { currentUser } from './auth';
 
interface Meta {
  span: string;
}
 
export const t = initTRPC.meta<Meta>().create();
 
export const serverActionProcedure = t.procedure
  .experimental_caller(
    experimental_nextAppDirCaller({
      pathExtractor: ({ meta }) => (meta as Meta).span,
    }),
  )
  .use(async (opts) => {
    // Inject user into context
    const user = await currentUser();
    return opts.next({ ctx: { user } });
  });
Copy

Slutligen skapar vi en protectedAction-procedur som skyddar alla åtgärder från oautentiserade användare. Om du redan har en middleware som gör detta kan du använda den, men jag definierar en inline i det här exemplet.

server/trpc.ts
ts
import { initTRPC, TRPCError } from '@trpc/server';
import { experimental_nextAppDirCaller } from '@trpc/server/adapters/next-app-dir';
import { currentUser } from './auth';
 
interface Meta {
  span: string;
}
 
export const t = initTRPC.meta<Meta>().create();
 
export const serverActionProcedure = t.procedure
  .experimental_caller(
    experimental_nextAppDirCaller({
      pathExtractor: ({ meta }) => (meta as Meta).span,
    }),
  )
  .use(async (opts) => {
    // Inject user into context
    const user = await currentUser();
           
const user: User | null
    return opts.next({ ctx: { user } });
  });
 
export const protectedAction = serverActionProcedure.use((opts) => {
  if (!opts.ctx.user) {
    throw new TRPCError({
      code: 'UNAUTHORIZED',
    });
  }
 
  return opts.next({
    ctx: {
      ...opts.ctx,
      user: opts.ctx.user, // <-- ensures type is non-nullable
       
(property) user: User
    },
  });
});
Copy

server/trpc.ts
ts
import { initTRPC, TRPCError } from '@trpc/server';
import { experimental_nextAppDirCaller } from '@trpc/server/adapters/next-app-dir';
import { currentUser } from './auth';
 
interface Meta {
  span: string;
}
 
export const t = initTRPC.meta<Meta>().create();
 
export const serverActionProcedure = t.procedure
  .experimental_caller(
    experimental_nextAppDirCaller({
      pathExtractor: ({ meta }) => (meta as Meta).span,
    }),
  )
  .use(async (opts) => {
    // Inject user into context
    const user = await currentUser();
           
const user: User | null
    return opts.next({ ctx: { user } });
  });
 
export const protectedAction = serverActionProcedure.use((opts) => {
  if (!opts.ctx.user) {
    throw new TRPCError({
      code: 'UNAUTHORIZED',
    });
  }
 
  return opts.next({
    ctx: {
      ...opts.ctx,
      user: opts.ctx.user, // <-- ensures type is non-nullable
       
(property) user: User
    },
  });
});
Copy

Okej, låt oss skriva en riktig serveråtgärd. Skapa en _actions.ts-fil, dekorera den med direktivet "use server", och definiera din åtgärd.

app/_actions.ts
ts
'use server';
 
import { z } from 'zod';
import { protectedAction } from '../server/trpc';
 
export const createPost = protectedAction
  .input(
    z.object({
      title: z.string(),
    }),
  )
  .mutation(async (opts) => {
    // Do something with the input
  });
 
// Since we're using the `experimental_caller`,
// our procedure is now just an ordinary function:
createPost;
    
const createPost: (input: {
    title: string;
}) => Promise<void>
Copy

app/_actions.ts
ts
'use server';
 
import { z } from 'zod';
import { protectedAction } from '../server/trpc';
 
export const createPost = protectedAction
  .input(
    z.object({
      title: z.string(),
    }),
  )
  .mutation(async (opts) => {
    // Do something with the input
  });
 
// Since we're using the `experimental_caller`,
// our procedure is now just an ordinary function:
createPost;
    
const createPost: (input: {
    title: string;
}) => Promise<void>
Copy

Wow, så enkelt är det att definiera en serveråtgärd som är skyddad från oautentiserade användare, med indatavalidering för att skydda mot attacker som SQL-injektioner. Låt oss importera den här funktionen på klienten och anropa den.

app/post-form.tsx
tsx
'use client';
import { createPost } from './_actions';
export function PostForm() {
  return (
    <form
      // Use `action` to make form progressively enhanced
      action={createPost}
      // `Using `onSubmit` allows building rich interactive
      // forms once JavaScript has loaded
      onSubmit={async (e) => {
        e.preventDefault();
        const title = new FormData(e.currentTarget).get('title') as string;
        // Maybe show loading toast, etc etc. Endless possibilities
        await createPost({ title });
      }}
    >
      <input type="text" name="title" />
      <button type="submit">Create Post</button>
    </form>
  );
}
Copy

app/post-form.tsx
tsx
'use client';
import { createPost } from './_actions';
export function PostForm() {
  return (
    <form
      // Use `action` to make form progressively enhanced
      action={createPost}
      // `Using `onSubmit` allows building rich interactive
      // forms once JavaScript has loaded
      onSubmit={async (e) => {
        e.preventDefault();
        const title = new FormData(e.currentTarget).get('title') as string;
        // Maybe show loading toast, etc etc. Endless possibilities
        await createPost({ title });
      }}
    >
      <input type="text" name="title" />
      <button type="submit">Create Post</button>
    </form>
  );
}
Copy

Vidareutveckling​

Genom att använda tRPC:s byggstenar och dess komponerbara sätt att definiera återanvändbara procedurer kan vi enkelt skapa mer komplexa serveråtgärder. Här är några exempel:

Observabilitet​

Du kan använda @baselime/node-opentelemtry:s tRPC-plugin för att lägga till observabilitet med bara några rader kod:

diff
--- server/trpc.ts
+++ server/trpc.ts
+ import { tracing } from '@baselime/node-opentelemetry/trpc';
  export const serverActionProcedure = t.procedure
    .experimental_caller(
      experimental_nextAppDirCaller({
        pathExtractor: (meta: Meta) => meta.span,
      }),
    )
    .use(async (opts) => {
      // Inject user into context
      const user = await currentUser();
      return opts.next({ ctx: { user } });
    })
+  .use(tracing());
--- app/_actions.ts
+++ app/_actions.ts
  export const createPost = protectedAction
+   .meta({ span: 'create-post' })
    .input(
      z.object({
        title: z.string(),
      }),
    )
    .mutation(async (opts) => {
      // Do something with the input
    });
Copy

diff
--- server/trpc.ts
+++ server/trpc.ts
+ import { tracing } from '@baselime/node-opentelemetry/trpc';
  export const serverActionProcedure = t.procedure
    .experimental_caller(
      experimental_nextAppDirCaller({
        pathExtractor: (meta: Meta) => meta.span,
      }),
    )
    .use(async (opts) => {
      // Inject user into context
      const user = await currentUser();
      return opts.next({ ctx: { user } });
    })
+  .use(tracing());
--- app/_actions.ts
+++ app/_actions.ts
  export const createPost = protectedAction
+   .meta({ span: 'create-post' })
    .input(
      z.object({
        title: z.string(),
      }),
    )
    .mutation(async (opts) => {
      // Do something with the input
    });
Copy

Kolla in Baselimes tRPC-integrering för mer information. Liknande mönster bör fungera oavsett vilken observabilitetsplattform du använder.

Begränsning av anrop (Rate Limiting)​

Du kan använda en tjänst som Unkey för att begränsa antalet anrop till dina serveråtgärder. Här är ett exempel på en skyddad serveråtgärd som använder Unkey för att begränsa antalet förfrågningar per användare:

server/trpc.ts
ts
import { Ratelimit } from '@unkey/ratelimit';
 
export const rateLimitedAction = protectedAction.use(async (opts) => {
  const unkey = new Ratelimit({
    rootKey: process.env.UNKEY_ROOT_KEY!,
    async: true,
    duration: '10s',
    limit: 5,
    namespace: `trpc_${opts.path}`,
  });
 
  const ratelimit = await unkey.limit(opts.ctx.user.id);
  if (!ratelimit.success) {
    throw new TRPCError({
      code: 'TOO_MANY_REQUESTS',
      message: JSON.stringify(ratelimit),
    });
  }
 
  return opts.next();
});
Copy

server/trpc.ts
ts
import { Ratelimit } from '@unkey/ratelimit';
 
export const rateLimitedAction = protectedAction.use(async (opts) => {
  const unkey = new Ratelimit({
    rootKey: process.env.UNKEY_ROOT_KEY!,
    async: true,
    duration: '10s',
    limit: 5,
    namespace: `trpc_${opts.path}`,
  });
 
  const ratelimit = await unkey.limit(opts.ctx.user.id);
  if (!ratelimit.success) {
    throw new TRPCError({
      code: 'TOO_MANY_REQUESTS',
      message: JSON.stringify(ratelimit),
    });
  }
 
  return opts.next();
});
Copy

app/_actions.ts
ts
'use server';
 
import { z } from 'zod';
import { rateLimitedAction } from '../server/trpc';
 
export const commentOnPost = rateLimitedAction
  .input(
    z.object({
      postId: z.string(),
      content: z.string(),
    }),
  )
  .mutation(async (opts) => {
    console.log(
      `${opts.ctx.user.name} commented on ${opts.input.postId} saying ${opts.input.content}`,
    );
  });
Copy

app/_actions.ts
ts
'use server';
 
import { z } from 'zod';
import { rateLimitedAction } from '../server/trpc';
 
export const commentOnPost = rateLimitedAction
  .input(
    z.object({
      postId: z.string(),
      content: z.string(),
    }),
  )
  .mutation(async (opts) => {
    console.log(
      `${opts.ctx.user.name} commented on ${opts.input.postId} saying ${opts.input.content}`,
    );
  });
Copy

Läs mer om att begränsa anrop till dina tRPC-procedurer i det här inlägget från Unkey.

Möjligheterna är oändliga, och jag slår vad om att du redan har en massa bra verktygsmiddlewares som du använder i dina tRPC-applikationer idag. Om inte, kanske du hittar några du kan npm installa!

Avslutningsvis​

Serveråtgärder är inget silverkul. I situationer som kräver mer dynamisk data kanske du vill behålla din data i React Queries klient-sidcache och göra mutationer med useMutation istället. Det är helt legitimt. Dessa nya primitiv bör också vara lätta att adoptera gradvis, så du kan flytta individuella procedurer från din befintliga tRPC-API till serveråtgärder där det är meningsfullt. Det finns inget behov av att skriva om hela ditt API.

Genom att definiera dina serveråtgärder med tRPC kan du återanvända mycket av samma logik du använder idag och välja var du exponerar mutationen som en serveråtgärd eller som en mer traditionell mutation. Du som utvecklare har makten att välja vilka mönster som fungerar bäst för din applikation. Om du inte använder tRPC idag finns det några paket (next-safe-action och zsa kommer att tänka på) som låter dig definiera typsäkra, indatavaliderade serveråtgärder som också är värda att kolla in.

Om du vill se en app som använder detta i praktiken, kolla in Trellix tRPC, en app jag nyligen gjorde som utnyttjar dessa nya primitiv.

Vad tycker du? Vi vill ha din feedback​

Så, vad tycker du? Berätta för oss på Github och hjälp oss att iterera för att få dessa primitiv till ett stabilt tillstånd.

Det finns fortfarande arbete kvar, särskilt när det gäller felhantering. Next.js förespråkar att returnera fel, och vi vill göra detta så typsäkert som möjligt. Kolla in denna pågående PR av Alex för tidigt arbete på detta.

Tills nästa gång, lycka till med kodandet!

Har du någonsin undrat hur tRPC fungerar? Kanske du vill börja bidra till projektet men är skrämd av internals? Syftet med detta inlägg är att bekanta dig med tRPC:s interna delar genom att bygga en minimal klient som täcker de stora delarna av hur tRPC fungerar.

Översikt​

Låt oss anta att vi har en enkel tRPC-router med tre procedurer som ser ut så här:

ts
type Post = { id: string; title: string };
const posts: Post[] = [];
 
const appRouter = router({
  post: router({
    byId: publicProcedure
      .input(z.object({ id: z.string() }))
      .query(({ input }) => {
        const post = posts.find((p) => p.id === input.id);
        if (!post) throw new TRPCError({ code: "NOT_FOUND" });
        return post;
      }),
    byTitle: publicProcedure
      .input(z.object({ title: z.string() }))
      .query(({ input }) => {
        const post = posts.find((p) => p.title === input.title);
        if (!post) throw new TRPCError({ code: "NOT_FOUND" });
        return post;
      }),
    create: publicProcedure
      .input(z.object({ title: z.string() }))
      .mutation(({ input }) => {
        const post = { id: uuid(), ...input };
        posts.push(post);
        return post;
      }),
  }),
});
Copy

ts
type Post = { id: string; title: string };
const posts: Post[] = [];
 
const appRouter = router({
  post: router({
    byId: publicProcedure
      .input(z.object({ id: z.string() }))
      .query(({ input }) => {
        const post = posts.find((p) => p.id === input.id);
        if (!post) throw new TRPCError({ code: "NOT_FOUND" });
        return post;
      }),
    byTitle: publicProcedure
      .input(z.object({ title: z.string() }))
      .query(({ input }) => {
        const post = posts.find((p) => p.title === input.title);
        if (!post) throw new TRPCError({ code: "NOT_FOUND" });
        return post;
      }),
    create: publicProcedure
      .input(z.object({ title: z.string() }))
      .mutation(({ input }) => {
        const post = { id: uuid(), ...input };
        posts.push(post);
        return post;
      }),
  }),
});
Copy

Målet med vår klient är att efterlikna denna objektstruktur på klientsidan så att vi kan anropa procedurer så här:

ts
const post1 = await client.post.byId.query({ id: '123' });
const post2 = await client.post.byTitle.query({ title: 'Hello world' });
const newPost = await client.post.create.mutate({ title: 'Foo' });
Copy

ts
const post1 = await client.post.byId.query({ id: '123' });
const post2 = await client.post.byTitle.query({ title: 'Hello world' });
const newPost = await client.post.create.mutate({ title: 'Foo' });
Copy

För att uppnå detta använder tRPC en kombination av Proxy-objekt och TypeScript-magik för att utöka objektstrukturen med .query och .mutate-metoderna - vilket innebär att vi faktiskt LJUGR för dig om vad du gör (mer om detta senare) för att ge en fantastisk utvecklarupplevelse!

På en hög nivå vill vi mappa post.byId.query() till en GET-förfrågan till vår server, och post.create.mutate() till en POST-förfrågan, samtidigt som typerna propageras från backend till frontend. Så, hur gör vi detta?

Implementera en minimal tRPC-klient​

🧙‍♀️ TypeScript-magirin​

Låt oss börja med den roliga TypeScript-magirin för att låsa upp den fantastiska autofyllningen och typsäkerheten vi alla känner och älskar från att använda tRPC.

Vi behöver använda rekursiva typer för att kunna inferera godtyckligt djupa routerstrukturer. Vi vet också att vi vill att våra procedurer post.byId och post.create ska ha .query respektive .mutate-metoder - i tRPC kallar vi detta för att dekorera procedurerna. I @trpc/server har vi några inferenshjälpare som infererar input- och outputtyper för våra procedurer med dessa metoder, vilket vi kommer använda för att inferera typerna för dessa funktioner - så låt oss skriva lite kod!

Låt oss överväga vad vi vill uppnå för att tillhandahålla autofyllning av sökvägar samt inferens av procedurernas input- och outputtyper:

• Om vi befinner oss på en router vill vi kunna komma åt dess underrouter och procedurer (vi återkommer till detta strax)

• Om vi befinner oss på en query-procedure vill vi kunna anropa .query på den

• Om vi befinner oss på en mutation-procedure vill vi kunna anropa .mutate på den

• Om vi försöker komma åt något annat vill vi få ett typfel som indikerar att proceduren inte finns på servern

Så låt oss skapa en typ som gör detta åt oss:

ts
type DecorateProcedure<TProcedure> = TProcedure extends AnyTRPCQueryProcedure
  ? {
      query: Resolver<TProcedure>;
    }
  : TProcedure extends AnyTRPCMutationProcedure
  ? {
      mutate: Resolver<TProcedure>;
    }
  : never;
Copy

ts
type DecorateProcedure<TProcedure> = TProcedure extends AnyTRPCQueryProcedure
  ? {
      query: Resolver<TProcedure>;
    }
  : TProcedure extends AnyTRPCMutationProcedure
  ? {
      mutate: Resolver<TProcedure>;
    }
  : never;
Copy

Vi kommer använda några av tRPC:s inbyggda inferenshjälpare för att inferera input- och outputtyperna för våra procedurer när vi definierar Resolver-typen.

ts
import type {
  AnyTRPCProcedure,
  inferProcedureInput,
  inferProcedureOutput,
  AnyTRPCQueryProcedure,
  AnyTRPCMutationProcedure
} from '@trpc/server';
 
 
 
type Resolver<TProcedure extends AnyTRPCProcedure> = (
  input: inferProcedureInput<TProcedure>,
) => Promise<inferProcedureOutput<TProcedure>>;
 
Copy

ts
import type {
  AnyTRPCProcedure,
  inferProcedureInput,
  inferProcedureOutput,
  AnyTRPCQueryProcedure,
  AnyTRPCMutationProcedure
} from '@trpc/server';
 
 
 
type Resolver<TProcedure extends AnyTRPCProcedure> = (
  input: inferProcedureInput<TProcedure>,
) => Promise<inferProcedureOutput<TProcedure>>;
 
Copy

Låt oss testa detta på vår post.byId-procedure:

ts
type PostById = Resolver<AppRouter['post']['byId']>;
        
type PostById = (input: {
    id: string;
}) => Promise<Post>
Copy

ts
type PostById = Resolver<AppRouter['post']['byId']>;
        
type PostById = (input: {
    id: string;
}) => Promise<Post>
Copy

Bra, det är precis vad vi förväntade oss - vi kan nu anropa .query på vår procedure och få korrekta infererade input- och outputtyper!

Slutligen skapar vi en typ som rekursivt traverserar routern och dekorera alla procedurer längs vägen:

ts
import type { TRPCRouterRecord } from "@trpc/server";
import type { AnyTRPCRouter } from "@trpc/server";
 
type DecorateRouterRecord<TRecord extends TRPCRouterRecord> = {
  [TKey in keyof TRecord]: TRecord[TKey] extends infer $Value
    ? $Value extends TRPCRouterRecord
      ? DecorateRouterRecord<$Value>
      : $Value extends AnyTRPCProcedure
      ? DecorateProcedure<$Value>
      : never
    : never;
};
Copy

ts
import type { TRPCRouterRecord } from "@trpc/server";
import type { AnyTRPCRouter } from "@trpc/server";
 
type DecorateRouterRecord<TRecord extends TRPCRouterRecord> = {
  [TKey in keyof TRecord]: TRecord[TKey] extends infer $Value
    ? $Value extends TRPCRouterRecord
      ? DecorateRouterRecord<$Value>
      : $Value extends AnyTRPCProcedure
      ? DecorateProcedure<$Value>
      : never
    : never;
};
Copy

Låt oss bryta ned denna typ lite:

1. Vi skickar in en TRPCRouterRecord till typen som en generic, vilket är en typ som innehåller alla procedurer och underrouter som finns på en tRPC-router.

2. Vi itererar över nycklarna i record-objektet, som är procedur- eller router-namn, och gör följande:

   • Om nyckeln pekar på en router, anropar vi typen rekursivt på den routerns procedur-record, vilket kommer att dekorera alla procedurer i den routern. Detta ger autofyllning när vi navigerar genom sökvägen.
   • Om nyckeln pekar på en procedur, dekorerar vi proceduren med DecorateProcedure-typen vi skapade tidigare.
   • Om nyckeln inte pekar på en procedur eller router, tilldelar vi never-typen vilket i praktiken betyder "denna nyckel existerar inte" och ger ett typfel om vi försöker komma åt den.

🤯 Proxy-omvandlingen​

Nu när vi har alla typer på plats måste vi implementera funktionaliteten som omvandlar serverns router-definition på klienten så att vi kan anropa procedurer som vanliga funktioner.

Vi börjar med att skapa en hjälpfunktion för rekursiva proxies - createRecursiveProxy:

ts
interface ProxyCallbackOptions {
  path: readonly string[];
  args: readonly unknown[];
}
 
type ProxyCallback = (opts: ProxyCallbackOptions) => unknown;
 
function createRecursiveProxy(callback: ProxyCallback, path: readonly string[]) {
  const proxy: unknown = new Proxy(
    () => {
      // dummy no-op function since we don't have any
      // client-side target we want to remap to
    },
    {
      get(_obj, key) {
        if (typeof key !== 'string') return undefined;
 
        // Recursively compose the full path until a function is invoked
        return createRecursiveProxy(callback, [...path, key]);
      },
      apply(_1, _2, args) {
        // Call the callback function with the entire path we
        // recursively created and forward the arguments
        return callback({
          path,
          args,
        });
      },
    },
  );
 
  return proxy;
}
Copy

ts
interface ProxyCallbackOptions {
  path: readonly string[];
  args: readonly unknown[];
}
 
type ProxyCallback = (opts: ProxyCallbackOptions) => unknown;
 
function createRecursiveProxy(callback: ProxyCallback, path: readonly string[]) {
  const proxy: unknown = new Proxy(
    () => {
      // dummy no-op function since we don't have any
      // client-side target we want to remap to
    },
    {
      get(_obj, key) {
        if (typeof key !== 'string') return undefined;
 
        // Recursively compose the full path until a function is invoked
        return createRecursiveProxy(callback, [...path, key]);
      },
      apply(_1, _2, args) {
        // Call the callback function with the entire path we
        // recursively created and forward the arguments
        return callback({
          path,
          args,
        });
      },
    },
  );
 
  return proxy;
}
Copy

Det här ser lite magiskt ut, vad gör den egentligen?

• get-metoden hanterar egenskapsåtkomst som t.ex. post.byId. Nyckeln är egenskapens namn vi kommer åt, så när vi skriver post blir vår key post, och när vi skriver post.byId blir vår key byId. Den rekursiva proxyn kombinerar alla dessa nycklar till en slutlig sökväg, t.ex. ["post", "byId", "query"], som vi kan använda för att bestämma vilken URL vi ska skicka vår förfrågan till.

• apply-metoden anropas när vi exekverar en funktion på proxyn, som t.ex. .query(args). args är argumenten vi skickar till funktionen, så när vi anropar post.byId.query(args) kommer vårt args att vara vårt input som vi skickar som query-parametrar eller request body beroende på procedurtyp. createRecursiveProxy tar emot en callback-funktion som vi mappar apply till med sökvägen och argumenten.

Här är en visuell representation av hur proxyn fungerar vid anropet trpc.post.byId.query({ id: 1 }):

🧩 Sätt ihop allt​

Nu när vi har denna hjälpfunktion och vet vad den gör, låt oss använda den för att skapa vår klient. Vi ger createRecursiveProxy en callback som tar emot sökvägen och argumenten och skickar en förfrågan till servern med fetch. Vi lägger till en generisk typ på funktionen som accepterar vilken tRPC-router som helst (AnyTRPCRouter), och sedan castar vi returtypen till DecorateRouterRecord-typen vi skapade tidigare:

ts
import { TRPCResponse } from '@trpc/server/rpc';
 
export const createTinyRPCClient = <TRouter extends AnyTRPCRouter>(
  baseUrl: string,
) =>
  createRecursiveProxy(async (opts) => {
    const path = [...opts.path]; // e.g. ["post", "byId", "query"]
    const method = path.pop()! as 'query' | 'mutate';
    const dotPath = path.join('.'); // "post.byId" - this is the path procedures have on the backend
    let uri = `${baseUrl}/${dotPath}`;
 
    const [input] = opts.args;
    const stringifiedInput = input !== undefined && JSON.stringify(input);
    let body: undefined | string = undefined;
    if (stringifiedInput !== false) {
      if (method === 'query') {
        uri += `?input=${encodeURIComponent(stringifiedInput)}`;
      } else {
        body = stringifiedInput;
      }
    }
 
    const json: TRPCResponse = await fetch(uri, {
      method: method === 'query' ? 'GET' : 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body,
    }).then((res) => res.json());
 
    if ('error' in json) {
      throw new Error(`Error: ${json.error.message}`);
    }
    // No error - all good. Return the data.
    return json.result.data;
  }, []) as DecorateRouterRecord<TRouter['_def']['record']>;
//   ^? provide empty array as path to begin with
Copy

ts
import { TRPCResponse } from '@trpc/server/rpc';
 
export const createTinyRPCClient = <TRouter extends AnyTRPCRouter>(
  baseUrl: string,
) =>
  createRecursiveProxy(async (opts) => {
    const path = [...opts.path]; // e.g. ["post", "byId", "query"]
    const method = path.pop()! as 'query' | 'mutate';
    const dotPath = path.join('.'); // "post.byId" - this is the path procedures have on the backend
    let uri = `${baseUrl}/${dotPath}`;
 
    const [input] = opts.args;
    const stringifiedInput = input !== undefined && JSON.stringify(input);
    let body: undefined | string = undefined;
    if (stringifiedInput !== false) {
      if (method === 'query') {
        uri += `?input=${encodeURIComponent(stringifiedInput)}`;
      } else {
        body = stringifiedInput;
      }
    }
 
    const json: TRPCResponse = await fetch(uri, {
      method: method === 'query' ? 'GET' : 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body,
    }).then((res) => res.json());
 
    if ('error' in json) {
      throw new Error(`Error: ${json.error.message}`);
    }
    // No error - all good. Return the data.
    return json.result.data;
  }, []) as DecorateRouterRecord<TRouter['_def']['record']>;
//   ^? provide empty array as path to begin with
Copy

Det viktigaste här är att vår sökväg är separerad med . istället för /. Detta låter oss ha en enda API-hanterare på servern som behandlar alla förfrågningar, istället för en per procedur. Om du använder ett ramverk med filbaserad routing som Next.js, känner du igen catchall-filen /api/trpc/[trpc].ts som matchar alla procedursökvägar.

Vi har också en TRPCResponse-typannotering på fetch-förfrågan. Den definierar det JSONRPC-kompatibla svarsformat som servern returnerar. Du kan läsa mer om det här. TL;DR: vi får tillbaka antingen ett result eller ett error-objekt som vi kan använda för att avgöra om förfrågan lyckades eller inte och hantera eventuella fel på lämpligt sätt.

Och det var allt! Detta är all kod du behöver för att anropa dina tRPC-procedurer på klienten som om de vore lokala funktioner. På ytan ser det ut som att vi bara anropar publicProcedure.query / mutation's resolver-funktion via normal egenskapsåtkomst, men i verkligheten korsar vi ett nätverksgräns så att vi kan använda serverbibliotek som Prisma utan att läcka databasuppgifter.

Testa det själv!​

Skapa nu klienten och ange din servers URL – du får fullständig autofyllning och typsäkerhet när du anropar dina procedurer!

ts
const url = 'http://localhost:3000/api/trpc';
const client = createTinyRPCClient<AppRouter>(url);
// 🧙‍♀️ magic autocompletion
client.post.b;
// 👀 fully typesafe
const post = await client.post.byId.query({ id: '123' });
Copy

ts
const url = 'http://localhost:3000/api/trpc';
const client = createTinyRPCClient<AppRouter>(url);
// 🧙‍♀️ magic autocompletion
client.post.b;
// 👀 fully typesafe
const post = await client.post.byId.query({ id: '123' });
Copy

Fullständig källkod för klienten finns här, och tester som visar användning här.

Avslutning​

Jag hoppas du gillade artikeln och lärde dig något om hur tRPC fungerar. Du bör förmodligen inte använda denna lösning i stället för @trpc/client som bara är några få KB större – den erbjuder mycket mer flexibilitet än vad vi visat här:

• Frågealternativ för abort-signaler, SSR m.m.

• Länkar

• Batchbearbetning av procedurer

• WebSockets / prenumerationer

• Bra felhantering

• Datatransformatorer

• Hantering av specialfall som när responsen inte följer tRPC-standarden

Vi täckte inte heller serversidan idag, det får kanske bli ett framtida inlägg. Har du frågor är du välkommen att höra av dig till mig på Twitter.

Det är ingen hemlighet att TypeScript är drivkraften bakom hur tRPC levererar sin fantastiska DX. Att använda TypeScript är modern standard för att skapa bra JavaScript-baserade upplevelser idag – men denna ökade typsäkerhet har sina avvägningar.

Det är ingen hemlighet att TypeScript är drivkraften bakom hur tRPC levererar sin fantastiska utvecklarupplevelse. Att använda TypeScript är den moderna standarden för att leverera bra JavaScript-baserade upplevelser idag – men denna förbättrade typsäkerhet medför vissa kompromisser.

Idag är TypeScripts typkontroller benägen att bli långsam (även om releaser som TS 4.9 är lovande!). Bibliotek innehåller nästan alltid de mest avancerade TypeScript-besvärjelserna i din kodbas, vilket pressar din TS-kompilator till sina gränser. Av den anledningen måste biblioteksförfattare som vi vara medvetna om vårt bidrag till denna börda och göra vårt bästa för att hålla din IDE så snabb som möjligt.

Automatisera bibliotekets prestanda​

Medan tRPC var i v9 började vi se rapporter från utvecklare om att deras stora tRPC-routrar började få skadliga effekter på deras typkontroll. Detta var en ny upplevelse för tRPC eftersom vi såg en enorm adoption under v9-fasen av tRPC:s utveckling. Med fler utvecklare som skapar allt större produkter med tRPC började vissa brister att visa sig.

Ditt bibliotek kanske inte är långsamt just nu, men det är viktigt att hålla ett öga på prestanda när ditt bibliotek växer och förändras. Automatiserade tester kan avlasta dig avsevärt när du skapar bibliotek (och bygger applikationer!) genom att programmatiskt testa din bibliotekskod vid varje incheckning.

För tRPC gör vi vårt bästa för att säkerställa detta genom att generera och testa en router med 3 500 procedurer och 1 000 routrar. Men detta testar bara hur långt vi kan pressa TS-kompilatorn innan den bryter samman, och inte hur lång tid typkontrollen tar. Vi testar alla tre delarna av biblioteket (server, vanilla-klient och React-klienten) eftersom de alla har olika kodvägar. Tidigare har vi sett regressioner som är isolerade till en sektion av biblioteket och förlitar oss på våra tester för att visa oss när dessa oväntade beteenden uppstår. (Vi vill fortfarande göra mer för att mäta kompileringstider)

• Långsam typkontroll med tsc

• Lång initial laddningstid

• Om TypeScript-språkservern tar lång tid på sig att svara på ändringar

• Den sista punkten är att tsc kan vara långsam vid type-checking, vilket tRPC måste vara extra uppmärksam på. Du vill aldrig att dina utvecklare ska behöva vänta på att språkservern ska uppdateras efter en ändring. Det är här tRPC måste bibehålla prestanda så att du kan njuta av enastående DX.

Hur jag hittade prestandamöjligheter i tRPC​

Det finns alltid en avvägning mellan TypeScript-accuracy och kompilatorprestanda. Båda är viktiga aspekter för andra utvecklare så vi måste vara extremt medvetna om hur vi skriver typer. Finns det risk för allvarliga fel i en applikation om en viss typ är "för lös"? Är prestandavinsten värd det?

Kommer det ens att bli en märkbar prestandavinst? Bra fråga.

Hur jag hittade prestandamöjligheter i tRPC​

Det finns alltid en avvägning mellan TypeScripts noggrannhet och kompilatorns prestanda. Båda är viktiga aspekter för andra utvecklare, så vi måste vara mycket medvetna om hur vi skriver typer. Kan en applikation stöta på allvarliga fel på grund av att en viss typ är "för lös"? Är prestandavinsten värt det?

Kommer det ens att bli någon märkbar prestandavinst alls? Bra fråga.

Låt oss titta på hur man hittar tillfällen för prestandaförbättringar i TypeScript-kod. Vi går igenom processen jag följde för att skapa PR #2716, vilket resulterade i 59% kortare TS-kompileringstid.

slug: typescript-performance-lessons title: Lärdomar om TypeScript-prestanda vid omstrukturering för v10 authors: [sachinraja]​

TypeScript har ett inbyggt spårningsverktyg som hjälper dig hitta flaskhalsar i dina typer. Det är inte perfekt, men det bästa tillgängliga verktyget.

Det är idealiskt att testa ditt bibliotek i en verklig applikation för att simulera vad ditt bibliotek gör för utvecklare. För tRPC skapade jag en grundläggande T3-app som liknar vad många användare arbetar med.

Så här spårade jag tRPC:

1. Länka biblioteket lokalt till exempelappen. Detta gör att du kan ändra bibliotekskod och omedelbart testa ändringar lokalt.

2. Kör detta kommando i exempelappen:

   sh
   tsc --generateTrace ./trace --incremental false
   Copy

   sh
   tsc --generateTrace ./trace --incremental false
   Copy

3. Du får en trace/trace.json-fil. Öppna den i ett spårningsverktyg (jag använder Perfetto) eller chrome://tracing.

Här blir det intressant - vi kan börja analysera typ-prestandan. Så här såg den första spårningen ut:

Ett längre fält indikerar längre exekveringstid. Jag har valt det gröna fältet i skärmdumpen, vilket visar att src/pages/index.ts är flaskhalsen. Under Duration ser vi att det tog 332ms - lång tid för typkontroll! Det blå checkVariableDeclaration-fältet visar att kompilatorn ägnade mest tid åt en variabel. Klickar man på fältet ser vi detaljer: Fältet pos avslöjar variabelns position i filen. När vi går till den positionen i src/pages/index.ts ser vi att boven är utils = trpc.useContext()!

Men hur är detta möjligt? Vi använder ju bara ett enkelt hook! Låt oss titta på koden:

tsx
import type { AppRouter } from '~/server/trpc';
const trpc = createTRPCReact<AppRouter>();
const Home: NextPage = () => {
  const { data } = trpc.r0.greeting.useQuery({ who: 'from tRPC' });
  const utils = trpc.useContext();
  utils.r49.greeting.invalidate();
};
export default Home;
Copy

tsx
import type { AppRouter } from '~/server/trpc';
const trpc = createTRPCReact<AppRouter>();
const Home: NextPage = () => {
  const { data } = trpc.r0.greeting.useQuery({ who: 'from tRPC' });
  const utils = trpc.useContext();
  utils.r49.greeting.invalidate();
};
export default Home;
Copy

Okej, inte mycket att se här. Bara ett useContext och en query-ogiltigförklaring. Inget som borde vara TypeScript-tungt vid första anblick, vilket indikerar att problemet ligger djupare i stacken. Låt oss undersöka typerna bakom denna variabel:

ts
type DecorateProcedure<
  TRouter extends AnyRouter,
  TProcedure extends Procedure<any>,
  TProcedure extends AnyQueryProcedure,
> = {
  /**
   * @see https://tanstack.com/query/v4/docs/framework/react/guides/query-invalidation
   */
  invalidate(
    input?: inferProcedureInput<TProcedure>,
    filters?: InvalidateQueryFilters,
    options?: InvalidateOptions,
  ): Promise<void>;
  // ... and so on for all the other React Query utilities
};
export type DecoratedProcedureUtilsRecord<TRouter extends AnyRouter> =
  OmitNeverKeys<{
    [TKey in keyof TRouter['_def']['record']]: TRouter['_def']['record'][TKey] extends LegacyV9ProcedureTag
      ? never
      : TRouter['_def']['record'][TKey] extends AnyRouter
        ? DecoratedProcedureUtilsRecord<TRouter['_def']['record'][TKey]>
        : TRouter['_def']['record'][TKey] extends AnyQueryProcedure
          ? DecorateProcedure<TRouter, TRouter['_def']['record'][TKey]>
          : never;
  }>;
Copy

ts
type DecorateProcedure<
  TRouter extends AnyRouter,
  TProcedure extends Procedure<any>,
  TProcedure extends AnyQueryProcedure,
> = {
  /**
   * @see https://tanstack.com/query/v4/docs/framework/react/guides/query-invalidation
   */
  invalidate(
    input?: inferProcedureInput<TProcedure>,
    filters?: InvalidateQueryFilters,
    options?: InvalidateOptions,
  ): Promise<void>;
  // ... and so on for all the other React Query utilities
};
export type DecoratedProcedureUtilsRecord<TRouter extends AnyRouter> =
  OmitNeverKeys<{
    [TKey in keyof TRouter['_def']['record']]: TRouter['_def']['record'][TKey] extends LegacyV9ProcedureTag
      ? never
      : TRouter['_def']['record'][TKey] extends AnyRouter
        ? DecoratedProcedureUtilsRecord<TRouter['_def']['record'][TKey]>
        : TRouter['_def']['record'][TKey] extends AnyQueryProcedure
          ? DecorateProcedure<TRouter, TRouter['_def']['record'][TKey]>
          : never;
  }>;
Copy

Nu har vi saker att analysera. Låt oss först förstå vad denna kod gör.

Vi har en rekursiv typ DecoratedProcedureUtilsRecord som traverserar alla procedurer i routern och "dekorerar" (lägger till metoder på) dem med React Query-verktyg som invalidateQueries.

I tRPC v10 stöder vi fortfarande gamla v9-routrar, men v10-klienter kan inte anropa procedurer från v9-routrar. Så för varje procedur kontrollerar vi om det är en v9-procedur (extends LegacyV9ProcedureTag) och filtrerar bort den i så fall. Detta är mycket arbete för TypeScript...om det inte utvärderas lättjefullt.

Lat utvärdering​

Problemet här är att TypeScript utvärderar all denna kod i typsystemet, även om den inte används omedelbart. Vår kod använder bara utils.r49.greeting.invalidate, så TypeScript borde bara behöva packa upp r49-egenskapen (en router), sedan greeting-egenskapen (en procedur), och slutligen invalidate-funktionen för den proceduren. Inga andra typer behövs i den koden och att omedelbart hitta typen för varje React Query-hjälpmetod för alla dina tRPC-procedurer skulle onödigt sakta ner TypeScript. TypeScript skjuter upp typutvärderingen av egenskaper på objekt tills de används direkt, så teoretiskt borde vår typ ovan få lazy evaluation... eller hur?

Nåväl, det är inte exakt ett objekt. Det finns faktiskt en typ som omsluter hela grejen: OmitNeverKeys. Denna typ är ett verktyg som tar bort nycklar med värdet never från ett objekt. Det är här vi skrapar bort v9-procedurerna så dessa egenskaper inte syns i Intellisense.

Men detta skapar ett enormt prestandaproblem. Vi tvingade TypeScript att utvärdera värdena för alla typer nu för att kontrollera om de är never.

Hur fixar vi detta? Låt oss ändra våra typer till att göra mindre.

Bli lat​

Vi måste hitta ett sätt för v10-API:et att anpassa sig till de äldre v9-routern mer graciöst. Nya tRPC-projekt borde inte drabbas av den reducerade TypeScript-prestandan i interop-läge.

Tanken är att omstrukturera kärntyperna själva. v9-procedurer är olika entiteter jämfört med v10-procedurer så de borde inte dela samma utrymme i vår bibliotekskod. På tRPC-serversidan innebar detta att vi hade arbete att göra för att lagra typerna på olika fält i routern istället för ett enda record-fält (se DecoratedProcedureUtilsRecord ovan).

Vi gjorde en ändring så att v9-routrar injicerar sina procedurer i ett legacy-fält när de konverteras till v10-routrar.

Gamla typer:

ts
export type V10Router<TProcedureRecord> = {
  record: TProcedureRecord;
};
// convert a v9 interop router to a v10 router
export type MigrateV9Router<TV9Router extends V9Router> = V10Router<{
  [TKey in keyof TV9Router['procedures']]: MigrateProcedure<
    TV9Router['procedures'][TKey]
  > &
    LegacyV9ProcedureTag;
}>;
Copy

ts
export type V10Router<TProcedureRecord> = {
  record: TProcedureRecord;
};
// convert a v9 interop router to a v10 router
export type MigrateV9Router<TV9Router extends V9Router> = V10Router<{
  [TKey in keyof TV9Router['procedures']]: MigrateProcedure<
    TV9Router['procedures'][TKey]
  > &
    LegacyV9ProcedureTag;
}>;
Copy

Om du minns DecoratedProcedureUtilsRecord-typen ovan ser du att vi bifogade LegacyV9ProcedureTag här för att skilja på v9- och v10-procedurer på typnivå och framtvinga att v9-procedurer inte anropas från v10-klienter.

Nya typer:

ts
export type V10Router<TProcedureRecord> = {
  record: TProcedureRecord;
  // by default, no legacy procedures
  legacy: {};
};
export type MigrateV9Router<TV9Router extends V9Router> = {
  // v9 routers inject their procedures into a `legacy` field
  legacy: {
    // v9 clients require that we filter queries, mutations, subscriptions at the top-level
    queries: MigrateProcedureRecord<TV9Router['queries']>;
    mutations: MigrateProcedureRecord<TV9Router['mutations']>;
    subscriptions: MigrateProcedureRecord<TV9Router['subscriptions']>;
  };
} & V10Router</* empty object, v9 routers have no v10 procedures to pass */ {}>;
Copy

ts
export type V10Router<TProcedureRecord> = {
  record: TProcedureRecord;
  // by default, no legacy procedures
  legacy: {};
};
export type MigrateV9Router<TV9Router extends V9Router> = {
  // v9 routers inject their procedures into a `legacy` field
  legacy: {
    // v9 clients require that we filter queries, mutations, subscriptions at the top-level
    queries: MigrateProcedureRecord<TV9Router['queries']>;
    mutations: MigrateProcedureRecord<TV9Router['mutations']>;
    subscriptions: MigrateProcedureRecord<TV9Router['subscriptions']>;
  };
} & V10Router</* empty object, v9 routers have no v10 procedures to pass */ {}>;
Copy

Nu kan vi ta bort OmitNeverKeys eftersom procedurerna är försorterade så en routers record-egenskapstyp kommer innehålla alla v10-procedurer och dess legacy-egenskapstyp kommer innehålla alla v9-procedurer. Vi tvingar inte längre TypeScript att helt utvärdera den enorma DecoratedProcedureUtilsRecord-typen. Vi kan också ta bort filtreringen för v9-procedurer med LegacyV9ProcedureTag.

Funkade det?​

Vår nya spårning visar att flaskhalsen är borta:

En betydande förbättring! Typkontrolleringstiden gick från 332ms till 136ms 🤯! Det kanske inte verkar mycket i det stora hela men det är en enorm vinst. 200ms är en liten mängd en gång - men tänk på:

• hur många andra TS-bibliotek som finns i ett projekt

• hur många utvecklare som använder tRPC idag

• hur många gånger deras typer omvärderas under ett arbetspass

Det blir många 200ms som lägger upp till ett väldigt stort antal.

Vi letar alltid efter fler möjligheter att förbättra upplevelsen för TypeScript-utvecklare, vare sig det är med tRPC eller ett TS-baserat problem att lösa i ett annat projekt. Pinga mig på Twitter om du vill prata TypeScript.

Tack till Anthony Shew för hjälpen med att skriva detta inlägg och till Alex för granskningen!

tRPC erbjuder en fantastisk utvecklarupplevelse genom att med TypeScripts kraft skapa tätt sammanlänkade typer i hela stacken. Inga avvikande API-kontrakt, ingen kodgenerering.

Sedan vårt senaste majorversionssläpp i augusti 2021 har tRPC-communityn vuxit avsevärt:

• Vi har nu över 15 000 stjärnor på GitHub

• En Discord-gemenskap med över 2 000 medlemmar

• 100k+ nedladdningar per vecka på npm

• Nästan 200 bidragsgivare

• Ett växande ekosystem av tillägg, exempel och innehåll

Idag lanserar vi tRPC v10. Vi är glada att dela med oss att v10 redan används i produktion av många stora TypeScript-projekt. Detta officiella släpp markerar allmän tillgänglighet för hela communityn.

För nya projekt kan du komma igång med ett exempelprogram för att lära dig om tRPC v10. För projekt som redan använde tRPC v9, besök migrationsguiden till v10.

Översikt över förändringar​

v10 är tRPC:s största släpp någonsin. Det här är första gången vi gjort fundamentala förändringar i tRPC:s struktur och vi tror att dessa förbättringar öppnar nya möjligheter för snabbrörliga team som arbetar med banbrytande applikationer.

Förbättrad utvecklarupplevelse​

tRPC v10 omfamnar din IDE. Vi vill enhetliggöra dina typer – men vi har också förenat din frontend, backend och redigeringsupplevelse i denna version.

Med v10 kan du:

• Använd "Go to Definition" för att hoppa direkt från din frontend-konsument till din backend-procedure

• Använd "Rename Symbol" för att byta namn på ett inargument eller en procedure i hela applikationen

• Hämta typer enklare när du vill använda dina tRPC-typer manuellt i applikationen

Kraftfull backend-ramverk​

I v10 har vi reviderat syntaxen för hur du definierar backend-procedurer, vilket öppnar fler möjligheter att integrera din önskade logik på ett strukturerat sätt. Denna version av tRPC innehåller:

• Återanvändbara middlewares med Context Extension

• Kedjebara & återanvändbara procedurer med stöd för flera inputparsare

• Flexibel felhantering med anpassad felformatering

• Procedurmetadata för att utöka dina procedurer med mer information

Betydande förbättring av TypeScript-prestanda​

TypeScript gör det möjligt för utvecklare att göra fantastiska saker – men det kan komma med en kostnad. Många tekniker vi använder för att hålla dina typer strikta lägger stort tryck på TypeScript-kompilatorn. Vi fick feedback från communityn att större applikationer med tRPC v9 började drabbas av sämre prestanda i utvecklarnas IDE:er på grund av detta kompilatortryck.

Vårt mål är att förbättra utvecklarupplevelsen för applikationer i alla storlekar. I v10 har vi dramatiskt förbättrat TypeScript-prestandan (särskilt med TS inkrementell kompilering) så att din editor fortsätter vara snabb.

Gradvis migrering​

Vi har också lagt ner mycket arbete på att göra migreringsprocessen så smidig som möjligt, inklusive en interop()-metod som ger (nästan) full bakåtkompatibilitet med v9-routrar. Läs migreringsguiden för mer information.

Sachin från kärnteamet har också skapat en codemod som kan göra mycket av det tunga lyftet vid migreringen åt dig.

Ett växande ekosystem​

Ett rikt utbud av underbibliotek fortsätter att växa fram kring tRPC. Här är några exempel:

• trpc-openapi för att enkelt skapa REST-kompatibla slutpunkter

• create-t3-app för att bootstrapa en fullstack Next.js-applikation med tRPC

• create-t3-turbo för att kickstarta din nästa React Native-app med tRPC

• trpc-chrome för att bygga Chrome-tillägg med tRPC

• Adapters för ramverk som Solid, Svelte och Vue

För fler plugins, exempel och adapters, besök Awesome tRPC-samlingen.

Tack!​

Kärnteamet och jag vill att ni ska veta: vi har precis börjat. Vi håller redan på att experimentera med React Server Components och Next.js 13.

Jag vill också ge ett jättestort tack till Sachin, Julius, James, Ahmed, Chris, Theo, Anthony och alla bidragsgivare som möjliggjort denna release.

Tack för att ni använder och stödjer tRPC.

slug: typescript-performance-lessons title: Lärdomar om TypeScript-prestanda vid omstrukturering för v10 authors: [sachinraja]​

• Följ @trpcio på Twitter.

• Gå med i vår Discord-community

• Testa tRPC direkt i webbläsaren

tRPC ger dig typsäkerhet från server till klient (hela vägen), utan att ens behöva deklarera typer. På serversidan returnerar du bara data i en funktion, och på klientsidan använder du datan direkt baserat på endpoint-namnet.

👋 Jag är Alex, eller "KATT" på GitHub, och jag vill berätta om ett bibliotek som heter tRPC. Jag har inte publicerat några artiklar om det ännu, så jag skriver bara den här introduktionen för att sätta igång (men vi har redan nått >530 🌟 på GitHub). Räkna med artiklar och videointroduktioner framöver! Om du vill hålla dig uppdaterad eller ställa frågor kan du följa mig på Twitter @alexdotjs.

Så här kan det se ut när du gör ett tRPC-anrop från klienten till en endpoint:

Jag har skapat ett bibliotek för React (@trpc/react) som bygger på det fantastiska react-query, men klientbiblioteket (@trpc/client) fungerar utan React (om du vill bygga ett bibliotek för Svelte/Vue/Angular/[..] - hör av dig!)

Ingen kodgenerering krävs och du kan enkelt lägga till det i ditt befintliga Next.js/CRA/Express-projekt.

Exempel​

Här är ett exempel på en tRPC-procedur (kallas även endpoint) som heter hello och tar ett string-argument.

tsx
const appRouter = trpc.router().query('hello', {
  input: z.string().optional(),
  resolve: ({ input }) => {
    return {
      text: `hello ${input ?? 'world'}`,
    };
  },
});
export type AppRouter = typeof appRouter;
Copy

tsx
const appRouter = trpc.router().query('hello', {
  input: z.string().optional(),
  resolve: ({ input }) => {
    return {
      text: `hello ${input ?? 'world'}`,
    };
  },
});
export type AppRouter = typeof appRouter;
Copy

Och här är en typsäker klient som använder datan:

tsx
import type { AppRouter } from './server';
async function main() {
  const client = createTRPCClient<AppRouter>({
    url: `http://localhost:2022`,
  });
  const result = await client.query('hello', '@alexdotjs');
  console.log(result); // --> { text: "hello @alexdotjs" }
}
main();
Copy

tsx
import type { AppRouter } from './server';
async function main() {
  const client = createTRPCClient<AppRouter>({
    url: `http://localhost:2022`,
  });
  const result = await client.query('hello', '@alexdotjs');
  console.log(result); // --> { text: "hello @alexdotjs" }
}
main();
Copy

Det är allt du behöver för typsäkerhet! result härleds automatiskt från vad servern returnerar. Indata härleds också från validerarens returvärde, så datan är säker att använda direkt – faktiskt måste du alltid skicka indata genom en validerare (tRPC fungerar out-of-the-box med zod/yup/egna validerare).

Här är en CodeSandbox-länk där du kan testa exemplet ovan: https://githubbox.com/trpc/trpc/tree/main/examples/standalone-server (titta på terminalutmatningen istället för förhandsgranskningen!)

Va? Importerar jag kod från min server till klienten? - Nej, det gör du faktiskt inte

Även om det kan se ut så, delas ingen kod från server till klient; TypeScripts import type "[...] importerar endast deklarationer för typannoteringar. Den tas alltid bort helt och hållet och lämnar inga spår vid körning." – en funktion tillagd i TypeScript 3.8 - läs i TypeScript-dokumentationen.

Ingen kodgenerering är inblandad – du kan implementera detta direkt i din applikation om du har ett sätt att dela typer mellan server och klient (förhoppningsvis använder du redan en monorepo).

Men vi har precis börjat!​

Jag nämnde tidigare att det finns ett React-bibliotek. Så här använder du datan i React:

tsx
const { data } = trpc.useQuery(['hello', '@alexdotjs']);
Copy

tsx
const { data } = trpc.useQuery(['hello', '@alexdotjs']);
Copy

...och du får typsäker data på klienten.

Du kan implementera tRPC redan idag i ditt befintliga projekt (det finns adaptrar för Express/Next.js). Det fungerar utmärkt med CRA och bör fungera med React Native också. Det är inte ens knutet till React – om du vill skapa ett bibliotek för Svelte eller Vue, kontakta mig.

Hur hanterar man datamutationer?​

Mutationer är lika enkla som queries – de är faktiskt samma sak under huven, men exponeras som syntaktisk socker och genererar HTTP POST-förfrågningar istället för GET.

Här är ett lite mer komplext exempel med en databas, hämtat från vårt TodoMVC-exempel på todomvc.trpc.io / https://github.com/trpc/trpc/tree/main/examples/next-prisma-todomvc

tsx
const todoRouter = createRouter().mutation('add', {
  input: z.object({
    id: z.string().uuid(),
    data: z.object({
      completed: z.boolean().optional(),
      text: z.string().min(1).optional(),
    }),
  }),
  async resolve({ ctx, input }) {
    const { id, data } = input;
    const todo = await ctx.task.update({
      where: { id },
      data,
    });
    return todo;
  },
});
Copy

tsx
const todoRouter = createRouter().mutation('add', {
  input: z.object({
    id: z.string().uuid(),
    data: z.object({
      completed: z.boolean().optional(),
      text: z.string().min(1).optional(),
    }),
  }),
  async resolve({ ctx, input }) {
    const { id, data } = input;
    const todo = await ctx.task.update({
      where: { id },
      data,
    });
    return todo;
  },
});
Copy