0Pricing
tRPC End-to-End Type Safe APIs · 课时

实现实时数据订阅

创建 tRPC 订阅过程，将实时更新从服务器推送到已连接的客户端。

实现实时数据订阅 是 CoddyKit 上的免费 tRPC End-to-End Type Safe APIs 课时。 这是第 3 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 tRPC End-to-End Type Safe APIs 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 tRPC End-to-End Type Safe APIs 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

Real-time Data with Subscriptions

Welcome to the final lesson on tRPC real-time! We've learned about WebSockets, now let's build live data features.

Subscriptions in tRPC allow your server to push real-time updates to connected clients. Unlike queries (which pull data) or mutations (which modify data), subscriptions are push-based.

  • Queries: Client asks, server responds once.
  • Mutations: Client sends data, server performs action, responds once.
  • Subscriptions: Client asks once, server sends updates over time.

Defining Server Subscriptions

To create a subscription on your tRPC server, you use the createSubscription helper, similar to createQuery or createMutation.

A key difference is that a subscription procedure returns an observable. An observable is a stream of data that can emit multiple values over time.

Let's look at the basic structure.

The Observable Pattern

When defining a subscription, you'll use an observable pattern. This involves a function that receives an emit function and returns a cleanup function.

  • The emit function is what you call to send data to clients.
  • The cleanup function (returned by your subscription logic) runs when a client unsubscribes.

This allows you to manage resources like event listeners or intervals.

Server Code: Basic Live Counter

Here's a simple tRPC server-side subscription that emits a number every second. This number could represent anything, like a live user count.

import { router, publicProcedure } from './trpc';
import { observable } from '@trpc/server/observable';

export const appRouter = router({
  onUpdate: publicProcedure.subscription(() => {
    // This is where we create the observable
    return observable<number>((emit) => {
      let count = 0;
      const interval = setInterval(() => {
        count++;
        emit.next(count); // Push new data to clients
      }, 1000);

      // Return a cleanup function
      return () => {
        clearInterval(interval);
      };
    });
  }),
});

// This code is illustrative and not directly runnable
// without a full Node.js server setup.
// For context, 'router' and 'publicProcedure' would be
// initialized from '@trpc/server'.

Understanding the Server Flow

In the previous example:

  • publicProcedure.subscription(() => {...}) defines the subscription endpoint.
  • observable((emit) => {...}) creates a data stream that will send number types.
  • emit.next(count) is called repeatedly inside setInterval to push the current count to all subscribed clients.
  • The returned function () => { clearInterval(interval); } ensures the interval stops when a client disconnects or unsubscribes, preventing memory leaks.

Consuming Subscriptions on the Client

On the client-side, tRPC provides a convenient hook for consuming subscriptions, typically trpc.useSubscription if you're using React Query.

This hook works similarly to useQuery but maintains an open connection and updates your component whenever new data arrives from the server.

Client Code: React Component Example

Here's a React component that subscribes to our onUpdate procedure and displays the live counter. Notice how data updates automatically.

import React from 'react';

// Mock tRPC client for runnable example
const mockTRPCClient = {
  onUpdate: {
    subscribe: (opts) => {
      let count = 0;
      const interval = setInterval(() => {
        count++;
        opts.onData(count); // Simulate server pushing data
      }, 1000);
      return { // Return unsubscribe function
        unsubscribe: () => clearInterval(interval),
      };
    },
  },
};

// Mock useSubscription hook
const useSubscription = (path, input, { onData, onError }) => {
  React.useEffect(() => {
    const subscription = mockTRPCClient[path].subscribe({
      onData,
      onError,
    });
    return () => subscription.unsubscribe();
  }, [path, input, onData, onError]);
};

function LiveCounter() {
  const [currentCount, setCurrentCount] = React.useState(0);

  useSubscription(
    'onUpdate', // Path to your tRPC subscription
    undefined,  // No input for this subscription
    {
      onData(data) {
        setCurrentCount(data); // Update state with new data
      },
      onError(err) {
        console.error('Subscription error:', err);
      },
    }
  );

  return (
    <div>
      <h3>Live Counter:</h3>
      <p>Current value: <b>{currentCount}</b></p>
    </div>
  );
}

// This would be rendered by a framework like React.
// For runnable purposes, we can simulate a main entry point.
export default function Main() {
  return <LiveCounter />;
}

Subscriptions with Input

Just like queries and mutations, subscriptions can accept input. This is incredibly useful for filtering or customizing the data stream for each client.

For example, you might subscribe to updates for a specific productId or a particular chat roomName.

You'll define the input schema using Zod on the server and pass the input object on the client.

