tRPC Blog

tRPC v11の発表

Fri, 21 Mar 2025 00:00:00 GMT

非公式ベータ版翻訳

このページは PageTurner AI で翻訳されました（ベータ版）。プロジェクト公式の承認はありません。エラーを見つけましたか？問題を報告 →

tRPC v11は長らく@nextタグを通じてプロダクション環境で使用可能でしたが、私たちはセマンティックバージョニングに厳密にならずに新機能を追加することに夢中になってしまいました。ついに今日、私たちはこのバンドエイドをはがす決断をし、tRPC v11の正式リリースを発表できることを大変嬉しく思います！

前回のメジャーバージョンリリース（2022年11月）以来、tRPCコミュニティは大幅な成長を遂げています：

tRPC v11のローンチに際し、@nextチャンネルでの安定した進化のおかげで、すでに多くの大規模TypeScriptプロジェクトが本番環境でv11を採用していることを共有できることを嬉しく思います。

新規プロジェクトではtRPC v11を学べるサンプルアプリケーションで始められます。tRPC v10を使用中のプロジェクトはv11移行ガイドをご参照ください。

変更点の概要

v11はv10との後方互換性をほぼ維持しつつ、多くの新機能と改善が導入されています。主なハイライトは以下の通りです：

TanStack Query v5サポート

TanStack Query v5のリリースに伴い、tRPCのreact-query統合部分に破壊的変更が導入されました。この変更は@nextタグで早期から利用可能でしたが、今回正式リリースとなりました。多くのプロジェクトがすでにアップグレードを完了し、React Suspenseの完全サポートなど多くの改善を享受しています。tRPC Reactクライアントコードの移行については、TanStack Query公式移行ガイドをご参照ください。

新しいTanStack React Query統合

ブログ記事を参照

FormData / 非JSONコンテンツタイプのサポート

最も要望の多かった機能の一つであるJSON以外のデータ送受信が可能になりました。tRPC v11では、様々な非JSONコンテンツタイプ、FormData、Blob、File、Uint8Arrayなどのバイナリタイプを送受信できるようになりました。これらのコンテンツタイプの使用方法はこちらのサンプルで確認できます。

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

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

React Server Components と Next.js App Router

Next.js App RouterとtRPCの組み合わせは初日から可能でしたが、主に以下の二つのアプローチがあります：

createCallerまたはcreateTRPCClientを使ったasync/awaitによるサーバー中心アプローチ
React Query統合とクライアントサイドフックを使ったクライアント中心アプローチ

この間をつなぐ部分には若干の課題がありました。異なるデータ取得パターンを混在させることで再検証パターンが複雑化し、tRPCが目指す理想的な開発者体験には届かない状態でした。

この問題を解決するため、React Server Components（RSC）のサポートを強化し、サーバー上で排他的に実行されるRSCの能力とReact Queryの高度なクライアントサイドキャッシュを組み合わせやすくするプリフェッチヘルパーを追加しました。これにより、サーバー上のRSCでプロシージャの実行を開始し、クライアント側で保留中のPromiseを引き継ぎ、React Queryキャッシュを自動的にハイドレートできるようになりました。これによってサーバーとクライアント間のウォーターフォールに悩まされることなく、高度に動的なアプリケーションを構築できます。詳細はServer Componentsのドキュメントをご覧ください。

新しいプリフェッチパターンに加え、サーバー関数の実験的サポートも追加しました。詳細は当社のブログ記事でご確認いただけます。サーバー関数がエコシステムでより確立されたパターンになるにつれ、この機能の改良を続けていく予定です。

またTanStackチームと協力してサーバー関数のAPI設計にも取り組みました。tRPCの強力なミドルウェアシステムの一部を切り出し、エコシステム全体で利用可能な別パッケージとすることを目指しています。

クエリとミューテーションからのストリーミング応答

クエリ応答をストリーミング可能なhttpBatchStreamLinkを導入しました。大規模データセットを扱う場合や、データをリアルタイムで処理しながらフロントエンドに送信する必要がある場合に有用です。これはサブスクリプションの代替ではなく、新たな選択肢としてご活用ください。

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, ): TRPCLink
import httpBatchStreamLink">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
 
for await (const value of iterable) {
  console.log('Iterable:', value);
                            
const value: number
}

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, ): TRPCLink
import httpBatchStreamLink">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
 
for await (const value of iterable) {
  console.log('Iterable:', value);
                            
const value: number
}

ルーター定義の短縮構文

ルート定義プロセスを簡素化するため、新しい省略構文を導入しました。ドキュメント

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

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

サブスクリプション：Server-Sent Eventsとその他の改良

tRPC v11ではServer-Sent Events（SSE）を利用した新たなサブスクリプション処理方法を導入しました。複雑なWebSocketを必要とせずリアルタイム更新を実現する優れた方法です。今後はまずこの方法をお試しください。
サブスクリプションにおけるJavaScriptジェネレーターのサポートを追加。時間経過とともに複数の値を生成し、終了時にクリーンアップできるより複雑なサブスクリプションハンドラーの記述が、JavaScriptらしい方法で可能になりました。
サブスクリプションで出力バリデーションをサポートし、サブスクリプションハンドラーの型安全性を向上させました。

v9 `.interop()`モードの終焉

tRPC v10ではv9ユーザーのスムーズな移行を支援するため.interop()モードを導入しましたが、v11では.interop()モードを削除しました。.interop()モードをまだ使用されている場合はv10移行ガイドを参照し、現在のtRPC APIへの移行を完了してください。

v11への移行

