QueryClient

QueryClient를 사용하여 캐시와 상호작용할 수 있습니다:

import { QueryClient } from '@tanstack/react-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: Infinity,
    },
  },
})

await queryClient.query({ queryKey: ['posts'], queryFn: fetchPosts })

사용 가능한 메서드는 다음과 같습니다:

• queryClient.query
• queryClient.infiniteQuery
• queryClient.getQueryData
• queryClient.getQueriesData
• queryClient.setQueryData
• queryClient.getQueryState
• queryClient.setQueriesData
• queryClient.invalidateQueries
• queryClient.refetchQueries
• queryClient.cancelQueries
• queryClient.removeQueries
• queryClient.resetQueries
• queryClient.isFetching
• queryClient.isMutating
• queryClient.getDefaultOptions
• queryClient.setDefaultOptions
• queryClient.getQueryDefaults
• queryClient.setQueryDefaults
• queryClient.getMutationDefaults
• queryClient.setMutationDefaults
• queryClient.getQueryCache
• queryClient.getMutationCache
• queryClient.clear
• queryClient.resumePausedMutations

옵션

• queryCache?: QueryCache
  • 선택 사항
  • 이 클라이언트가 연결된 쿼리 캐시입니다.
• mutationCache?: MutationCache
  • 선택 사항
  • 이 client가 연결된 뮤테이션 캐시입니다.
• defaultOptions?: DefaultOptions
  • 선택 사항
  • 이 queryClient를 사용하여 모든 쿼리와 뮤테이션의 기본값을 정의합니다.
  • 하이드레이션에 사용할 기본값도 정의할 수 있습니다

queryClient.query

query는 쿼리를 가져와 캐시하는 데 사용할 수 있는 비동기 메서드입니다. 데이터를 이행하거나 오류를 발생시킵니다.

쿼리가 존재하고 데이터가 무효화되지 않았으며 지정된 staleTime보다 오래되지 않았다면 캐시의 데이터를 반환합니다. 그렇지 않으면 최신 데이터를 가져오려고 시도합니다.

try {
  const data = await queryClient.query({ queryKey, queryFn })
} catch (error) {
  console.log(error)
}

데이터가 일정 시간보다 오래된 경우에만 가져오려면 staleTime을 지정합니다:

try {
  const data = await queryClient.query({
    queryKey,
    queryFn,
    staleTime: 10000,
    select: (data) => data.items,
  })
} catch (error) {
  console.log(error)
}

옵션

query의 옵션은 다음 항목을 제외하면 useQuery의 옵션과 정확히 같습니다: enabled, refetchInterval, refetchIntervalInBackground, refetchOnWindowFocus, refetchOnReconnect, refetchOnMount, notifyOnChangeProps, throwOnError, suspense, placeholderData; 이는 useQuery 및 useInfiniteQuery 전용입니다. 더 명확한 내용을 확인하려면 소스 코드를 살펴볼 수 있습니다.

반환값

• Promise<TData>

queryClient.infiniteQuery

infiniteQuery는 query와 유사하지만, 무한 쿼리를 가져오고 캐시하는 데 사용할 수 있습니다.

try {
  const data = await queryClient.infiniteQuery({ queryKey, queryFn })
  console.log(data.pages)
} catch (error) {
  console.log(error)
}

옵션

infiniteQuery의 옵션은 query의 옵션과 정확히 동일하며, 여기에 useInfiniteQuery의 initialPageParam, pages 및 getNextPageParam 옵션이 추가됩니다.

반환값

• Promise<InfiniteData<TData, TPageParam>>

queryClient.getQueriesData

getQueriesData는 여러 쿼리의 캐시된 데이터를 가져오는 데 사용할 수 있는 동기 함수입니다. 전달된 queryKey 또는 queryFilter와 일치하는 쿼리만 반환됩니다. 일치하는 쿼리가 없으면 빈 배열이 반환됩니다.

const data = queryClient.getQueriesData(filters)

옵션

• filters: QueryFilters: 쿼리 필터
  • 필터가 전달되면 필터와 일치하는 queryKeys가 있는 데이터가 반환됩니다

반환값

