Chapter 25 — RTK Query with TypeScript

// services/api.ts
import { createApi, fetchBaseQuery } from "@reduxjs/toolkit/query/react";
import type { RootState } from "../app/store";
import type { Paginated, PublicUser, CreateUserDto, UpdateUserDto } from "@app/shared";

export interface Task {
  id: string;
  title: string;
  done: boolean;
  ownerId: string;
  createdAt: string;
}

export const api = createApi({
  reducerPath: "api",
  baseQuery: fetchBaseQuery({
    baseUrl: "/api",
    credentials: "include",                             // send the refresh-token cookie
    prepareHeaders: (headers, { getState }) => {
      const token = (getState() as RootState).auth.accessToken;
      if (token) headers.set("Authorization", `Bearer ${token}`);
      return headers;
    },
  }),
  tagTypes: ["User", "Task"],
  endpoints: (builder) => ({
    //               ┌ result type          ┌ argument type
    getUsers: builder.query<Paginated<PublicUser>, { page: number; search?: string }>({
      query: ({ page, search }) => ({ url: "/users", params: { page, search } }),
      providesTags: (result) =>
        result
          ? [...result.items.map((u) => ({ type: "User" as const, id: u.id })), { type: "User", id: "LIST" }]
          : [{ type: "User", id: "LIST" }],
    }),

    getUser: builder.query<PublicUser, string>({
      query: (id) => `/users/${id}`,
      // Unwrap our { success, data } envelope so components get the entity directly
      transformResponse: (res: { success: true; data: PublicUser }) => res.data,
      providesTags: (_r, _e, id) => [{ type: "User", id }],
    }),

    createUser: builder.mutation<PublicUser, CreateUserDto>({
      query: (body) => ({ url: "/users", method: "POST", body }),
      invalidatesTags: [{ type: "User", id: "LIST" }],   // refetch any user list
    }),

    updateUser: builder.mutation<PublicUser, { id: string } & UpdateUserDto>({
      query: ({ id, ...patch }) => ({ url: `/users/${id}`, method: "PATCH", body: patch }),
      invalidatesTags: (_r, _e, { id }) => [{ type: "User", id }],
    }),

    deleteUser: builder.mutation<void, string>({
      query: (id) => ({ url: `/users/${id}`, method: "DELETE" }),
      invalidatesTags: (_r, _e, id) => [{ type: "User", id }, { type: "User", id: "LIST" }],
    }),
  }),
});

export const {
  useGetUsersQuery,
  useGetUserQuery,
  useCreateUserMutation,
  useUpdateUserMutation,
  useDeleteUserMutation,
} = api;

getUsers({page:1})  provides  [User:a, User:b, User:LIST]
getUser("a")        provides  [User:a]

updateUser({id:"a"}) invalidates [User:a]
   → getUser("a") refetches
   → getUsers({page:1}) refetches  (it also provided User:a)

createUser(...)     invalidates [User:LIST]
   → only list queries refetch

import { useState } from "react";
import { skipToken } from "@reduxjs/toolkit/query/react";
import { useGetUsersQuery, useGetUserQuery } from "../../services/api";

export function UserList() {
  const [page, setPage] = useState(1);
  const { data, isLoading, isFetching, isError, error, refetch } = useGetUsersQuery(
    { page },
    { refetchOnMountOrArgChange: 30 },   // refetch if cached data is older than 30s
  );

  if (isLoading) return <p>Loading…</p>;                 // first load only
  if (isError) return <ErrorBox error={error} onRetry={refetch} />;

  return (
    <>
      {isFetching && <small>Updating…</small>}           {/* background refetch */}
      <ul>{data?.items.map((u) => <li key={u.id}>{u.name}</li>)}</ul>
      <button disabled={page === 1} onClick={() => setPage((p) => p - 1)}>Prev</button>
      <button onClick={() => setPage((p) => p + 1)}>Next</button>
    </>
  );
}

export function UserDetails({ id }: { id?: string }) {
  // skipToken: don't run the query until we have an id (typed alternative to { skip: true })
  const { data: user } = useGetUserQuery(id ?? skipToken);
  return user ? <h2>{user.name}</h2> : null;
}