現在tRPC v10をご使用の場合、移行ガイドに従ってv11にアップグレードできます。移行ガイドではv11の全破壊的変更と新機能を網羅しています。

感謝を込めて

tRPCコアチーム一同、tRPCをご利用・ご支援いただいている皆様に感謝申し上げます。

新たなTanStack React Query統合のご紹介

Mon, 17 Feb 2025 00:00:00 GMT

非公式ベータ版翻訳

このページは PageTurner AI で翻訳されました（ベータ版）。プロジェクト公式の承認はありません。エラーを見つけましたか？問題を報告 →

tRPCのnextリリースで、新たなTanStack React Query統合が利用可能になりましたことをお知らせします。従来のReact Query統合と比較して、よりシンプルでTanStack Queryネイティブなアプローチを採用しており、独自クライアントでuseQueryやuseMutationをラップする代わりに、TanStack React QueryネイティブのQueryOptionsやMutationOptionsインターフェースを直接利用します。

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

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

この新クライアントでは、新規ユーザーが混乱しがちだった抽象化レイヤーを排除し、代わりにTanStack公式ドキュメントを参照している開発者にとって即座に馴染み深い、より直接的な作業方法を提供します。また、tRPC側の説明ドキュメントも少なくて済むようになります（もちろん導入ガイドは用意しています）。

なぜ変更するのか？

詳細な背景は当時のRFCディスカッションこちらでご覧いただけますが、主な理由は以下の通りです：

簡素化: 新クライアントはよりシンプルでTanStack Queryネイティブであり、QueryKeysやQueryOptions、MutationOptionsといった共通インターフェースのファクトリを提供します。これにより学習曲線が緩和され、公式TanStack Queryドキュメントをそのまま活用できます
親和性: 既にTanStack Queryを使用している開発者にとってより親しみやすい設計です。アプリケーション内の他の処理でTanStack Queryを使用している場合でも、tRPCのために別の構文を使う必要がなくなります
React対応: 従来のReact Query統合は実際にフックのルールに違反しており、正しいリンター検査が不可能でした。さらにフックをプロパティとして受け渡すような、React Compiler下で問題を引き起こすパターンを助長していました。この点で新クライアントはよりイディオマティックなReact仕様に沿っています
保守性: バージョン管理における課題として、TanStack Queryの変更（特にQueryClientに追加される新機能）とtRPCの歩調を合わせることが困難でした。ネイティブインターフェースという最小限の接点を利用することで、React Queryのサポートが容易になり、TanStackメンテナーが推奨するベストプラクティスにも沿えます
フィードバック: 前述のように従来クライアントは新規ユーザーにとって難解でしたが、RFCに対する反応は圧倒的に肯定的で、多くのユーザーがこのクライアントの利用に期待を寄せています。もちろん全員が即座に移行するわけではないため、従来クライアントも引き続き維持します

従来のtRPC React Query統合はどうなる？

すぐになくなることはありません！長期的にメンテナンスを継続しますが、大きな新機能は追加されず、安定版として位置付けます。

新規プロジェクトには新TanStack React Query統合の利用を推奨し、既存プロジェクトは段階的な移行をご検討ください。

移行方法

従来クライアントは長期にわたり維持されますが、新規プロジェクトでは新クライアントの利用を推奨し、進行中のプロジェクトは段階的移行をご検討ください。

両クライアントは互換性があり同一アプリケーション内で共存可能なため、ご自身のペースで移行できます。現在コミュニティ協力を大歓迎しているコードモッドも開発中です。これまでにコードモッドへ貢献いただいた@reaper氏に謝意を表します！

👉 移行ドキュメントを読む

tRPCでServer Actionsを使う

Thu, 23 May 2024 00:00:00 GMT

非公式ベータ版翻訳

このページは PageTurner AI で翻訳されました（ベータ版）。プロジェクト公式の承認はありません。エラーを見つけましたか？問題を報告 →

tRPC v10で導入されたプロシージャ作成のビルダーパターンはコミュニティから高く評価され、多くのライブラリが同様のパターンを採用しています。このパターンの人気が高まっている証拠に、tRPC like XYZという用語まで生まれました。実際、先日tRPCと似たAPIでCLIアプリケーションを作る方法はないかという投稿も見かけました。ちなみに、tRPCを直接使って実現する方法もありますが、今日のテーマはそれではなく、Next.jsのServer ActionsをtRPCで活用する方法についてです。

Server Actionとは？

最新のReactやNext.js機能を追っていない方のために説明すると、Server Actionsを使えばサーバー上で実行される通常の関数をクライアント側からインポートし、あたかもローカル関数のように呼び出せます。これはtRPCと似ていると思うかもしれませんが、その通りです。Dan Abramovによれば、Server Actionsとは「バンドラー機能としてのtRPC」なのです：

この指摘はまったく正確で、Server ActionsはtRPCと似ています。結局のところ両者ともRPCの一種です。どちらもバックエンドに関数を定義し、フロントエンドからネットワーク層を抽象化した状態で完全な型安全を保ちながら呼び出せます。

ではtRPCの役割はどこにあるのでしょうか？なぜ両方必要なのか？Server Actionsはプリミティブであり、すべてのプリミティブと同様に基本的な機能に留まるため、API構築において重要な側面が欠けています。ネットワーク経由で公開されるAPIエンドポイントには、悪用を防ぐためのリクエスト検証と認可が不可欠です。前述のようにtRPCのAPIは高く評価されているので、tRPCを使ってServer Actionsを定義し、入力検証、ミドルウェアによる認証認可、出力検証、データ変換などtRPC組み込みの優れた機能を活用できたら素晴らしいと思いませんか？私もそう考えます。さっそく詳しく見ていきましょう。