• [queryKey: QueryKey, data: TQueryFnData | undefined][]
  • 일치하는 쿼리 키에 대한 튜플 배열이며, 일치 항목이 없으면 []입니다. 각 튜플은 쿼리 키와 연결된 데이터로 구성됩니다.

주의 사항

각 튜플에서 반환되는 데이터의 구조가 서로 다를 수 있으므로(예: 필터를 사용해 "활성" 쿼리를 반환하면 서로 다른 데이터 타입이 반환될 수 있음) TData 제네릭의 기본값은 unknown입니다. TData에 더 구체적인 타입을 제공하면 각 튜플의 데이터 항목이 모두 동일한 타입이라고 확신하는 것으로 간주합니다.

이 구분은 어떤 구조가 반환될지 아는 TypeScript 개발자를 위한 "편의성"에 더 가깝습니다.

queryClient.setQueryData

setQueryData는 쿼리의 캐시된 데이터를 즉시 업데이트하는 데 사용할 수 있는 동기 함수입니다. 쿼리가 존재하지 않으면 생성됩니다. 기본 gcTime 내에서 쿼리 훅이 해당 쿼리를 사용하지 않으면 쿼리는 가비지 컬렉션됩니다. 기본 gcTime이 구성되지 않았다면 기본값은 5분입니다. 여러 쿼리를 한 번에 업데이트하고 쿼리 키를 부분적으로 일치시키려면 대신 queryClient.setQueriesData를 사용해야 합니다.

setQueryData와 query 사용의 차이점은 setQueryData가 동기식이며 데이터를 이미 동기적으로 사용할 수 있다고 가정한다는 것입니다. 데이터를 비동기적으로 가져와야 한다면 쿼리 키를 다시 가져오거나 query를 사용하여 비동기 가져오기를 처리하는 것이 좋습니다.

queryClient.setQueryData(queryKey, updater)

옵션

• queryKey: QueryKey: 쿼리 키
• updater: TQueryFnData | undefined | ((oldData: TQueryFnData | undefined) => TQueryFnData | undefined)
  • 함수가 아닌 값이 전달되면 데이터가 이 값으로 업데이트됩니다.
  • 함수가 전달되면 이전 데이터 값을 받으며 새 데이터 값을 반환해야 합니다.

업데이터 값 사용하기

setQueryData(queryKey, newData)

값이 undefined이면 쿼리 데이터가 업데이트되지 않습니다.

업데이터 함수 사용하기

구문을 편리하게 작성하기 위해 현재 데이터 값을 받아 새 값을 반환하는 업데이터 함수를 전달할 수도 있습니다:

setQueryData(queryKey, (oldData) => newData)

업데이터 함수가 undefined를 반환하면 쿼리 데이터가 업데이트되지 않습니다. 업데이터 함수가 undefined를 입력으로 받으면 undefined를 반환하여 업데이트를 중단하고, 이에 따라 새 캐시 항목을 생성하지 않을 수 있습니다.

불변성

setQueryData를 통한 업데이트는 불변 방식으로 수행해야 합니다. oldData 또는 getQueryData를 통해 가져온 데이터를 제자리에서 변경하여 캐시에 직접 쓰려고 절대 시도하지 마세요.

queryClient.getQueryState

getQueryState는 기존 쿼리의 상태를 가져오는 데 사용할 수 있는 동기 함수입니다. 쿼리가 존재하지 않으면 undefined가 반환됩니다.

const state = queryClient.getQueryState(queryKey)
console.log(state.dataUpdatedAt)

옵션

• queryKey: QueryKey: 쿼리 키

queryClient.setQueriesData

setQueriesData는 필터 함수 또는 쿼리 키의 부분 일치를 사용해 여러 쿼리의 캐시된 데이터를 즉시 업데이트할 수 있는 동기 함수입니다. 전달된 queryKey 또는 queryFilter와 일치하는 쿼리만 업데이트되며, 새로운 캐시 항목은 생성되지 않습니다. 내부적으로 기존의 각 쿼리에 대해 setQueryData가 호출됩니다.

queryClient.setQueriesData(filters, updater)

옵션

