[TS] useQuery, useMutation의 제네릭 타입 살펴보기 / Base Query 훅 만들기

React Query에서 제공하는 useQuery, useMutation을 그대로 사용하면 항상 쿼리키와 쿼리 함수를 지정해야 하는 번거로움이 있다. API 유형에 따라 Base Query|Mutation 커스텀 훅을 만들어 두고 사용하면 쿼리키와 쿼리 함수를 일일이 지정하지 않고 여러 곳에서 재사용하기 좋다.

 

하지만 커스텀 훅을 만들 때 쿼리 타입을 지정하지 않으면 데이터가 unknown, any인 경우가 많아서 어떤 데이터를 다루는지 알기 어렵다. 쿼리 타입은 대부분 제네릭으로 되어 있는데 이를 잘 사용하면 타입을 보장 받으면서 데이터를 편리하게 다룰 수 있다.

 

useQuery

---

제네릭 타입 톺아보기 ⚡️

export declare function useQuery<
  TQueryFnData = unknown,
  TError = unknown,
  TData = TQueryFnData,
  TQueryKey extends QueryKey = QueryKey // string | readonly unknown[];
>

 

❶ TQueryFnData : 쿼리 함수 리턴 타입 (AxiosResponse<T> 등)

❷ TError : 쿼리 함수 에러 타입 (AxiosError 등)

const { data, error } = useQuery<number, AxiosError>("todo", getTodo);
// data 타입 : number | undefined
// error 타입 : AxiosError | null

 

❸ TData : select 함수로 쿼리 함수 리턴값을 가공할 때 사용하는 최종 리턴 타입. 기본값 TQueryFnData

TQueryFnData is the data returned from your query function, and TData is the eventual data. The eventual data can be different from the query function data when using select for example. — TanStack

 

const { data } = useQuery<Todo[], AxiosError, number>("todos", getTodos, {
  select: (todos) => todos.length,
});
// select 함수가 number(todos.length) 타입을 반환하므로
// TData(3번째 제네릭 타입) 타입도 number 타입으로 지정해준다

 

❹ TQueryKey : 쿼리 키 타입. 기본값 문자열 혹은 배열. 

쿼리키 배열 각 요소에 어떤 타입이 들어갈지 TQueryKey 타입에 직접 지정할 수 있다. 

useQuery<Todo[], AxiosError, Todo[], [string, number]>(["todos", id], getTodo);

 

참고로 QueryKey 타입은 문자열 혹은 배열이지만 쿼리 함수의 context 인자엔 항상 배열로 전달된다. 즉 쿼리키를 문자열로 지정해도 쿼리 함수엔 항상 배열로 전달되는 것. e.g. 'todo' → ['todo']

queryFn: (context: QueryFunctionContext) => Promise<TData>

 

Base Query 커스텀 훅

파라미터가 없을 때

훅을 사용하는 곳에서 쿼리 옵션을 넘길 수 있도록 options 파라미터를 추가한다. 쿼리 옵션은 React Query에서 제공하는 UseQueryOptions 타입을 import 해서 사용하면 된다. UseQueryOptions, useQuery 둘의 타입 인터페이스는 동일하다.

UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>

 

// 커스텀 훅 정의
import { useQuery, UseQueryOptions } from "react-query";
// ...

export default function useClientQuery<T = Client[]>(
  options?: UseQueryOptions<Client[], AxiosError, T>,
) {
  const { getClientList } = ClientAPI;

  return useQuery<Client[], AxiosError, T>(
    queryKeys.CLIENT_LIST,
    getClientList, // resolved data를 반환하는 쿼리 함수
    options,
  );
}

 

useClientQuery 제네릭 타입 T의 기본값을 Client[]로 설정했으므로 select 함수를 넘기지 않았을 때 data 타입은 Client[]가 된다. select 함수를 넘기면 select 함수가 반환하는 값의 타입이 data 타입이 된다.

 

💡 select 함수 인자엔 쿼리 함수의 리턴 값이 전달된다. 위 예시에선 Client[] 타입의 data가 전달된다. 참고로 select 함수는 캐시에 저장되는 내용엔 영향을 주지 않고, 반환한 데이터 값에만 영향을 준다.

// 커스텀 훅 사용
// 다른 컴포넌트에서 커스텀 훅을 사용할 때
const selectFn = (data: Client[]) => { /* ... */ };
const { data, ...queryResults } = useClientQuery({ select: selectFn /* ... */ });

 