tRPCでServer Actionsを定義する

注記

前提条件: Server Actionsを使用するにはNext.jsのApp Routerが必要です。また、これから使用するtRPC機能はすべてtRPC v11で利用可能なため、必ずtRPCのベータリリースチャンネルを使用してください：

npm
yarn
pnpm
bun
deno

npm install @trpc/server

yarn add @trpc/server

pnpm add @trpc/server

bun add @trpc/server

deno add npm:@trpc/server

まずtRPCを初期化し、基本となるServer Actionsプロシージャを定義します。ここではプロシージャビルダーのexperimental_callerメソッドを使用します。これは関数が呼び出された際の実行方法をカスタマイズできる新機能です。また、Next.js互換にするためにexperimental_nextAppDirCallerアダプターも使用します。このアダプターは、クライアント側でuseActionStateでラップされたServer Actionsの呼び出しシグネチャが変化するケースを処理します。

通常のルーター（例：user.byId）のようなパスがないため、メタデータとしてspanプロパティも使用します。このspanプロパティは、ロギングやオブザーバビリティなどでプロシージャを区別するのに活用できます。

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

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

次にコンテキストを追加します。通常のHTTPアダプター経由でルーターをホストしないため、アダプターのcreateContextメソッドによるコンテキスト注入は行われません。代わりにミドルウェアを使用してコンテキストを注入します。この例ではセッションから現在のユーザーを取得し、コンテキストに注入してみましょう。

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

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

最後に、未認証ユーザーからアクションを保護する protectedAction プロシージャを作成します。既存のミドルウェアがある場合はそれを使えますが、ここでは例としてインラインで定義します。

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

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

では実際のサーバーアクションを書きましょう。_actions.ts ファイルを作成し、"use server" ディレクティブを付与してアクションを定義します。

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

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

未認証ユーザーからの保護とSQLインジェクションなどの攻撃を防ぐ入力検証を備えたサーバーアクションを、これほど簡単に定義できるのです。クライアント側でこの関数をインポートして呼び出してみましょう。

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

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

さらに発展させる

tRPCビルダーとその再利用可能なプロシージャを定義する合成可能な方法を活用すれば、より複雑なサーバーアクションも簡単に構築できます。以下にいくつかの例を示します：

オブザーバビリティ

@baselime/node-opentelemtry のtrpcプラグインを使えば、数行のコードでオブザーバビリティを追加できます：

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

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

詳細は Baselime tRPC統合ドキュメントを参照してください。同様のパターンは、使用しているオブザーバビリティプラットフォームでも動作するはずです。

レート制限

Unkeyのようなサービスを使えば、サーバーアクションにレート制限をかけられます。ユーザーごとのリクエスト数を制限するUnkeyを使った保護付きサーバーアクションの例です：

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

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

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

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

tRPCプロシージャのレート制限については Unkeyチームのこちらの記事で詳しく解説されています。

可能性は無限大です。皆さんが現在tRPCアプリケーションで使用している便利なユーティリティミドルウェアも既にたくさんあるでしょう。もしなければ、npm install で導入できるものが見つかるかもしれません！

まとめ

サーバーアクションは決して万能薬ではありません。より動的なデータが必要な場面では、クライアントサイドのReact Queryキャッシュにデータを保持し、useMutation を使った変更を行う方が適切かもしれません。それはまったく合理的な判断です。これらの新しいプリミティブは段階的に導入できるため、既存のtRPC APIから個々のプロシージャを、適切な場所でサーバーアクションに移行できます。API全体を書き直す必要はありません。

tRPCを使ってサーバーアクションを定義することで、現在使用しているロジックの多くを共有し、変更をサーバーアクションとして公開するか、より伝統的なミューテーションとして公開するかを選択できます。開発者である皆さんが、アプリケーションに最適なパターンを選ぶ権限を持っているのです。現在tRPCを使用していない場合でも、型安全で入力検証付きのサーバーアクションを定義できるパッケージ（next-safe-action や zsa など）が存在し、これらも検討する価値があります。

実際にこの仕組みを採用したアプリを見たい場合は、私が最近作成した Trellix tRPC をチェックしてみてください。これらの新しいプリミティブを活用したアプリケーションです。

ご意見をお聞かせください

いかがでしたか？ Githubディスカッションでぜひご意見をお聞かせいただき、これらのプリミティブを安定版に仕上げるための改善にご協力ください。

特にエラーハンドリングに関してはまだ作業が必要です。Next.jsはエラーを返すことを推奨しており、これを可能な限り型安全にしたいと考えています。AlexによるこちらのWIPプルリクエストで初期段階の作業を確認できます。

それでは次回まで、コーディングを楽しんでください！

小さなtRPCクライアントを作成する

Tue, 17 Jan 2023 00:00:00 GMT

非公式ベータ版翻訳

このページは PageTurner AI で翻訳されました（ベータ版）。プロジェクト公式の承認はありません。エラーを見つけましたか？問題を報告 →

tRPCがどのように動作するか考えたことはありますか？プロジェクトへの貢献を始めたいけれど、内部実装に怖気づいていませんか？この記事では、tRPCの主要な仕組みをカバーする最小限のクライアントを作成することで、tRPCの内部実装に親しむことを目的としています。

情報

ジェネリクス、条件型、extendsキーワード、再帰型など、TypeScriptの核心概念を理解しておくことを推奨します。これらの概念に慣れていない場合は、Matt PocockのBeginner TypeScriptチュートリアルで学んでから読み進めることをおすすめします。

概要

次のような3つのプロシージャを持つシンプルなtRPCルーターがあると仮定しましょう：

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

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