• filters: QueryFilters: 쿼리 필터
  • 필터가 전달되면 필터와 일치하는 queryKeys가 업데이트됩니다
• updater: TQueryFnData | (oldData: TQueryFnData | undefined) => TQueryFnData
  • setQueryData 업데이트 함수 또는 새 데이터는 일치하는 각 queryKey에 대해 호출됩니다

queryClient.invalidateQueries

invalidateQueries 메서드는 쿼리 키 또는 쿼리에서 기능적으로 접근 가능한 다른 속성/상태를 기준으로 캐시에 있는 하나 이상의 쿼리를 무효화하고 다시 가져오는 데 사용할 수 있습니다. 기본적으로 일치하는 모든 쿼리는 즉시 무효로 표시되며 활성 쿼리는 백그라운드에서 다시 가져옵니다.

• 활성 쿼리를 다시 가져오지 않고 단순히 무효화된 것으로 표시하려면 refetchType: 'none' 옵션을 사용할 수 있습니다.
• 비활성 쿼리도 다시 가져오게 하려면 refetchType: 'all' 옵션을 사용하세요
• 다시 가져오기에는 queryClient.refetchQueries가 호출됩니다.

await queryClient.invalidateQueries(
  {
    queryKey: ['posts'],
    exact,
    refetchType: 'active',
  },
  { throwOnError, cancelRefetch },
)

옵션

• filters?: QueryFilters: 쿼리 필터
  • queryKey?: QueryKey: 쿼리 키
  • refetchType?: 'active' | 'inactive' | 'all' | 'none'
    • 기본값은 'active'입니다
    • active로 설정하면 다시 가져오기 조건자와 일치하고 useQuery 및 관련 항목을 통해 활발하게 렌더링되는 쿼리만 백그라운드에서 다시 가져옵니다.
    • inactive로 설정하면, 다시 가져오기 조건자와 일치하고 useQuery 및 관련 기능을 통해 현재 활발하게 렌더링되지 않는 쿼리만 백그라운드에서 다시 가져옵니다.
    • all로 설정하면 다시 가져오기 조건자와 일치하는 모든 쿼리를 백그라운드에서 다시 가져옵니다.
    • none로 설정하면 어떤 쿼리도 다시 가져오지 않으며, 다시 가져오기 조건자와 일치하는 쿼리는 무효로만 표시됩니다.
• options?: InvalidateOptions:
  • throwOnError?: boolean
    • true로 설정하면 쿼리 다시 가져오기 작업 중 하나라도 실패할 경우 이 메서드가 오류를 발생시킵니다.
  • cancelRefetch?: boolean
    • 기본값은 true입니다
      • 기본적으로 새 요청을 보내기 전에 현재 실행 중인 요청이 취소됩니다
    • false로 설정하면 이미 요청이 실행 중일 때 다시 가져오기를 수행하지 않습니다.

참고 사항

• refetchQueries와 달리 invalidateQueries는 일치하는 쿼리를 무효화된 것으로 표시한 다음 active 쿼리를 다시 가져옵니다(refetchType 옵션으로 달리 지정하지 않는 한).
• removeQueries와 달리, invalidateQueries는 일치하는 쿼리를 캐시에 유지합니다.

queryClient.refetchQueries

refetchQueries 메서드는 특정 조건에 따라 쿼리를 다시 가져오는 데 사용할 수 있습니다.

예시:

// refetch all queries:
await queryClient.refetchQueries()

// refetch all stale queries:
await queryClient.refetchQueries({ stale: true })

// refetch all active queries partially matching a query key:
await queryClient.refetchQueries({ queryKey: ['posts'], type: 'active' })

// refetch all active queries exactly matching a query key:
await queryClient.refetchQueries({
  queryKey: ['posts', 1],
  type: 'active',
  exact: true,
})

옵션

• filters?: QueryFilters: 쿼리 필터
• options?: RefetchOptions:
  • throwOnError?: boolean
    • true로 설정하면 쿼리 다시 가져오기 작업 중 하나라도 실패할 경우 이 메서드가 오류를 발생시킵니다.
  • cancelRefetch?: boolean
    • 기본값은 true입니다
      • 기본적으로 새 요청을 보내기 전에 현재 실행 중인 요청이 취소됩니다
    • false로 설정하면 이미 요청이 실행 중일 때 다시 가져오기를 수행하지 않습니다.