파라미터가 있을 때

URL에 동적 path를 추가해야 하는 API라면(/orders/{userId}) Base Query 훅이 path를 파라미터로 받을 수 있도록 하고 쿼리 함수로 path를 넘기면 된다. 아래 예시에선 쿼리 함수가 resolved data를 반환하기 때문에 쿼리 함수를 async () => (await queryFn(params)).data 형태로 작성했다.

// 커스텀 훅 정의
import { useQuery, UseQueryOptions } from "react-query";
// ...

export default function useOrderQuery<T = Order[]>(
  userId: number,
  options?: UseQueryOptions<Order[], AxiosError, T>,
) {
  const { getOrdersById } = OrderAPI;

  return useQuery<Order[], AxiosError, T>(
    queryKeys.ORDER_LIST,
    async () => (await getOrdersById(userId)).data, // resolved data를 반환하는 쿼리 함수
    options,
  );
}

 

쿼리 함수 반환값 AxiosResponse vs Resolved Data ⚡️

쿼리 함수가 AxiosResponse를 반환하면 쿼리의 TQueryFnData 타입도 동일하게 지정해야 한다.

//쿼리 함수가 AxiosResponse를 반환할 때
// AxiosResponse를 반환하는 쿼리 함수
const getClientList = async () => {
  return await axios.get<Client[]>("clients");
};

// useClientQuery 훅
return useQuery<AxiosResponse<Client[]>, AxiosError, T>(/* ... */);

 

쿼리 함수가 resolved data를 반환하면 TQueryFnData 타입에 반환 데이터 타입(Client[])만 지정하면 된다.

// 쿼리 함수가 resolved data를 반환할 때
// resolved data를 반환하는 쿼리 함수
const getClientList = async () => {
  const { data } = await axios.get<Client[]>("clients");
  return data;
};

// useClientQuery 훅
return useQuery<Client[], AxiosError, T>(/* ... */);

 

useMutation

---

제네릭 타입 톺아보기 ⚡️

export function useMutaion<
  TData = unknown,
  TError = unknown,
  TVariables = void,
  TContext = unknown
>

 

❶ TData : mutation 함수 실행 결과 타입 (AxiosResponse<T> 등)

TData 타입은 ❶onSuccess 콜백의 인자 타입과 ❷useMutation 훅이 반환하는 data 타입이 된다. 

const { data } = useMutation<AxiosResponse<boolean>>(postTodo, {
  onSuccess: (res) => { /* ... */ },
});
// data 타입 : AxiosResponse<boolean> | undefined
// onSuccess 콜백의 res 인자 타입 : AxiosResponse<boolean>

 

❷ TError : mutation 함수 에러 타입 (AxiosError 등)

TError 타입은 ❶onError 콜백의 인자 타입과 ❷useMutation 훅이 반환하는 error 타입이 된다. 

const { error } = useMutation<AxiosResponse<boolean>, AxiosError>(postTodo, {
  onError: (err) => { /* ... */ },
});
// error 타입 : AxiosError | null
// onError 콜백의 err 인자 타입 : AxiosError

 

❸ TVariables : mutation 함수의 인자 타입

TVariables 타입은 mutate 함수와 onSuccess 등 옵션 메서드 콜백 함수의 인자 타입이 된다. 

const { mutate } = useMutation<AxiosResponse<boolean>, AxiosError, number>(
  postTodo, // mutationFn
  {
    onSuccess: (res, id) => { /* ... */ },
    onError: (err, id) => { /* ... */ },
    onMutate: (id) => { /* ... */ },
    onSettled: (res, err, id) => { /* ... */ },
  },
);

const onClick = () => mutate(8);

 

❹ TContext : onMutate 콜백 함수의 리턴 타입

onMutate 콜백 함수는 mutation 함수 실행 전에 실행되며, onMutate 결과 값은 onSuccess 같은 옵션 메서드의 콜백 함수 인자로 전달된다. 

const { mutate } = useMutation<
  AxiosResponse<boolean>,
  AxiosError,
  number,
  number
>(postTodo, {
  onSuccess: (res, id, nextId) => { /* ... */ },
  onError: (err, id, nextId) => { /* ... */ },
  onMutate: (id) => id + 1, // onMutate 콜백 함수의 인자(id) 타입은 TVariables
  onSettled: (res, err, id, nextId) => { /* ... */ },
});