クライアントの目標は、このオブジェクト構造をクライアント側で再現し、次のようにプロシージャを呼び出せるようにすることです：

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

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

これを実現するため、tRPCはProxyオブジェクトとTypeScriptのマジックを組み合わせて、オブジェクト構造に.queryや.mutateメソッドを追加します。つまり、優れた開発者体験を提供するために、実際には（後述しますが）操作の実態について「嘘」をついているのです！

高レベルで言えば、post.byId.query()をサーバーへのGETリクエストに、post.create.mutate()をPOSTリクエストにマッピングし、型情報がバックエンドからフロントエンドに正しく伝播されるようにしたいわけです。では、どう実装すればよいでしょうか？

小さなtRPCクライアントの実装

🧙‍♀️ TypeScriptのマジック

まずは、tRPC使用時に皆が愛用している素晴らしいオートコンプリートと型安全性を実現する楽しいTypeScriptのマジックから始めましょう。

任意の深さのルーター構造を推論するために再帰型を使用する必要があります。また、post.byIdやpost.createといったプロシージャにそれぞれ.queryや.mutateメソッドを持たせたいと考えています。tRPCではこれをプロシージャの装飾(decorating)と呼びます。@trpc/serverには、解決済みメソッドを持つプロシージャの入力/出力型を推論するヘルパーがあるので、これらを使用して関数の型を推論するコードを書きましょう。

パスのオートコンプリートとプロシージャの入力/出力型推論を実現するために必要なことを考えてみましょう：

ルーター上では、そのサブルーターやプロシージャにアクセス可能であること（これについては後ほど説明します）
クエリプロシージャ上では、.queryを呼び出せること
ミューテーションプロシージャ上では、.mutateを呼び出せること
それ以外のものにアクセスしようとした場合、バックエンドに存在しないプロシージャであることを示す型エラーが発生すること

これらを実現する型を作成しましょう：

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

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

tRPC組み込みの推論ヘルパーの一部を使用して、プロシージャの入力/出力型を推論し、Resolver型を定義します。

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

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

post.byIdプロシージャで試してみましょう：

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

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

素晴らしい、期待通りです！プロシージャで.queryを呼び出し、正しい入力/出力型が推論されるようになりました。

最後に、ルーターを再帰的に走査し、通過する全てのプロシージャを装飾する型を作成します：

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

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

この型を少し解釈してみましょう：

ジェネリックとしてTRPCRouterRecordを型に渡します。これはtRPCルーター上に存在する全てのプロシージャとサブルーターを含む型です。
レコードのキー（手続きまたはルーター名）を反復処理し、以下を実行します：
- キーがルーターを指す場合、そのルーターの手続きレコードに対して再帰的にこの型を適用し、そのルーター内のすべての手続きを装飾します。これによりパスをたどる際のオートコンプリートが提供されます。
- キーが手続きを指す場合、先ほど作成した DecorateProcedure 型を使用して手続きを装飾します。
- キーが手続きもルーターも指さない場合、never 型を割り当てます。これは「このキーは存在しない」ことを意味し、アクセスしようとすると型エラーが発生します。

🤯 Proxyを使ったリマッピング

型定義が整ったので、クライアント上でサーバーのルーター定義を拡張し、手続きを通常の関数のように呼び出せる機能を実際に実装します。

まず再帰的プロキシを作成するヘルパー関数 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;
}

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

少し魔法のように見えますが、これは何をするのでしょうか？

get メソッドは post.byId のようなプロパティアクセスを処理します。キーはアクセスするプロパティ名で、例えば post と入力すると key は post に、post.byId と入力すると key は byId になります。再帰的プロキシはこれらすべてのキーを最終的なパス（例：["post", "byId", "query"]）に結合し、リクエストを送信するURLを決定するために使用します。
apply メソッドは .query(args) のようにプロキシ上で関数を呼び出す際に実行されます。args は関数に渡す引数で、例えば post.byId.query(args) を呼び出すと args は入力値となり、手続きのタイプに応じてクエリパラメータまたはリクエストボディとして提供されます。createRecursiveProxy はコールバック関数を受け取り、apply をパスと引数でマッピングします。

以下は trpc.post.byId.query({ id: 1 }) の呼び出しにおけるプロキシの動作を視覚化したものです：

🧩 すべてを組み合わせる

このヘルパーとその動作が理解できたので、クライアント作成に使用しましょう。createRecursiveProxy にパスと引数を受け取り fetch を使ってサーバーにリクエストするコールバックを提供します。関数には任意のtRPCルーター型（AnyTRPCRouter）を受け入れるジェネリックを追加し、戻り型を先ほど作成した DecorateRouterRecord 型にキャストします：

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

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

特に注目すべきは、パスが / ではなく . で区切られている点です。これによりサーバー側で各手続きごとに個別のハンドラーを作成するのではなく、単一のAPIハンドラーですべてのリクエストを処理できます。Next.jsのようなファイルベースルーティングを使用するフレームワークでは、すべての手続きパスにマッチするキャッチオールファイル /api/trpc/[trpc].ts を認識するかもしれません。

また fetch リクエストには TRPCResponse 型の注釈が付いています。これはサーバーが応答するJSONRPC準拠のレスポンス形式を定義します。詳細はこちらで読めます。要約すると、成功時は result オブジェクトが、エラー時は error オブジェクトが返り、これを使ってリクエストの成否を判断し適切なエラー処理が行えます。

