TanStack Query

bun add @tanstack/react-query
bun add -d @tanstack/react-query-devtools
bun add -d @tanstack/eslint-plugin-query  # optional
# npm i @tanstack/react-query
# pnpm add @tanstack/react-query

import {
  QueryClient,
  QueryClientProvider,
} from "@tanstack/react-query";
import {
  ReactQueryDevtools,
} from "@tanstack/react-query-devtools";
import { createRoot } from "react-dom/client";
import { App } from "./app";
 
const queryClient = new QueryClient({
  defaultOptions: {
    queries: { staleTime: 30_000 },
  },
});
 
createRoot(document.getElementById("root")!).render(
  <QueryClientProvider client={queryClient}>
    <App />
    <ReactQueryDevtools initialIsOpen={false} />
  </QueryClientProvider>,
);

export type TodoStatus = "all" | "open" | "done";
 
export const todoKeys = {
  all: ["todos"] as const,
  lists: () => [...todoKeys.all, "list"] as const,
  list: (status: TodoStatus) =>
    [...todoKeys.lists(), { status }] as const,
  details: () => [...todoKeys.all, "detail"] as const,
  detail: (id: string) =>
    [...todoKeys.details(), id] as const,
};

import { useQuery } from "@tanstack/react-query";
 
type Todo = { id: string; title: string; done: boolean };
 
async function getTodo(id: string, signal: AbortSignal) {
  const res = await fetch(`/api/todos/${id}`, { signal });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return (await res.json()) as Todo;
}
 
export function useTodo(id: string) {
  return useQuery({
    queryKey: ["todos", "detail", id],
    queryFn: ({ signal }) => getTodo(id, signal),
  }); // UseQueryResult<Todo, Error>
}

import { useTodo } from "./use-todo";
 
function TodoTitle({ id }: { id: string }) {
  const { data, error, isPending, isFetching } = useTodo(id);
  if (isPending) return <p>Loading…</p>;
  if (error) return <p>{error.message}</p>;
  return <h2>{data.title}{isFetching && " ↻"}</h2>;
}

import { queryOptions } from "@tanstack/react-query";
import { z } from "zod";
import { fetchJson } from "@/lib/fetch-json";
import { todoKeys, type TodoStatus } from "./todo-keys";
 
export const Todo = z.object({
  id: z.string(),
  title: z.string(),
  done: z.boolean(),
});
export type Todo = z.infer<typeof Todo>;
 
export const todoListOptions = (status: TodoStatus) =>
  queryOptions({
    queryKey: todoKeys.list(status),
    queryFn: ({ signal }) =>
      fetchJson(
        `/api/todos?status=${status}`,
        z.array(Todo),
        { signal },
      ),
    staleTime: 30_000,
  });
 
export const todoOptions = (id: string) =>
  queryOptions({
    queryKey: todoKeys.detail(id),
    queryFn: ({ signal }) =>
      fetchJson(`/api/todos/${id}`, Todo, { signal }),
  });

import {
  type QueryClient,
  useQuery,
} from "@tanstack/react-query";
import {
  todoListOptions,
  todoOptions,
} from "@/queries/todos";
 
declare const qc: QueryClient;
const { queryKey } = todoListOptions("open");
 
const list = qc.getQueryData(queryKey); // Todo[] | undefined
qc.setQueryData(queryKey, (old) => old?.slice(0, 10));
 
export function useOpenCount() {
  return useQuery({
    ...todoListOptions("open"),
    select: (todos) => todos.length,       // number
  });
}
await qc.query(todoOptions("1"));        // Promise<Todo>

import {
  skipToken,
  useQueries,
  useQuery,
} from "@tanstack/react-query";
import { todoOptions } from "@/queries/todos";
 
type User = { id: string; teamId: string | null };
declare function getUser(e: string): Promise<User>;
declare function getTeam(id: string): Promise<string[]>;
 
export function useTeam(email: string) {
  const user = useQuery({
    queryKey: ["user", email],
    queryFn: () => getUser(email),
  });
  const teamId = user.data?.teamId;
  return useQuery({                  // waits for user
    queryKey: ["team", teamId],
    queryFn: teamId ? () => getTeam(teamId) : skipToken,
  });
}
 