// onSuccess, onMutate, onSettled 콜백의 nextId 인자는 onMutate의 리턴값(number)

 

Base Mutation 커스텀 훅

Base Query 커스텀 훅을 정의한 것처럼 훅을 사용하는 곳에서 mutation 옵션을 넘길 수 있도록 options 파라미터를 추가한다. 마찬가지로 UseQueryOptions 타입을 import해서 사용한다.

 

🔍 invalidateQueries vs setQueryData : invalidation is less code on the frontend, but one more network request. That's the tradeoff (via TanStack Discussions)

• invalidateQueries : refetch related queries that should be stale after the mutation
• setQueryData : merge mutation response to current query data

 

mutation 함수를 호출한 이후 기본적으로 수행할 작업이 있다면 onSuccess, onError 같은 옵션 메서드를 미리 정의해둘 수도 있다. 참고로 mutation은 명시한 쿼리키를 stale 데이터로 취급하도록해서 re-fetching을 트리거하는 queryClient.invalidateQueries 메서드와 자주 사용한다.

// 커스텀 훅 정의
import { useMutation, UseQueryOptions } from "react-query";
// ...

export default function useAddTodoMutation(
  options?: UseMutationOptions<PostTodoResponse, AxiosError, PostTodoPayload>,
) {
  // PostTodoResponse 타입 : AxiosResponse<boolean>
  // PostTodoPayload 타입 : number
  return useMutation<PostTodoResponse, AxiosError, PostTodoPayload>(
    // AxiosResponse를 반환하는 mutation 함수 ↓
    // id 파라미터 타입은 PostTodoPayload ↓
    (id) => postTodo(id),
    options,
  );
}

 

useAddTodoMutation 훅이 반환하는 mutate 함수로 mutation을 실행시킬 수 있다. mutate 함수의 첫번째 인자는 mutation 함수로 전달되며, useMutation 3번째 제네릭 타입으로 넘긴 PostTodoPayload 타입(TVariables)을 갖는다. 필요에 따라 onSuccess 같은 옵션 메서드를 넘길 수도 있다.

// 커스텀 훅 사용
const onSuccess = () => { /* ... */ };
const { mutate, ...useMutationResults } = useAddTodoMutation({ onSuccess });

const onClick = (id: PostTodoPayload) => mutate(id);
// mutate 함수 두번째 인자에 { onError, onSettled, onSuccess }를 넘길 수도 있다.
// ex) mutate(id, { onSuccess: () => {} })
// 실행 순서 : useMutation 옵션 메서드 -> mutate 옵션 메서드

 

제네릭으로 깔끔하게 작성하기 ⚡️

---

useQuery|Mutation에 제네릭을 사용하려면 쿼리(API) 함수도 제네릭을 받을 수 있도록 수정해야 한다.

const getClientList = async <T = Client[],>() => {
  const { data } = await axios.get<T>("clients");
  return data;
};

 

Query 훅의 제네릭 T는 쿼리 함수 리턴 타입(TQueryFnData)으로, K는 최종 리턴 타입(TData)으로 들어가도록 수정한다. T, K 모두 기본값을 지정했으므로, 지정한 타입과 동일하다면 따로 넘기지 않아도 된다.

// useQuery 제네릭 사용 예시
export default function useClientQuery<T = Client[], K = T>(
  options?: UseQueryOptions<T, AxiosError, K>,
) {
  const { getClientList } = ClientAPI;

  return useQuery<T, AxiosError, K>(
    queryKeys.CLIENT_LIST,
    getClientList,
    options,
  );
}

 

Mutation 훅의 제네릭 T는 mutation 함수 실행 결과 타입(TData)으로, K는 mutation 함수의 인자 타입(TVariables)으로 들어가도록 수정한다. 마찬가지로 쿼리 함수가 제네릭을 받을 수 있어야 한다.

// useMutation 제네릭 사용 예시
export default function useAddTodoMutation<
  T = PostTodoResponse,
  K = PostTodoPayload,
>(options?: UseMutationOptions<T, AxiosError, K>) {
  return useMutation<T, AxiosError, K>((id) => postTodo(id), options);
}

 

레퍼런스

---

• useMutation | TanStack Query Docs
• [React Query] 리액트 쿼리 useQuery 실용 편
• react-query에 typescript 적용하기 - 리액트 쿼리, 타입스크립트

 

---

글 수정사항은 노션 페이지에 가장 빠르게 반영됩니다. 링크를 참고해 주세요