これで完了です！このコードだけで、tRPCの手続きをあたかもローカル関数のようにクライアントから呼び出せます。表面的には単に publicProcedure.query / mutation のリゾルバー関数を通常のプロパティアクセスで呼んでいるように見えますが、実際にはネットワーク境界を越えており、Prismaのようなサーバーサイドライブラリをデータベース認証情報を漏らさずに使用できます。

試してみよう！

クライアントを作成し、サーバーのURLを指定すれば、手続きを呼び出す際に完全なオートコンプリートと型安全性が得られます！

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

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

クライアントの完全なコードはこちらで、使用方法を示すテストはこちらで確認できます。

まとめ

この記事が楽しめ、tRPCの仕組みについて学びが得られたなら幸いです。ただし今回作成したクライアントではなく、ほんの数KB大きいだけの@trpc/clientを使用することをお勧めします。公式クライアントにはここで紹介した機能以上の柔軟性が備わっています：

中止シグナルやSSR対応などのクエリオプション
リンク機能
手続きのバッチ処理
WebSocket/サブスクリプション対応
洗練されたエラーハンドリング
データ変換機能
tRPC準拠でないレスポンスへのエッジケース対応

サーバー側の詳細については今回は深く触れませんでしたが、今後の記事で取り上げるかもしれません。質問があれば、Twitterでお気軽に連絡ください。

v10リファクタリングで学んだTypeScriptパフォーマンスの教訓

Sat, 14 Jan 2023 00:00:00 GMT

非公式ベータ版翻訳

このページは PageTurner AI で翻訳されました（ベータ版）。プロジェクト公式の承認はありません。エラーを見つけましたか？問題を報告 →

ライブラリ作者としての私たちの目標は、開発者仲間のために最高の開発者体験（DX）を提供することです。エラー発生までの時間を短縮し、直感的なAPIを提供することで、開発者の精神的負担を軽減し、最も重要なことに集中できるようにします。それは素晴らしいエンドユーザー体験の実現です。

tRPCが驚くべきDXを実現する原動力がTypeScriptであることは周知の事実です。TypeScriptの採用は現代のJavaScriptベースの体験を提供する上での標準となりましたが、型に関する確実性の向上にはトレードオフも存在します。

現在、TypeScriptの型チェッカーは遅くなる傾向があります（TS 4.9のようなリリースは期待が持てますが！）。ライブラリはコードベース内で最も高度なTypeScriptの技法を含むことがほとんどで、TSコンパイラを限界まで酷使します。そのため、私たちのようなライブラリ作者はこの負担に寄与しないよう注意深く配慮し、IDEが可能な限り高速に動作し続けるよう最善を尽くさなければなりません。

ライブラリパフォーマンスの自動化

tRPCがv9の段階にあるとき、大規模なtRPCルーターが型チェッカーに悪影響を与え始めているという開発者からの報告が見られ始めました。これはtRPCにとって新しい経験でした。なぜならv9開発フェーズで驚異的な採用が進んだからです。より多くの開発者がtRPCで大規模な製品を作るにつれ、いくつかの問題点が表面化したのです。

今は遅くないかもしれませんが、ライブラリが成長・変化するにつれてパフォーマンスに目を光らせることが重要です。自動化されたテストは、各コミットごとにライブラリコードをプログラム的にテストすることで、ライブラリ開発（そしてアプリケーション構築！）における莫大な負担を取り除きます。

tRPCでは、3,500のプロシージャと1,000のルーターを含むルーターを生成し、テストすることで、これを可能な限り保証しています。しかしこれはTSコンパイラが破綻する前にどこまで押し込めるかをテストするもので、型チェックにかかる時間を測定するものではありません。サーバー、バニラクライアント、Reactクライアントというライブラリの3つの部分をすべてテストします。なぜならそれぞれ異なるコードパスを持つからです。過去には、ライブラリの特定のセクションに限定されたリグレッションが発生したことがあり、予期せぬ動作が発生したときにテストがそれを明らかにしてくれました。（コンパイル時間の測定についてはさらなる改善を計画中です）

tRPCはランタイム負荷の大きいライブラリではないため、パフォーマンス指標は型チェックを中心に据えています。そのため私たちは以下の点に注意を払っています：

tscを使った型チェックの遅延
初期ロード時間の長さ
TypeScript言語サーバーが変更への応答に時間がかかること

最後の点はtRPCが最も注意を払わなければならない部分です。開発者が変更後に言語サーバーの更新を待たされることが決してあってはなりません。これこそtRPCがパフォーマンスを維持すべき領域であり、優れたDXを享受できるようにするためです。

tRPCにおけるパフォーマンス改善の機会をどう発見したか

TypeScriptの正確性とコンパイラパフォーマンスの間には常にトレードオフがあります。どちらも他の開発者にとって重要な関心事であるため、型の記述方法には細心の注意を払わなければなりません。特定の型が「緩すぎる」ためにアプリケーションが深刻なエラーに遭遇する可能性はあるか？パフォーマンス向上はその価値があるか？

そもそも有意義なパフォーマンス向上が得られるのか？これは素晴らしい問いです。

TypeScriptコードにおけるパフォーマンス改善の機会を_どのように_見つけるかを見ていきましょう。PR #2716を作成したプロセスを追跡し、TSコンパイル時間を59%削減した事例を紹介します。

TypeScriptには組み込みのトレーシングツールがあり、型のボトルネックを見つけるのに役立ちます。完璧ではありませんが、現状で最良のツールです。

実際のアプリケーションでライブラリをテストするのが理想的です。tRPCの場合、多くのユーザーが使用する環境を模倣するために基本的なT3アプリを作成しました。

tRPCのトレース手順は以下の通りです：

例示アプリにライブラリをローカルリンクします。これによりライブラリコードを変更後、即座にローカルでテストできます。

