useQuery 옵션들

목차

1) staleTime과 gcTime

const {
  data,
  // ...
} = useQuery({
  queryKey: ["super-heroes"],
  queryFn: getAllSuperHero,
  gcTime: 5 * 60 * 1000, // 5분
  staleTime: 1 * 60 * 1000, // 1분
});

1. staleTime: (number | Infinity)
   • staleTime은 데이터가 fresh에서 stale 상태로 변경되는 데 걸리는 시간, 만약 staleTime이 3000이면 fresh 상태에서 3초 뒤에 stale로 변환
   • fresh 상태일 때는 쿼리 인스턴스가 새롭게 mount 되어도 네트워크 요청(fetch)이 일어나지 않는다.
   • 참고로, staleTime의 기본값은 0이기 때문에 일반적으로 fetch 후에 바로 stale이 된다.
2. gcTime: (number | Infinity)
   • 데이터가 사용하지 않거나, inactive 상태일 때 캐싱 된 상태로 남아있는 시간(밀리초)이다.
   • 쿼리 인스턴스가 unmount 되면 데이터는 inactive 상태로 변경되며, 캐시는 gcTime만큼 유지된다.
   • gcTime이 지나면 가비지 콜렉터로 수집된다.
   • gcTime이 지나기 전에 쿼리 인스턴스가 다시 mount 되면, 데이터를 fetch 하는 동안 캐시 데이터를 보여준다.
   • gcTime은 staleTime과 관계없이, 무조건 inactive 된 시점을 기준으로 캐시 데이터 삭제를 결정한다.
   • gcTime의 기본값은 5분이다. SSR 환경에서는 Infinity이다.

2) refetchOnMount

const {
  data,
  // ...
} = useQuery({
  queryKey: ["super-heroes"],
  queryFn: getAllSuperHero,
  refetchOnMount: true,
});

• refetchOnMount: boolean | "always" | ((query: Query) => boolean | "always")
• 데이터가 stale 상태일 경우, mount마다 refetch를 실행하는 옵션이다.
• 기본값은 true이다.
• always로 설정하면 마운트 시마다 매번 refetch를 실행한다.
• false로 설정하면 최초 fetch 이후에는 refetch 하지 않는다.

3) refetchOnWindowFocus

const {
  data,
  // ...
} = useQuery({
  queryKey: ["super-heroes"],
  queryFn: getAllSuperHero,
  refetchOnWindowFocus: true,
});

• refetchOnWindowFocus: boolean | "always" | ((query: Query) => boolean | "always")
• 데이터가 stale 상태일 경우, 윈도우 포커싱 될 때마다 refetch를 실행하는 옵션이다.
• 기본값은 true이다.
• 예를 들어, 크롬에서 다른 탭을 눌렀다가 다시 원래 보던 중인 탭을 눌렀을 때도 이 경우에 해당한다. 심지어 F12로 개발자 도구 창을 켜서 네트워크 탭이든, 콘솔 탭이든 개발자 도구 창에서 놀다가 페이지 내부를 다시 클릭했을 때도 이 경우에 해당한다.
• always로 설정하면 항상 윈도우 포커싱 될 때마다 refetch를 실행한다는 의미이다.

4) polling

const {
  data,
  // ...
} = useQuery({
  queryKey: ["super-heroes"],
  queryFn: getAllSuperHero,
  refetchInterval: 2000,
  refetchIntervalInBackground: true,
});

💡 `Polling(폴링)`이란? 실시간 웹을 위한 기법으로 "`일정한 주기(특정한 시간`)"를 가지고 `서버와 응답을 주고받는 방식`이 폴링 방식이다. react-query에서는 "`refetchInterval`", "`refetchIntervalInBackground`"을 이용해서 구현할 수 있다.

1. refetchInterval: number | false | ((data: TData | undefined, query: Query) => number | false)
   • refetchInterval은 시간(ms)를 값으로 넣어주면 일정 시간마다 자동으로 refetch를 시켜준다.
2. refetchIntervalInBackground: boolean
   • refetchIntervalInBackground는 refetchInterval과 함께 사용하는 옵션이다.
   • 탭/창이 백그라운드에 있는 동안 refetch 시켜준다. 즉, 브라우저에 focus 되어 있지 않아도 refetch를 시켜주는 것을 의미한다.