import type { FetchBaseQueryError } from "@reduxjs/toolkit/query";
import type { SerializedError } from "@reduxjs/toolkit";

export function isFetchBaseQueryError(e: unknown): e is FetchBaseQueryError {
  return typeof e === "object" && e != null && "status" in e;
}

export function errorMessage(e: FetchBaseQueryError | SerializedError | undefined): string {
  if (!e) return "";
  if (isFetchBaseQueryError(e)) {
    // our Express error envelope: { success:false, code, message }
    const data = e.data as { message?: string } | undefined;
    return data?.message ?? `Request failed (${String(e.status)})`;
  }
  return e.message ?? "Unexpected error";
}

import { useCreateUserMutation } from "../../services/api";
import { errorMessage } from "../../services/errors";   // helper from the previous example

export function NewUserForm() {
  const [createUser, { isLoading, error }] = useCreateUserMutation();

  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault();
    const formEl = e.currentTarget;      // capture now: currentTarget is null after an await
    const form = new FormData(formEl);
    try {
      await createUser({
        name: String(form.get("name")),
        email: String(form.get("email")),
        password: String(form.get("password")),
      }).unwrap();                       // throws on error
      formEl.reset();
    } catch {
      /* error is also available from the hook state */
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input name="name" required />
      <input name="email" type="email" required />
      <input name="password" type="password" minLength={8} required />
      <button disabled={isLoading}>{isLoading ? "Saving…" : "Create"}</button>
      {error && <p role="alert">{errorMessage(error)}</p>}
    </form>
  );
}

toggleTask: builder.mutation<Task, { id: string; done: boolean; page: number }>({
  query: ({ id, done }) => ({ url: `/tasks/${id}`, method: "PATCH", body: { done } }),
  async onQueryStarted({ id, done, page }, { dispatch, queryFulfilled }) {
    // 1. Patch the cached list immediately
    const patch = dispatch(
      api.util.updateQueryData("getTasks", { page }, (draft) => {
        const task = draft.items.find((t) => t.id === id);
        if (task) task.done = done;
      }),
    );
    try {
      await queryFulfilled;      // 2. Wait for the server
    } catch {
      patch.undo();              // 3. Roll back if it failed
    }
  },
}),

import { fetchBaseQuery, type BaseQueryFn, type FetchArgs, type FetchBaseQueryError } from "@reduxjs/toolkit/query/react";
import { tokenRefreshed, loggedOut } from "../features/auth/authSlice";

const rawBaseQuery = fetchBaseQuery({ /* same config as above */ baseUrl: "/api", credentials: "include" });

let refreshing: Promise<boolean> | null = null;   // share one refresh between parallel 401s

export const baseQueryWithReauth: BaseQueryFn<string | FetchArgs, unknown, FetchBaseQueryError> =
  async (args, api, extraOptions) => {
    let result = await rawBaseQuery(args, api, extraOptions);

    if (result.error?.status === 401) {
      refreshing ??= (async () => {
        const r = await rawBaseQuery({ url: "/auth/refresh", method: "POST" }, api, extraOptions);
        const data = r.data as { accessToken: string } | undefined;
        if (data) api.dispatch(tokenRefreshed(data.accessToken));
        else api.dispatch(loggedOut());
        return Boolean(data);
      })().finally(() => { refreshing = null; });

      if (await refreshing) result = await rawBaseQuery(args, api, extraOptions);   // retry once
    }
    return result;
  };

// createApi({ baseQuery: baseQueryWithReauth, ... })

// features/tasks/tasksApi.ts
import { api } from "../../services/api";

export const tasksApi = api.injectEndpoints({
  endpoints: (builder) => ({
    getTasks: builder.query<Paginated<Task>, { page: number }>({
      query: ({ page }) => `/tasks?page=${page}`,
      providesTags: [{ type: "Task", id: "LIST" }],
    }),
  }),
});

export const { useGetTasksQuery } = tasksApi;