例示アプリで次のコマンドを実行：

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

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

trace/trace.jsonファイルが生成されます。このファイルはトレース分析アプリ（私はPerfettoを使用）またはchrome://tracingで開けます。

ここからが本番で、アプリケーションの型パフォーマンスプロファイルを分析できます。最初のトレース結果は次のようになりました：

バーが長いほど、その処理に時間がかかっていることを示します。スクリーンショットでは最上位の緑バーを選択しており、src/pages/index.tsがボトルネックであることを示しています。Durationフィールドには332msと表示されています - 型チェックにこれほど時間がかかるのは異常です！青いcheckVariableDeclarationバーは、コンパイラが1つの変数に大部分の時間を費やしたことを伝えています。バーをクリックすると対象変数が特定できます： posフィールドから変数のファイル内位置が判明します。src/pages/index.tsの該当位置を確認すると、原因がutils = trpc.useContext()であることがわかりました！

しかしなぜでしょう？単純なフックを使っているだけなのに！コードを見てみます：

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;

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;

表面的には特に問題なさそうです。useContextとクエリの無効化だけです。一見TypeScriptに負荷をかけるような処理には見えず、問題はより深い層にあることを示唆しています。この変数の背後にある型を確認しましょう：

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

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

ここでいくつかの要素を解析する必要があります。まずこのコードの動作を理解しましょう。

再帰型DecoratedProcedureUtilsRecordが存在し、ルーター内の全手続き(procedure)を走査しながら、invalidateQueriesのようなReact Queryユーティリティで「装飾」しています。

tRPC v10では古いv9ルーターをサポートしていますが、v10クライアントはv9ルーターの手続きを呼べません。そこで各手続きについてv9手続きかどうか(extends LegacyV9ProcedureTag)をチェックし、該当する場合は除外しています。これはTypeScriptにとって大きな負荷です...遅延評価されていない場合。

遅延評価

ここでの問題は、TypeScriptがすぐに使用されないコードも含めて型システム内で評価していることです。私たちのコードはutils.r49.greeting.invalidateしか使用していないため、TypeScriptはr49プロパティ（ルーター）をアンラップし、次にgreetingプロパティ（プロシージャ）、最後にそのプロシージャのinvalidate関数を見つけるだけで済むはずです。そのコードでは他の型は必要ありません。すべてのtRPCプロシージャに対するReact Queryユーティリティメソッドの型を即座に見つけようとすることは、TypeScriptを不必要に遅くするだけです。TypeScriptはオブジェクトのプロパティの型評価を直接使用されるまで遅延させるため、理論上は上記の型は遅延評価されるはずです...よね？

しかし、これは厳密にはオブジェクトではありません。全体をラップする型が存在します：OmitNeverKeysです。この型は値がneverであるキーをオブジェクトから削除するユーティリティです。ここでv9プロシージャを剥ぎ取り、これらのプロパティがIntellisenseに表示されないようにしています。

しかしこれが巨大なパフォーマンス問題を引き起こします。私たちはTypeScriptにすべての型の値を評価させ、それらがneverかどうかをチェックすることを強制してしまったのです。

どう修正すればよいでしょうか？型に行わせることを減らすように変更しましょう。

遅延評価の導入

v10 APIがレガシーv9ルーターをより優雅に扱える方法を見つける必要があります。新しいtRPCプロジェクトが相互運用モードのTypeScriptパフォーマンス低下の影響を受けるべきではありません。

アイデアはコア型自体を再構成することです。v9プロシージャとv10プロシージャは異なる実体であるため、ライブラリコード内で同じ空間を共有すべきではありません。tRPCサーバーサイドでは、ルーター内の単一のrecordフィールドではなく（前述のDecoratedProcedureUtilsRecord参照）、異なるフィールドに型を格納する作業が必要でした。

v9ルーターがv10ルーターに変換される際、プロシージャをlegacyフィールドに注入するように変更しました。

変更前の型:

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

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

前述のDecoratedProcedureUtilsRecord型を思い出せば、ここでLegacyV9ProcedureTagを付加してv9とv10のプロシージャを型レベルで区別し、v9プロシージャがv10クライアントから呼び出されないように強制していたことがわかります。

変更後の型:

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 */ {}>;

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 */ {}>;

これでOmitNeverKeysを削除できます。プロシージャが事前にソートされるため、ルーターのrecordプロパティ型にはすべてのv10プロシージャが含まれ、legacyプロパティ型にはすべてのv9プロシージャが含まれるようになります。巨大なDecoratedProcedureUtilsRecord型の完全な評価をTypeScriptに強制することがなくなりました。またLegacyV9ProcedureTagによるv9プロシージャのフィルタリングも不要になります。

結果はどうだったか？

新しいトレースはボトルネックが解消されたことを示しています：

大幅な改善です！型チェック時間が332msから136msへと減少しました 🤯！大局的に見れば大したことないように思えるかもしれませんが、これは大きな勝利です。200msは一度きりなら小さいものですが、以下の点を考慮してください：

プロジェクト内に存在する他のTSライブラリの数
現在tRPCを使用している開発者の数
作業セッション中に型が再評価される回数

これらを考慮すると、200msという時間が積み上がって非常に大きな数字になります。

私たちは常にTypeScript開発者の体験向上の機会を探しています。tRPCに関連するものか、他のプロジェクトで解決すべきTSベースの問題かは問いません。TypeScriptについて話したい方は、Twitterで@s4chinrajaまでメンションしてください。

この記事の執筆を手伝ってくれたAnthony Shewと、レビューを担当してくれたAlexに感謝します！