반환값

이 함수는 모든 쿼리의 다시 가져오기가 완료되면 이행되는 Promise를 반환합니다. 기본적으로 해당 쿼리의 다시 가져오기에 실패해도 오류를 발생시키지 않지만, throwOnError 옵션을 true로 설정하여 이를 구성할 수 있습니다.

참고 사항

• 비활성화된 Observer만 있어 "비활성화된" 쿼리는 절대 다시 가져오지 않습니다.
• Static StaleTime을 사용하는 Observer만 있어 "정적"인 쿼리는 절대 다시 가져오지 않습니다.
• invalidateQueries와 달리 refetchQueries는 일치하는 모든 쿼리를 다시 가져옵니다.

queryClient.cancelQueries

cancelQueries 메서드를 사용하면 쿼리 키 또는 함수로 접근 가능한 쿼리의 다른 속성/상태를 기준으로 진행 중인 쿼리를 취소할 수 있습니다.

이는 낙관적 업데이트를 수행할 때 가장 유용합니다. 진행 중인 쿼리 다시 가져오기가 이행될 때 낙관적 업데이트를 덮어쓰지 않도록 해당 작업을 취소해야 할 가능성이 높기 때문입니다.

await queryClient.cancelQueries(
  { queryKey: ['posts'], exact: true },
  { silent: true },
)

옵션

• filters?: QueryFilters: 쿼리 필터
• cancelOptions?: CancelOptions: 취소 옵션

반환값

이 메서드는 아무것도 반환하지 않습니다

queryClient.removeQueries

removeQueries 메서드는 쿼리 키나 함수로 접근할 수 있는 쿼리의 다른 속성/상태를 기준으로 캐시에서 쿼리를 제거하는 데 사용할 수 있습니다.

queryClient.removeQueries({ queryKey, exact: true })

옵션

• filters?: QueryFilters: 쿼리 필터

반환값

이 메서드는 아무것도 반환하지 않습니다

참고 사항

• invalidateQueries 또는 refetchQueries와 달리, removeQueries는 일치하는 쿼리를 다시 가져오는 대신 캐시에서 제거합니다.

queryClient.resetQueries

resetQueries 메서드를 사용하여 캐시의 쿼리를 원래 상태로 재설정할 수 있습니다 쿼리 키 또는 기능적으로 접근 가능한 다른 요소를 기반으로 한 초기 상태 쿼리의 속성/상태입니다.

이는 모든 항목을 제거하는 clear와 달리 구독자에게 알립니다 — 구독자 — 그리고 쿼리를 미리 로드된 상태로 재설정합니다 — 이와 달리 invalidateQueries. 쿼리에 initialData가 있으면 쿼리의 데이터는 해당 값으로 재설정합니다. 쿼리가 활성 상태이면 다시 가져옵니다.

queryClient.resetQueries({ queryKey, exact: true })

옵션

• filters?: QueryFilters: 쿼리 필터
• options?: ResetOptions:
  • throwOnError?: boolean
    • true로 설정하면 쿼리 다시 가져오기 작업 중 하나라도 실패할 경우 이 메서드가 오류를 발생시킵니다.
  • cancelRefetch?: boolean
    • 기본값은 true입니다
      • 기본적으로 새 요청을 보내기 전에 현재 실행 중인 요청이 취소됩니다
    • false로 설정하면 이미 요청이 실행 중일 때 다시 가져오기를 수행하지 않습니다.

반환값

이 메서드는 모든 활성 쿼리를 다시 가져오고 나면 이행되는 Promise를 반환합니다.

queryClient.isFetching

이 isFetching 메서드는 현재 캐시에서 가져오는 중인 쿼리 수(있는 경우)를 나타내는 integer를 반환합니다(백그라운드 가져오기, 새 페이지 로딩 또는 더 많은 무한 쿼리 결과 로딩 포함).

if (queryClient.isFetching()) {
  console.log('At least one query is fetching!')
}