5) retry

const {
  data,
  refetch,
  // ...
} = useQuery({
  queryKey: ["super-heroes"],
  queryFn: getAllSuperHero,
  retry: 10, // 오류를 표시하기 전에 실패한 요청을 10번 재시도합니다.
});

• retry: (boolean | number | (failureCount: number, error: TError) => boolean)
• 쿼리가 실패하면 useQuery를 특정 횟수만큼 재요청하는 옵션이다.
• retry가 false인 경우, 실패한 쿼리는 기본적으로 다시 시도하지 않는다. true인 경우에는 실패한 쿼리에 대해서 무한 재요청을 시도한다.
• 값으로 숫자를 넣을 경우, 실패한 쿼리가 해당 숫자를 충족할 때까지 요청을 재시도한다.
• 기본값은 클라이언트 환경에서는 3, 서버 환경에서는 0이다.

6) select

const {
  data,
  // ...
} = useQuery({
  queryKey: ["super-heroes"],
  queryFn: getAllSuperHero,
  select: (data) => {
    const superHeroNames = data.data.map((hero) => hero.name);
    return superHeroNames;
  },
});

return (
  <div>
    {data.map((heroName, idx) => (
      <div key={`${heroName}-${idx}`}>{heroName}</div>
    ))}
  </div>
);

• select: (data: TData) => unknown
• select 옵션을 사용하여 쿼리 함수에서 반환된 데이터의 일부를 변환하거나 선택할 수 있다.
• 참고로, 반환된 데이터 값에는 영향을 주지만 쿼리 캐시에 저장되는 내용에는 영향을 주지 않는다.

7) placeholderData

const placeholderData = useMemo(() => generateFakeHeroes(), []);

const {
  data,
  // ...
} = useQuery({
  queryKey: ["super-heroes"],
  queryFn: getAllSuperHero,
  placeholderData: placeholderData,
});

• placeholderData: TData | (previousValue: TData | undefined; previousQuery: Query | undefined,) => TData
• placeholderData를 설정하면 쿼리가 pending 상태인 동안 특정 쿼리에 대한 placeholder data로 사용된다.
• placeholderData는 캐시에 유지되지 않으며, 서버 데이터와 관계없는 보여주기용 가짜 데이터다.
• placeholderData에 함수를 제공하는 경우 첫 번째 인자로 이전에 관찰된 쿼리 데이터를 수신하고, 두 번째 인자는 이전 쿼리 인스턴스가 된다.

8) 요약

1. gcTime/staleTime: staleTime은 data가 fresh에서 stale로 변경되기까지의 시간, gcTime은 data가 사용되지 않거나 inactive 상태일 때 stale 유지하는 시간
   • 기본값: gcTime: 5000ms, staleTime: 0ms
2. refetchOnMount: 데이터가 stale 상태일 경우, mount마다 refetch를 실행. always로 설정하면 마운트 시마다 매번 refetch를 실행. false로 설정하면 최초 fetch 이후에는 refetch 하지 않는다.
   • 기본값: true
3. refetchOnWindowFocus : 데이터가 stale 상태일 경우 윈도우 포커싱 될 때마다 refetch를 실행하는 옵션.
   • 기본값: true
4. polling: 일정한 주기(특정한 시간)"를 가지고 서버와 응답을 주고받는 방식
   • refetchInterval: 시간(ms)를 값으로 넣어주면 일정 시간마다 자동으로 refetch
   • refetchIntervalInBackground : 탭/창이 백그라운드에 있는 동안 refetch, refetchInterval 와 같이 사용.
5. retry: 쿼리가 실패하면 useQuery를 특정 횟수만큼 재요청하는 옵션
   • 기본값: 클라이언트 환경에서는 3, 서버 환경에서는 0
6. select: 쿼리 함수에서 반환된 데이터의 일부를 변환하거나 선택할 수 있다.
7. placeholderData:  쿼리가 pending 상태인 동안 특정 쿼리에 대한 placeholder data로 사용

출처

https://github.com/ssi02014/react-query-tutorial?tab=readme-ov-file#refetchonmount