tRPC v10 のリリースを発表します

Mon, 21 Nov 2022 00:00:00 GMT

非公式ベータ版翻訳

このページは PageTurner AI で翻訳されました（ベータ版）。プロジェクト公式の承認はありません。エラーを見つけましたか？問題を報告 →

tRPCはTypeScriptの力を活用した厳密なフルスタック型バインディングにより、優れた開発者体験を提供します。API契約の乖離やコード生成は不要です。

前回のメジャーバージョンリリース（2021年8月）以降、tRPCコミュニティは著しい成長を遂げました：

本日、tRPC v10を正式リリースします。既に多くの大規模TypeScriptプロジェクトで本番環境で採用されており、広くコミュニティへ提供開始することを発表できることを嬉しく思います。

新規プロジェクトではサンプルアプリケーションでtRPC v10を学習可能です。既にv9をご利用の方は移行ガイドをご参照ください。

変更点の概要

v10はtRPC史上最大のリリースです。初めて中核構造に根本的な変更を加え、最先端アプリケーションを開発する高速チームに新たな可能性を開きます。

開発者体験の向上

tRPC v10はIDEとの親和性を強化。型の統一だけでなく、フロントエンド・バックエンド・編集体験を統合しました。

v10では以下が可能です：

フロントエンドの呼び出し元からバックエンドプロシージャへ「定義へ移動」で直接ジャンプ
入力引数やプロシージャ名を「シンボルの名前変更」でアプリケーション全体へ反映
手動でtRPC型を使用する際の型推論が容易に

強力なバックエンド基盤

v10ではバックエンドプロシージャ定義構文を見直し、健全なロジック統合の機会を拡大。本バージョンの特徴：

TypeScriptパフォーマンスの大幅改善

TypeScriptは強力ですが代償を伴います。型を厳密に保つ技法の多くはTypeScriptコンパイラに高負荷をかけ、大規模アプリケーションではIDEパフォーマンス低下が課題となっていました。

あらゆる規模のアプリケーションで開発者体験を向上させるため、v10ではTypeScriptパフォーマンス（特に増分コンパイル時）を劇的に改善し、エディタの応答性を維持します。

段階的な移行

移行体験の簡素化にも注力し、v9ルーターとの（ほぼ）完全な後方互換性を提供するinterop()メソッドを実装。移行ガイドで詳細を確認ください。

コアチームのSachinは移合作業を自動化するコードモッドも開発しました。

拡大するエコシステム

tRPCを中心に豊富なサブライブラリが形成中です。代表例：

REST互換エンドポイント作成用trpc-openapi
tRPC統合Next.jsアプリ構築用create-t3-app
React Nativeアプリ起動用create-t3-turbo
Chrome拡張開発用trpc-chrome
Solid、Svelte、Vue向けアダプター

その他プラグイン・サンプル・アダプターはAwesome tRPCコレクションで。

感謝を込めて

コアチーム一同から伝えたい：私たちの旅は始まったばかりです。現在React Server ComponentsとNext.js 13の実験を推進中。

Sachin、Julius、James、Ahmed、Chris、Theo、Anthony、そして全てのコントリビューターの皆様に心から感謝します。

tRPCのご利用とご支援に感謝申し上げます。

tRPCの紹介

Wed, 05 May 2021 00:00:00 GMT

非公式ベータ版翻訳

このページは PageTurner AI で翻訳されました（ベータ版）。プロジェクト公式の承認はありません。エラーを見つけましたか？問題を報告 →

tRPCは（Node.js）サーバーからクライアントまでエンドツーエンドの型安全性を提供します。しかも_型を宣言する必要すらありません_。バックエンドで行うのは関数内でデータを返すことだけ。フロントエンドではエンドポイント名に基づいてそのデータを使用するだけです。

👋 GitHubでは「KATT」として活動しているAlexです。皆さんにtRPCというライブラリを紹介したいと思います。まだこれに関する記事は公開していませんが、まずはこのイントロダクションで始動します（GitHubでは既に530🌟を超えています！）。今後記事や動画での紹介を予定しています！最新情報を追いたい方や質問がある方は、Twitterで@alexdotjsをフォローしてください。

tRPCエンドポイントとクライアント呼び出しの例:

React向けライブラリ（@trpc/react）は優れたreact-queryの上に構築されていますが、クライアントライブラリ（@trpc/client）はReactなしでも動作します（Svelte/Vue/Angular向けの専用ライブラリを開発したい方はぜひご連絡ください！）。

コード生成は不要で、既存のNext.js/CRA/Expressプロジェクトに簡単に追加できます。

例

以下はhelloという名前のtRPCプロシージャ（エンドポイント）の例です。string型の引数を取ります。

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

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

そして型安全なクライアントでの使用例:

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

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

これだけで型安全性が実現されます！ resultの型はバックエンド関数が返す内容から推論されます。入力データの型もバリデータの戻り値から推論されるため、データをそのまま安全に使用できます。実際、入力データは必ずバリデータを通す必要があります（tRPCはzod/yup/カスタムバリデータをすぐに利用可能です）。

上記の例を試せるCodeSandboxリンク: https://githubbox.com/trpc/trpc/tree/main/examples/standalone-server (プレビューではなくターミナル出力を確認してください！)

待って？バックエンドのコードをクライアントにインポートしてるの？ - いえ、実際には違います

一見そう見えますが、サーバーからクライアントへコードは共有されていません。TypeScriptのimport typeは「型注釈と宣言に使用される宣言のみをインポートします。常に完全に消去されるため、実行時には痕跡も残りません。」- TypeScript 3.8で追加された機能です - TypeScriptドキュメント参照。

