[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는 쿼리 함수가 반환하는 원본 데이터 타입이고, TData는 최종적으로 사용하게 될 데이터 타입이다. select 옵션을 사용하면 쿼리 함수가 반환한 데이터를 가공할 수 있으므로, TData는 TQueryFnData와 달라질 수 있다. — 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 인자엔 항상 배열로 전달된다. 즉, 쿼리키를 문자열로 지정해도 쿼리 함수엔 항상 배열로 전달되는 것. 예: '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는 프론트엔드에서 처리할 코드가 적은 대신, 쿼리를 다시 가져오기 때문에 네트워크 요청이 한 번 더 발생한다. 반대로 setQueryData는 추가 요청 없이 캐시를 직접 갱신할 수 있지만, 응답 데이터를 현재 캐시에 맞게 직접 반영하는 코드가 필요하다. (참고 링크)

 

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 적용하기 - 리액트 쿼리, 타입스크립트