export function useTodosById(ids: string[]) {
  return useQueries({          // parallel, dynamic count
    queries: ids.map((id) => todoOptions(id)),
    combine: (rs) => ({
      todos: rs.flatMap((r) => (r.data ? [r.data] : [])),
      pending: rs.some((r) => r.isPending),
    }),
  });
}

"use client";
import { useSuspenseQuery } from "@tanstack/react-query";
import { todoOptions } from "@/queries/todos";
 
export function TodoView({ id }: { id: string }) {
  const { data } = useSuspenseQuery(todoOptions(id));
  return <h1>{data.title}</h1>; // data: Todo, defined
}

import { Suspense } from "react";
import { ErrorBoundary } from "react-error-boundary";
import { TodoView } from "@/components/todo-view";
 
export const Page = ({ id }: { id: string }) => (
  <ErrorBoundary fallback={<p>Failed to load</p>}>
    <Suspense fallback={<p>Loading…</p>}>
      <TodoView id={id} />
    </Suspense>
  </ErrorBoundary>
);

import {
  keepPreviousData,
  useQuery,
} from "@tanstack/react-query";
 
type PageOf<T> = { items: T[]; hasMore: boolean };
declare function getPage(p: number): Promise<PageOf<string>>;
 
export function usePage(page: number) {
  return useQuery({
    queryKey: ["projects", { page }],
    queryFn: () => getPage(page),
    placeholderData: keepPreviousData, // no page flash
  });
}
// isPlaceholderData: old page is on screen, disable "Next"

import { infiniteQueryOptions } from "@tanstack/react-query";
 
type Item = { id: string; text: string };
type Page = { items: Item[]; next: string | null };
declare function getFeed(
  cursor: string,
  signal: AbortSignal,
): Promise<Page>;
 
export const feedOptions = infiniteQueryOptions({
  queryKey: ["feed"],
  queryFn: ({ pageParam, signal }) =>
    getFeed(pageParam, signal),
  initialPageParam: "",        // TPageParam = string
  getNextPageParam: (last) => last.next, // null: no more
  select: (d) => d.pages.flatMap((p) => p.items), // Item[]
});

import {
  useMutation,
  useQueryClient,
} from "@tanstack/react-query";
import { todoKeys } from "@/queries/todo-keys";
import type { Todo } from "@/queries/todos";
 
declare function postTodo(title: string): Promise<Todo>;
 
export function AddTodo() {
  const qc = useQueryClient();
  const add = useMutation({
    mutationKey: ["todos", "add"],
    mutationFn: postTodo,
    onSuccess: (todo) => {
      qc.setQueryData(todoKeys.detail(todo.id), todo);
      // return the promise: isPending lasts until refetched
      return qc.invalidateQueries({
        queryKey: todoKeys.lists(),
      });
    },
  });
  return (
    <form
      action={(fd) => add.mutate(String(fd.get("title")))}
    >
      <input name="title" disabled={add.isPending} />
      {add.error && <p>{add.error.message}</p>}
    </form>
  );
}

import {
  useMutation,
  useQuery,
} from "@tanstack/react-query";
import { todoKeys } from "@/queries/todo-keys";
import { todoListOptions } from "@/queries/todos";
 
declare function postTodo(title: string): Promise<unknown>;
 
export function TodoList() {
  const { data = [] } = useQuery(todoListOptions("all"));
  const add = useMutation({
    mutationFn: postTodo,
    onSettled: (_d, _e, _v, _r, { client }) =>
      client.invalidateQueries({ queryKey: todoKeys.all }),
  });
  return (
    <ul>
      {data.map((t) => <li key={t.id}>{t.title}</li>)}
      {add.isPending && (
        <li style={{ opacity: 0.5 }}>{add.variables}</li>
      )}
    </ul>
  );
}

import {
  defaultShouldDehydrateQuery,
  environmentManager,
  QueryClient,
} from "@tanstack/react-query";
 
