useQuery
queryKey
queryKey: unknown[]- 필수 값
- 쿼리에 해당하는 키
- 키가 변하면 쿼리는 자동으로 업데이트 된다. (enabled옵션이 false가 아닐 시)
queryFn
queryFn: (context: QueryFunctionContext) ⇒ Promise- 필수 값. 기본 쿼리 함수가 정의되지 않은 경우에만.
- 요청 데이터를 받는데 필요한 함수
- 프로미스를 리턴. 데이터는 undefined일 수 없다.
enabled
enabled: boolean- false로 설정하면 자동으로 쿼리를 받아오지 않음.
- enalbed옵션으로 등록된 값이 존재하기 이전에는 쿼리 실행이 중단됨.
networkMode
networkMode: ‘online’ | ‘always’ | ‘offlineFirst’- 네트워크 연결이 없을 때 status의 종류. 어떤식으로 동작할지를 선택. 이 모드는 query/ mutation에 대해 개별적으로 동작하거나 전역적으로 동작할 수도 있음.
- 기본값은 online
retry
retry: boolean | number | (failureCount: number, error: TError) => boolean- false 설정시 실패한 쿼리가 재요청되지 않음.
- true 설정시 실패한 쿼리가 계속 재요청 됨.
- 숫자값 설정시 설정한 만큼 재요청함. (기본값 3)
retryOnMound
retryOnMound: boolean- 기본값 true.
- false 설정시 마운트시 쿼리에 오류가 있는 경우 재요청X.
retryDelay
retryDelay: number | (retryAttempt: number, error: TError) => number- 이 함수는 retryAttempt와 오류를 받고, 다음 시도 전까지의 지연시간을 설정할 수 있다.
const queryClient = new QueryClient({
defaultOptions: {
queries: {
retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
// 1000ms의 두배로 시작 **(제곱) 시도한 횟수, 30초(최대) 중에 더 작은 수로 지정
},
},
})staleTime
staleTime: number | Infinity- 기본값 0
- 데이터가 오래된것으로 간주되는 시간.
- Infinity설정시 데이터가 오래된것으로 간주되지 않음.
gcTime
gcTime: number | Infinity- 기본값 5분. SSR은 Infinity
- 사용되지 않은/비활성화 캐시 데이터가 메모리에 남아있는 시간. 쿼리 캐시가 사용되지 않거나 비활성화 시, 캐시데이터는 해당 시간 이후 가비지 수집된다. 수집시간이 다르게 설정되면 가장 긴 시간이 사용됨.
- Infinity설정시 가비지 수집되지 않음.
queryKeyHashFn
queryKeyHashFn: (queryKey: QueryKey) ⇒ string- 설정되면 이 함수는 쿼리키 문자열을 해시하는데 사용된다.
- refetchInterval: number | false | ((query: Query) ⇒ number | false | undefined)
- 숫자로 설정시 모든 쿼리는 설정 시간마다 지속적으로 리패치된다.
- 함수 설정시 빈도를 계산하는 쿼리와 함께 함수가 실행된다.
refetchOnMount
refetchOnMount: boolean | "always" | ((query: Query) => boolean | "always")- true: 마운트할 때 데이터가 오래되었으면 리패치함. (기본값)
- false: 마운트시 리패치X
- always: 마운트시 항상 리패치
refetchOnWindowFocus / refetchOnReconnect
- 윈도우 포커스 되었을 때/ 재연결되었을 때 리패치되는 옵션. 나머지 옵션은 위와 동일.
- notifyOnChangeProps: string[] | "all" | (() => string[] | "all")
- 설정하면 리스트의 프로퍼티중 하나라도 바뀌었을때 컴포넌트가 리렌더링됨.
- [’data’, ‘error’]로 설정시, data나 error프로퍼티에 변화가 있을 때 컴포넌트 리렌더링
- all: 쿼리에 업데이트가 있을 때마다 컴포넌트가 리렌더링됨.
- 함수 설정시 함수가 실행되며 속성을 계산.
- 기본적으로 컴포넌트는 모든 속성의 변경에 대해 다시 렌더링함.
select
select: (data: TData) ⇒ unknown- 쿼리 함수에서 반환되는 데이터에서 일부를 선택하거나 변형하는데 사용된다. 반환되는 data값에는 영향을 주지만 쿼리 캐시에 저장되는 값에는 영향이 가지 않는다.
initialData
initialData: TData | () ⇒ TData- 설정시 이 값은 쿼리캐시의 기본값으로 지정된다. (아직 쿼리가 생성되거나 캐시된 값이 없는경우)
- 함수 설정시 공유/루트 쿼리 초기화 중에 함수가 한 번 호출되며 동기적으로 초기 데이터를 반환할 것으로 예상됩니다.
- 초기데이터는 staleTime지정되지 않은 경우 기본적으로 오래된것으로 간주된다.
- 캐시에 유지된다.
initialDataUpdatedAt
initialDataUpdatedAt: number | (() => number | undefined)- initialData가 마지막 업데이트 된 시간을 설정.
- placeholderData: TData | (previousValue: TData | undefined; previousQuery: Query | undefined,) => TData
- 설정된 값은 쿼리가 아직 pending상태인 경우에 Placeholder데이터로 사용된다.
- 캐시에 저장되지 않는다.
- 함수 설정시 첫번째 인자는 이전에 관찰된 쿼리 데이터, 두번째 인자는 완료된 이전 쿼리 인스턴스임.
structuralSharing
structuralSharing: boolean | ((oldData: T | undefined, newData: T) => T)- 기본값 true
- false: 쿼리 결과의 구조적 공유 비활성화
- 함수 설정시 이전과 새로운 데이터값이 이 함수로 전달되고 이들을 쿼리에 대한 확인된 데이터로 결합해야 한다. 이 경우, 데이터가 직렬화 되지 않은 값을 포함하고 있을 때 성능을 향상 시키기 위한 이전 데이터의 참조를 가지고 있을 수 있다. (뭔소리???)
throwOnError
throwOnError: undefined | boolean | (error: TError, query: Query) => boolean- true: 가까운 에러 바운더리로 에러가 전파됨.
- false: 에러 바운더리로 에러를 전파하는 suspense의 기본동작을 비활성화 함.
- • 함수로 설정하면 오류와 쿼리가 전달되며 오류 경계에 오류를 표시할지(true) 또는 오류를 상태(false) 로 반환할지 여부를 반환해야 함.
useQuery 반환값
status: string
- pending: 캐시된 데이터가 없고 쿼리 시도가 진행중.
- error: 쿼리에 대한 시도에 오류 발생.
- success: 쿼리에 에러가 없고 응답을 받았으며 데이터가 준비됨.
- 쿼리에 대응하는 data프로퍼티는 성공적인 패치가 된 데이터이거나 enabled프로퍼티가 false로 설정되고 아직 가져오지 않은경우 데이터는 처음initialData로 초기설정된 쿼리이다.
isPending / isSuccess / isError: boolean
편의를 위해 status변수에서 파생됨.
isLoadingError: boolean
처음에 쿼리가 패칭 실패한 경우 true.
isRefetchError: boolean
쿼리가 리패칭중에 실패한 경우 true
data: TData
- 기본값 undefined.
- 쿼리에서 마지막으로 성공적으로 완료된 데이터.
dataUpdatedAt: number
쿼리의 최근 status가 success인 시점.
error: null | TError
기본값 null
errorUpdatedAt: number
쿼리의 최근 status가 error인 시점.
isStale: boolean
캐시 데이터가 무효화된 경우이거나 지정한 staleTime보다 오래된 경우 true
isPlaceholderData: boolean
데이터가 placeholder데이터인지 판별.
isFetchedAfterMount: boolean
- 컴포넌트 마운트 이후 쿼리가 패치되었으면 true
- 이 프로퍼티는 이전 캐시 데이터를 보여주지 않는데에 사용될 수 있음.
fetchStatus: FetchStatus
isFetching / isPaused
fetchStatus의 상태에서 편의를 위해 파생된 상태.
useQueries
쿼리 오브젝트의 배열에서 하나이상의 같은 쿼리키를 가진다는 것은 어떤 데이터는 쿼리간에 공유될 수 있다는 것을 의미한다. 이것을 방지하려면 쿼리 중복을 제거하고 원하는 구조로 결과를 다시 매핑하는것을 고려해야한다.
placeholderData
placeholderData옵션은 useQueries에도 존재하지만 useQuery처럼 이전 렌더된 쿼리들에서 정보를 넘겨 받을 수 있는건 아님.
반환값
useQueries훅은 모든 쿼리 결과가 포함된 배열을 리턴한다. 순서는 입력된 순서와 동일하다.
combine
반환된 결과값들을 하나의 결합된 데이터 값으로 만들고 싶다면 combine옵션을 사용하면 된다.
const ids = [1,2,3]
const combinedQueries = useQueries({
queries: ids.map(id => (
{ queryKey: ['post', id], queryFn: () => fetchPost(id) },
)),
combine: (results) => {
return ({
data: results.map(result => result.data),
pending: results.some(result => result.isPending),
})
}
}) // data, pending 프로퍼티 외에 다른 결과값들은 손실됨.