Queries, mutacje i subskrypcje

Do publicProcedure należy dołączyć .input(zodSchema).query(async ({ input, ctx }) => ...). Handler otrzymuje zweryfikowane dane wejściowe oraz kontekst żądania. Może zwrócić dowolną wartość możliwą do serializacji: obiekt, tablicę lub wartość prostą.

Typ zwracany jest automatycznie wywnioskowywany i staje się typem danych odpowiedniego hooka useQuery po stronie klienta.

trpc.post.getById.useQuery({ id: '1' }) wywołuje procedurę getById w routerze post. Hook zwraca znany obiekt wynikowy React Query: { data, isLoading, isError, refetch }.

Obiekt wejściowy jest typowany statycznie: przekazanie { id: 123 }, gdy schemat oczekuje ciągu znaków, powoduje błąd TypeScript wykrywany podczas programowania.

Do operacji zapisu po stronie serwera — tworzenia, aktualizowania lub usuwania danych — należy użyć .input(zodSchema).mutation(async ({ input, ctx }) => ...). Mutacje wywołuje się jawnie, a nie automatycznie podczas montowania komponentu.

Handler mutacji ma za pośrednictwem ctx dostęp do pełnego kontekstu żądania, w tym do sesji z NextAuth.

const { mutate, isLoading, error } = trpc.post.create.useMutation(). Aby uruchomić mutację, należy wywołać mutate({ title: 'New', content: '...' }). Podobnie jak useMutation w React Query, nie wykonuje się ona podczas montowania komponentu.

Do opcji useMutation należy przekazać funkcje zwrotne onSuccess i onError, aby obsłużyć działania wykonywane po mutacji.

Aby odświeżyć dane zapytania po pomyślnym zakończeniu mutacji, należy użyć hooka narzędzi tRPC: const utils = trpc.useUtils(). W onSuccess należy wywołać utils.post.getAll.invalidate(), aby uruchomić ponowne pobranie listy postów.

Jest to odpowiednik tRPC metody React Query queryClient.invalidateQueries() i działa według tego samego schematu oznaczania danych jako nieaktualnych i ponownego ich pobierania.

tRPC domyślnie używa biblioteki Zod do walidacji danych wejściowych. Schemat Zod jest wykonywany na serwerze w czasie działania i odrzuca niepoprawne dane, zanim dotrą one do handlera. Ten sam schemat dostarcza typów TypeScript klientowi.

Ta podwójna rola (walidacja w czasie działania i typy TypeScript) eliminuje powielanie: kontrakt definiuje się raz w Zod, uzyskując bez dodatkowej pracy oba mechanizmy bezpieczeństwa.

Domyślnie tRPC używa httpBatchLink, który łączy wiele równoczesnych żądań tRPC w jedno żądanie HTTP. Wiele wywołań useQuery w tym samym cyklu renderowania komponentu jest wysyłanych i rozwiązywanych razem.

Znacznie ogranicza to narzut sieciowy w porównaniu z wysyłaniem osobnego żądania HTTP dla każdego zapytania na stronie wymagającej wielu zestawów danych.

Należy zdefiniować procedurę subskrypcji: publicProcedure.subscription(async function*() { while (true) { yield await nextEvent(); } }). Subskrypcje korzystają z generatorów asynchronicznych i wymagają transportu WebSocket.

Subskrypcje doskonale nadają się do funkcji działających w czasie rzeczywistym: bieżących powiadomień, kursorów używanych podczas wspólnej edycji lub strumieniowanych odpowiedzi AI.

Należy zastąpić httpBatchLink połączeniem httpBatchLink i wsLink za pomocą splitLink: przekierować subskrypcje do wsLink, a zapytania i mutacje do httpBatchLink. Klienta WebSocket należy utworzyć za pomocą createWSClient({ url: 'ws://localhost:3000' }).

Taki hybrydowy transport oznacza, że większość żądań korzysta z wydajnego grupowania HTTP, a subskrypcje z trwałych połączeń WebSocket.

trpc.notifications.onNew.useSubscription(undefined, { onData: (notification) => addToList(notification), onError: console.error }) subskrybuje procedurę. Funkcja zwrotna onData jest wywoływana dla każdej zwróconej wartości.

Subskrypcja jest automatycznie ustanawiana ponownie po rozłączeniu i ponownym połączeniu WebSocket.

Rzeczywista strona z listą aktualizowaną w czasie rzeczywistym może używać zapytania do załadowania początkowej listy, mutacji do dodawania elementu oraz subskrypcji do odbierania na bieżąco elementów dodawanych przez innych użytkowników. Wszystkie trzy elementy są typowane względem tego samego AppRouter i naturalnie ze sobą współdziałają.

Strategia unieważniania pamięci podręcznej zależy od tego, czy preferuje się pełne ponowne pobieranie danych (invalidate po mutacji), czy aktualizowanie pamięci podręcznej (utils.post.getAll.setData).

Jaką metodą narzędzi tRPC można uruchomić ponowne pobranie zapytania po pomyślnym zakończeniu mutacji?

Zapytania definiuje się za pomocą .query(), a mutacje za pomocą .mutation(); oba rodzaje są sprawdzane przez schematy Zod. Po stronie klienta należy używać trpc.router.procedure.useQuery() i useMutation(). Po mutacji należy unieważniać zapytania za pomocą utils.procedure.invalidate(). Subskrypcje korzystają z generatorów asynchronicznych i wymagają wsLink jako transportu WebSocket.

Domyślnie httpBatchLink łączy równoczesne zapytania w jedno żądanie HTTP.