useSubscription()

비공식 베타 번역

이 페이지는 PageTurner AI로 번역되었습니다(베타). 프로젝트 공식 승인을 받지 않았습니다. 오류를 발견하셨나요? 문제 신고 →

useSubscription 훅은 서버의 구독(subscription) 프로시저를 구독하는 데 사용할 수 있습니다.

시그니처

옵션

팁

• 옵션 설정이 필요하지만 입력값을 전달하지 않으려면 undefined를 전달할 수 있습니다.
• @tanstack/react-query의 skipToken을 전달하면 구독이 일시 중지됩니다.
• 구독 사용법의 완전한 예시는 SSE 예제를 참고하세요

tsx
function useSubscription<TOutput, TError>(
  input: TInput | SkipToken,
  opts?: UseTRPCSubscriptionOptions<TOutput, TError>,
): TRPCSubscriptionResult<TOutput, TError>;
interface UseTRPCSubscriptionOptions<TOutput, TError> {
  /**
   * Callback invoked when the subscription starts.
   */
  onStarted?: () => void;
  /**
   * Callback invoked when new data is received from the subscription.
   * @param data - The data received.
   */
  onData?: (data: TOutput) => void;
  /**
   * Callback invoked when an **unrecoverable error** occurs and the subscription is stopped.
   */
  onError?: (error: TError) => void;
  /**
   * Callback invoked when the subscription is completed.
   */
  onComplete?: () => void;
  /**
   * @deprecated Use a `skipToken` from `@tanstack/react-query` instead.
   * This will be removed in a future version.
   */
  enabled?: boolean;
}

tsx
function useSubscription<TOutput, TError>(
  input: TInput | SkipToken,
  opts?: UseTRPCSubscriptionOptions<TOutput, TError>,
): TRPCSubscriptionResult<TOutput, TError>;
interface UseTRPCSubscriptionOptions<TOutput, TError> {
  /**
   * Callback invoked when the subscription starts.
   */
  onStarted?: () => void;
  /**
   * Callback invoked when new data is received from the subscription.
   * @param data - The data received.
   */
  onData?: (data: TOutput) => void;
  /**
   * Callback invoked when an **unrecoverable error** occurs and the subscription is stopped.
   */
  onError?: (error: TError) => void;
  /**
   * Callback invoked when the subscription is completed.
   */
  onComplete?: () => void;
  /**
   * @deprecated Use a `skipToken` from `@tanstack/react-query` instead.
   * This will be removed in a future version.
   */
  enabled?: boolean;
}

반환 타입

ts
type TRPCSubscriptionResult<TOutput, TError> = {
  /**
   * The current status of the subscription.
   * Will be one of: `'idle'`, `'connecting'`, `'pending'`, or `'error'`.
   *
   * - `idle`: subscription is disabled or ended
   * - `connecting`: trying to establish a connection
   * - `pending`: connected to the server, receiving data
   * - `error`: an error occurred and the subscription is stopped
   */
  status: 'idle' | 'connecting' | 'pending' | 'error';
  /**
   * The last data received from the subscription.
   */
  data: TOutput | undefined;
  /**
   * The last error received - will be `null` whenever the status is `'pending'` or `'idle'`
   * - has a value only when the status is `'error'`
   * - *may* have a value when the status is `'connecting'`
   */
  error: TRPCClientError | null;
  /**
   * Function to reset the subscription.
   */
  reset: () => void;
};

ts
type TRPCSubscriptionResult<TOutput, TError> = {
  /**
   * The current status of the subscription.
   * Will be one of: `'idle'`, `'connecting'`, `'pending'`, or `'error'`.
   *
   * - `idle`: subscription is disabled or ended
   * - `connecting`: trying to establish a connection
   * - `pending`: connected to the server, receiving data
   * - `error`: an error occurred and the subscription is stopped
   */
  status: 'idle' | 'connecting' | 'pending' | 'error';
  /**
   * The last data received from the subscription.
   */
  data: TOutput | undefined;
  /**
   * The last error received - will be `null` whenever the status is `'pending'` or `'idle'`
   * - has a value only when the status is `'error'`
   * - *may* have a value when the status is `'connecting'`
   */
  error: TRPCClientError | null;
  /**
   * Function to reset the subscription.
   */
  reset: () => void;
};

예시

components/MyComponent.tsx
tsx
import { trpc } from '../utils/trpc';
export function MyComponent() {
  const [numbers, setNumbers] = React.useState<number[]>([]);
  const result = trpc.onNumber.useSubscription(undefined, {
    onData: (num) => {
      setNumbers((prev) => [...prev, num]);
    },
  });
  return (
    <div>
      <h1>Subscription Example</h1>
      <p>
        {result.status}: <pre>{JSON.stringify(result.data, null, 2)}</pre>
      </p>
      <h2>Previous numbers:</h2>
      <ul>
        {numbers.map((num, i) => (
          <li key={i}>{num}</li>
        ))}
      </ul>
      {result.status === 'error' && (
        <button onClick={() => result.reset()}>
          Something went wrong - restart the subscription
        </button>
      )}
    </div>
  );
}

components/MyComponent.tsx
tsx
import { trpc } from '../utils/trpc';
export function MyComponent() {
  const [numbers, setNumbers] = React.useState<number[]>([]);
  const result = trpc.onNumber.useSubscription(undefined, {
    onData: (num) => {
      setNumbers((prev) => [...prev, num]);
    },
  });
  return (
    <div>
      <h1>Subscription Example</h1>
      <p>
        {result.status}: <pre>{JSON.stringify(result.data, null, 2)}</pre>
      </p>
      <h2>Previous numbers:</h2>
      <ul>
        {numbers.map((num, i) => (
          <li key={i}>{num}</li>
        ))}
      </ul>
      {result.status === 'error' && (
        <button onClick={() => result.reset()}>
          Something went wrong - restart the subscription
        </button>
      )}
    </div>
  );
}