function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: { staleTime: 60_000 }, // no instant refetch
      dehydrate: {
        shouldDehydrateQuery: (q) =>
          defaultShouldDehydrateQuery(q) ||
          q.state.status === "pending", // stream pending
        shouldRedactErrors: () => false, // let Next see them
      },
    },
  });
}
 
let browserClient: QueryClient | undefined;
 
export function getQueryClient() {
  if (environmentManager.isServer()) {
    return makeQueryClient(); // fresh per request
  }
  return (browserClient ??= makeQueryClient());
}

"use client";
import { QueryClientProvider } from "@tanstack/react-query";
import type { ReactNode } from "react";
import { getQueryClient } from "@/lib/query-client";
 
export function Providers({
  children,
}: {
  children: ReactNode;
}) {
  const client = getQueryClient(); // not useState
  return (
    <QueryClientProvider client={client}>
      {children}
    </QueryClientProvider>
  );
}

import {
  dehydrate,
  HydrationBoundary,
  noop,
} from "@tanstack/react-query";
import { getQueryClient } from "@/lib/query-client";
import { todoListOptions } from "@/queries/todos";
import { TodoList } from "@/features/todos/todo-list";
 
export default async function TodosPage() {
  const qc = getQueryClient();
  await qc.query(todoListOptions("all")).catch(noop);
  return (
    <HydrationBoundary state={dehydrate(qc)}>
      <TodoList />
    </HydrationBoundary>
  );
}

import {
  QueryCache,
  QueryClient,
  QueryErrorResetBoundary,
} from "@tanstack/react-query";
import { Suspense, type ReactNode } from "react";
import { ErrorBoundary } from "react-error-boundary";
 
declare function toast(msg: string): void;
 
export const qc = new QueryClient({
  queryCache: new QueryCache({
    // once per failed query, not per component
    onError: (err, query) => {
      if (query.state.data !== undefined) toast(err.message);
    },
  }),
});
 
export const Boundary = (p: { children: ReactNode }) => (
  <QueryErrorResetBoundary>
    {({ reset }) => (
      <ErrorBoundary
        onReset={reset}
        fallbackRender={({ resetErrorBoundary }) => (
          <button onClick={resetErrorBoundary}>Retry</button>
        )}
      >
        <Suspense fallback={<p>Loading…</p>}>
          {p.children}
        </Suspense>
      </ErrorBoundary>
    )}
  </QueryErrorResetBoundary>
);

import "@tanstack/react-query";
import type { HttpError } from "@/lib/fetch-json";
 
type Key = readonly unknown[];
 
declare module "@tanstack/react-query" {
  interface Register {
    defaultError: HttpError;   // error type everywhere
    queryMeta: { errorMessage?: string };
    mutationMeta: { invalidates?: readonly Key[] };
  }
}

import { expect, spyOn, test } from "bun:test";
import {
  QueryClient,
  QueryClientProvider,
  useQuery,
} from "@tanstack/react-query";
import { renderHook, waitFor } from "@testing-library/react";
import type { ReactNode } from "react";
import { todoOptions } from "@/queries/todos";
 
function wrapper({ children }: { children: ReactNode }) {
  const client = new QueryClient({
    defaultOptions: { queries: { retry: false } },
  });
  return (
    <QueryClientProvider client={client}>
      {children}
    </QueryClientProvider>
  );
}
 
test("loads a todo", async () => {
  const todo = { id: "1", title: "Write", done: false };
  const spy = spyOn(globalThis, "fetch").mockResolvedValue(
    Response.json(todo),
  );
  const { result } = renderHook(
    () => useQuery(todoOptions("1")),
    { wrapper },
  );
  await waitFor(() =>
    expect(result.current.isSuccess).toBe(true),
  );
  expect(result.current.data).toEqual(todo);
  spy.mockRestore();
});

import { queryOptions } from "@tanstack/react-query";
 
type User = { id: string; name: string };
type Get<T> = (arg: string, s: AbortSignal) => Promise<T>;
declare const getUsers: Get<User[]>;
declare const getUser: Get<User>;
 
const all = ["users"] as const;
 