Code: Subscription with Input

Here's how you'd define a subscription that takes a topic string as input on the server, and how a client would use it.

/* --- SERVER-SIDE (Illustrative) --- */
import { z } from 'zod';
import { router, publicProcedure } from './trpc';
import { observable } from '@trpc/server/observable';

export const appRouterWithInput = router({
  onTopicUpdate: publicProcedure
    .input(z.object({ topic: z.string() })) // Define input schema
    .subscription(({ input }) => {
      return observable<string>((emit) => {
        // Simulate updates for a specific topic
        const interval = setInterval(() => {
          emit.next(`Update for '${input.topic}': ${Date.now()}`);
        }, 2000);
        return () => clearInterval(interval);
      });
    }),
});

/* --- CLIENT-SIDE (React Component) --- */
import React from 'react';

// Mock tRPC client for runnable example
const mockTRPCClientWithInput = {
  onTopicUpdate: {
    subscribe: (input, opts) => {
      const interval = setInterval(() => {
        opts.onData(`Update for '${input.topic}': ${Date.now()}`);
      }, 2000);
      return {
        unsubscribe: () => clearInterval(interval),
      };
    },
  },
};

// Mock useSubscription hook for runnable example
const useSubscriptionWithInput = (path, input, { onData, onError }) => {
  React.useEffect(() => {
    const subscription = mockTRPCClientWithInput[path].subscribe(
      input,
      { onData, onError }
    );
    return () => subscription.unsubscribe();
  }, [path, input, onData, onError]);
};

function TopicUpdates({ topic }) {
  const [latestUpdate, setLatestUpdate] = React.useState('');

  useSubscriptionWithInput(
    'onTopicUpdate', 
    { topic }, // Pass the input object
    {
      onData(data) {
        setLatestUpdate(data);
      },
      onError(err) {
        console.error('Subscription error:', err);
      },
    }
  );

  return (
    <div>
      <h4>Topic: {topic}</h4>
      <p>{latestUpdate}</p>
    </div>
  );
}

export default function Main() {
  return (
    <div>
      <TopicUpdates topic="news" />
      <TopicUpdates topic="sports" />
    </div>
  );
}

Best Practices for Subscriptions

When working with tRPC subscriptions, consider these best practices:

  • Cleanup: Always return a cleanup function from your observable to release resources (e.g., clear intervals, close database connections).
  • Error Handling: Implement onError callbacks on the client to gracefully handle subscription errors.
  • Rate Limiting: Be mindful of how frequently you emit data to avoid overwhelming clients or your server.
  • When to Use: Subscriptions are great for truly real-time data. For less critical updates, traditional queries with polling or client-side caching might be sufficient.
  • Authentication/Authorization: Use tRPC middleware to protect subscription procedures, ensuring only authorized users receive updates.

Quick Check: Subscription Basics

You've defined a tRPC subscription that emits a string every 5 seconds. Which part of the client-side useSubscription hook would you use to process each incoming string?

Recap: Live Data Subscriptions

In this lesson, you've learned to implement live data subscriptions with tRPC:

  • Server-side: Define subscription procedures using publicProcedure.subscription and return an observable.
  • Observable Logic: Use the emit.next() function to push data and return a cleanup function.
  • Client-side: Consume subscriptions using trpc.useSubscription, providing an onData callback to handle incoming real-time updates.
  • Input: Pass arguments to subscriptions for filtered or customized data streams.

Congratulations! You can now build powerful real-time features with tRPC's end-to-end type safety.

常见问题解答

「实现实时数据订阅」课时是免费的吗？

是的 — 「实现实时数据订阅」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 tRPC End-to-End Type Safe APIs 课程的其余内容，请升级到 CoddyKit PRO。 tRPC End-to-End Type Safe APIs 课程共包含 4 节课。

「实现实时数据订阅」这节课中我会学到什么？

创建 tRPC 订阅过程，将实时更新从服务器推送到已连接的客户端。 你通过在浏览器中直接运行的动手代码来练习 tRPC End-to-End Type Safe APIs，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 tRPC End-to-End Type Safe APIs 需要有经验吗？

无需任何先前经验。CoddyKit 上的 tRPC End-to-End Type Safe APIs 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 3 节课，共 4 节。

「实现实时数据订阅」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 tRPC End-to-End Type Safe APIs 课中编写并运行代码吗？

能。每节 tRPC End-to-End Type Safe APIs 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. tRPC 实时通信简介
  2. 设置用于订阅的 WebSockets
  3. 实现实时数据订阅
  4. 处理重新连接与订阅清理
← 返回 tRPC End-to-End Type Safe APIs