コード生成は不要で、サーバーからクライアントに型を共有する方法があれば（できればモノレポを使用している場合）、今日からアプリに導入できます。

しかし、これは始まりに過ぎません！

前述したReactライブラリを使用する場合、以下のようにデータを利用します:

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

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

..これでクライアント側で型安全なデータが得られます。

既存のブラウンフィールドプロジェクト（Express/Next.js用アダプタあり）にtRPCを追加可能で、CRAとも互換性があり、React Nativeでも動作するはずです。Reactに縛られていないため、SvelteやVue向けライブラリを開発したい方はぜひご連絡ください。

データの変更は？

ミューテーションはクエリと同様にシンプルで、内部的には同じものです。構文糖として別途公開されており、HTTP POSTリクエストを生成する点が異なります。

データベースを使用したもう少し複雑な例をご紹介します。これはTodoMVCのサンプル（todomvc.trpc.io）から引用したものです。詳細はGitHubリポジトリをご覧ください: 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;
  },
});

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

この場合のReactでの実装は以下のようになります:

tsx
const addTask = trpc.useMutation('todos.add');
return (
  <>
    <input
      placeholder="What needs to be done?"
      onKeyDown={(e) => {
        const text = e.currentTarget.value.trim();
        if (e.key === 'Enter' && text) {
          addTask.mutate({ text });
          e.currentTarget.value = '';
        }
      }}
    />
  
)

tsx
const addTask = trpc.useMutation('todos.add');
return (
  <>
    <input
      placeholder="What needs to be done?"
      onKeyDown={(e) => {
        const text = e.currentTarget.value.trim();
        if (e.key === 'Enter' && text) {
          addTask.mutate({ text });
          e.currentTarget.value = '';
        }
      }}
    />
  
)

ひとまずここまで

冒頭でも述べたように、今回は導入編として基本的な内容をご紹介しました。さらに多くの機能が用意されています:

リゾルバに依存性注入するユーザー固有のリクエストコンテキスト作成 - リンク
ルーター向けミドルウェアサポート - リンク
ルーターの統合（全バックエンドロジックを単一ファイルに置きたくない場合に有用） - リンク
React環境で実現する最もシンプルなサーバーサイドレンダリング（@trpc/nextアダプター使用） - リンク
型安全なエラーフォーマット - リンク
データトランスフォーマー（Date/Map/Setオブジェクトをクライアント-サーバー間で転送） - リンク
React Query向けヘルパー機能

実際に始めるには、Next.js向けスタートガイドにいくつかのサンプルが用意されています。

最新情報はTwitterでフォローしてください！

tRPC Blog

tRPC v11の発表

変更点の概要​

TanStack Query v5サポート​

新しいTanStack React Query統合​

FormData / 非JSONコンテンツタイプのサポート​

React Server Components と Next.js App Router​

クエリとミューテーションからのストリーミング応答​

ルーター定義の短縮構文​

サブスクリプション：Server-Sent Eventsとその他の改良​

v9 .interop()モードの終焉​

v11への移行​

感謝を込めて​

新たなTanStack React Query統合のご紹介

なぜ変更するのか？​

従来のtRPC React Query統合はどうなる？​

移行方法​

tRPCでServer Actionsを使う

Server Actionとは？​

tRPCでServer Actionsを定義する​

さらに発展させる​

オブザーバビリティ​

レート制限​

まとめ​

ご意見をお聞かせください​

小さなtRPCクライアントを作成する

概要​

小さなtRPCクライアントの実装​

🧙‍♀️ TypeScriptのマジック​

🤯 Proxyを使ったリマッピング​

🧩 すべてを組み合わせる​

試してみよう！​

まとめ​

v10リファクタリングで学んだTypeScriptパフォーマンスの教訓

ライブラリパフォーマンスの自動化​

tRPCにおけるパフォーマンス改善の機会をどう発見したか​

遅延評価​

遅延評価の導入​

結果はどうだったか？​

tRPC v10 のリリースを発表します

変更点の概要​

開発者体験の向上​

強力なバックエンド基盤​

TypeScriptパフォーマンスの大幅改善​

段階的な移行​

拡大するエコシステム​

感謝を込めて​

tRPCの紹介

例​

しかし、これは始まりに過ぎません！​

データの変更は？​

ひとまずここまで​

変更点の概要

TanStack Query v5サポート

新しいTanStack React Query統合

FormData / 非JSONコンテンツタイプのサポート

React Server Components と Next.js App Router

クエリとミューテーションからのストリーミング応答

ルーター定義の短縮構文

サブスクリプション：Server-Sent Eventsとその他の改良

v9 `.interop()`モードの終焉

v11への移行

感謝を込めて

なぜ変更するのか？

従来のtRPC React Query統合はどうなる？

移行方法

Server Actionとは？

tRPCでServer Actionsを定義する

さらに発展させる

オブザーバビリティ

レート制限

まとめ

ご意見をお聞かせください

概要

小さなtRPCクライアントの実装

🧙‍♀️ TypeScriptのマジック

🤯 Proxyを使ったリマッピング

🧩 すべてを組み合わせる

試してみよう！

まとめ

ライブラリパフォーマンスの自動化

tRPCにおけるパフォーマンス改善の機会をどう発見したか

遅延評価

遅延評価の導入

結果はどうだったか？

変更点の概要

開発者体験の向上

強力なバックエンド基盤

TypeScriptパフォーマンスの大幅改善

段階的な移行

拡大するエコシステム

感謝を込めて

例

しかし、これは始まりに過ぎません！

データの変更は？

ひとまずここまで