export const userQueries = {
  all,
  lists: () => [...all, "list"] as const,
  list: (search: string) =>
    queryOptions({
      queryKey: [...all, "list", { search }] as const,
      queryFn: ({ signal }) => getUsers(search, signal),
    }),
  detail: (id: string) =>
    queryOptions({
      queryKey: [...all, "detail", id] as const,
      queryFn: ({ signal }) => getUser(id, signal),
      staleTime: 5 * 60_000,
    }),
};
// qc.invalidateQueries({ queryKey: userQueries.lists() })

import { useMutation } from "@tanstack/react-query";
import { todoKeys } from "./todo-keys";
import { todoListOptions, type Todo } from "./todos";
 
declare function patchTodo(t: Pick<Todo, "id" | "done">):
  Promise<Todo>;
const listKey = todoListOptions("all").queryKey;
 
export const useToggleTodo = () =>
  useMutation({
    mutationFn: patchTodo,
    onMutate: async ({ id, done }, { client }) => {
      await client.cancelQueries({ queryKey: listKey });
      const prev = client.getQueryData(listKey); // Todo[]
      client.setQueryData(listKey, (old) =>
        old?.map((t) => (t.id === id ? { ...t, done } : t)),
      );
      return { prev };
    },
    onError: (_e, _v, res, { client }) =>
      client.setQueryData(listKey, res?.prev),
    onSettled: (_d, _e, _v, _r, { client }) =>
      client.invalidateQueries({ queryKey: todoKeys.all }),
  });

import { useInfiniteQuery } from "@tanstack/react-query";
import { feedOptions } from "@/queries/feed";
 
export function Feed() {
  const q = useInfiniteQuery(feedOptions);
  // React 19: a ref callback may return its cleanup
  const watch = (el: HTMLLIElement | null) => {
    if (!el) return;
    const io = new IntersectionObserver(([e]) => {
      if (e?.isIntersecting) void q.fetchNextPage();
    });
    io.observe(el);
    return () => io.disconnect();
  };
  return (
    <ul>
      {q.data?.map((r) => <li key={r.id}>{r.text}</li>)}
      {q.hasNextPage && !q.isFetchingNextPage && (
        <li ref={watch} aria-hidden />
      )}
    </ul>
  );
}

import { noop, useQueryClient } from "@tanstack/react-query";
import { todoOptions } from "@/queries/todos";
 
export function TodoLink(p: { id: string; title: string }) {
  const qc = useQueryClient();
  const prefetch = () => {
    // no request while cached data is younger than 60 s
    void qc
      .query({ ...todoOptions(p.id), staleTime: 60_000 })
      .catch(noop);
  };
  return (
    <a
      href={`/todos/${p.id}`}
      onPointerEnter={prefetch}
      onFocus={prefetch}
    >
      {p.title}
    </a>
  );
}

import {
  dehydrate,
  HydrationBoundary,
  noop,
} from "@tanstack/react-query";
import { Suspense } from "react";
import { getQueryClient } from "@/lib/query-client";
import { todoOptions } from "@/queries/todos";
import { TodoView } from "@/components/todo-view";
 
type Props = { params: Promise<{ id: string }> };
 
export default async function Page({ params }: Props) {
  const { id } = await params;
  const qc = getQueryClient();
  void qc.query(todoOptions(id)).catch(noop); // no await
  return (
    <HydrationBoundary state={dehydrate(qc)}>
      <Suspense fallback={<p>Loading…</p>}>
        <TodoView id={id} />
      </Suspense>
    </HydrationBoundary>
  );
}

import { z } from "zod";
 
export class HttpError extends Error {
  override name = "HttpError";
  constructor(readonly status: number, message: string) {
    super(message);
  }
}
 
export async function fetchJson<S extends z.ZodType>(
  url: string,
  schema: S,
  init: RequestInit = {},
): Promise<z.output<S>> {
  const headers = new Headers(init.headers);
  headers.set("accept", "application/json");
  const res = await fetch(url, { ...init, headers });
  if (!res.ok) {
    throw new HttpError(res.status, `${res.status} ${url}`);
  }
  return schema.parse(await res.json()); // throws ZodError
}
// no retry on 4xx:
// retry: (n, e) =>
//   n < 3 && !(e instanceof HttpError && e.status < 500)