TanStack Query는 쿼리 캐시에 대한 수동 구독을 생성하지 않고도 컴포넌트에서 이 상태를 구독할 수 있게 해 주는 편리한 useIsFetching 훅도 내보냅니다.

옵션

• filters?: QueryFilters: 쿼리 필터

반환값

이 메서드는 가져오는 중인 쿼리의 수를 반환합니다.

queryClient.isMutating

이 isMutating 메서드는 현재 캐시에서 가져오기 중인 뮤테이션의 수를 나타내는 integer를 반환하며, 해당 뮤테이션이 없을 수도 있습니다.

if (queryClient.isMutating()) {
  console.log('At least one mutation is fetching!')
}

TanStack Query는 뮤테이션 캐시에 대한 수동 구독을 생성하지 않고도 컴포넌트에서 이 상태를 구독할 수 있게 해주는 편리한 useIsMutating 훅도 내보냅니다.

옵션

• filters: MutationFilters: 뮤테이션 필터

반환값

이 메서드는 가져오는 중인 뮤테이션의 수를 반환합니다.

queryClient.getDefaultOptions

getDefaultOptions 메서드는 클라이언트를 생성할 때 또는 setDefaultOptions로 설정한 기본 옵션을 반환합니다.

const defaultOptions = queryClient.getDefaultOptions()

queryClient.setDefaultOptions

setDefaultOptions 메서드를 사용하여 이 queryClient의 기본 옵션을 동적으로 설정할 수 있습니다. 이전에 정의된 기본 옵션은 덮어씁니다.

queryClient.setDefaultOptions({
  queries: {
    staleTime: Infinity,
  },
})

queryClient.getQueryDefaults

getQueryDefaults 메서드는 특정 쿼리에 설정된 기본 옵션을 반환합니다:

const defaultOptions = queryClient.getQueryDefaults(['posts'])

여러 쿼리 기본값이 주어진 쿼리 키와 일치하면 등록 순서에 따라 함께 병합된다는 점에 유의하세요. setQueryDefaults를 참조하세요.

queryClient.setQueryDefaults

setQueryDefaults를 사용하여 특정 쿼리의 기본 옵션을 설정할 수 있습니다:

queryClient.setQueryDefaults(['posts'], { queryFn: fetchPosts })

function Component() {
  const { data } = useQuery({ queryKey: ['posts'] })
}

옵션

• queryKey: QueryKey: 쿼리 키
• options: QueryOptions

getQueryDefaults에 명시된 대로, 쿼리 기본값의 등록 순서는 중요합니다. 일치하는 기본값은 getQueryDefaults에 의해 병합되므로 다음 순서로 등록해야 합니다: 가장 일반적인 키에서 가장 덜 일반적인 키 순입니다. 이렇게 하면 더 구체적인 기본값이 더 일반적인 기본값을 재정의합니다.

queryClient.getMutationDefaults

getMutationDefaults 메서드는 특정 뮤테이션에 설정된 기본 옵션을 반환합니다:

const defaultOptions = queryClient.getMutationDefaults(['addPost'])

queryClient.setMutationDefaults

setMutationDefaults를 사용하여 특정 뮤테이션의 기본 옵션을 설정할 수 있습니다:

queryClient.setMutationDefaults(['addPost'], { mutationFn: addPost })

function Component() {
  const { data } = useMutation({ mutationKey: ['addPost'] })
}

옵션

• mutationKey: unknown[]
• options: MutationOptions

setQueryDefaults와 마찬가지로 여기에서도 등록 순서가 중요합니다.

queryClient.getQueryCache

getQueryCache 메서드는 이 클라이언트가 연결된 쿼리 캐시를 반환합니다.

const queryCache = queryClient.getQueryCache()

queryClient.getMutationCache

getMutationCache 메서드는 이 client가 연결된 뮤테이션 캐시를 반환합니다.

const mutationCache = queryClient.getMutationCache()

queryClient.clear

clear 메서드는 연결된 모든 캐시를 지웁니다.

queryClient.clear()

queryClient.resumePausedMutations

네트워크 연결이 없어 일시 중지된 뮤테이션을 재개하는 데 사용할 수 있습니다.

queryClient.resumePausedMutations()